@gmickel/gno 2.5.1 → 2.7.0

package/spec/cli.md

@@ -9,13 +9,14 @@ This document specifies the command-line interface for GNO, a local knowledge in
 
 ### Exit Codes
 
-| Code | Name        | Description                                                                                |
-| ---- | ----------- | ------------------------------------------------------------------------------------------ |
-| 0    | SUCCESS     | Command completed successfully                                                             |
-| 1    | VALIDATION  | Validation or usage error (bad args, missing required params)                              |
-| 2    | RUNTIME     | Runtime failure (IO, DB, conversion, model, network)                                       |
-| 3    | NOT_RUNNING | `--status`/`--stop` found no live matching process                                         |
-| 4    | BUSY        | Write-lease contention on `index` / `update` / `embed`; a lost `remember --supersede` race |
+| Code | Name          | Description                                                                                                                                                                                                                                                                         |
+| ---- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | SUCCESS       | Command completed successfully                                                                                                                                                                                                                                                      |
+| 1    | VALIDATION    | Validation or usage error (bad args, missing required params)                                                                                                                                                                                                                       |
+| 2    | RUNTIME       | Runtime failure (IO, DB, conversion, model, network)                                                                                                                                                                                                                                |
+| 3    | NOT_RUNNING   | `--status`/`--stop` found no live matching process; `CONTEXT_STALE`: a saved Context Capsule is stale                                                                                                                                                                               |
+| 4    | BUSY          | Write-lease contention on `index` / `update` / `embed`; a lost `remember --supersede` race; a concurrent `sessions import`; a request ID still in progress (`REQUEST_PENDING`); `AUDIT_FINDINGS`: `gno audit` found findings; `CONTEXT_CONFLICT`: a saved Context Capsule conflicts |
+| 5    | AUDIT_PARTIAL | `gno audit` evidence is partial                                                                                                                                                                                                                                                     |
 
 ### Global Flags
 
@@ -85,7 +86,9 @@ equivalent files fail closed as ambiguous.
 | ask                | yes    | no      | no    | yes  | no    | terminal |
 | capture            | yes    | no      | no    | no   | no    | terminal |
 | remember           | yes    | no      | no    | no   | no    | terminal |
+| request-status     | yes    | no      | no    | no   | no    | terminal |
 | recall             | yes    | no      | no    | no   | no    | terminal |
+| sessions           | yes    | no      | no    | no   | no    | terminal |
 | get                | yes    | no      | no    | yes  | no    | terminal |
 | multi-get          | yes    | yes     | no    | yes  | no    | terminal |
 | ls                 | yes    | yes     | no    | yes  | no    | terminal |
@@ -224,9 +227,20 @@ setup and emits `setup-profile-result@1.0`.
 
 Display index status and health information.
 
-Embedding backlog follows the last verified partition for the selected model
-when exact-input storage is authoritative, counting pending document/chunk
-owners. Per-collection chunk totals remain deduplicated by canonical chunk;
+Embedding backlog follows the partition this runtime's retrieval reads (the
+caller's recorded identity under the shared selection rule; before any query or
+embed has resolved it, the activated runtime-independent partition) when
+exact-input storage is authoritative, counting pending document/chunk owners.
+`vectorRuntime` reports `{label, state: vectors|unavailable|unresolved,
+partition, reason?}` for the calling process.
+`vectorPartitions` (omitted when no partition exists) lists every partition of
+the model with `id`, `model`, `dimensions`, `state` (`active`|`shadow`),
+`legacy` (pre-runtime-independent key), `retrieval` (this runtime reads it),
+`droppable` (`gno vec drop` accepts it), `owners` (current chunks),
+`provenance` (building runtime, e.g. `CUDA, Bun 1.4.2`),
+`compatibleRuntimes` (runtimes that read it) and `incompatibleRuntimes`.
+Terminal output prints a `Vector partitions:` block
+unless there is exactly one healthy partition. Per-collection chunk totals remain deduplicated by canonical chunk;
 embedded counts require matching current inputs for every active owner within
 that collection. Status reads persisted identity and coverage without loading
 models. Legacy storage remains the fallback before variant authority; ambiguous
@@ -257,6 +271,21 @@ gno status [--json|--md]
   "totalDocuments": 100,
   "totalChunks": 500,
   "embeddingBacklog": 0,
+  "vectorPartitions": [
+    {
+      "id": "3f2a9c1b2d4e...",
+      "model": "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf",
+      "dimensions": 1024,
+      "state": "active",
+      "legacy": false,
+      "retrieval": true,
+      "droppable": false,
+      "owners": 500,
+      "provenance": "CUDA, Bun 1.4.2",
+      "compatibleRuntimes": ["CUDA, Bun 1.4.2", "CPU, Bun 1.3.14"],
+      "incompatibleRuntimes": []
+    }
+  ],
   "lastUpdated": "2025-12-23T10:00:00Z",
   "healthy": true,
   "activation": {
@@ -326,6 +355,32 @@ truthful about its lifecycle: `mode:"direct-cli"`, `resident:false`, no
 listener, and zero resident counters. It does not imply attachment to a live
 `serve` or `daemon`.
 
+When a detached `serve` or `daemon` (found through its pid-file) has a
+background job in trouble, JSON output adds `backgroundIssues`; the key is
+absent otherwise. Each item is a resident-status `backgroundIssue` plus the
+process that reported it:
+
+```json
+"backgroundIssues": [
+  {
+    "process": "serve",
+    "pid": 41234,
+    "job": "embed",
+    "state": "parked",
+    "consecutiveFailures": 5,
+    "runningSeconds": null
+  }
+]
+```
+
+`state` is `failing` (background embed passes failing and retrying with
+backoff), `parked` (retries stopped after 5 failed passes; pending chunks wait
+for new changes or `gno embed`), `overrunning` (one pass running longer than 15
+minutes, `runningSeconds` set), or `unresponsive` (`job:"resident"`: the process
+is alive but did not answer its status request within 500ms). Each resident is
+asked once with that 500ms budget, so `gno status` never waits on a hung
+resident. Terminal output lists the same issues under `Background issues:`.
+
 Local activation fingerprints use active-document identifiers and source/mirror
 hashes plus schema, tokenizer, and owned FTS synchronization metadata. Passive
 status never selects or compares stored markdown or FTS bodies. On a receipt
@@ -1004,7 +1059,7 @@ gno update [--git-pull] [--json] [--lock-wait <duration>] [--no-wait]
 | `--lock-wait <duration>` | duration | How long to wait for the index write lease (default: `120s`). Accepts `120`, `120s`, or `2m`. |
 | `--no-wait` | boolean | Do not wait; fail immediately if another writer holds the lease |
 
-**Concurrency:** One writer at a time on the shared index database. `update` waits up to `--lock-wait` for the lease (the same `.mcp-write.lock` MCP write tools use); `index`, `embed`, `cleanup`, `vec sync`, `vec rebuild`, `collection clear-embeddings`, `tags add`, and `tags rm` follow the same contract; `capture` takes the same lock internally, and single-row writes such as `collection policy set` are absorbed by `busy_timeout`. `--no-wait` opts out. Reads (`search`, `query`, `get`) never take the lease. External serialising wrappers are no longer required for CLI-vs-CLI and CLI-vs-MCP overlap. Residual window: a resident (`gno serve`/`gno daemon`) watch or embed flush writes without the lease; those short transactions are absorbed by the raised `busy_timeout` and the SQLITE_BUSY retry, and a deferred chunk is reported as contention, never as an embedding failure.
+**Concurrency:** One writer at a time on the shared index database. `update` waits up to `--lock-wait` for the lease (the same `.mcp-write.lock` MCP write tools use); `index`, `embed`, `cleanup`, `vec sync`, `vec rebuild`, `vec drop`, `collection clear-embeddings`, `tags add`, and `tags rm` follow the same contract; `capture` takes the same lock internally, and single-row writes such as `collection policy set` are absorbed by `busy_timeout`. `--no-wait` opts out. Reads (`search`, `query`, `get`) never take the lease. External serialising wrappers are no longer required for CLI-vs-CLI and CLI-vs-MCP overlap. A resident (`gno serve`/`gno daemon`) takes the same lease without waiting around each watcher sync, embed preparation, background-embedding page write (never around inference), and the final vector activation; when the lease is held it defers that work (watcher retry after 5s, embed pass rescheduled) instead of writing, so resident background writes never hold a SQLite write lock outside the lease. The resident's own SQLite busy wait is capped at 500ms so a stop signal is always handled within the stop grace.
 
 **Behavior:**
 
@@ -1133,9 +1188,20 @@ memory pressure prevents creating the full pool.
 **Synopsis:**
 
 ```bash
-gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--yes] [--json] [--lock-wait <duration>] [--no-wait]
+gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--yes] [--new-partition] [--json] [--lock-wait <duration>] [--no-wait]
 ```
 
+Vector partitions are keyed on model weights, formatter, dimensions, context
+size and truncation policy. Runtime details (Bun, `node-llama-cpp`, GPU/CPU
+backend, threads) are provenance. A runtime meeting a partition for the first
+time re-embeds up to 8 stored chunks; every one must reach cosine 0.99 against
+its stored vector, and the verdict is cached per (partition, runtime). A
+compatible runtime resumes the backlog in that partition. An incompatible one
+(or an ambiguous one-time re-key of pre-existing partitions) would build a
+separate partition: embed then states the full chunk count and an estimate and
+requires confirmation, interactively or with `--new-partition`. `--yes` alone
+never confirms; without confirmation embed exits 2 and writes nothing.
+
 **Options:**
 
 | Option                   | Type     | Default | Description                                                                 |
@@ -1144,7 +1210,8 @@ gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--yes] [--js
 | `--model`                | string   | config  | Override embedding model URI                                                |
 | `--batch-size`           | integer  | 32      | Chunks per batch                                                            |
 | `--dry-run`              | boolean  | false   | Show what would be embedded without doing it                                |
-| `--yes`, `-y`            | boolean  | false   | Skip confirmation prompts                                                   |
+| `--yes`, `-y`            | boolean  | false   | Skip confirmation prompts (never confirms a separate vector partition)      |
+| `--new-partition`        | boolean  | false   | Confirm building a separate vector partition for an incompatible runtime    |
 | `--json`                 | boolean  | false   | Output result as JSON                                                       |
 | `--lock-wait <duration>` | duration | `120s`  | How long to wait for the index write lease. Accepts `120`, `120s`, or `2m`. |
 | `--no-wait`              | boolean  | false   | Do not wait; fail immediately if another writer holds the lease             |
@@ -1314,7 +1381,9 @@ by default when the collection root and `source.relPath` can be joined; search
 has no `--source` flag. When `absPath` is absent (unresolvable collection path,
 missing relPath, or a hit without a filesystem file), consumers display the URI
 tail and must disable file-open for that row — do not call `gno get` just to
-recover a path.
+recover a path. The CLI always runs on the owner's machine; the same result shape over
+remote REST or HTTP MCP omits `absPath` (see
+[docs/API.md](../docs/API.md#host-paths-and-remote-callers)).
 
 Every structured search result may include `context`, the matching
 user-configured guidance joined in deterministic global, collection, then
@@ -1628,7 +1697,7 @@ Capture a note into an editable collection with structured provenance.
 **Synopsis:**
 
 ```bash
-gno capture [content...] [--stdin|--file <path>] [--collection <name>] [--title <title>] [--path <relPath>] [--folder <relPath>] [--preset <id>] [--tags <tags>] [--collision-policy <policy>] [--source-kind <kind>] [--source-url <url>] [--source-title <title>] [--source-author <author>] [--source-date <date>] [--source-id <id>] [--json]
+gno capture [content...] [--stdin|--file <path>] [--collection <name>] [--title <title>] [--path <relPath>] [--folder <relPath>] [--preset <id>] [--tags <tags>] [--collision-policy <policy>] [--source-kind <kind>] [--source-url <url>] [--source-title <title>] [--source-author <author>] [--source-date <date>] [--source-id <id>] [--request-id <id>] [--json]
 ```
 
 **Content Sources:**
@@ -1684,8 +1753,33 @@ gno capture "thought to remember"
 gno capture --stdin --collection notes --preset source-summary --tags inbox,gno
 gno capture --file ./clip.md --source-url https://example.com --source-kind web --json
 gno capture "meeting note" --quiet
+gno capture "Release moves to Friday" --collection notes --request-id 0f8e5c1a-3c1e-4d0b-9a57-2f4f3b8f2c11 --json
 ```
 
+**Write and sync:**
+
+- Planning, the write, and lexical sync run under the shared write lease
+  (`.mcp-write.lock`), the same leased publication MCP `gno_capture` and REST
+  `POST /api/capture` use. A lease held past the wait window fails with the
+  busy error; nothing is written.
+- Without `--request-id`, a written file whose lexical sync fails still exits 0
+  with `sync.status: "failed"` and `sync.error` in the receipt; `gno update`
+  indexes it. `open_existing` on a file that is on disk but not indexed yet
+  returns `sync.status: "skipped"` (`Existing file is not indexed yet.`).
+
+**Request IDs:**
+
+- `--request-id <id>` (1-128 of `A-Z a-z 0-9 . _ : -`, starting with a letter
+  or digit) makes a retry of the same command safe.
+- With an ID, a written file whose lexical sync fails exits `RUNTIME` (2) and
+  the request stays pending; rerunning with the same ID finishes it.
+- With an ID, `--json` adds
+  `request: { requestId, status: "committed", replayed, committedAt }` to the
+  capture receipt; terminal output adds `Request: <id> committed`, plus
+  `(replayed, nothing written again)` on a replay.
+- Request error codes and exits: see [gno request-status](#gno-request-status).
+  Semantics: `docs/guides/retries-and-request-ids.md`.
+
 ---
 
 ### gno remember
@@ -1697,7 +1791,7 @@ write lease directly.
 **Synopsis:**
 
 ```bash
-gno remember <text> --scope <scope> [--scope <scope>...] [--collection <name>] [--decision add|supersede | --add | --supersede <uri>] [--predecessor <uri>] [--predecessor-hash <hash>] [--receipt <path>] [--derived-from <uri>...] [--source <text>] [--caller <id>] [--session <id>] [--json]
+gno remember <text> --scope <scope> [--scope <scope>...] [--collection <name>] [--decision add|supersede | --add | --supersede <uri>] [--predecessor <uri>] [--predecessor-hash <hash>] [--receipt <path>] [--derived-from <uri>...] [--source <text>] [--caller <id>] [--session <id>] [--request-id <id>] [--json]
 ```
 
 **Scope and collection (fail-closed):**
@@ -1731,6 +1825,16 @@ gno remember <text> --scope <scope> [--scope <scope>...] [--collection <name>] [
 - A write returns success only after the file exists and lexical sync
   completed; the fact is retrievable before the command exits.
 
+**Request IDs:**
+
+- `--request-id <id>` applies to writes only (`--add`, `--supersede`, or
+  `--decision`); without a decision it fails `VALIDATION`
+  (`REQUEST_ID_INVALID`). Rerunning the same write with the same ID is safe.
+- With an ID, `--json` adds
+  `request: { requestId, status: "committed", replayed, committedAt }`;
+  terminal output adds `Request: <id> committed`.
+- Semantics (replay, recovery, conflicts): `docs/guides/retries-and-request-ids.md`.
+
 **Context fencing:**
 
 - `--receipt <path>` presents a recall receipt (the `recall --json` output or
@@ -1762,7 +1866,8 @@ predecessor, and fence errors; `BUSY` (4) when another writer holds the lease
 (`MEMORY_SUPERSEDE_CONFLICT`); `RUNTIME` (2) when the file was written but
 lexical sync failed (`MEMORY_SYNC_FAILED`) or the successor's `supersedes`
 edge did not project (`MEMORY_SUPERSEDE_PROJECTION_FAILED`). The JSON envelope carries the core code in
-`details.memoryCode`.
+`details.memoryCode`. Request ID errors map as listed under
+[gno request-status](#gno-request-status) and carry `details.requestCode`.
 
 **Examples:**
 
@@ -1770,6 +1875,86 @@ edge did not project (`MEMORY_SUPERSEDE_PROJECTION_FAILED`). The JSON envelope c
 gno remember "Finn's kindergarten starts at 08:30" --scope family --add
 gno remember "Prod deploys from main only" --scope project:gno --scope ops
 gno remember "Prod deploys from release/*" --scope project:gno --supersede gno://memory/facts/2026/... --predecessor-hash <hash> --json
+gno remember "Prod deploys from main only" --scope project:gno --add --request-id 7d2e4b90-1f7a-4c2e-8f55-0b9c1d3e6a42 --json
+```
+
+---
+
+### gno request-status
+
+Look up a request ID sent with `gno capture`, `gno remember`, or a REST/Web UI
+document save before retrying the write. Read-only; takes no write lease.
+
+**Synopsis:**
+
+```bash
+gno request-status <request-id> [--json]
+```
+
+**Behavior:**
+
+- Reads the index's private request ledger in the local-owner namespace.
+  Honors the global `--index` flag.
+- Returns a content-free pointer, never note or fact text. Status meanings and
+  namespaces: `docs/guides/retries-and-request-ids.md`.
+
+**Output:**
+
+`--json` prints the [`request-status`](./output-schemas/request-status.schema.json)
+result:
+
+```json
+{
+  "requestId": "0f8e5c1a-3c1e-4d0b-9a57-2f4f3b8f2c11",
+  "status": "committed",
+  "operation": "capture",
+  "createdAt": "2026-09-24T08:00:00.000Z",
+  "updatedAt": "2026-09-24T08:00:00.120Z",
+  "result": {
+    "uri": "gno://notes/inbox/2026-09-24/capture-3f9c.md",
+    "docid": "#a1b2c3",
+    "contentHash": "<sha256>"
+  }
+}
+```
+
+- `status`: `pending` | `committed` | `expired` | `not_found`.
+- `operation`: `capture` | `remember` | `document.update`; `createdAt`,
+  `updatedAt`, and `operation` are absent for `not_found`.
+- `result` only for `committed`: `uri`, `docid`, and `contentHash` (capture,
+  remember) or `sourceHash` (document update).
+
+Terminal output prints `Request:`, `Status:`, and, when present,
+`Operation:`, `Updated:`, and `URI:` lines, then one next-step line:
+
+| Status      | Next-step line                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------------- |
+| `committed` | `Committed: do not resend; the retained outcome replays.`                                         |
+| `pending`   | `Pending: retry the same command with the same --request-id to finish it.`                        |
+| `expired`   | `Expired: this ID already ran and will not run again; check current state before using a new ID.` |
+| `not_found` | `Not found: nothing was accepted under this ID.`                                                  |
+
+**Request error codes** (every CLI surface that takes a request ID; the JSON
+error envelope carries the request code in `details.requestCode`):
+
+| Request code                 | CLI code     | Exit |
+| ---------------------------- | ------------ | ---- |
+| `REQUEST_ID_INVALID`         | `VALIDATION` | 1    |
+| `REQUEST_ID_CONFLICT`        | `VALIDATION` | 1    |
+| `REQUEST_EXPIRED`            | `VALIDATION` | 1    |
+| `REQUEST_PENDING`            | `BUSY`       | 4    |
+| `REQUEST_RECOVERY_CONFLICT`  | `RUNTIME`    | 2    |
+| `REQUEST_CAPACITY_EXHAUSTED` | `RUNTIME`    | 2    |
+| `REQUEST_LEDGER_UNAVAILABLE` | `RUNTIME`    | 2    |
+
+`gno request-status` itself exits `VALIDATION` (1) for a malformed ID and
+`RUNTIME` (2) when the ledger exists but cannot be opened.
+
+**Examples:**
+
+```bash
+gno request-status 0f8e5c1a-3c1e-4d0b-9a57-2f4f3b8f2c11
+gno request-status 0f8e5c1a-3c1e-4d0b-9a57-2f4f3b8f2c11 --json
 ```
 
 ---
@@ -1823,6 +2008,206 @@ gno recall "kindergarten" --scope family --max-facts 3 --json > receipt.json
 
 ---
 
+### gno sessions
+
+Discover and manually import local agent sessions (Codex, Claude Code,
+OpenClaw, Hermes) into a dedicated session archive. Thin adapters over the
+core sessions service (`src/sessions/service.ts`). A fresh installation
+imports, watches, hooks and schedules nothing; every import is an explicit
+invocation.
+
+**Archive pair (binding):**
+
+- A session archive is one dedicated config file (carrying a `sessions`
+  block) paired with one named index. Every archive command passes both
+  explicitly: `gno --config <archive.yml> --index <name> sessions ...`.
+- `sessions init` refuses the default config file and the `default` index.
+- Before every command (all of `gno`, not only `sessions`), a config whose
+  `sessions.index` differs from `--index` exits `VALIDATION`
+  (`SESSIONS_BINDING_MISMATCH`), and an index recorded as an archive exits
+  `VALIDATION` when opened with any other config (including cross-index
+  `get`). Plain `gno update` on the default config therefore never reads the
+  archive.
+- The archive root must lie outside GNO's config/data/cache directories so
+  `gno reset`, index cleanup or uninstall cannot remove it, and outside every
+  folder the default config indexes (`SESSIONS_UNSAFE_PATH`).
+
+**Synopsis:**
+
+```bash
+gno sessions [discover] [--json]
+gno --config <archive.yml> --index <name> sessions init --archive <dir> --collection <name> [--json]
+gno --config <archive.yml> --index <name> sessions source add <id> --harness <codex|claude-code|openclaw|hermes> --path <root> --collection <name> [--project <prefix>=<collection>...] [--json]
+gno --config <archive.yml> --index <name> sessions source remove <id> [--json]
+gno --config <archive.yml> --index <name> sessions import (--source <id> | <paths...> --collection <name>) [--format <harness>] [--dry-run] [--limit <n>] [--json]
+gno --config <archive.yml> --index <name> sessions status [--json]
+gno --config <archive.yml> --index <name> sessions prune --source <id> [--apply] [--json]
+gno --config <archive.yml> --index <name> sessions automation set <profile> --source <id>... [--cadence <n>s|m|h|d] [--limit <n>] [--retries <n>] [--json]
+gno --config <archive.yml> --index <name> sessions automation preview <profile> [--settings <file>] [--json]
+gno --config <archive.yml> --index <name> sessions automation enable <profile> [--hook claude-code [--settings <file>]] [--schedule --cadence <n>s|m|h|d] [--json]
+gno --config <archive.yml> --index <name> sessions automation disable <profile> [--hook] [--schedule] [--json]
+gno --config <archive.yml> --index <name> sessions automation remove <profile> [--json]
+gno --config <archive.yml> --index <name> sessions automation run <profile> [--json]
+gno --config <archive.yml> --index <name> sessions hook claude-code --profile <id>
+```
+
+**discover** (default): previews supported local roots (`$CODEX_HOME` or
+`~/.codex/sessions`; `~/.claude/projects` and `$CLAUDE_CONFIG_DIR/projects`;
+`$OPENCLAW_STATE_DIR` or `~/.openclaw`; `$HERMES_HOME` or `~/.hermes`) with
+unit counts, sizes and sampled format versions. Never imports and needs no
+archive. Output: `sessions-discovery` schema.
+
+**init**: creates or extends the archive config (idempotent). Adds the
+`sessions` block (`index`, `archiveRoot`) and one archive collection at
+`<archive>/<collection>` with the JSONL record mapping. A config already bound
+to another index or root is never retargeted.
+
+**source add / remove**: registers an owner-approved source root, file or
+database with a default archive collection (created under the archive root
+when missing). `--project <prefix>=<collection>` maps recorded working
+directories under `prefix` to another archive collection. Removing a source
+keeps its archive. Registration never imports.
+
+**import**: parses the selected source (or explicit paths), classifies turns
+structurally, redacts, and writes one sanitized JSONL archive file per
+thread, then syncs the changed files through the ordinary JSONL record
+adapter.
+
+- Selection is required: `--source <id>` (uses the registered collection and
+  project mappings) or explicit absolute paths plus `--collection`.
+  `--collection` with `--source` is rejected.
+- `--format` overrides structural detection for path imports.
+- `--dry-run` parses and reports without writing archive files, checkpoint
+  state or index rows.
+- `--limit <n>` bounds the number of changed units processed; unchanged units
+  do not count; the rest are reported as `deferredUnits`.
+- Reruns are idempotent: a unit whose fingerprint, parser, redaction and
+  archive format are unchanged is skipped; a changed unit is re-rendered and
+  compared with the archived bytes. Turn IDs are stable across appends.
+- A unit whose final line is cut mid-write, or whose structure drifted (for
+  example assistant turns without any recognised human turn), is
+  `incomplete`: its readable threads are archived but its checkpoint does not
+  advance, and the next run retries it.
+- A thread whose recorded working directories map to different collections
+  is quarantined (`skipped_policy`, reason `mixed_domain`) instead of being
+  written to the less restricted one.
+- A unit is identified by source ID plus its safe locator, so moving a file
+  within the source root or re-registering the source at a new path keeps
+  its archive files; two units with the same locator fail the second one
+  (`unit_conflict`). Archive files are namespaced per unit, so two units
+  reporting the same thread ID never overwrite each other.
+- A unit is re-imported when its routing settings (collection or project
+  mappings) change, so a quarantined thread is imported once it is mapped.
+- Units are recorded complete only after the lexical sync of the changed
+  archive files succeeds; a failed or interrupted sync is retried by the next
+  run. Units with malformed records stay `incomplete` (`malformed_records`).
+- A thread withheld by policy (`mixed_domain`, `over_limit`; a thread at the
+  turn limit is skipped whole) has any earlier archive copy moved to
+  `<archive>/.gno-sessions/withheld/` and removed from the index.
+- A registered source whose root is missing or cannot be listed still gets
+  archive-only maintenance (redaction rescans), then the import fails with
+  `SESSIONS_SOURCE_UNAVAILABLE` (exit 2). A directory or unit file inside a
+  source that cannot be read is a `failed` unit (`permission_denied`,
+  `source_missing` or `read_failed`; directories use the locator `.`), so the
+  receipt is never `nothing_to_do`, and its checkpoint does not advance.
+- Imports on one archive serialize on `<archive>/.gno-sessions/import.lock`;
+  a concurrent run exits `BUSY` (`SESSIONS_BUSY`).
+- A source file that disappears keeps its archive; `status` reports it as
+  `sourceUnavailable`. When the redaction rules or the configured literals
+  (`sessions.redaction.literals`) change, units with a source are re-rendered
+  and archives without a source are rescanned in place; a parser change
+  cannot reparse a missing source and is reported instead.
+- Output: `sessions-import-receipt` schema. `status` is `complete`,
+  `partial` (any incomplete, failed, unsupported or deferred unit, or failed
+  lexical sync), `failed` (nothing archived or unchanged and nothing
+  incomplete, for example every selected unit unsupported or failed) or
+  `nothing_to_do`. Units skipped as already current count their archived
+  threads as `unchanged`; an unsupported unit selected as a file is reported
+  by its (redacted) file name.
+  Receipts carry counts, per-unit outcomes with safe locators (never host
+  paths), lexical readiness and the embedding backlog. Embeddings are not
+  generated by import; run `gno embed` on the archive pair.
+
+**status**: archive collections with thread counts, and per source its
+availability (`false` when the root is missing or cannot be read), unit counts (complete, incomplete, failed, pending),
+`sourceUnavailable`, `staleParser` and last import time, plus the
+`automation` block (daemon state, per-profile state, triggers, pending and
+running work, last run, last success, next due time only with a live
+daemon, recovery action). Output: `sessions-status` schema.
+
+**automation** (opt-in; nothing is enabled by install, upgrade, repair or
+restart):
+
+- `set` creates or reconfigures a profile in `sessions.automation` of the
+  archive config: registered `--source` IDs (1-64), optional `--cadence`
+  (`<n>s|m|h|d`, 1m..30d), `--limit` (changed units per source per run,
+  default 200) and `--retries` (0-10, default 3). Triggers keep their state;
+  a new profile has none. Unknown sources exit `VALIDATION`
+  (`SESSIONS_UNKNOWN_SOURCE`). Output: the preview object.
+- `preview` prints sources with host paths, destination collections, the
+  hook command and target settings file (`--settings`, else
+  `$CLAUDE_CONFIG_DIR/settings.json` or `~/.claude/settings.json`), the
+  schedule, the budget, and the daemon prerequisite. Local only.
+- `enable --hook claude-code` installs exactly one owned SessionEnd entry
+  (identified by its command for this config and profile; other entries are
+  preserved; a `.bak` copy is kept; invalid JSON is left untouched and exits
+  `VALIDATION`) and then sets `hook.enabled`. Other harnesses exit
+  `VALIDATION` with `SESSIONS_UNSUPPORTED_INTEGRATION`. `enable --schedule`
+  requires a cadence (flag or profile); the first run is due one cadence
+  later. Enabling never installs or starts a service.
+- `disable` switches the selected triggers off (both when none is named),
+  removes the owned hook entry, and clears pending work admitted by those
+  triggers; a run in progress finishes. `remove` uninstalls the owned entry
+  (failing closed when the settings file cannot be read) and deletes the
+  profile and its run state. Archives are never deleted.
+- `run` admits a manual trigger and runs the profile through the importer
+  (`sessions import --source` per source, bounded by `limit`). Output:
+  `sessions-automation-run` schema; exit `BUSY` (4, `SESSIONS_BUSY`) when the
+  run failed with reason `busy` (another import, lease holder or a locked
+  index; the busy run is recorded), exit `RUNTIME` (2) when the outcome is
+  `failed`.
+
+**hook**: `sessions hook claude-code --profile <id>` is the command an
+installed hook runs. It reads the event JSON on stdin (at most 64 KiB), skips
+anything other than `SessionEnd`, rechecks under the marker lock that the
+profile's hook is enabled, and durably records one pending generation. It
+never imports, parses sessions or uses the network, and waits at most 1 s for
+the lock. Output is one content-free line: `accepted (…pending, not yet
+archived…)`, `skipped (…)` (exit 0), or `not accepted (…)` (exit 2).
+`GNO_SESSIONS_HOOKS=off` or `0` skips immediately. An unknown profile is
+reported as `skipped (… unknown_profile)`, a profile whose hook is off as
+`skipped (… hook_disabled)`. An explicit `--settings` other than the default
+location must name an existing file (`VALIDATION`).
+
+**prune**: lists archived units whose source is gone (preview by default);
+`--apply` deletes exactly those archive files and syncs the index, never a
+file a still-present unit references. It requires a complete listing of the
+source and fails with `SESSIONS_SOURCE_UNAVAILABLE` when part of it cannot be
+read or the listing was truncated. It plans under the archive lock; when
+the index sync fails it records nothing, returns `applied: false` with an
+`error`, and the next prune retries. Source deletion alone never removes
+archive files.
+
+**Exit codes:** `VALIDATION` (1) for selection, destination, binding,
+unknown source/collection, unsafe path and unsupported format errors;
+`BUSY` (4) for `SESSIONS_BUSY`; `RUNTIME` (2) for an import or automation
+run whose status is `failed` and for a hook that was not accepted, except `VALIDATION` (1, `SESSIONS_UNSUPPORTED_FORMAT`) when no
+selected unit is a supported format. The JSON error envelope carries the core code in
+`details.sessionsCode`.
+
+**Examples:**
+
+```bash
+gno sessions
+gno --config ~/gno-sessions/archive.yml --index sessions sessions init --archive ~/gno-sessions/archive --collection sessions-work
+gno --config ~/gno-sessions/archive.yml --index sessions sessions source add codex --harness codex --path ~/.codex/sessions --collection sessions-work
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source codex --dry-run
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source codex --json
+gno --config ~/gno-sessions/archive.yml --index sessions query "why did we pick sqlite" --category harness/codex --author human
+```
+
+---
+
 ### gno get
 
 Retrieve a single document by reference.
@@ -2387,6 +2772,31 @@ content, asset descriptors, source references, nor raster bytes.
 
 ---
 
+### gno vec drop
+
+Drop an abandoned shadow vector partition (legacy shadows included) the calling runtime's
+retrieval does not read, with its vectors, owners and runtime verdicts.
+
+**Synopsis:**
+
+```bash
+gno vec drop <partition> [--json] [--lock-wait <duration>] [--no-wait]
+```
+
+`<partition>` is an id prefix of at least 8 characters from `gno status`
+(`vectorPartitions[].id`). Only partitions with `droppable: true` are accepted:
+shadow partitions this runtime does not read; every active partition, legacy
+included, is refused. JSON output is
+`{"dropped": <vectorPartitions item>}`.
+
+**Exit Codes:**
+
+- 0: Dropped
+- 1: Unknown, ambiguous or protected partition
+- 4: Write lease busy with `--no-wait`
+
+---
+
 ### gno cleanup
 
 Remove orphaned content, chunks, and vectors not referenced by active documents.
@@ -4118,32 +4528,36 @@ Errors are written to stderr. With `--json` flag, errors are also returned as:
 }
 ```
 
-Error codes match exit codes: `VALIDATION` (exit 1), `RUNTIME` (exit 2), `NOT_RUNNING` (exit 3), `BUSY` (exit 4).
+Error codes and their exit codes: `VALIDATION` (1), `RUNTIME` (2), `NOT_RUNNING` (3), `CONTEXT_STALE` (3), `BUSY` (4), `AUDIT_FINDINGS` (4), `CONTEXT_CONFLICT` (4), `AUDIT_PARTIAL` (5). `error.schema.json` lists exactly this set.
+`AUDIT_FINDINGS`, `AUDIT_PARTIAL`, `CONTEXT_STALE`, and `CONTEXT_CONFLICT` signal through the exit code alone, after the command's own output; they write no envelope.
+Request ID errors keep their stable request code in `details.requestCode`
+(see [gno request-status](#gno-request-status)).
 
 Write-lease contention on `index` / `update` / `embed` does not use the generic envelope. Text mode writes the dedicated "index is busy" message to stderr; `--json` writes `{ success: false, error, contention }` to stdout. Both exit 4. `gno audit` also uses exit 4 for findings.
 
-**`NOT_RUNNING` is not an error envelope.**
-
-**`NOT_RUNNING` is not an error envelope.** `gno serve|daemon --status --json` returns a `process-status`-shaped payload on stdout with exit 3 when no live matching process is found (it reports observable state, not failure). `--stop` exits 3 silently when there is nothing to stop and does not accept `--json`. The error envelope above is reserved for `VALIDATION` and `RUNTIME` failures where the command could not produce its structured output at all.
+**`NOT_RUNNING` is not a failure payload.** `gno serve|daemon --status --json` returns a `process-status`-shaped payload on stdout with exit 3 when no live matching process is found (it reports observable state, not failure); the `NOT_RUNNING` envelope goes to stderr only. `--stop` exits 3 silently when there is nothing to stop and does not accept `--json`. The error envelope above is reserved for `VALIDATION`, `RUNTIME`, and `BUSY` failures where the command could not produce its structured output at all.
 
 ---
 
 ## Environment Variables
 
-| Variable                   | Description                                                                                                                |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `GNO_CONFIG_DIR`           | Override config directory                                                                                                  |
-| `GNO_DATA_DIR`             | Override data directory (DB location)                                                                                      |
-| `GNO_CACHE_DIR`            | Override cache directory (models)                                                                                          |
-| `NO_COLOR`                 | Disable colored output (standard)                                                                                          |
-| `PAGER`                    | Pager for long output (default: less -R on Unix, built-in on Windows)                                                      |
-| `GNO_SKILLS_HOME_OVERRIDE` | Override home dir for skill user scope (testing)                                                                           |
-| `GNO_MEMORY_CALLER`        | Default `--caller` identity for `gno remember` / `gno recall`                                                              |
-| `GNO_MEMORY_SESSION`       | Default `--session` identity for `gno remember` / `gno recall`                                                             |
-| `CLAUDE_SKILLS_DIR`        | Override Claude skills directory                                                                                           |
-| `CODEX_SKILLS_DIR`         | Override Codex skills directory                                                                                            |
-| `CLAUDE_CONFIG_DIR`        | Claude Code config dir; `gno agents` resolves Claude's instruction file under it (suppressed by an explicit home override) |
-| `CODEX_HOME`               | Codex config dir; same rule as `CLAUDE_CONFIG_DIR`                                                                         |
+| Variable                   | Description                                                                                                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GNO_CONFIG_DIR`           | Override config directory                                                                                                                                                       |
+| `GNO_DATA_DIR`             | Override data directory (DB location)                                                                                                                                           |
+| `GNO_CACHE_DIR`            | Override cache directory (models)                                                                                                                                               |
+| `NO_COLOR`                 | Disable colored output (standard)                                                                                                                                               |
+| `PAGER`                    | Pager for long output (default: less -R on Unix, built-in on Windows)                                                                                                           |
+| `GNO_SKILLS_HOME_OVERRIDE` | Override home dir for skill user scope (testing)                                                                                                                                |
+| `GNO_MEMORY_CALLER`        | Default `--caller` identity for `gno remember` / `gno recall`                                                                                                                   |
+| `GNO_MEMORY_SESSION`       | Default `--session` identity for `gno remember` / `gno recall`                                                                                                                  |
+| `CLAUDE_SKILLS_DIR`        | Override Claude skills directory                                                                                                                                                |
+| `CODEX_SKILLS_DIR`         | Override Codex skills directory                                                                                                                                                 |
+| `CLAUDE_CONFIG_DIR`        | Claude Code config dir; `gno agents` resolves Claude's instruction file under it (suppressed by an explicit home override); `gno sessions discover` also checks its `projects/` |
+| `CODEX_HOME`               | Codex config dir; same rule as `CLAUDE_CONFIG_DIR`; `gno sessions discover` checks its `sessions/`                                                                              |
+| `OPENCLAW_STATE_DIR`       | OpenClaw state dir checked by `gno sessions discover` (else `$OPENCLAW_HOME/.openclaw` or `~/.openclaw`)                                                                        |
+| `HERMES_HOME`              | Hermes home checked by `gno sessions discover` (else `~/.hermes`)                                                                                                               |
+| `GNO_SESSIONS_HOOKS`       | `off` or `0` makes every installed `gno sessions hook` return immediately without admitting work                                                                                |
 
 ---