@gmickel/gno 1.43.0 → 1.45.0

package/assets/skill/SKILL.md

@@ -62,6 +62,9 @@ the matching recipe, then run the commands it names.
 | Summarize a source                  | `recipes/source-summary.md`          | Source-summary note with provenance verified  |
 | Preserve an idea                    | `recipes/idea-capture.md`            | Original phrasing captured and findable       |
 | Verify claims and citations         | `recipes/citation-and-provenance.md` | Claims labeled with evidence or explicit gaps |
+| File a fact that may change         | `recipes/memory-file-decision.md`    | Fact stored (add) or proposal resolved, cited |
+| Replace a stale recalled fact       | `recipes/memory-supersede-fact.md`   | Successor written, predecessor superseded     |
+| What do we know/believe about X     | `recipes/memory-scoped-recall.md`    | Current facts recalled under budget, cited    |
 
 Recipe rules:
 

package/assets/skill/recipes/memory-file-decision.md

@@ -0,0 +1,76 @@
+# Memory: File A Decision
+
+Use this recipe when a conversation settles one fact that may later change (a
+decision, a preference, a standing rule) and the agent should be able to
+recall it next session. Documents and long notes go through
+`recipes/capture-and-file.md`; this recipe stores one fact.
+
+## Inputs
+
+- The fact, in one or two sentences, as it should be recalled later.
+- One to eight explicit scopes (`project:gno`, `family`, `client/acme`).
+  There is no implicit global scope; every call names its scopes.
+- Source evidence when known (a meeting, a message, a URL — never a `gno://`
+  URI, which the fence rejects as GNO-derived).
+- The memory-managed collection when more than one is configured.
+
+## Workflow
+
+1. Recall first so a fact that already exists is not filed twice.
+
+```bash
+gno recall "<the topic>" --scope <scope> --json > /tmp/recall.json
+```
+
+2. Propose the fact. Without a decision `remember` writes nothing and returns
+   `outcome: "candidates"` with likely and weak matches from the same scopes.
+
+```bash
+gno remember "<fact>" --scope <scope> --json
+```
+
+3. Decide from the candidates. GNO never adjudicates a likely match; the
+   caller does.
+   - No match, or the match is a different fact: add.
+   - A match says the same thing: stop; `outcome: "existing"` means nothing
+     is written and the record is already current.
+   - A match is the same fact with stale content: switch to
+     `recipes/memory-supersede-fact.md`.
+
+```bash
+gno remember "<fact>" --scope <scope> --add \
+  --source "<where this came from>" --receipt /tmp/recall.json --json
+```
+
+4. Read the result. `outcome: "added"` plus `sync.status: "completed"` means
+   the fact file exists and is retrievable now; a `failed` sync means the
+   file exists and the index lags (`gno update <collection>`).
+
+5. Verify by recalling it back and cite the returned `uri`.
+
+```bash
+gno recall "<distinctive phrase>" --scope <scope>
+```
+
+## Guardrails
+
+- Store what the user said or decided, not GNO's own recall output. Pass the
+  recall receipt (`--receipt`) so a recalled span cannot be re-filed as new;
+  a paraphrase without lineage cannot be fenced, so do not paraphrase
+  recalled facts into new ones.
+- Never store a fact without an explicit `--add`; a question alone is
+  read-only, and `remember` without a decision is a proposal.
+- Scopes are visibility, not access control. Pick the scope the fact belongs
+  to; use a shared scope name only when several callers agree on it.
+- `remember` works only on a collection with `memoryManaged: true`; other
+  collections fail with `MEMORY_COLLECTION_UNMANAGED`. Do not fall back to
+  `gno capture` for a fact that may change.
+- Keep the text self-contained; recall returns the fact without the
+  conversation that produced it.
+
+## Done
+
+- `outcome: "added"` with a `gno://` URI, or `existing` with the current
+  record.
+- Recall in the same scope returns the fact.
+- The user's wording, scopes, and source are preserved.

package/assets/skill/recipes/memory-scoped-recall.md

@@ -0,0 +1,66 @@
+# Memory: Scoped Recall
+
+Use this recipe for "what do we know / what did we decide / what does the
+user believe about X" questions, before document search and before answering
+from general knowledge. Recall returns only current facts, under a budget,
+with `gno://` cites.
+
+## Inputs
+
+- The question, as a short query.
+- The scopes the answer may draw from (`project:gno`, `family`,
+  `client/acme`). Every call names its scopes; there is no implicit global
+  scope.
+- Budget when the default (8 facts, 512 tokens) is too much or too little.
+- The memory-managed collection when more than one is configured.
+
+## Workflow
+
+1. Recall in the narrowest scope that should hold the answer.
+
+```bash
+gno recall "<question>" --scope <scope> --json
+gno recall "<question>" --scope <scope-a> --scope <scope-b> --max-facts 3 --max-tokens 256 --json
+```
+
+Visibility is any-intersection: a fact is returned when at least one of
+the call's scopes appears on it. Widen by adding scopes, not by dropping
+the flag.
+
+2. Read the response.
+   - `facts[]`: `uri`, `text`, `scopes`, `contentHash`, `supersedes`, `score`.
+     Superseded records never appear.
+   - `budget.omitted` > 0: facts matched but did not fit. Narrow the query
+     or raise the budget.
+   - Empty `facts` plus a `hint`: nothing is stored in scope yet. Say so;
+     the hint names `gno remember` for when the user wants to store one.
+   - `retrieval.mode: "lexical"`: the collection has no cached embeddings, so
+     the query matched every term. Rephrase to the fact's own words, or embed
+     the collection (`gno embed <collection>`) for question-shaped queries.
+
+3. Answer from the facts and cite each by its `gno://` URI. When memory is
+   silent or stale, fall through to `gno search` / `gno query` on the
+   documents; memory answers "what we believe", documents answer "what the
+   sources say".
+
+4. Keep the JSON if a write may follow. Its `receipt` is what `gno remember
+--receipt` fences against, and its `contentHash` is what a supersede
+   requires (`recipes/memory-supersede-fact.md`).
+
+## Guardrails
+
+- Recalled spans are context, not new facts. Never feed recall output back
+  into `gno remember`; the fence catches exact replays with a receipt, not
+  paraphrases.
+- Do not widen to every scope by habit. Scopes partition visibility; a recall
+  scoped to `project:other` should not surface family facts.
+- `recall` reads memory-managed collections only; ordinary notes are not
+  facts. Use the document ladder for them.
+- Respect the response's `egressLineage`; derived output inherits the
+  strictest policy across the returned facts.
+
+## Done
+
+- Facts cited by `gno://` URI, or an explicit "nothing stored in scope".
+- Omitted facts acknowledged when `budget.omitted` is non-zero.
+- Recall JSON kept when a remember or supersede follows.

package/assets/skill/recipes/memory-supersede-fact.md

@@ -0,0 +1,68 @@
+# Memory: Supersede A Stale Fact
+
+Use this recipe when a recalled fact is no longer true and a newer statement
+replaces it. Facts are replaced, never edited in place and never deleted by
+the memory contract.
+
+## Inputs
+
+- The stale fact's `uri` and `contentHash`, taken from a recall.
+- The replacement text.
+- The same scopes the stale fact is visible in.
+- Source evidence for the change when known.
+
+## Workflow
+
+1. Recall the current fact and keep the JSON; it carries the predecessor's
+   `uri`, `contentHash`, and the receipt.
+
+```bash
+gno recall "<the topic>" --scope <scope> --json > /tmp/recall.json
+```
+
+2. Confirm the match is the same fact with stale content, not a different
+   fact. Two facts that both hold get an add, not a supersede.
+
+3. Supersede, naming the predecessor and its hash.
+
+```bash
+gno remember "<replacement text>" --scope <scope> \
+  --supersede <uri> --predecessor-hash <contentHash> \
+  --source "<what changed and where that is recorded>" \
+  --receipt /tmp/recall.json --json
+```
+
+The scriptable spelling `--decision supersede --predecessor <uri>` means
+the same thing.
+
+4. Read the result. `outcome: "superseded"` returns the successor record with
+   `supersedes: [<uri>]`.
+   - `MEMORY_PREDECESSOR_HASH_MISMATCH`: the fact changed since the recall.
+     Recall again and decide against the current text.
+   - `MEMORY_SUPERSEDE_CONFLICT` (exit 4): another writer superseded it
+     first. Recall again; the successor may already say what you meant.
+
+5. Verify: recall returns the successor and not the predecessor.
+
+```bash
+gno recall "<distinctive phrase>" --scope <scope>
+```
+
+## Guardrails
+
+- Never supersede without the `contentHash` from a recall; the hash is what
+  proves the replacement targets the fact the agent actually read.
+- The replacement must be a new statement. Re-storing the recalled text is
+  fenced (`MEMORY_FENCED_REPLAY`) when the receipt is presented; a
+  paraphrase without lineage is not, so do not rephrase the old fact as a
+  "new" one.
+- Superseded facts stay on disk and in ordinary `gno search`; only `recall`
+  excludes them. To remove a file, the user deletes it and runs
+  `gno update`; the contract has no delete.
+- Do not chain supersedes speculatively; one recalled fact, one decision.
+
+## Done
+
+- `outcome: "superseded"` with a successor URI carrying `supersedes`.
+- Recall in scope returns the successor only.
+- A conflict or hash mismatch ended in a fresh recall, not a retry loop.

package/browser-extension/artifacts/gno-browser-clipper-v1.45.0.zip.sha256

@@ -0,0 +1 @@
+ea5867ff2927a15524f4d5167c7ee9ee8a530b3604fefad886ec0327af7185d8  gno-browser-clipper-v1.45.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.43.0"
+  "version": "1.45.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.43.0",
+  "version": "1.45.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -1025,24 +1025,51 @@ gno index [collection] [--no-embed] [--models-pull] [--git-pull] [--json] [--yes
 
 **Behavior:**
 
-- Runs `update` then `embed` by default
-- With `--no-embed`, runs `update` only
+- Runs two separable stages: `lexical` (`update`) then `embed`
+- With `--no-embed`, runs the `lexical` stage only (embed stage `skipped`)
 - Waits by default for the shared write lease; `--no-wait` fails immediately with exit 4
 
-**JSON output:** Emits `{ syncResult, embedSkipped, embedResult? }`.
+**Staged, resumable contract:** each stage persists its own progress inside
+the index database (documents and chunks for `lexical`; vectors per batch for
+`embed`) plus a per-stage lifecycle marker (`schema_meta.index_stage_state`).
+A stage that fails never invalidates a completed earlier stage: the lexical
+index stays searchable when embedding fails or the process dies. A process
+killed mid-stage (SIGKILL, native crash, power loss) emits nothing; the next
+`gno index` or `gno embed` run reads the marker, reports the interrupted stage
+in its resume preamble (stderr in human mode, `resumedFrom` in JSON), and
+continues from persisted progress - unchanged files are skipped and already
+stored chunks are never re-embedded. A `gno index --no-embed` run that
+surfaces an interrupted embed stage settles that marker (the embed progress
+itself stays on disk), so later runs do not repeat the preamble.
+
+**JSON output:** conforms to
+[`index-receipt@1.0`](./output-schemas/index-receipt.schema.json):
+`{ success, error?, stages: { lexical, embed }, resumedFrom, syncResult?, embedSkipped, embedResult? }`.
+Each stage reports `state` (`completed` | `failed` | `skipped` |
+`interrupted`) with counts (`filesProcessed`/`filesAdded`/`filesUpdated`/
+`filesErrored`/`filesSkipped`/`durationMs` for lexical;
+`embedded`/`errors`/`contentionErrors`/`durationMs` for embed), a `reason`
+when skipped, and an `error` when failed. The embed stage is `completed` only
+when every attempted chunk was stored: any `errors > 0` or a vector-sync error
+makes it `failed`. `resumedFrom` is `null` on a clean start or
+`{ stage, state: "interrupted", startedAt, pid, collection? }`.
 `syncResult.collections[].files[].recordImport`, when present, conforms to
 [`record-import@1.0`](./output-schemas/record-import.schema.json) with the same
 deterministic ordering, bounds, truncation disclosure, and partial-snapshot
 warnings as `gno update --json`. Human progress and diagnostics remain on
-stderr. On lease timeout, stdout is one object `{ success: false, error, contention }`
-and the process exits 4.
+stderr. A failed stage still emits the partial receipt on stdout (with
+`success: false` and `error`) before the non-zero exit. On lease timeout,
+stdout is one object `{ success: false, error, contention }` and the process
+exits 4.
 
 **Exit Codes:**
 
-- 0: Success
+- 0: Every attempted stage completed
 - 1: Invalid collection name or invalid `--lock-wait`
-- 2: DB or model failure
-- 4: Write lease busy (contention, not corruption)
+- 2: DB or model failure, or any stage `failed` (including chunk-level embed
+  failures; the partial receipt is still emitted)
+- 4: Write lease busy (contention, not corruption), or chunks deferred by
+  index contention after an otherwise completed embed stage
 
 **Examples:**
 
@@ -2372,11 +2399,21 @@ gno doctor [--json|--md]
           }
         ]
       }
+    },
+    {
+      "name": "findings-pass",
+      "status": "ok",
+      "message": "disabled (opt-in via findings.enabled)"
     }
   ]
 }
 ```
 
+The `findings-pass` check reports the daemon's scheduled findings pass from
+its persisted run state: `ok` when disabled or the last run succeeded, `warn`
+on `skipped_lease` / `overdue` / no recorded run, `error` on `failed` or a
+misconfigured `findings` block (see [Daemon Mode](../docs/DAEMON.md#scheduled-findings-pass)).
+
 The `embedding-fingerprint` check is additive doctor-only diagnostics. It uses
 the active embed model and stored vector dimensions to report the current
 freshness fingerprint, pending/stale chunks, legacy empty-fingerprint vectors,
@@ -3595,6 +3632,7 @@ List retained, metadata-only document lifecycle changes.
 
 ```bash
 gno changes [--since <ISO-8601|cursor>] [--collection <name>] [--limit <n>] [--json]
+gno changes --follow --jsonl [--cursor <cursor>] [--collection <name>]
 ```
 
 - `--since` accepts an ISO-8601 time or an opaque cursor returned by an earlier
@@ -3605,6 +3643,42 @@ gno changes [--since <ISO-8601|cursor>] [--collection <name>] [--limit <n>] [--j
   cursor-expiry, and retention-truncation disclosure.
 - The journal never returns source bodies.
 
+**Follow mode (`--follow --jsonl`)** streams journal events as they land and is
+the durable automation input for consumers that resume across restarts.
+
+- `--follow` and `--jsonl` are one mode and must be given together; `--cursor`
+  requires both. The mode excludes `--since`, `--limit`, and `--json` (exit 1).
+  `--collection` filters the stream.
+- Wire contract: one JSON object per stdout line, validated by
+  `changes-follow-event.schema.json`. An event line is
+  `{"event": <change>, "postCursor": "<cursor>"}` where `event` is one
+  `changes.schema.json` change and `postCursor` is the journal cursor after
+  that event was applied. Lines are emitted in journal order.
+- Checkpoint rule: a consumer persists `postCursor` after it has durably
+  handled the line and restarts with `--cursor <postCursor>`; nothing at or
+  before that cursor is replayed. Delivery is at-least-once: a line the
+  consumer received but did not checkpoint is redelivered on resume, so
+  handlers must be idempotent by `event.id` (each event id is unique and
+  equals its own `postCursor`).
+- Start position: without `--cursor` the stream starts at the journal's
+  current `latestCursor` (tail semantics, no backfill). `--cursor` must be an
+  opaque cursor from an earlier response (exit 1 when malformed or ahead of
+  the journal).
+- Quiet periods emit nothing. There is no keepalive line in v1; consumers
+  detect liveness from the process, not the stream.
+- Cursor expiry: when the resume cursor falls below the retention floor the
+  stream writes exactly one terminal line,
+  `{"error": "cursor_expired", "earliestCursor": "<cursor>", "latestCursor": "<cursor>"}`,
+  then exits 2 with nothing on stderr. `earliestCursor` is the journal's
+  documented resume floor (`gno changes --json` reports the same value);
+  `latestCursor` is the current tail. The consumer chooses whether to backfill
+  from `earliestCursor` or resume from `latestCursor` and accept the gap;
+  resuming from `latestCursor` skips every retained event.
+- Signals: SIGINT or SIGTERM ends the stream after the line in progress and
+  exits 0. No partial line is ever written.
+- The reader never takes the write lease; `gno index`, `gno update`, capture,
+  and the daemon are never blocked by a follower.
+
 ### gno diff
 
 Show the latest retained structural delta for one document, or select an exact
@@ -3851,6 +3925,13 @@ is blocked.
   watcher behavior.
 - Runs an initial sync by default
 - Triggers embedding after initial sync completes
+- With `findings.enabled`, runs the scheduled findings pass on its cadence:
+  a read-only audit of every collection except the findings one, written as
+  deterministic Markdown records into `findings.collection`. The audit runs
+  without the write lease; only the record write takes it (no wait; a busy
+  lease is recorded as `skipped_lease`). Every attempt persists to
+  `{data}/index-<name>.findings-run.json`, surfaced by `--status` (`findings`)
+  and the `findings-pass` doctor check. See [Daemon Mode](../docs/DAEMON.md#scheduled-findings-pass)
 - Runs in the foreground until `SIGINT` / `SIGTERM`
 - Starts a headless `/mcp` Streamable HTTP listener; it does not serve the Web UI
 - Exposes the same safe REST lifecycle snapshot at `/api/resident/status`;

package/spec/mcp.md

@@ -1537,6 +1537,17 @@ Create a new document in a collection (write-enabled).
 - For non-Markdown files, tags are stored as user-source in the database
 - Receipts distinguish write result from sync and embedding state; capture does
   not imply embedding unless `embed.status` is `completed`
+- Success is retrievability: the write and its lexical sync complete under the
+  shared write lease before the tool returns, so a successful result always
+  carries `sync.status: "completed"` and the note is an immediate `gno_search`
+  hit. A written file whose sync fails is a tool error `CAPTURE_SYNC_FAILED`
+  (message names the written path; run `gno update` to retry), never a success
+  with `sync.status: "failed"`
+- `open_existing` on a file that is on disk but not indexed yet syncs it before
+  returning `collisionPolicyResult: "opened_existing"`
+- The lease wait follows the v1.38 contention contract: the tool waits up to
+  120s for a concurrent CLI/MCP/REST writer, then returns `LOCKED` without
+  writing
 - Writes run under the MCP write lock and are only registered when the server
   starts with `--enable-write` or `GNO_MCP_ENABLE_WRITE=1`
 
@@ -2742,6 +2753,7 @@ Resource errors use standard MCP error responses.
 - `PATH_NOT_FOUND` — Path does not exist
 - `JOB_CONFLICT` — Another job is already running
 - `LOCKED` — Another MCP process holds the write lock
+- `CAPTURE_SYNC_FAILED` — `gno_capture` wrote the file but lexical sync failed
 - `WRITE_DISABLED` — Write tool dispatched while writes are disabled
 - `MEMORY_*` — Memory contract errors from `gno_recall` / `gno_remember`;
   the stable code set is `MemoryErrorCode` in `src/core/memory.ts` and each

package/spec/output-schemas/changes-follow-event.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/changes-follow-event@1.0",
+  "title": "GNO Knowledge Changes Follow Line",
+  "description": "One stdout line of `gno changes --follow --jsonl`: either a journal event with the cursor after it was applied, or the single terminal cursor-expiry record.",
+  "oneOf": [
+    { "$ref": "#/definitions/eventLine" },
+    { "$ref": "#/definitions/expiredLine" }
+  ],
+  "definitions": {
+    "eventLine": {
+      "type": "object",
+      "required": ["event", "postCursor"],
+      "properties": {
+        "event": { "$ref": "gno://schemas/changes@1.0#/definitions/change" },
+        "postCursor": { "type": "string", "minLength": 1, "maxLength": 512 }
+      },
+      "additionalProperties": false
+    },
+    "expiredLine": {
+      "type": "object",
+      "required": ["error", "earliestCursor", "latestCursor"],
+      "properties": {
+        "error": { "type": "string", "const": "cursor_expired" },
+        "earliestCursor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "latestCursor": { "type": "string", "minLength": 1, "maxLength": 512 }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/spec/output-schemas/index-receipt.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/index-receipt@1.0",
+  "title": "GNO Index Receipt",
+  "description": "Per-stage receipt emitted by `gno index --json`. The lexical (sync) and embed stages are separable and resumable; the run succeeds only when every attempted stage completed. A run interrupted by a killed process emits nothing - the next run reports the interrupted stage under `resumedFrom`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["success", "stages", "resumedFrom", "embedSkipped"],
+  "properties": {
+    "success": {
+      "type": "boolean",
+      "description": "True only when every attempted stage completed."
+    },
+    "error": {
+      "type": "string",
+      "description": "Present when success is false: the failed stage's error."
+    },
+    "stages": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lexical", "embed"],
+      "properties": {
+        "lexical": { "$ref": "#/definitions/lexicalStage" },
+        "embed": { "$ref": "#/definitions/embedStage" }
+      }
+    },
+    "resumedFrom": {
+      "oneOf": [
+        { "$ref": "#/definitions/interruptedStage" },
+        { "type": "null" }
+      ],
+      "description": "Stage a previous run left running (process died mid-stage); null when this run started clean."
+    },
+    "syncResult": {
+      "type": "object",
+      "description": "Complete deterministic sync result (same shape as `gno update --json`); absent when the lexical stage failed before producing one."
+    },
+    "embedSkipped": {
+      "type": "boolean",
+      "description": "True when `--no-embed` was passed."
+    },
+    "embedResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["embedded", "errors", "contentionErrors", "duration"],
+      "description": "Embedding outcome when the embed stage ran to a result (present for completed and for partially failed passes; absent when the stage failed before embedding).",
+      "properties": {
+        "embedded": { "type": "integer", "minimum": 0 },
+        "errors": { "type": "integer", "minimum": 0 },
+        "contentionErrors": { "type": "integer", "minimum": 0 },
+        "duration": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Seconds."
+        }
+      }
+    }
+  },
+  "definitions": {
+    "stageState": {
+      "type": "string",
+      "enum": ["completed", "failed", "skipped", "interrupted"]
+    },
+    "lexicalStage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "state",
+        "filesProcessed",
+        "filesAdded",
+        "filesUpdated",
+        "filesErrored",
+        "filesSkipped",
+        "durationMs"
+      ],
+      "properties": {
+        "state": { "$ref": "#/definitions/stageState" },
+        "filesProcessed": { "type": "integer", "minimum": 0 },
+        "filesAdded": { "type": "integer", "minimum": 0 },
+        "filesUpdated": { "type": "integer", "minimum": 0 },
+        "filesErrored": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Per-file errors are counted, not fatal; the stage still completes."
+        },
+        "filesSkipped": { "type": "integer", "minimum": 0 },
+        "durationMs": { "type": "integer", "minimum": 0 },
+        "error": { "type": "string" }
+      }
+    },
+    "embedStage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "state",
+        "embedded",
+        "errors",
+        "contentionErrors",
+        "durationMs"
+      ],
+      "properties": {
+        "state": { "$ref": "#/definitions/stageState" },
+        "embedded": { "type": "integer", "minimum": 0 },
+        "errors": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Chunks that failed to embed after same-run retries; any non-zero value makes the stage `failed`."
+        },
+        "contentionErrors": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Chunks deferred by SQLITE_BUSY/LOCKED - not embedding failures."
+        },
+        "durationMs": { "type": "integer", "minimum": 0 },
+        "reason": {
+          "type": "string",
+          "description": "Why the stage was skipped (`--no-embed`, `lexical stage failed`)."
+        },
+        "error": { "type": "string" }
+      }
+    },
+    "interruptedStage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stage", "state", "startedAt", "pid"],
+      "properties": {
+        "stage": { "type": "string", "enum": ["lexical", "embed"] },
+        "state": { "const": "interrupted" },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "pid": { "type": "integer", "minimum": 1 },
+        "collection": { "type": "string" }
+      }
+    }
+  }
+}