@cairnkeep/cli 2.3.1 → 2.4.0

package/docs/storage.md

@@ -18,6 +18,10 @@ registration, memory remains on that computer.
 | Scope | Database path |
 |---|---|
 | `project` | `<server working directory>/.agentfs/project.db` |
+| Opt-in session trajectories and capability callback state | `<harness project root>/.agentfs/trajectory.db` |
+| Opt-in local artifacts and compaction revisions | `<project root>/.agentfs/artifacts.db` |
+| Opt-in evaluation reports and note snapshots | `<project root>/.agentfs/eval/experiments/<experiment-id>/` |
+| Opt-in derived hindsight notes | `${CAIRN_AGENTFS_BASE_DIR:-~/.cairnkeep}/notes/` |
 | Any named/global scope, such as `identity` or `work` | `${CAIRN_AGENTFS_BASE_DIR:-~/.cairnkeep}/<scope>.db` |
 
 For the local launchers, the server working directory is normally the project
@@ -29,6 +33,180 @@ services used to process/search memory. They do not change where the SQLite
 databases are stored. Git-provider and routing configuration do not change
 storage either.
 
+Trajectory storage is deliberately separate from MCP memory. The harness hook
+writes `.agentfs/trajectory.db` on the client machine where Claude Code,
+OpenCode, or Pi is running; it is never redirected to the remote HTTP memory server.
+The database contains versioned full-session records and small time-ordered
+indexes. Defaults are 5 MiB per serialized session, 256 MiB logical total and
+30 days retention. Capture and `cairn trajectory prune` remove expired records
+and then the oldest records needed to meet the logical budget. `prune
+--dry-run` reports the same decision without changing the database.
+
+## Capability callback storage
+
+Managed operating callbacks use two separate versioned KV namespaces inside
+the existing project-local `.agentfs/trajectory.db`:
+
+- `capability-callback/v1/pending/` contains bounded transient issuance
+  markers for operating starts.
+- `capability-callback/v1/record/` contains immutable retained final callback
+  records.
+
+No capability state exists in exact legacy master-off operation. With the
+master contract on, a target-enabled invocation creates no lease or final when
+either measurement consent is off. A target-disabled invocation still blocks
+before owner I/O in that unmeasured branch, but likewise writes no state. Only
+all three consents may create the recoverable lease and, for a disabled target,
+atomically settle it as exactly one value-free `disabled` final.
+
+An issuance marker contains only the strict operating-handle allow-list:
+schema version, capability/invocation/correlation identifiers,
+harness/source/transport classifications, start time, effective state source,
+and configuration digest. It contains no arguments, results, errors, paths,
+prompts, queries, secrets, or arbitrary metadata. A marker is not a trajectory
+session, trajectory start, or callback start record. It is consumed once by a
+matching finish or defensive invalidation and is never exposed as final
+callback evidence.
+
+Both namespaces are project-local state, not trajectory sessions: the existing
+`trajectory/v1` session envelopes, keys, indexes, CLI, and path are unchanged.
+There is no database migration, mirror, or second callback database. The file
+is created with mode `0600`; its SQLite `-wal` and `-shm` files remain in the
+same sensitive backup boundary.
+
+Each eligible completed invocation consumes its exact recoverable lease and
+appends one immutable final record in the same immediate transaction. This
+settlement is atomic and idempotent: duplicate success, error, timeout,
+disabled, or abandonment attempts cannot append or rewrite another final.
+Crash recovery and SessionEnd/plugin-disposal cleanup consume only unfinished
+leases as abandonment; they never replace a settled terminal. Callback age retention reuses
+`CAIRN_TRAJECTORY_RETENTION_DAYS` (default 30 days). Each namespace has an
+independent 10,000-record cap that prunes its oldest keys.
+Expired issuance is consumed without a final record, and a final record older
+than the current retention cutoff is not appended. Existing trajectory session
+byte limits and total-store accounting remain session contracts; callback
+state does not change their schema or path.
+
+The namespaces are strictly local. Stdio MCP callbacks, offline notes, and
+guarded local harness commands may persist final evidence only after all three
+consents pass. Pending issuance and final records are never redirected through
+HTTP or remote project storage. Authenticated HTTP callbacks are skipped:
+there is no remote/HTTP callback persistence, server-base-directory mapping,
+payload delivery, telemetry, export, or network delivery. Disabling logging
+stops future records, invalidates an already-issued operating marker at finish,
+and does not delete retained final rows.
+
+Default uninstall retains `.agentfs/trajectory.db` and its sidecars exactly.
+It removes the managed `.ai/capabilities.json` only after backing it up, and
+the generated `revert.sh` restores the exact bytes and mode. An explicit
+`cairn uninstall --purge-memory PROJECT` backs up and removes the entire
+project `.agentfs/` boundary, including trajectory sessions and callback rows;
+its `revert.sh` restores that boundary byte-for-byte. Back up the database and
+sidecars together while moving or inspecting a project.
+
+Hindsight notes are also separate derived data. They are human-readable
+Markdown below `notes/projects/` and `notes/shared/`, with a local schema-v1
+manifest and lock directories below `notes/.cairnkeep/`. Project paths are
+represented in visible filenames by readable slugs plus stable local hashes;
+the hidden local manifest retains the canonical project root needed for later
+all-project runs. Occurrence provenance is capped at 1024 entries per note and
+the processed-session ledger at 4096 digests per project. Note bodies do not
+expire automatically: inspect/delete them according to your own retention
+policy. Trajectory pruning does not delete already-derived notes.
+
+## Artifact storage
+
+Artifacts are deliberately separate from memory and trajectories. Local
+compaction hooks, recovery, operator commands, and stdio MCP tools use
+`<project>/.agentfs/artifacts.db` with restrictive permissions. Existing
+memory/trajectory databases are not migrated, rewritten, or mirrored into it.
+SQLite `-wal` and `-shm` sidecars share the same sensitive backup boundary.
+
+The schema-v1 authoritative rows are immutable full envelopes containing ID,
+kind, creation time, stable session reference, optional typed-node reference,
+media type, logical/stored bytes, digest, provenance, redaction/truncation
+metadata, optional supersession, and bounded content. Small derived namespaces
+hold created/session/kind indexes, request-dedupe bindings, monotonic
+`compaction/sequence/<session>` counters, and latest session/project pointers.
+Artifact indexes contain value-minimized metadata and references, never bodies.
+Full record, indexes, dedupe, counter, and pointer updates share one immediate
+transaction. An identical retry returns the existing ID; changed content
+appends a new immutable revision. Deleted revision numbers are never reused.
+
+Defaults are 1 MiB per artifact, 16 MiB per session, 256 MiB total, 30 days,
+eight compaction revisions per session, and a 256 KiB generated-file snapshot
+cap (or the lower artifact cap). Automatic retention applies age and revision
+limits, then removes the oldest eligible records to meet session/store budgets.
+It protects the newest valid project compaction. Explicit delete or
+`cairn artifact prune --include-protected` may remove that record. Hard delete
+removes content, indexes, dedupe rows, and affected pointers; there is no
+tombstone or hidden retained body.
+
+`cairn doctor` validates SQLite integrity, schema, authoritative envelopes and
+digests, derived indexes, dedupe state, revision pointers, and retention state.
+`--repair` rebuilds only safely derived indexes/dedupe/pointers from valid full
+records. Unsupported schema, invalid full records, digest mismatch, or SQLite
+corruption remains failed and untouched; preserve `.agentfs/artifacts.db` and
+its sidecars before manual inspection.
+
+Generated-file `path_label` values are contained project-relative labels only.
+They are never dereferenced by MCP, CLI, capture, doctor, or recovery. Binary
+or oversized candidates become metadata-only; optional inline text is bounded.
+
+For separately enabled HTTP artifact access, the server requires a validated
+`X-Cairn-Project` and derives the database under the server-side configured
+base directory as `${CAIRN_AGENTFS_BASE_DIR}/<project-id>/.agentfs/artifacts.db`.
+Clients cannot supply a filesystem path, and different project identities use
+separate derived roots. The bearer token still defines the trust domain.
+Neither `CAIRN_ARTIFACT_HTTP` nor remote memory registration redirects local
+compaction hooks or trajectories.
+Artifact backup follows the project `.agentfs/` backup boundary described below.
+
+## Evaluation report and note-snapshot storage
+
+Evaluation is disabled by default. When `CAIRN_EVAL` is explicitly enabled and
+an operator confirms a run, each experiment is stored below
+`<project>/.agentfs/eval/experiments/<experiment-id>/`. `report.json` is the
+canonical complete replacement checkpoint; it is rewritten atomically after
+schedule creation and every terminal, distillation, cancellation, and cleanup
+transition. An interrupted run therefore remains an inspectable `partial`
+report rather than an inferred success or failure.
+
+The eval root and experiment directories are mode `0700`; `report.json` is
+mode `0600`. A report is limited to 16 MiB by default (64 MiB is the hard
+implementation ceiling), and one root admits at most 10,000 experiment
+directories. Task sets contain at most 10,000 tasks and input/configuration
+files at most 4 MiB. Experiment-owned note snapshots live under
+`<experiment-id>/snapshots/`; one snapshot contains at most 10,000 files and
+16 MiB. Snapshot files are mode `0400` and their directories are made
+read-only after creation. Each Run 2 receives a separate read-only task-local
+copy; digests are checked before and after exposure.
+
+Reports contain versioned observations, reproducibility digests, optional
+metrics, populations, missingness, warnings, and strict component identifiers.
+Snapshots contain only the same task's distilled note files plus their
+relative-path/byte/digest manifest. Both remain sensitive local data even
+though prompts, model outputs, arbitrary stdout/stderr, environment snapshots,
+and secret values are structurally excluded from reports.
+
+There is no automatic age deletion. Operators inspect with `cairn eval report`,
+remove one validated contained experiment with `cairn eval delete`, or apply
+oldest-eligible removal with `cairn eval prune --older-than-days N` (default
+30 days). Both destructive commands have `--dry-run`; malformed, tampered,
+unsafe-mode, symlinked, or path-escaping trees fail closed. A hard delete or
+prune removes the selected experiment directory, including its report and note
+snapshots, without a hidden tombstone. Cancellation retains the partial report
+and completed snapshot checkpoints until one of these explicit operations or
+an uninstall purge removes them.
+
+Normal `cairn uninstall PROJECT` retains the entire `.agentfs/` tree, including
+evaluation reports and snapshots, byte-for-byte. `--dry-run` changes no file,
+mode, or directory entry. Explicit `cairn uninstall --purge-memory PROJECT`
+backs up the complete project `.agentfs/` boundary before removing it; the
+generated `revert.sh` restores the exact evaluation bytes, modes, and layout
+alongside adjacent project memory, trajectory, and artifact data. Evaluation
+has no separate destructive uninstall shortcut.
+
 When the memory server runs in the official container, the same rule applies:
 the process stores databases below `/data`, normally backed by the
 `cairnkeep-data` named volume. Replacing the container preserves that volume;
@@ -118,6 +296,80 @@ sqlite3 /path/to/project/.agentfs/project.db \
 Treat every database and export archive as sensitive. They may contain source
 paths, decisions, incident details, and other project context.
 
+The same backup boundary applies to `<project>/.agentfs/trajectory.db`, which
+is not included in `cairn memory export`. `cairn uninstall PROJECT` retains the
+whole `.agentfs/` directory by default. `cairn uninstall --purge-memory PROJECT`
+backs it up and removes it, including memory and trajectories; the generated
+`revert.sh` can restore it.
+
+The same boundary includes `<project>/.agentfs/artifacts.db` and its sidecars.
+`cairn memory export` does not include artifacts. Default uninstall retains the
+whole `.agentfs/` tree. `cairn uninstall --purge-memory PROJECT` backs it up
+before removal, and the generated `revert.sh` restores the exact durable bytes.
+No automatic export or migration of existing artifact stores is performed.
+
+The same boundary includes `<project>/.agentfs/eval/experiments/`. `cairn
+memory export` does not include reports or note snapshots. Default uninstall
+retains them; `--purge-memory PROJECT` backs them up with the whole project
+`.agentfs/` tree before removal, and the generated `revert.sh` restores their
+exact bytes, modes, and directory layout.
+
+Global hindsight notes share the `${CAIRN_AGENTFS_BASE_DIR}` durable-store
+boundary. `cairn uninstall` keeps them by default. `cairn uninstall
+--purge-memory` backs up and removes the entire boundary, including `notes/`,
+and the generated bundle's `revert.sh` restores the exact files. Back up both
+the global store and each project's `.agentfs/` when moving a complete setup;
+`cairn memory export` covers SQLite memory scopes, not the Markdown note tree.
+
+## Typed metadata, import replay, and history
+
+With `CAIRN_TYPED_MEMORY_NODES=1`, each concrete AgentFS database keeps raw
+live values in the existing `kv_store`. The same SQLite transaction stores
+only additive metadata in `cairn_node_metadata_v1` and optional import-ID
+bindings in `cairn_node_import_replays_v1`. A legacy row with no metadata is
+projected as schema-v1 type `memory` with no tags; reading it creates no table,
+row, cache, or rewritten value. There is no ORM or schema-push step: tables are
+created lazily only by enabled mutations.
+The public portable contract is `schemas/memory-node.schema.json`; matching
+runtime validation lives in the packaged server.
+
+Supersede, metadata-only supersede, reviewed changes, import replacement, and
+delete write complete value/type/tag snapshots under hidden `__history__` keys
+in the same immediate transaction. Delete removes the live metadata row but
+retains its final snapshot; recreating the key is supported. Import commit
+rechecks conflicts and replay inside one concrete store transaction. Dry-run
+does not create the database or metadata tables.
+
+SQLite backups and `cairn memory export` include metadata, replay bindings, and
+history. `cairn doctor` treats absent tables as healthy legacy state. Repair
+may remove provably orphaned derived metadata, but never rewrites raw KV,
+infers non-default types, discards corrupt authoritative metadata, or repairs
+a divergent replay digest.
+
+## Canonical note lifecycle and recovery
+
+Note address spaces remain file-backed. The canonical set includes Markdown
+leaves, `README.md` indexes, `.cairnkeep/manifest-v1.json`, typed history,
+`note-import-replays-v1.json`, and transaction directories below
+`notes/.cairnkeep/transactions/<transaction-id>/`. Create, supersede, delete,
+and import render immutable path/byte/pre-image/hash plans and install them
+through one journal primitive, with the manifest last. There is no AgentFS
+mirror and clients never supply filesystem paths.
+
+Staged same-filesystem bytes, backups, and a `prepared` journal are durable
+before live replacement. `committing` records completed paths; `committed`
+records intended final hashes. Any pending journal blocks later mutations.
+Doctor repair restores verified pre-images for prepared/committing state. For
+committed-before-cleanup state it verifies final hashes, preserves the completed
+operation, and removes only transaction artifacts. Failed verification leaves
+the journal and live state untouched; a committed operation is never treated
+as an uncommitted rollback candidate.
+
+Generated managed blocks may change, but unmarked maintainer bytes after the
+managed marker are preserved exactly. Default uninstall retains databases,
+note history, replay ledgers, and journals. `--purge-memory` uses the existing
+backup-first whole-store boundary; `revert.sh` restores their exact bytes.
+
 ## Reviewed-memory integration
 
 External review systems should not compose `memory_write`, `memory_read`, and

package/examples/eval/README.md

@@ -0,0 +1,42 @@
+# Offline evaluation fixture
+
+This directory contains Cairnkeep's deterministic, network-free evaluation
+population. It validates the evaluation framework; its designed differences are
+not performance, efficiency, quality, or live-product evidence.
+
+`task-set.json` is the immutable `cairn-offline-fake-v1` source. The loader
+requires its exact canonical bytes, the package version, and the SHA-256 digest
+recorded by `bundled-fake.json` before it creates a workspace. `adapter.json`
+selects the only executable adapter shipped by Cairnkeep,
+`scripts/fake-eval-adapter.mjs`. Live harness adapters remain explicit
+operator-owned program-plus-argument configurations.
+
+The coordinator sends one bounded JSON request on standard input. The fake
+emits exactly one schema-valid JSON result on standard output for ordinary
+cases and uses standard error only for value-free diagnostics. Requests include
+the task, arm, repetition, pass, seed, relative workspace/notes/output paths,
+limits, and expected capability digest. Results can include terminal adapter
+status, turn semantics, optional usage, component identities, the observed
+capability digest, and a task-local trajectory reference. The independent task
+verifier, never the adapter, assigns pass or fail.
+
+The population has ten stable tasks covering verified pass, verifier failure,
+missing tokens, successful note creation, no notes, distillation failure,
+skipped distillation, timeout, structured adapter error, invalid result, and a
+cancellation control. With one repetition the two-pass run estimates and then
+performs exactly 20 serial adapter invocations. Run 2 starts only after all ten
+Run 1 observations and offline distillation stages finish.
+
+Validate without invoking the adapter:
+
+```bash
+CAIRN_EVAL=1 node mcp-memory-server/dist/eval-cli.js validate \
+  --task-set examples/eval/task-set.json \
+  --adapter examples/eval/adapter.json \
+  --output .agentfs/eval/experiments --json
+```
+
+Run only in a disposable checkout when exercising the fixture directly. The
+result is always scoped as `offline-framework`; it cannot authorize a README or
+release claim. No provider, endpoint, credential, model service, or network
+default is included.

package/examples/eval/adapter.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "id": "cairn-offline-fake",
+  "command": {
+    "program": "../../scripts/fake-eval-adapter.mjs",
+    "args": []
+  },
+  "turn_semantics": {
+    "id": "offline-fixture-turn",
+    "description": "One deterministic fixture state transition; meaningful only for offline framework verification."
+  }
+}

package/examples/eval/bundled-fake.json

@@ -0,0 +1 @@
+{"identifier":"cairn-offline-fake-v1","package_version":"2.4.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/examples/eval/task-set.json

@@ -0,0 +1 @@
+{"id":"cairn-offline-fake-v1","schema_version":1,"source":{"files":[{"content":"cairn-offline-fixture-v1\n","path":"fixture.txt"}],"identifier":"cairn-offline-fake-v1","kind":"bundled_fake"},"tasks":[{"id":"offline-pass-note","input":"Produce one deterministic note-producing result.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(require('node:fs').existsSync('adapter-result.txt')?0:9)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-verifier-fail","input":"Produce a result rejected by the independent verifier.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(9)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-missing-tokens","input":"Omit optional usage fields.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(require('node:fs').existsSync('adapter-result.txt')?0:9)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-no-notes","input":"Close a trajectory with no distillable notes.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(require('node:fs').existsSync('adapter-result.txt')?0:9)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-distillation-failure","input":"Expose an exact but unreadable trajectory store.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(require('node:fs').existsSync('adapter-result.txt')?0:9)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-skipped-notes","input":"Complete without a trajectory reference.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(require('node:fs').existsSync('adapter-result.txt')?0:9)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-timeout","input":"Exceed the declared adapter timeout.","limits":{"elapsed_ms":100,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(0)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-adapter-error","input":"Return a structured adapter error.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(0)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-invalid-result","input":"Return a schema-invalid result.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(0)"],"program":"node"},"workspace":{"path":"."}},{"id":"offline-cancellation-control","input":"Complete normally unless the cancellation control is enabled.","limits":{"elapsed_ms":5000,"stdout_bytes":16384},"prepare":{"args":["-e","process.exit(require('node:fs').readFileSync('fixture.txt','utf8')==='cairn-offline-fixture-v1\\n'?0:8)"],"program":"node"},"verify":{"args":["-e","process.exit(require('node:fs').existsSync('adapter-result.txt')?0:9)"],"program":"node"},"workspace":{"path":"."}}]}

package/mcp-memory-server/dist/artifact-cli.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { getArtifactLimits } from "./artifact-schema.js";
+import { deleteArtifact, doctorArtifactStore, listArtifacts, pruneArtifacts, putArtifact, readArtifact, recordUnsupportedCompactionAdapter, } from "./artifact-store.js";
+import { normalizeClaudePostCompact, normalizeOpenCodeCompaction, renderCompactionRecovery, selectCompactionRecovery, } from "./compaction-normalize.js";
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+function usage() {
+    return `cairn artifact — local immutable artifacts
+
+Usage:
+  cairn artifact list [--kind K] [--session REF] [--json]
+  cairn artifact show <artifact-id-or-prefix> [--json]
+  cairn artifact delete <artifact-id-or-prefix> [--dry-run] [--json]
+  cairn artifact prune [--dry-run] [--include-protected] [--json]
+`;
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function option(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+function publicList(value) {
+    return {
+        ...value,
+        artifacts: value.artifacts.map(({ content: _content, ...artifact }) => artifact),
+    };
+}
+function humanList(value) {
+    if (value.artifacts.length === 0)
+        return "No local artifacts found.";
+    return `${value.artifacts.map((artifact) => [artifact.artifact_id, artifact.kind, artifact.session_ref, artifact.created_at, `${artifact.logical_bytes} bytes`].join("\t")).join("\n")}\n${value.artifacts.length} artifact(s), ${value.logical_bytes} logical bytes`;
+}
+function humanShow(value) {
+    return [
+        `Artifact: ${value.artifact_id}`,
+        `Kind: ${value.kind}`,
+        `Session: ${value.session_ref}`,
+        `Created: ${value.created_at}`,
+        `Digest: ${value.content_digest}`,
+        "",
+        JSON.stringify(value.content, null, 2),
+    ].join("\n");
+}
+function artifactInput(normalized) {
+    return {
+        kind: "compaction_summary",
+        session_ref: normalized.session_ref,
+        media_type: "text/markdown",
+        provenance: {
+            producer: normalized.harness === "claude-code" ? "claude-post-compact" : "opencode-session-compacted",
+            source_event: normalized.source_event,
+            harness: normalized.harness,
+            harness_version: normalized.harness_version,
+            ...("native_id" in normalized ? { native_id: normalized.native_id } : {}),
+        },
+        content: {
+            raw_summary: normalized.raw_summary,
+            ...normalized.projection,
+            trigger: normalized.trigger,
+        },
+    };
+}
+async function captureClaude(projectRoot, args) {
+    const harnessVersion = option(args, "--harness-version") ?? "unknown";
+    const normalized = normalizeClaudePostCompact(JSON.parse(await readStdin()), { harnessVersion });
+    if (!normalized) {
+        await recordUnsupportedCompactionAdapter(projectRoot, {
+            harness: "claude-code",
+            harness_version: harnessVersion === "unknown" ? undefined : harnessVersion,
+            reason: ["2.1.219", "2.1.220"].includes(harnessVersion) ? "invalid_shape" : "unsupported_version",
+        });
+        return;
+    }
+    await putArtifact(projectRoot, artifactInput(normalized));
+}
+async function captureOpenCode(projectRoot) {
+    const raw = JSON.parse(await readStdin());
+    const version = typeof raw.harness_version === "string"
+        ? raw.harness_version
+        : typeof raw.session?.version === "string"
+            ? String(raw.session.version) : "1.17.20";
+    const normalized = normalizeOpenCodeCompaction(raw.event, raw.session, raw.messages, { harnessVersion: version });
+    if (!normalized) {
+        await recordUnsupportedCompactionAdapter(projectRoot, { harness: "opencode", harness_version: version, reason: "unsupported_version" });
+        return;
+    }
+    await putArtifact(projectRoot, artifactInput(normalized));
+}
+async function recover(projectRoot, args) {
+    const listed = await listArtifacts(projectRoot, { kind: "compaction_summary" });
+    const selected = selectCompactionRecovery(listed.artifacts, {
+        currentSessionRef: option(args, "--session-ref"),
+        now: new Date(),
+        staleAfterSeconds: 86400,
+    });
+    if (!selected)
+        return;
+    process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(selected) : renderCompactionRecovery(selected)}${hasFlag(args, "--json") ? "\n" : ""}`);
+}
+async function main() {
+    const [command = "help", ...args] = process.argv.slice(2);
+    if (command === "capture-claude" || command === "capture-opencode") {
+        const projectRoot = args.find((arg) => !arg.startsWith("-"));
+        if (!projectRoot)
+            return;
+        try {
+            if (command === "capture-claude")
+                await captureClaude(projectRoot, args);
+            else
+                await captureOpenCode(projectRoot);
+        }
+        catch {
+            process.stderr.write("artifact capture skipped: local validation or persistence failed\n");
+        }
+        return;
+    }
+    try {
+        if (command === "list") {
+            const kind = option(args, "--kind");
+            const value = publicList(await listArtifacts(process.cwd(), { kind, session_ref: option(args, "--session") }));
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : humanList(value)}\n`);
+            return;
+        }
+        if (command === "show") {
+            const identifier = args.find((arg) => !arg.startsWith("-"));
+            if (!identifier)
+                throw new Error("show requires an artifact ID or unambiguous prefix.");
+            const value = await readArtifact(identifier, process.cwd());
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : humanShow(value)}\n`);
+            return;
+        }
+        if (command === "delete") {
+            const identifier = args.find((arg) => !arg.startsWith("-"));
+            if (!identifier)
+                throw new Error("delete requires an artifact ID or unambiguous prefix.");
+            const value = await deleteArtifact(identifier, process.cwd(), { dryRun: hasFlag(args, "--dry-run") });
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : `${value.deleted ? "Deleted" : "Would delete"} ${value.artifact_id}.`}\n`);
+            return;
+        }
+        if (command === "prune") {
+            const includeProtected = hasFlag(args, "--include-protected");
+            const value = await pruneArtifacts(process.cwd(), getArtifactLimits(), {
+                dryRun: hasFlag(args, "--dry-run"), includeProtected,
+            });
+            const output = { ...value, include_protected: includeProtected };
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(output) : `${value.dry_run ? "Would remove" : "Removed"} ${value.removed.length} artifact(s); ${value.remaining_artifacts} remain.`}\n`);
+            return;
+        }
+        if (command === "recover") {
+            const projectRoot = args.find((arg) => !arg.startsWith("-")) ?? process.cwd();
+            await recover(projectRoot, args);
+            return;
+        }
+        if (command === "doctor") {
+            const value = await doctorArtifactStore(process.cwd(), hasFlag(args, "--repair"));
+            process.stdout.write(`${JSON.stringify(value)}\n`);
+            if (!value.ok)
+                process.exitCode = 2;
+            return;
+        }
+        if (command === "help" || command === "--help" || command === "-h") {
+            process.stdout.write(usage());
+            return;
+        }
+        throw new Error(`unknown artifact command "${command}".`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "unknown error";
+        process.stderr.write(`cairn artifact: ${message}\n`);
+        process.exitCode = 2;
+    }
+}
+await main();