@cairnkeep/cli 2.3.1 → 2.5.0

package/docs/operating.md

@@ -16,8 +16,9 @@ installs. This guide covers all three in order.
 
 ## Prerequisites
 
-- Node.js 22 or newer (for the memory server) and a supported harness: Claude
-  Code or OpenCode.
+- Node.js 22 or newer (for the memory server) and a supported harness. Claude
+  Code and OpenCode receive the full operating layer. Kimi Code receives the
+  memory MCP and launcher. Pi receives its native trajectory adapter.
 - Optional: the `sqlite3` CLI for `cairn memory export`. Runtime memory and
   `cairn memory import` do not require it.
 - Optional: an OpenAI-compatible LLM endpoint for memory extraction and
@@ -93,11 +94,15 @@ Step 3 installs into `~/.claude` (override with `CLAUDE_CONFIG_DIR` or
   `repo-review`, `graphify`, `context-explore`
 - **7 agents** → `agents/`: `code-reviewer`, the three `security-*` agents, and
   the three `wiki-*` agents
-- **3 hooks** → `hooks/`, registered in `settings.json`:
+- **5 hooks** → `hooks/`, registered in `settings.json`:
   - `memory-wakeup.sh` on **SessionStart** — surfaces AgentFS memory + wiki index
   - `memory-capture.sh` on **SessionEnd** — extracts memory candidates to staging
   - `memory-recall.sh` on **PreToolUse** (Edit/Write/MultiEdit) — injects
     file-specific memory before an edit
+  - `context-explore-pretask.sh` on **UserPromptSubmit** — inert unless the
+    separate context-exploration opt-in is enabled
+  - `compaction-capture.sh` on **PostCompact** — inert unless local compaction
+    continuity is enabled
 - **scaffold templates** → `templates/`, used by `/security-audit` and `/wiki-*`
 
 Re-running `sync-claude-assets.sh --apply` is idempotent; use `--check` to see
@@ -121,7 +126,7 @@ OpenCode is a secondary path. Steps 1, 4, and 5 are identical (use
 The operating-layer assets are installed by topic-specific scripts:
 
 ```bash
-scripts/sync-opencode-plugin-assets.sh   --apply   # memory-wakeup plugin
+scripts/sync-opencode-plugin-assets.sh   --apply   # memory wakeup/capture/recall plugins
 scripts/sync-opencode-memory-assets.sh   --apply   # memory-sync/review + code-review
 scripts/sync-opencode-wiki-assets.sh     --apply   # wiki commands/agents/workflows
 scripts/sync-opencode-security-assets.sh --apply   # security-audit chain
@@ -153,6 +158,64 @@ Model selection stays operator-env-driven through the existing
 variables (see "Configuration" below) — the harness commits no default model
 and carries no known-good allowlist.
 
+## Setup order (Kimi Code)
+
+Kimi Code can use the Cairnkeep memory MCP and the generated project launcher.
+It does not yet receive Cairnkeep-specific skills, commands, or hooks.
+
+For local stdio memory, create `.kimi-code/mcp.json` in the project:
+
+```json
+{
+  "mcpServers": {
+    "cairn-memory": {
+      "command": "cairn",
+      "args": ["memory-server"]
+    }
+  }
+}
+```
+
+Then launch from the project root with `./.ai/start-kimi.sh`. The launcher
+loads `.ai/.env`, runs the optional pre-launch and post-exit hooks, and forwards
+all arguments to `kimi`.
+
+Remote HTTP configuration needs one extra precaution: Kimi validates `url` as
+a literal URL and does not expand `${CAIRN_MEMORY_REMOTE_URL}` there. Put the
+resolved URL in a private `.kimi-code/mcp.json` and use
+`bearerTokenEnvVar: "CAIRN_MEMORY_HTTP_TOKEN"` so the token value remains in
+the environment. A repository-root `.mcp.json` must also be valid because Kimi
+parses it before applying its private override. See
+[Harness compatibility](harness-compatibility.md#kimi-code) for the complete
+configuration and trust-boundary guidance.
+
+## Setup order (Pi)
+
+Pi trajectory capture uses the same project scaffold and store, but its source
+is a native TypeScript extension installed into Pi's agent root:
+
+```bash
+npm install -g @cairnkeep/cli
+cairn sync-pi --apply                    # default: ~/.pi/agent
+cairn bootstrap /path/to/project
+cp /path/to/project/.ai/env.example /path/to/project/.ai/.env
+cd /path/to/project && cairn doctor && ./.ai/start-pi.sh
+```
+
+This command does not install an MCP bridge. Cairnkeep does not own or select a
+Pi bridge; if you want `cairn memory-server` tools inside Pi as well, configure
+a user-chosen Pi extension/bridge separately.
+
+Use `cairn sync-pi --check` to report drift without writing, or
+`--live-root DIR` to target an isolated Pi agent root. The command owns exactly
+`extensions/cairnkeep-trajectory.ts`; `cairn uninstall --pi-live-root DIR`
+removes that file backup-first and leaves every other Pi asset untouched.
+
+The extension listens for Pi's native `session_shutdown` event and reads only
+the active branch from the read-only session manager. It returns before doing
+that work unless `CAIRN_TRAJECTORY_CAPTURE` is explicitly enabled. Capture is
+local, fail-open, and capped at three seconds so it cannot hold Pi open.
+
 Before burning a multi-run soak, a preflight probe drives one real tool call
 and fails fast with a trait-named message if the configured model is not
 tool-call-reliable. The harness keeps a three-tier speed structure:
@@ -175,6 +238,38 @@ vendor or host.
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
 | `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
 | `CAIRN_AGENTFS_BASE_DIR` | Server-side base dir for named/global memory scopes (default `~/.cairnkeep`); it does not affect `project` scope |
+| `CAIRN_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; unset/default → no capture work) |
+| `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per session (default `5242880`, 5 MiB; minimum 1024) |
+| `CAIRN_TRAJECTORY_STORE_MAX_BYTES` | Logical local trajectory budget (default `268435456`, 256 MiB; must be at least the session maximum) |
+| `CAIRN_TRAJECTORY_RETENTION_DAYS` | Age retention applied on capture/prune (default `30`; `0` removes sessions once they are older than the current instant) |
+| `CAIRN_TRAJECTORY_REDACTION_FILE` | Optional redaction JSON path contained by the project (default `.ai/trajectory-redaction.json` when that file exists) |
+| `CAIRN_REDACTION_FILE` | Optional project-contained redaction JSON shared by trajectories and artifacts; takes precedence over `CAIRN_TRAJECTORY_REDACTION_FILE` |
+| `CAIRN_COMPACTION_CAPTURE` | Opt in to supported local compaction capture and automatic structured recovery (off by default; unset means zero new work) |
+| `CAIRN_ARTIFACT_STORE` | Expose the four local stdio artifact tools (off by default; independent of compaction capture) |
+| `CAIRN_ARTIFACT_HTTP` | Separately expose artifact tools over authenticated HTTP (off by default; also requires `CAIRN_ARTIFACT_STORE`) |
+| `CAIRN_ARTIFACT_MAX_BYTES` | Per-artifact stored-byte cap (default `1048576`, minimum `1024`) |
+| `CAIRN_ARTIFACT_SESSION_MAX_BYTES` | Per-session logical-byte cap (default `16777216`; at least the artifact cap) |
+| `CAIRN_ARTIFACT_STORE_MAX_BYTES` | Total logical-byte cap (default `268435456`; at least the session cap) |
+| `CAIRN_ARTIFACT_RETENTION_DAYS` | Age retention in days (default `30`, minimum `0`) |
+| `CAIRN_COMPACTION_MAX_REVISIONS` | Immutable compaction revisions retained per session (default `8`, minimum `1`) |
+| `CAIRN_ARTIFACT_GENERATED_FILE_SNAPSHOT_MAX_BYTES` | Generated-file inline snapshot cap (default `262144`; effective cap is the lower of this and the artifact cap) |
+| `CAIRN_NOTE_DISTILLATION` | Master opt-in for local one-shot/scheduled hindsight distillation and exact lookup (unset/default → disabled before I/O) |
+| `CAIRN_NOTE_ENRICHMENT` | Separate opt-in for provider prose enrichment; credentials alone never enable it |
+| `CAIRN_NOTE_ENRICHMENT_MODEL` | Explicit OpenAI-compatible chat model for note enrichment (no default) |
+| `CAIRN_NOTE_ENRICHMENT_TIMEOUT_MS` | Enrichment timeout in milliseconds (default `15000`, allowed `100`–`120000`) |
+| `CAIRN_TYPED_MEMORY_NODES` | Add typed metadata, filters, logical note address spaces, and `memory_import` (unset/default off; restart after changing) |
+| `CAIRN_CAPABILITY_CONTRACT` | Enable the managed eight-capability contract (unset/default off) |
+| `CAIRN_CAPABILITY_LOGGING` | Strict per-process callback-logging override (`1`/`0`; compatibility default off) |
+| `CAIRN_CAPABILITY_MEMORY_WRITE` | Strict per-process override for `memory.write` |
+| `CAIRN_CAPABILITY_MEMORY_SEARCH` | Strict per-process override for `memory.search` |
+| `CAIRN_CAPABILITY_NOTES_DISTILL` | Strict per-process override for `notes.distill` |
+| `CAIRN_CAPABILITY_WIKI` | Strict per-process override for `wiki` |
+| `CAIRN_CAPABILITY_GRAPH` | Strict per-process override for `graph` |
+| `CAIRN_CAPABILITY_SECURITY_AUDIT` | Strict per-process override for `security.audit` |
+| `CAIRN_CAPABILITY_ROUTE_CHECK` | Strict per-process override for `route.check` |
+| `CAIRN_CAPABILITY_CONTEXT_EXPLORE` | Strict per-process override for `context.explore` |
+| `CAIRN_EVAL` | Opt in to the local evaluation coordinator (`1`, `true`, `yes`, or `on`; unset/default → stable disabled result before input reads, writes, or adapter execution) |
+| `CAIRN_HARNESS_STATE_DIR` | Optional absolute local root for recoverable native capability leases (default `${XDG_STATE_HOME:-~/.local/state}/cairn/harness`) |
 | `CAIRN_GIT_PROVIDER` | Git host for collaboration commands: `github`\|`gitlab`\|`codeberg`\|`forgejo`\|`none`. See [git-providers.md](git-providers.md) |
 | `CAIRN_ROUTE_ENDPOINT` | Base URL of an already-running token-miser routing/tiering proxy (unset → the `route_check` tool is inert) |
 | `CAIRN_EXPLORE_BINARY` | Absolute path to the `token_miser` binary used by `context_explore` (unset → the tool throws at call time) |
@@ -187,6 +282,208 @@ vendor or host.
 | `CAIRN_ANYTHINGLLM_PROJECTS_FILE` | Override path to the bundled sync script's project configuration |
 | `CAIRN_ANYTHINGLLM_STATE_FILE` | Override path to the bundled sync script's incremental state |
 
+### Managed capability contract (opt-in)
+
+The managed contract is a narrow state and measurement boundary around eight
+existing owners. It adds no runtime dependency and does not move business logic
+from the MCP server, note CLI/timer, installed workflows, or the external
+token-miser delegates.
+
+The canonical registry is exactly:
+
+| ID | Kind | Owner | Compatibility default | Environment override | Restart required |
+|---|---|---|---:|---|---:|
+| `memory.write` | `mcp-tool` | `mcp-memory-server:index#memory_write` | on | `CAIRN_CAPABILITY_MEMORY_WRITE` | yes |
+| `memory.search` | `mcp-tool` | `mcp-memory-server:index#memory_search` | on | `CAIRN_CAPABILITY_MEMORY_SEARCH` | yes |
+| `notes.distill` | `offline-job` | `mcp-memory-server:note-cli#distill` | `CAIRN_NOTE_DISTILLATION`, otherwise off | `CAIRN_CAPABILITY_NOTES_DISTILL` | no |
+| `wiki` | `operating-workflow` | `operating-layer:wiki` | on | `CAIRN_CAPABILITY_WIKI` | no |
+| `graph` | `operating-workflow` | `operating-layer:graph` | `.planning/config.json` `graphify.enabled`, otherwise off | `CAIRN_CAPABILITY_GRAPH` | no |
+| `security.audit` | `operating-workflow` | `operating-layer:security-audit` | on | `CAIRN_CAPABILITY_SECURITY_AUDIT` | no |
+| `route.check` | `mcp-tool` | `mcp-memory-server:index#route_check` | on | `CAIRN_CAPABILITY_ROUTE_CHECK` | yes |
+| `context.explore` | `mcp-tool` | `mcp-memory-server:index#context_explore` | on | `CAIRN_CAPABILITY_CONTEXT_EXPLORE` | yes |
+
+`CAIRN_CAPABILITY_CONTRACT` is the default-off rollout gate. Master off is exact
+legacy behavior: the launchers and sync commands preserve the legacy installed
+assets byte-for-byte, install and invoke no capability hook or plugin, introduce
+no capability block, and create no capability measurement state. Master on is
+not enough to modify the normal harness root. The launcher must also select the
+explicit `capability-overlay` mode; only that two-factor path renders the
+isolated `.ai/capability-contract/` root and installs its native hooks/plugins.
+Normal installed assets remain in place, and toggling never deletes
+configuration, retained data, or installed files.
+
+Bootstrap creates a mode-`0600` `.ai/capabilities.json` only if it is absent:
+
+```json
+{
+  "schema_version": 1,
+  "capabilities": {},
+  "logging": { "callbacks": false }
+}
+```
+
+Use the managed CLI; do not hand-edit the file:
+
+```bash
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities list
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities status
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities status --json
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities enable wiki
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities disable memory.search
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities reset memory.search
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities reset --all
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities logging enable
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities logging disable
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities logging reset
+```
+
+Precedence is strict: the derived per-capability environment value (or
+`CAIRN_CAPABILITY_LOGGING`) wins over the project value, which wins over the
+compatibility resolver. Every derived key uses the `CAIRN_CAPABILITY_` prefix
+followed by the uppercased ID with dots replaced by underscores. Accepted
+values are `1|true|yes|on` and
+`0|false|no|off`, case-insensitively. An invalid top-level value is reported
+with a fixed value-free issue and falls directly back to compatibility; it does
+not reveal the raw value or consult a lower project override. Unknown IDs and
+invalid project rows are likewise reported without their values. Each bad row
+falls back independently, so it cannot disable another capability or the
+server.
+
+`reset` removes the explicit override; `reset --all` clears every capability
+and logging override. The returned schema-v1 status orders all eight rows and
+reports `enabled`, `source` (`environment`, `project`, or `compatibility`),
+`restart_required`, contract/logging state, fixed issue codes, and the SHA-256
+`configuration_digest` of the canonical effective snapshot. The digest is
+evidence, not a signature or secret. MCP state is resolved once before server
+registration, so changes to `memory.write`, `memory.search`, `route.check`, or
+`context.explore` require a new server start; a disabled tool is omitted from
+`tools/list`. Notes and operating workflows resolve current state for the next
+invocation. Disabled notes retain the existing structured `enabled: false`
+offline result.
+
+Wiki covers ingest, query, and lint; graph covers its command family; security
+audit covers its command and workflow family. There are no subcommand-level
+switches. The four enabled MCP tools retain their exact names, schemas,
+responses, timeout/error behavior, and owners. In particular, `route_check`
+and `context_explore` remain thin token-miser delegates; Cairnkeep does not gain
+endpoint, model, tier, sandbox, or inference-loop ownership.
+
+The five operating command surfaces are still `wiki-ingest`, `wiki-query`,
+`wiki-lint`, `graphify`, and `security-audit`. Their installed commands, agents,
+and workflows remain the owners described by D-10, D-12, and D-16; the native
+boundary admits or blocks an invocation and settles evidence, but does not move
+or duplicate owner logic.
+
+#### Native operating lifecycle
+
+Claude Code uses two native hooks. `capability-command-start.sh` runs on
+`UserPromptExpansion`, before command or MCP-prompt expansion can enter owner
+I/O. It validates the exact target-command event and binds the canonical
+project root from the event to the process root. The coordinator then creates
+an issued recoverable lease for an eligible measured invocation. That validated
+project identity and lease are immutable for the invocation: terminal events
+carry neither a replacement project path nor a caller-selected handle.
+`capability-command-finish.sh` maps `Stop` to success and maps `StopFailure`
+immediately to an error terminal; error settlement is not deferred to
+`SessionEnd`. `SessionEnd` performs abandonment cleanup only for unfinished
+leases, while `CwdChanged` updates lifecycle state without rebinding the
+start-time project.
+
+OpenCode uses the pinned native plugin for OpenCode 1.17.20.
+`command.execute.before` validates the target command, session, output shape,
+and the one canonical project identity supplied at plugin initialization before
+expansion. `session.idle` and `session.status:idle` settle success,
+`session.error` settles error, and `session.deleted` performs abandonment
+cleanup only for an unfinished invocation. Plugin disposal likewise abandons
+only unfinished leases. Both harnesses settle the issued lease atomically and
+idempotently: one terminal can win, replay cannot add another final, and
+crash-recovery cleanup cannot rewrite a settled outcome.
+
+The three operating states are exact. With master off, no native capability
+owner is installed or invoked and no measurement state exists. With master on
+and a target disabled, the native boundary returns the fixed block before owner
+I/O regardless of measurement consent. Only when all three consents are on may
+that block settle exactly one D-25/D-26 value-free `disabled` final through an
+issued lease; if either measurement consent is off, it blocks with no state.
+With master on and a target enabled, either measurement consent being off
+preserves owner execution unchanged and creates no measurement state.
+
+Deterministic native-boundary tests prove pinned event shapes, admission before
+owner delegation, terminal ordering, and overlay installation. They are not
+exhaustive live real-owner evidence. Phase 18 also requires the complete live
+eight-by-seven matrix: eight capabilities across seven target-disabled cells,
+56 genuine owner executions in total. Any missing, failed, or unavailable cell
+keeps Phase 18 incomplete.
+
+Callback logging is separately default-off. When all three consents are on
+(`CAIRN_CAPABILITY_CONTRACT`, managed callback logging, and
+`CAIRN_TRAJECTORY_CAPTURE`), the native boundary measures only the capability-owned
+invocation. State is resolved first; the timer starts immediately before the
+owned body and stops after its terminal outcome but before final presentation.
+Discovery, configuration resolution, guard work, and unrelated harness overhead
+are excluded. Logging is payload-free, local-only, final-only, and fail-open;
+HTTP callbacks are never persisted. See the privacy and storage guides for the
+exact record and retention contract.
+
+Phase 19 must explicitly enable all eight capabilities to establish its
+baseline before disabling one at a time. This contract records status/digest
+and callback evidence only: it does not implement tasks, a runner, turns/tokens,
+statistics, confidence intervals, or a quality/efficiency claim.
+
+### Typed memory nodes and note address spaces (opt-in)
+
+Set `CAIRN_TYPED_MEMORY_NODES=1` in the memory-server process and restart it.
+Tool schemas are selected when `createMemoryServer` constructs a stdio server
+or authenticated HTTP session. With the flag unset, Cairnkeep retains the
+existing 14-tool list, required inputs, structured response roots, raw KV
+values, files, processes, network behavior, and output. Enabled mode adds
+optional fields to the existing lifecycle tools and exactly `memory_import`;
+it does not add `memory_edit`, `memory_update`, `memory_remove`, or duplicate
+read/delete tools. Use `memory_supersede` for both content and metadata edits.
+
+Types are `memory`, `knowledge`, `hindsight`, `shared`, `provenance`, or a
+lowercase namespaced extension such as `team:runbook`. Tags are trimmed, ASCII
+lowercased, normalize whitespace/underscore runs to one hyphen, collapse
+hyphens, deduplicate, and sort. `memory_list` and `memory_search` accept
+non-empty `node_types`, `tags_all`, and `tags_any`; these are hard eligibility
+filters applied before `top_k`, cache lookup, or embedding. Case-insensitive
+key matches and exact canonical tag/type matches sort before semantic results.
+Endpoint failure or absent embedding configuration falls back to stable local
+substring matching over key, value, type, and tags.
+
+Enabled `memory_write` without any Phase 16 field preserves collision-safe
+legacy overwrite behavior. Supplying `address_space`, `node_type`, `tags`, or
+`note` makes it create-only on a differing live node and returns `CONFLICT`;
+use `memory_supersede` to preserve the complete prior value/type/tags snapshot.
+Delete also records the complete final snapshot, and recreation is allowed.
+
+`memory_import` takes `schema_version: 1`, one concrete `scope`, optional
+`address_space` (default `memory`), 1–256 `nodes`, optional `import_id`,
+`dry_run`, and `conflict_policy` (default `reject`, or explicit `supersede`).
+Each unique logical key is a contained relative slash path; values are limited
+to 256 KiB UTF-8 each and 5 MiB per batch. The content digest excludes retry
+controls, while `import_id` durably binds to it. Dry-run performs no create,
+lock, cache, journal, or mutation and returns only the digest, sorted actions,
+and counts. Committed and replay results likewise omit values. Stable failures
+include `INVALID_SCHEMA`, `INVALID_SCOPE`, `INVALID_PATH`, `CONFLICT`,
+`IMPORT_ID_REUSE`, and `UNSUPPORTED_TARGET`.
+
+`project-notes` and `shared-notes` both require `scope: project`; no named
+memory scope is reserved. Keys such as `knowledge/build-cache` are logical,
+not client filesystem paths. Rich hindsight/shared/provenance imports require
+the complete nested note record; knowledge values must still losslessly encode
+the validated record. Canonical Markdown and its manifest remain authoritative.
+Unmanaged collisions are refused, and bytes after the managed marker are
+preserved exactly. Local stdio derives project identity from its working
+directory. Authenticated HTTP project notes require validated
+`X-Cairn-Project`; the bearer token still defines the trust domain.
+
+An interrupted note mutation blocks later note writes with `RECOVERY_REQUIRED`.
+`cairn doctor --repair` rolls prepared/committing journals back to verified
+pre-images, but verifies and finalizes committed-before-cleanup journals without
+undoing the completed operation. Unverifiable committed state remains failed
+and untouched for backup-guided manual recovery.
+
 ### Domain knowledge (RAG via AnythingLLM, opt-in)
 
 `domain_knowledge_query` / `domain_knowledge_sync` bridge to an optional
@@ -293,6 +590,7 @@ is guarded and **fails closed**:
 | `CAIRN_MEMORY_HTTP_TOKEN` | **Required** in HTTP mode — clients send `Authorization: Bearer <token>`; the server refuses to start without it |
 | `CAIRN_MEMORY_HTTP_ALLOWED_ORIGINS` | Comma-separated browser origins allowed via CORS (default: none — no cross-origin access) |
 | `CAIRN_MEMORY_HTTP_ALLOWED_HOSTS` | Comma-separated allowed `Host` headers for DNS-rebinding protection (default: the bind host + `localhost` on the chosen port) |
+| `CAIRN_ARTIFACT_HTTP` | Additional consent for artifact tools (default off; requires `CAIRN_ARTIFACT_STORE`, a valid `X-Cairn-Project`, bearer auth, and the normal Host/CORS checks) |
 
 Requests without a valid bearer token get `401`; requests with an unexpected
 `Host` header get `403`. Keep HTTP mode bound to `127.0.0.1` unless you have a
@@ -364,13 +662,14 @@ maintain a running install — without forking the core. All are opt-in.
 
 ### Launcher seams
 
-The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`) run three
-optional hooks around the harness, each a no-op when absent:
+The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`,
+`.ai/start-kimi.sh`, and `.ai/start-pi.sh`) run optional hooks around the
+harness, each a no-op when absent:
 
 | Seam | When | Purpose |
 |---|---|---|
 | `.ai/pre-launch.sh` | sourced after `.env`, before launch | export env (e.g. a provider base URL / auth), refresh credentials, or abort by returning non-zero |
-| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered on the harness (`--settings` / `--config`); process env still wins over it |
+| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered on Claude Code (`--settings`) or OpenCode (`OPENCODE_CONFIG`); Kimi and Pi leave the variable available to hooks but do not interpret it |
 | `.ai/post-exit.sh` | sourced after the harness exits | teardown; `CAIRN_EXIT_STATUS` holds the exit code |
 
 A wrapper that needs a non-default provider drops a `pre-launch.sh` that renders
@@ -384,10 +683,265 @@ harness's remote HTTP registration. Unconfigured optional dependencies are
 skipped; it exits non-zero when the local server probe fails or a configured
 dependency (LLM/embedding endpoint, writable store) is unreachable.
 
+It also checks an existing project-local trajectory database for SQLite
+integrity, schema compatibility and index consistency. Because capture is
+opt-in, a missing database is skipped. Metadata or indexes can be rebuilt from
+valid full records only through the explicit repair operation:
+
 ```bash
 cd /path/to/project && cairn doctor
+cd /path/to/project && cairn doctor --repair
+```
+
+The same command checks `.agentfs/artifacts.db`. Absence is a healthy skip
+because both producers are opt-in. A valid schema, full-record digest, index,
+dedupe row, compaction pointer, and retention state passes. `--repair` may
+rebuild only derived indexes/dedupe/pointers from valid authoritative records.
+Unsupported schema, SQLite failure, invalid full records, or digest corruption
+fails untouched with guidance to preserve the database before manual recovery.
+
+### Evaluation harness (opt-in)
+
+`cairn eval` is a local, serial experiment coordinator. It is disabled unless
+`CAIRN_EVAL` is explicitly truthy. The disabled path returns before reading a
+task set or adapter configuration, creating a workspace or report, opening a
+database, starting a subprocess, or making a network request. Enabling the
+flag does not choose a harness, model, endpoint, or credential: inference
+remains owned by the operator-configured adapter process.
+
+Task sets and adapters are strict schema-v1 JSON. Each task names an immutable
+source commit, fixed input, shell-free preparation and verification commands,
+and limits. An adapter configuration is one program-plus-arguments array and
+an exact turn-semantics ID plus definition. Cairnkeep sends one bounded JSON
+request on stdin and accepts exactly one bounded, strict JSON observation on
+stdout. The adapter may report terminal status, turns under its declared
+semantics, independently optional token components and total, optional
+currency-bearing cost, component identities, capability digest, and local
+trajectory/artifact references. The independent task verifier—not the
+adapter—assigns pass, fail, or unknown. Arbitrary adapter stderr remains live
+operator diagnostics and is not copied into the report.
+
+The request's `workspace_path` is the task's Cairnkeep project root for all
+trajectory-producing harness work. An adapter that returns `trajectory_ref`
+must run that work against the supplied root so the closed trajectory is in
+that task's local store. The reference is a bounded session identifier, not a
+filesystem locator. A task manifest with `workspace.path: "."` remains the
+compatible repository-root case; there is no second trajectory-root field.
+
+Validate before spending or mutating:
+
+```bash
+export CAIRN_EVAL=1
+cairn eval validate --task-set tasks.json --adapter adapter.json \
+  --output .agentfs/eval/experiments --json
+
+# Two serial observations per task and repetition: Run 1, then fresh Run 2.
+cairn eval run --task-set tasks.json --adapter adapter.json \
+  --output .agentfs/eval/experiments --repetitions 1 --seed trial-1 --yes --json
+
+# Four serial observations per task and repetition: all-on and one-off,
+# with Run 1 and Run 2 in each arm. Only one capability may be disabled.
+cairn eval ablate --disable memory.search --task-set tasks.json \
+  --adapter adapter.json --output .agentfs/eval/experiments --seed trial-1
+# Inspect the printed invocation estimate and both configuration digests, then
+# repeat with --yes to confirm execution.
+
+cairn eval report --experiment EXPERIMENT-ID --json
+cairn eval prune --older-than-days 30 --dry-run --json
+cairn eval prune --older-than-days 30 --json
+cairn eval delete --experiment EXPERIMENT-ID --dry-run --json
+cairn eval delete --experiment EXPERIMENT-ID --json
+```
+
+`validate` resolves task/adapter bytes and digests, immutable revisions,
+commands, limits, output containment, seeds, and the complete deterministic
+schedule without invoking the adapter. `run` requires `--yes` and prints its
+serial invocation estimate. `ablate` first prints the estimate, the explicit
+all-eight-enabled baseline, the exactly-one-disabled treatment, and their
+configuration digests; execution likewise requires `--yes`. There are no
+automatic retries: repetitions and paired seeds are explicit experiment
+inputs.
+
+The packaged fake workflow uses `examples/eval/task-set.json` and
+`examples/eval/adapter.json` with the same `validate`, `run`, `report`,
+`prune`, and `delete` commands. Its manifest must match the package-owned ID,
+version, canonical bytes, and digest. It is deterministic and network-free,
+but proves framework behavior only; it is not live performance evidence.
+
+Run 1 starts every task from a fresh workspace without evaluation notes. After
+a closed trajectory, the existing offline note distiller may create an
+experiment-owned immutable snapshot. Run 2 uses another fresh workspace and
+can see only its own task's snapshot. Tasks with `no_notes`, failed, or skipped
+distillation still run and remain visible. Reports show the full committed
+population and the note-eligible subset, plus executed, verified, paired, and
+missing populations and reason-coded missingness.
+
+Turns are paired or aggregated only when exact turn-semantics IDs match.
+Token fields remain independent and totals are never inferred. Verified pass
+rates exclude unknown verifier outcomes while retaining them in denominators
+and missingness tables. Task-clustered paired bootstrap intervals use recorded
+seeds and streams; fewer than two valid pairs has no interval and fewer than
+20 emits a small-sample warning. Results are estimates and may be
+inconclusive—reports do not make causal, significance, quality, or efficiency
+claims.
+
+SIGINT or SIGTERM stops schedule admission, terminates the active adapter,
+checkpoints a `cancelled` observation, waits for bounded cleanup, and retains
+an inspectable partial report. On POSIX systems the runner targets the child
+process group with TERM then bounded KILL escalation. Windows descendant-tree
+termination is not guaranteed and is not a supported evaluation claim.
+
+See [storage](storage.md#evaluation-report-and-note-snapshot-storage) for local
+retention/removal and [privacy](privacy-and-data-flow.md#evaluation-adapter-and-report-flow)
+for the exact request, observation, environment, and persistence boundaries.
+
+### Structured session trajectories (opt-in)
+
+Trajectory capture is disabled by default. To enable it for a launched Claude
+Code, OpenCode, or Pi session, set the flag in the project's private `.ai/.env`:
+
+```bash
+CAIRN_TRAJECTORY_CAPTURE=1
+```
+
+The Claude Code SessionEnd hook, OpenCode session-idle plugin, or Pi
+`session_shutdown` extension then normalizes the closed session, redacts it,
+and writes it locally without a model, API key, or remote request. Inspect and
+manage the result from the project root:
+
+```bash
+cairn trajectory list
+cairn trajectory show <session-id-or-unambiguous-prefix>
+cairn trajectory prune --dry-run
+cairn trajectory prune
+```
+
+All commands accept `--json`; `--dry-run` applies to `prune`. Bootstrap creates
+`.ai/trajectory-redaction.json` with an empty custom-pattern list but does not
+enable capture. Add bounded regular-expression entries there only for
+project-specific secrets; built-in credential patterns always apply. See
+[Privacy and data flow](privacy-and-data-flow.md) for the exact capture boundary
+and [Memory storage and deployment](storage.md) for retention and backup.
+
+### Compaction continuity and artifacts (opt-in)
+
+The two flags are independent and off by default. Enable either in the private
+project `.ai/.env`, sync the harness assets, and restart both the harness and
+the MCP server when changing tool registration:
+
+```bash
+cd /path/to/project
+printf '%s\n' 'CAIRN_COMPACTION_CAPTURE=1' >> .ai/.env
+printf '%s\n' 'CAIRN_ARTIFACT_STORE=1' >> .ai/.env
+cairn sync --apply                 # Claude Code PostCompact + SessionStart
+# OpenCode: re-run scripts/sync-opencode-plugin-assets.sh --apply from a clone
+# Restart the harness and cairn-memory after changing flags.
+
+# Disable: remove/comment both lines, sync again, and restart.
+```
+
+Compaction continuity accepts only the pinned Claude Code `PostCompact`
+2.1.219 and 2.1.220 payloads and OpenCode `session.compacted` 1.17.20 payload.
+The Claude hook resolves the local CLI version and passes that exact version to
+the normalizer. Unknown or malformed versions fail open, retain none of the
+unknown payload, and leave only a
+bounded value-free doctor diagnostic. The flag is checked before parsing,
+SDK, subprocess, filesystem, database, network, stdout, stderr, or injection
+work. Capture forwards the harness-produced summary unchanged to the local
+normalizer; it never generates a summary, changes a prompt, or triggers
+compaction.
+
+Automatic recovery prefers the exact current/resumed harness session. When a
+fresh session has no match, it chooses the newest valid project compaction. It
+injects provenance, revision, time, age, completeness, and only structured
+goals/decisions/TODOs/critical errors. Old state is still shown with a stale
+warning to validate it against the repository. The redacted raw summary is
+available only through explicit `artifact_read` or `cairn artifact show`.
+
+`CAIRN_ARTIFACT_STORE=1` registers exactly `artifact_write`, `artifact_read`,
+`artifact_list`, and `artifact_delete`. The first schema supports exactly
+`compaction_summary`, `diff`, `test_output`, and `generated_file`. Writes are
+bounded inline values; generated-file paths are labels and are never read.
+Operator commands remain available for already-retained local data:
+
+```bash
+cairn artifact list --kind compaction_summary --session SESSION-REF --json
+cairn artifact show ARTIFACT-ID --json
+cairn artifact delete ARTIFACT-ID --dry-run --json
+cairn artifact delete ARTIFACT-ID --json
+cairn artifact prune --dry-run --json
+cairn artifact prune --dry-run --include-protected --json
 ```
 
+Defaults are 1 MiB per artifact, 16 MiB per session, 256 MiB total, 30 days,
+eight compaction revisions, and a 256 KiB generated-file snapshot cap. Pruning
+is oldest-first after age/revision eligibility and protects the newest valid
+project compaction unless `--include-protected` or explicit delete is used.
+Hard delete removes the body and derived rows with no tombstone.
+
+No key, model, endpoint, or network is required. Stdio access needs only
+`CAIRN_ARTIFACT_STORE`. HTTP requires double consent—both artifact flags—plus
+the existing bearer token, allowed `Host`, CORS policy, and a valid
+`X-Cairn-Project`; the latter derives an isolated server-side artifact root.
+Artifact HTTP does not expose trajectories. See [storage](storage.md#artifact-storage)
+and [privacy](privacy-and-data-flow.md#compaction-and-artifact-flows).
+
+### Hindsight notes (opt-in)
+
+Note distillation is a separate asynchronous/one-shot capability. It never runs
+inside SessionEnd, session-idle, `session_shutdown`, or any other online agent
+callback. It consumes only closed, schema-validated trajectories already
+redacted by the capture path. Enable the master flag in the process that runs
+the command:
+
+```bash
+export CAIRN_NOTE_DISTILLATION=1
+
+# Incremental current project, or one exact session for deterministic replay
+cd /path/to/project
+cairn notes distill --json
+cairn notes distill --session SESSION-ID --json
+
+# Scheduled/manual sweep below one explicit PARA root
+cairn notes distill --all-projects --para-root "$HOME/PARA" --json
+
+# Exact signature lookup; stdin avoids quoting a real multiline stack trace
+printf '%s\n' 'TypeError: cache closed' '    at loadCache (/tmp/src/cache.ts:44:2)' \
+  | cairn notes search-error --project /path/to/project --json
+
+# Validate/rebuild generated indexes, or explicitly promote corroborated notes
+cairn notes doctor --json
+cairn notes doctor --repair --json
+cairn notes promote NOTE-ID --with CORROBORATING-NOTE-ID --confirm --json
+```
+
+The hierarchy is `${CAIRN_AGENTFS_BASE_DIR:-~/.cairnkeep}/notes/README.md`,
+`shared/`, and `projects/<slug--stable-id>/{README.md,knowledge/,hindsight/}`.
+Each Markdown leaf has validated `id`, `title`, `description`, `keywords`,
+`node_type`, and `tags` front matter. Hindsight nodes add a deterministic
+signature and `unresolved`, `resolved`, or `abandoned` lifecycle. A later
+recurrence reopens the same stable node. Generated content is enclosed by
+`cairnkeep:managed:v1` markers; text after that block is preserved. An existing
+unmarked target is treated as a collision and is never overwritten.
+
+JSON distillation output separates `created`, `updated`, `already_processed`,
+`enrichment_skipped`, `enrichment_failed`, and session-level `failed` results.
+Project locks reject concurrent writers. Exact lookup normalizes the message,
+causal stack, and component with the same versioned implementation used by the
+index; it runs without embeddings or network access. Promotion requires two
+compatible notes from distinct projects plus `--confirm`, creates one shared
+canonical body, and converts each project note into a provenance reference.
+
+Optional prose enrichment requires all of the master flag,
+`CAIRN_NOTE_ENRICHMENT=1`, `CAIRN_LLM_API_KEY`, `CAIRN_LLM_API_URL`, and an
+explicit `CAIRN_NOTE_ENRICHMENT_MODEL`. It sends bounded already-redacted
+evidence to `{CAIRN_LLM_API_URL}/chat/completions`, labels returned prose as
+non-authoritative, and cannot change signature, lifecycle, or provenance. Any
+missing configuration, malformed response, timeout, or provider failure leaves
+the deterministic note usable and is reported as skipped/failed. Review the
+[privacy data flow](privacy-and-data-flow.md#hindsight-note-distillation) before
+enabling it.
+
 ### `cairn memory export|import|path`
 
 Relocate named/global memory (one SQLite `.db` per scope under
@@ -414,3 +968,9 @@ cairn audit-timer --on-calendar daily            # install + enable the timer
 cairn audit-timer --render-only ./units          # just render the unit files
 # no systemd? cron:  @daily .../scripts/memory-wiki-audit.sh --para-root "$HOME/PARA" --report ...
 ```
+
+The timer inherits its process environment. With `CAIRN_NOTE_DISTILLATION`
+truthy it launches exactly one separate `cairn notes distill --all-projects`
+process after the wiki scan and reports its bounded status. With the flag unset
+it performs no note work. Note failure does not replace wiki findings or change
+their actionable exit status; no credentials are embedded in rendered units.