@cairnkeep/cli 2.9.0 → 2.11.0

package/docs/operating.md

@@ -7,20 +7,23 @@ Cairnkeep has three moving parts:
 
 1. **The memory server** (`cairn-memory`) — an MCP server your harness talks to.
 2. **The project scaffold** — `.ai/` launchers and the `.planning/` knowledge
-   layer, written by `cairn bootstrap`.
+   layer, written by `cairn setup` or the compatibility-oriented
+   `cairn bootstrap` primitive.
 3. **The operating layer** — the commands, agents, and hooks that live in your
    harness config and drive the workflow.
 
-`cairn bootstrap` only does step 2. Steps 1 and 3 are one-time-per-machine
-installs. This guide covers all three in order.
+`cairn setup` is the recommended project entry point. `cairn bootstrap`
+retains its established deterministic behavior for existing automation. Steps
+1 and 3 are one-time-per-machine installs; project setup reports the explicit
+sync command but never runs it automatically. This guide covers all three.
 
 ## Prerequisites
 
 - 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, launcher, and opt-in graph Skill; Qwen Code receives the memory
-  MCP and launcher. Pi receives its native trajectory adapter, graph prompt,
-  and launcher.
+  MCP and launcher. Pi receives a maintained local stdio MCP extension, native
+  trajectory adapter, graph prompt, and launcher after explicit machine sync.
 - 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
@@ -29,6 +32,12 @@ installs. This guide covers all three in order.
 - Optional: rootless Podman for the containerized memory server and isolated
   workspace base described in [Containers](containers.md).
 
+Native Windows x64 is supported directly from PowerShell or Command Prompt;
+WSL and Git Bash are not required. The npm package installs a Node entry point,
+and bootstrap emits `.cmd` plus PowerShell launchers. See
+[Native Windows operation](native-windows.md) for the exact setup and recovery
+contract. Windows ARM64 currently uses x64 emulation.
+
 ## Shell completion
 
 Generate completion definitions directly from the CLI:
@@ -37,12 +46,65 @@ Generate completion definitions directly from the CLI:
 cairn completion bash
 cairn completion zsh
 cairn completion fish
+cairn completion powershell
 ```
 
 Distributions can install these outputs into the platform's normal completion
 directories. They can also be loaded for the current shell, for example with
 `source <(cairn completion bash)`.
 
+In PowerShell, load completion for the current session with:
+
+```powershell
+Invoke-Expression (& cairn completion powershell | Out-String)
+```
+
+## Guided project setup
+
+Interactive terminals may run `cairn setup` and answer the target, Git,
+harness, memory, and confirmation questions. Automation must make every choice
+explicit:
+
+```bash
+cairn setup /path/to/project --git init --harness claude,pi --memory local --yes
+```
+
+The deterministic form accepts `--git init|existing|none`, a comma-separated
+subset of `claude,opencode,pi,kimi,qwen`, and `--memory local|none`. `--git
+existing` requires the target to be in an existing work tree. `--git init`
+requires Git and is the only non-interactive authorization to initialize a
+repository. `--git none` is an explicit limited mode: repository-aware features
+remain unavailable, and both setup output and `cairn doctor` say so. A missing
+or empty interactive target recommends initialization and asks before writing;
+an existing non-Git tree is never initialized silently.
+
+Setup first classifies the target and Git state without writing, then creates or
+reconciles only the selected project launchers and common scaffold assets.
+Identical managed files remain unchanged, changed managed files are updated,
+and unrelated files are preserved. The result reports created, updated,
+unchanged, and skipped counts; `cairn doctor`; an exact launcher per selected
+harness; and the deterministic setup command to use for recovery. `--json`
+returns the same schema-v1 result. The private mode-`0600`
+`.ai/cairnkeep.json` record stores the package version, Git and memory modes,
+selected harnesses, and digests/modes/template identifiers for setup-owned
+assets. It contains no credentials, endpoints, or absolute paths.
+
+Setup never installs or refreshes machine-level harness assets. Its
+`machine_sync.automatic` field is always false, and the human output labels the
+reported command as not run automatically. Apply the relevant machine command
+explicitly, check it, then diagnose and launch:
+
+```bash
+cairn sync --apply                    # Claude Code operating assets
+cairn sync-pi --apply                 # Pi extension and prompt
+cairn sync-pi --check
+cd /path/to/project && cairn doctor
+./.ai/start-pi.sh
+```
+
+`cairn bootstrap [--untracked] PATH` remains available for scripts that depend
+on its original scaffold and Git-exclusion contract.
+
 ## Setup order (Claude Code)
 
 The commands below install the default local topology: `cairn-memory` runs as a
@@ -206,8 +268,9 @@ cairn graph diff
 ```
 
 The same direct CLI works with Qwen Code, Codex, and other shell-capable
-clients. This does not add a Pi MCP bridge or imply that those harnesses receive
-the rest of Cairnkeep's operating layer.
+clients. Pi sync separately installs Cairnkeep's maintained local stdio MCP
+extension; the graph prompt remains a thin adapter and does not expand the rest
+of Pi's operating surface.
 
 All six modes delegate to `cairn graph`. Managed builds run Graphify's local
 code-only `update` path with provider credentials removed from the subprocess
@@ -217,6 +280,9 @@ so Graphify cannot re-index its own generated HTML/report/JSON. Managed builds
 do not perform Graphify's optional semantic document extraction. Prefer exact
 function, class, or file names; broad natural-language graph queries are less
 precise. Cairnkeep does not install or update Graphify automatically.
+Set `CAIRN_GRAPHIFY_BINARY` to override the `graphify` command when Graphify is
+installed at a specific path. Native executables run directly; `.js`, `.mjs`,
+and `.cjs` helpers run through the active Node runtime on every platform.
 
 Graphify also maintains an incremental `graphify-out/` work directory at the
 repository root. It is separate from Cairnkeep's published
@@ -299,26 +365,52 @@ configuration, approval behavior, and overlay guidance.
 
 ## Setup order (Pi)
 
-Pi trajectory capture uses the same project scaffold and store. Its sync also
-installs a thin `/graphify` prompt into Pi's agent root:
+Pi uses the same project scaffold and local memory store. Its explicit sync
+installs the maintained memory extension, native trajectory extension, and thin
+`/graphify` prompt into Pi's agent root:
 
 ```bash
 npm install -g @cairnkeep/cli
 cairn sync-pi --apply                    # default: ~/.pi/agent
-cairn bootstrap /path/to/project
+cairn setup /path/to/project --git init --harness pi --memory local --yes
 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.
+The memory extension starts `cairn memory-server` as a local stdio child from
+the project root. It dynamically discovers the effective server catalog, so
+feature gates, capability state, and the current MCP tool profile remain
+authoritative. It does not contain a second hard-coded catalog. Startup is
+bounded to 10 seconds, calls to 30 seconds, results to 4 MiB, and retained child
+stderr to the newest 16 KiB. Cancellation is propagated, child or protocol
+failure is surfaced, and session shutdown closes the child.
+
+Tool names, descriptions, input and output schemas, content,
+`structuredContent`, `_meta`, and failure behavior cross the bridge without
+semantic rewriting. The exact MCP annotations are preserved in the trusted Pi
+result `details`, together with the discovered tool metadata and original
+content. Pi 0.84.1 has no native annotations field in its public tool API, so
+Cairnkeep does not claim native model-facing annotation propagation or invent a
+substitute field.
+
+The bridge is tools-only: it does not run prompts, activate context-pack skills,
+create an autonomous loop, add remote access, or bypass server-side tool
+restrictions. Removing `MCP_HTTP_PORT` from the child environment deliberately
+keeps this integration on local stdio.
 
 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` and `prompts/graphify.md`; `cairn
-uninstall --pi-live-root DIR` removes those files backup-first and leaves every
-other Pi asset untouched.
+`extensions/cairnkeep-memory.ts`, `extensions/cairnkeep-trajectory.ts`, and
+`prompts/graphify.md`; `cairn doctor` reports a selected Pi extension that is
+missing or drifted and points to `cairn sync-pi --apply`. `cairn uninstall
+--pi-live-root DIR` removes those files backup-first and leaves every other Pi
+asset untouched.
+
+Pi 0.84.1 is the validated minimum supported version for this extension. The
+v2.11 release passed the complete setup and bridge matrix on separate Pi 0.84.1
+minimum and registry-current installations, Node.js 22, 24, and 26, Bash 3.2,
+and native Windows. The two Pi executable paths differed, while both reported
+0.84.1 because that was also the registry-current release.
 
 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
@@ -381,6 +473,7 @@ vendor or host.
 | `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_GRAPHIFY_BINARY` | Optional Graphify command/path override; JavaScript helpers run through the active Node runtime (default `graphify` from `PATH`) |
 | `CAIRN_EXPLORE_BINARY` | Absolute path to the `token_miser` binary used by `context_explore` (unset → the tool throws at call time) |
 | `CAIRN_EXPLORE_REPO_ROOT` | Default repo root for `context_explore` when no per-call `repo_root` is given (unset + no param → the tool throws) |
 | `CAIRN_EXPLORE_CACHE` | Caches `context_explore` results keyed on query + repo HEAD + dirty-state; default ON, set to `0` to disable |
@@ -809,6 +902,13 @@ 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.
 
+When `.ai/cairnkeep.json` exists, doctor also validates its private state,
+selected assets, digests, and modes. It reports `limited` for explicit
+`--git none`, fails an incomplete or drifted setup with the recorded
+deterministic `cairn setup` recovery command, and checks the Pi machine
+extension when Pi was selected. `cairn sync-pi --apply` repairs that
+machine-level drift; setup itself never performs the sync.
+
 ### Evaluation harness (opt-in)
 
 `cairn eval` is a local, serial experiment coordinator. It is disabled unless
@@ -897,8 +997,9 @@ 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.
+process group with TERM then bounded KILL escalation. Native Windows targets
+the adapter and its descendant tree with `taskkill.exe /T`, escalating to `/F`
+after the bounded grace period.
 
 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)

package/docs/privacy-and-data-flow.md

@@ -36,6 +36,8 @@ request unless the corresponding endpoint and credential are configured.
 | Automatic compaction recovery | None | Structured categories are injected locally; raw summary and other bodies are excluded |
 | Explicit artifact read/show | The redacted body only when HTTP is separately enabled and the operator/client explicitly reads it | Local terminal/stdio, or the explicitly registered authenticated server |
 | Opt-in evaluation coordinator | Adapter-defined inference may leave the machine only according to the explicit operator-owned adapter and inherited environment | Local adapter subprocess; Cairnkeep supplies no provider, endpoint, credential, model, or network default |
+| Guided project setup | None | Selected scaffold assets and private `.ai/cairnkeep.json` state in the target; machine sync is never automatic |
+| Pi memory extension | None | Local `cairn memory-server` stdio child; no HTTP transport is inherited |
 
 Model endpoints may be local or remote. Cairnkeep cannot determine a provider's
 retention, training, or logging policy; verify it before sending confidential
@@ -91,6 +93,35 @@ and its generated `revert.sh` restores exact bytes, modes, and layout. Explicit
 `cairn eval delete` and `prune` remove selected contained experiment trees with
 no hidden tombstone.
 
+## Guided setup and Pi bridge
+
+Guided setup performs a read-only target and Git preflight before project
+writes. Its schema-v1 `.ai/cairnkeep.json` record contains the package version,
+Git and memory choices, selected harness names, and setup-owned asset paths,
+digests, modes, and template identifiers. It does not contain credentials,
+endpoints, absolute paths, prompts, or memory values. The file is mode `0600`
+on POSIX and receives the private managed-file ACL on native Windows. Setup
+never invokes machine sync, and it does not start a harness or server child.
+
+When the explicitly installed Pi memory extension starts a session, it spawns
+`cairn memory-server` as a child in the project directory over local stdio. The
+bridge removes `MCP_HTTP_PORT` from the child environment, retains only the
+newest 16 KiB of child stderr for bounded failure diagnostics, caps startup,
+calls, catalogs, and results, and closes the child at shutdown. The child still
+inherits the remaining operator environment needed by the normal local server,
+so those environment values and the project directory are a child-process trust
+boundary even though they are not persisted by the bridge.
+
+Catalog and call replay is allow-listed to MCP tool metadata and result fields.
+Names, schemas, annotations, content, `structuredContent`, `_meta`, and error
+state are preserved without sanitizing away protocol meaning; Pi receives the
+annotations in trusted result `details` because Pi 0.84.1 has no native
+annotations field. The bridge does not log requests or results, create a second
+catalog, activate prompts or skills, add remote access, or persist a transcript.
+Sanitized test replay uses synthetic tool arguments, results, stderr, and
+project paths only; release evidence must not include credentials, private
+endpoints, memory values, or identifying local paths.
+
 ## Evaluation adapter and report flow
 
 `CAIRN_EVAL` is unset/off by default. With it off, `cairn eval` returns a fixed
@@ -169,7 +200,9 @@ network-free, and permanently scoped as framework-only evidence.
 SIGINT/SIGTERM stops new schedule admission, terminates the active adapter,
 checkpoints cancellation, performs bounded cleanup, and retains a partial
 report. POSIX process groups receive TERM followed by bounded KILL escalation.
-There is no Windows descendant-process-tree termination guarantee.
+Native Windows uses `taskkill.exe /T` for the exact child tree and `/F` for
+bounded force escalation; it does not enumerate or terminate unrelated
+processes.
 
 Turns aggregate only under exact matching compatibility IDs. Missing token
 components/totals, unknown verifier outcomes, incompatible turn semantics, and

package/docs/storage.md

@@ -31,6 +31,17 @@ For the local launchers, the server working directory is normally the project
 root. Bootstrap installs `.agentfs/.gitignore` so private project memory is not
 accidentally committed. SQLite may also create `-wal` and `-shm` sidecar files.
 
+Private-file protection is platform-equivalent rather than mode-identical.
+Linux and macOS use `0600` files and `0700` directories. Native Windows removes
+inherited ACLs and grants access only to the current SID, Local System, and the
+built-in Administrators group. `cairn doctor` fails closed when a managed MCP
+profile or context-pack pointer has broader access. Context-pack objects also
+receive a read-only attribute after their content digest is verified.
+
+Where this document names a generated `revert.sh`, native Windows produces the
+equivalent backup manifest and `revert.ps1`; it restores exact bytes and the
+Windows ACL contract rather than emulating POSIX mode bits.
+
 `CAIRN_LLM_API_URL` and `CAIRN_MEMORY_EMBEDDING_URL` select optional model
 services used to process/search memory. They do not change where the SQLite
 databases are stored. Git-provider and routing configuration do not change
@@ -502,8 +513,9 @@ bearer_token_env_var = "CAIRN_MEMORY_HTTP_TOKEN"
 Context-pack objects are content-addressed, immutable directories. Installation
 copies verified content through a temporary directory and atomically publishes
 the digest; a failed or concurrent install never changes project enablement.
-Project pointers are separate atomic mode-`0600` files keyed by canonical local
-project identity or a validated remote project ID. Updates retain old objects
+Project pointers are separate atomic private files (`0600` on POSIX, restricted
+ACLs on Windows) keyed by canonical local project identity or a validated
+remote project ID. Updates retain old objects
 and switch only the named project after exact-digest confirmation.
 
 `cairn doctor` verifies objects, pointers, and interrupted-install remnants.

package/examples/eval/bundled-fake.json

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

package/mcp-memory-server/dist/artifact-store-windows-worker.js

@@ -0,0 +1,74 @@
+import { AgentFS } from "agentfs-sdk";
+import { deleteArtifactForWindowsWorker, doctorArtifactStore, getArtifactDbPath, listArtifacts, pruneArtifactsForWindowsWorker, putArtifact, readArtifact, readLatestCompaction, recordUnsupportedCompactionAdapter, } from "./artifact-store.js";
+async function readRequest() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    if (!parsed || typeof parsed.operation !== "string" || typeof parsed.projectRoot !== "string") {
+        throw new Error("Invalid Windows artifact worker request.");
+    }
+    return parsed;
+}
+function resolvedOptions(options = {}) {
+    const { now, ...rest } = options;
+    return { ...rest, ...(now ? { now: new Date(now) } : {}) };
+}
+async function rawOperation(request) {
+    const agent = await AgentFS.open({ id: "artifacts", path: getArtifactDbPath(request.projectRoot) });
+    try {
+        if (request.action === "list")
+            return await agent.kv.list(request.prefix ?? "");
+        if (request.action === "get")
+            return await agent.kv.get(request.key ?? "");
+        if (request.action === "set") {
+            await agent.kv.set(request.key ?? "", request.value);
+            return null;
+        }
+        if (request.action === "delete") {
+            await agent.kv.delete(request.key ?? "");
+            return null;
+        }
+        throw new Error("Unsupported raw Windows artifact operation.");
+    }
+    finally {
+        await agent.close();
+    }
+}
+async function dispatch(request) {
+    const limits = request.limits;
+    if (request.operation === "put" && limits) {
+        return { result: await putArtifact(request.projectRoot, request.candidate, limits, resolvedOptions(request.options)) };
+    }
+    if (request.operation === "read" && request.identifier) {
+        return { result: await readArtifact(request.identifier, request.projectRoot) };
+    }
+    if (request.operation === "list") {
+        return { result: await listArtifacts(request.projectRoot, request.filters) };
+    }
+    if (request.operation === "latest") {
+        return { result: await readLatestCompaction(request.projectRoot, request.sessionRef) };
+    }
+    if (request.operation === "delete" && request.identifier) {
+        return deleteArtifactForWindowsWorker(request.identifier, request.projectRoot, request.options);
+    }
+    if (request.operation === "prune" && limits) {
+        return pruneArtifactsForWindowsWorker(request.projectRoot, limits, resolvedOptions(request.options));
+    }
+    if (request.operation === "record-unsupported") {
+        await recordUnsupportedCompactionAdapter(request.projectRoot, request.diagnostic);
+        return { result: null };
+    }
+    if (request.operation === "doctor" && limits) {
+        return { result: await doctorArtifactStore(request.projectRoot, request.repair, limits) };
+    }
+    if (request.operation === "raw")
+        return { result: await rawOperation(request) };
+    throw new Error("Unsupported Windows artifact worker operation.");
+}
+dispatch(await readRequest())
+    .then((response) => process.stdout.write(JSON.stringify(response)))
+    .catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});