Assurance NDJSON — Wire Contract

In a folder linked to a shared project (kane-cli 0.10.0+) the same commands add their own events (for example folder_linked, nothing_new, remote_* progress, session_save, session_discard, session_ended, pull_test) and refusal codes, and session_complete there carries the save's next. They are in agent-contract.md §3 and §6; this page covers the local store.

kane-cli context extract --mode agent, kane-cli context ingest … --mode agent, and kane-cli design tests --mode agent speak a versioned NDJSON vocabulary on stdout — one JSON object per line, envelope {"type": "<name>", "v": 1, "verb": "extract"|"design", ...}. On 0.7.2+ the stream is strict: stdout carries only NDJSON and stderr stays silent (crash traces excepted); on 0.7.1, prose diagnostics could ride stderr. maintain reconcile --mode agent (verb reconcile) and cover/cover gaps --mode agent (verbs cover/gaps) share the envelope with their own event sets (below).

The vocabulary is open: new event types and fields may appear in any release — tolerate unknowns, never fail on them.

Prefix handling: on 0.7.2+ there is NO stdout impurity — nothing precedes the stream (the landing receipts ARE the ingested events) and every line parses as JSON. On 0.7.1, a merged context ingest … --mode agent run prints its landing receipts — a few prose lines per file — BEFORE the NDJSON begins. Skip non-JSON prefix lines and start parsing at the first line that begins with { — correct on both releases, a harmless no-op on 0.7.2+.

Terminal detection — the done guarantee

Except for kane-cli context review --mode agent (below), every --mode agent invocation ends its stream with exactly one {"type":"done","status":…,"exit_code":…} — including refusals. Build all post-run logic on it, exactly like run_end for browser runs:

for each line:
  if obj.type === "done"           → terminal: status ∈ complete|paused|error|refused|interrupted|aborted; stop
  else if obj.type === "session_paused" → capture sid + resume + pending_questions (the pause deliverable)
  else                             → per-type handling below

A stream that ends without done means the process crashed — outcome unknown; inspect context sessions --json and context list before retrying anything paid. No stream at all, with one line on stderr and exit 2, is a command-line refusal before anything ran (for example --json with --mode agent): fix the command, don't treat it as a crash. One designed exception: kane-cli context review --mode agent keeps its --json shape — verdict and drift listings are one JSON object per line with no done (an empty listing prints nothing, exit 0); its early refusals — no store, an open rebase, a verdict queue that needs a terminal (TTY_REQUIRED) — are typed events followed by done; its later refusals exit without done. Read its exit code instead. One version-scoped rule for merged-ingest landing failures (bad path, unsupported media, refused URL, a misused --mode or --as): on 0.7.2+ they ride the stream as error (codes MODE_USAGE, AS_SINGLE_SOURCE, UNSUPPORTED_URL, INGEST_FAILED) + done — the guarantee covers the whole invocation; on 0.7.1 they end with prose + exit 1/2 before any NDJSON begins — no stream at all is a refusal to fix, not a crash, and the guarantee starts with the extraction stream.

Events (extract / design)

next[] on pauses, refusals, and done lists ready-to-run follow-up commands. Usual shape: objects {cmd, why, title}; a few refusal sites emit plain strings — handle both. Offer them to the user; never auto-run a mutating next command.

session_paused — the shapes the pause loop parses

The full pause (questions pending):

{"type":"session_paused","v":1,"verb":"extract","sid":"ext-…",
 "resume":"kane-cli context extract --resume ext-… --mode agent",
 "expires_at":"…",
 "pending_questions":[{
   "id":"q1","text":"…the question…","risk":"high",
   "rationale":"…why it matters, with the conflicting evidence…",
   "options":[{"label":"…","detail":"…"},{"label":"…","detail":"…","input":true}],
   "recommended_index":0,"allow_free_text":true}]}

Two sibling shapes (0.7.1+), distinguished by their fields — branch on presence:

• crashed: true and no pending_questions — a crash-paused session; the resume command re-enters the conversation, nothing to answer up front.
• held (a count) — only sid, resume, and held are present (no expires_at); the session holds items awaiting the user's review; resume presents them.

Use text + options[].label + recommended_index + rationale to decide or to present the question. An option carrying input: true (0.7.1+) needs a typed value with the pick — answer it via --answer <id>="<value>" or plain-words --message. The resume field is the exact command to run — append --message "<plain words>", --answer <id>=<v> pairs, or --with-source <ref>.

Reconcile events (verb reconcile)

(0.7.2+) the stream opens with a minimal run_start (session only — no trace) and the re-extract child rides the SAME stream: extract-vocabulary events (source_start, agent_activity, plan, commit, …) interleave between the reconcile_* events, all stamped verb: "reconcile" — dispatch on type, never on position. The reconcile family: reconcile_plan {source_id, plan_path, rows[], archive[]} → per row reconcile_row_start {kind, ref, stale?, direct?} + reconcile_row_end {kind, ref, outcome: applied|failed|skipped|plan-only|paused, exit_code?, detail?} → reconcile_paused {plan_path, pending[]} when ARCHIVE rows remain (exit 3; a human resumes with --apply <plan_path> in a terminal) → reconcile_summary {applied, skipped, deferred, plan_only, failed, paused, stale_created} on every path → done always last. Validation refusals ride the stream as error + done (exit 2), never stderr alone.

Evolve events (verb evolve) (0.8.21+)

kane-cli maintain evolve <ref> --mode agent (or --from-stale, never both) shares the envelope with verb: "evolve".

• Answering. --answer evolve:<use-case>=1 (or =proceed) and --answer evolve:<use-case>=2 (or =decline), repeatable, with --mode agent. A refused answer is error + done with nothing before it.
• Refusals. An explicit target that is fresh and has no --because, that was never designed, or that is out of date only because its source changed (evolve_skipped source_changed; --because lets it run), exits 2. A --from-stale run with nothing stale exits 0, and one whose every stale use-case is source-changed sends those evolve_skipped events and exits 0.
• Batches. Every use-case runs whatever the earlier ones did. The exit is the first design-run code that is neither 0 nor 3; otherwise 3 if any paused; otherwise 0.

Sync events (verb sync) (0.8.14+)

kane-cli context sync, kane-cli context push, kane-cli context pull and kane-cli context clone under --mode agent (and kane-cli context sync add, kane-cli context sync list, kane-cli context sync remove, kane-cli context sync status, kane-cli context sync doctor) share the envelope with verb: "sync" and their own sync_* family — sync_probe_started/sync_probe, sync_status, sync_pull_done/sync_push_done, sync_rebase_started/sync_rebase_decision/sync_rebase_done/sync_rebase_open, sync_error{code, detail, remedy} — then done. Two of them cross into the assurance streams: sync_behind (an advisory on extract/design/reconcile streams: the location has records this store has not pulled — one line, not a failure) and sync_error code SYNC_REBASE_PENDING (the fence: a sync rebase is open, so the write verb refused; verb carries that verb's own name). Schema, refusal codes and the --answer loop: references/context-sync.md.

Coverage events (verbs cover / gaps) (0.7.1+)

One payload event carrying the full --json document — coverage for cover, gaps for cover gaps; with a <uc-id> (0.8.2+) the gaps document closes over that use-case — then done (with the worklist's ready-commands in next[]). Refusal = error + done{refused, 2}.

Exit codes (these commands only)

Reminder: this exit-3 meaning is specific to these assurance commands. run / testmd / testrun keep their own meanings (3 = timeout/cancelled).