@gmickel/gno 2.5.1 → 2.6.0

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": "2.5.1"
+  "version": "2.6.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -82,6 +82,7 @@
     "eval:hybrid": "bun --bun evalite evals/hybrid.eval.ts",
     "eval:memory": "bun --bun evalite evals/memory.eval.ts --threshold 100",
     "eval:memory:fixtures": "bun scripts/memory-eval-fixtures.ts",
+    "eval:sessions": "bun --bun evalite evals/sessions.eval.ts --threshold 100",
     "eval:hybrid:baseline": "bun scripts/hybrid-benchmark.ts --write",
     "eval:hybrid:delta": "bun scripts/hybrid-benchmark.ts --delta",
     "bench:ast-chunking": "bun scripts/ast-chunking-benchmark.ts",

package/spec/cli.md

@@ -9,13 +9,13 @@ 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                                                                                                                             |
+| 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`) |
 
 ### Global Flags
 
@@ -85,7 +85,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 |
@@ -1628,7 +1630,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 +1686,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 +1724,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 +1758,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 +1799,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 +1808,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 +1941,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.
@@ -4119,6 +4437,8 @@ 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).
+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.
 
@@ -4130,20 +4450,23 @@ Write-lease contention on `index` / `update` / `embed` does not use the generic
 
 ## 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                                                                                |
 
 ---