@cairnkeep/cli 2.12.0 → 2.13.1

package/docs/work-evidence.md

@@ -0,0 +1,80 @@
+# Git-linked work evidence
+
+Cairnkeep can record a bounded, local account of the Git state surrounding a
+harness session. The feature is off by default. Enable it in the project's
+`.ai/.env`:
+
+```sh
+CAIRN_WORK_EVIDENCE=1
+```
+
+Generated Claude Code, OpenCode, Pi, Kimi, Qwen and Codex launchers then start
+an evidence record before the harness and settle it after the harness exits.
+The harness still launches when Git is unavailable, the directory is not a Git
+worktree, or evidence capture fails; Cairnkeep prints a warning instead of
+turning optional evidence into an availability dependency.
+
+## Recorded metadata
+
+Each completed record contains the harness, start/end timestamps, exit status,
+repository-relative identity, and the start/end commit, branch, detached or
+unborn state, dirty state, status digest and workspace digest. It also contains
+a bounded list of paths whose observed state changed during the session and an
+overall evidence digest.
+
+Workspace digests are content-derived, including for observed untracked files.
+They do not retain file bodies, but low-entropy candidate content can sometimes
+be tested against a known digest; do not treat hashing as redaction.
+
+Records may link to exact trajectories, artifacts and reviewed-memory writes
+created while that launcher-owned session is active. Links are append-only and
+carry identifiers, not copied content. Cairnkeep does not capture keystrokes,
+prompts, shell history or model reasoning.
+
+The record describes a time interval, not authorship. Concurrent processes can
+change the same worktree, and a file changed and restored to its starting state
+will not appear as touched. Treat the evidence as integrity-linked operational
+context, not proof that a particular person or model made a change.
+
+## Optional patch artifact
+
+Patch capture requires two independent feature flags:
+
+```sh
+CAIRN_WORK_EVIDENCE_PATCH=1
+CAIRN_ARTIFACT_STORE=1
+```
+
+The patch is produced at session end from the starting commit to the ending
+worktree. It can therefore include tracked changes that already existed when
+the session started. Untracked file names can appear in metadata, but their
+bodies are not included. The patch is redacted, bounded by the lower of the
+work-evidence and artifact limits, and stored in the existing artifact store.
+Cairnkeep provides no patch apply, restore or replay command.
+
+## Inspect and maintain
+
+```sh
+cairn evidence list [--status pending|complete] [--json]
+cairn evidence show <evidence-id-or-prefix> [--json]
+cairn evidence delete <evidence-id-or-prefix> [--dry-run] [--json]
+cairn evidence prune [--dry-run] [--json]
+cairn evidence doctor [--repair] [--json]
+```
+
+Metadata and links live below
+`<repository>/.agentfs/work-evidence/v1/`. Records default to 30-day retention,
+1 MiB per optional patch, 4,096 touched paths and a 64 MiB metadata budget.
+Interrupted sessions remain visibly pending rather than being fabricated as
+complete. `doctor` reports malformed records, broken links, permission drift,
+temporary remnants and stale pending sessions. `--repair` can remove temporary
+remnants, but it does not change records or invent an ending Git state.
+
+With the feature enabled, local stdio MCP registers `work_evidence_list` and
+`work_evidence_read`. Both are read-only, non-destructive, idempotent and
+closed-world. They are never exposed by the HTTP transport. MCP profiles can
+further restrict them, but cannot enable the feature.
+
+Ordinary uninstall retains the project `.agentfs` boundary. As with other
+project evidence stores, `cairn uninstall --purge-memory` backs up and removes
+it only after explicit confirmation.

package/examples/eval/bundled-fake.json

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

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

@@ -82,7 +82,9 @@ async function captureClaude(projectRoot, args) {
         });
         return;
     }
-    await putArtifact(projectRoot, artifactInput(normalized));
+    const result = await putArtifact(projectRoot, artifactInput(normalized));
+    const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
+    await linkActiveWorkEvidence(projectRoot, { kind: "artifact", artifact_id: result.artifact.artifact_id });
 }
 async function captureOpenCode(projectRoot) {
     const raw = JSON.parse(await readStdin());
@@ -95,7 +97,9 @@ async function captureOpenCode(projectRoot) {
         await recordUnsupportedCompactionAdapter(projectRoot, { harness: "opencode", harness_version: version, reason: "unsupported_version" });
         return;
     }
-    await putArtifact(projectRoot, artifactInput(normalized));
+    const result = await putArtifact(projectRoot, artifactInput(normalized));
+    const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
+    await linkActiveWorkEvidence(projectRoot, { kind: "artifact", artifact_id: result.artifact.artifact_id });
 }
 async function recover(projectRoot, args) {
     const listed = await listArtifacts(projectRoot, { kind: "compaction_summary" });

package/mcp-memory-server/dist/index.js

@@ -20,6 +20,7 @@ import { attachNodeMetadata, applyReviewedTypedNode, commitMemoryImport, createT
 import { contextPackHttpEnabled, contextPacksEnabled, listVisibleContext, readVisibleContext, searchVisibleContext } from "./context-pack.js";
 import { metadataForTool } from "./mcp-tool-catalog.js";
 import { profileAllowsTool, resolveMcpToolProfile } from "./mcp-tool-profile.js";
+import { isWorkEvidenceEnabled } from "./work-evidence-schema.js";
 const MINIMUM_NODE_MAJOR = 22;
 const nodeMajor = Number.parseInt(process.versions.node, 10);
 if (!Number.isInteger(nodeMajor) || nodeMajor < MINIMUM_NODE_MAJOR) {
@@ -871,6 +872,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
     const typedNodesEnabled = isTypedMemoryNodesEnabled();
     const artifactToolsEnabled = isArtifactStoreEnabled() && (!context.remote || isArtifactHttpEnabled());
     const contextPackToolsEnabled = contextPacksEnabled() && (!context.remote || contextPackHttpEnabled());
+    const workEvidenceToolsEnabled = isWorkEvidenceEnabled() && !context.remote;
     if (artifactToolsEnabled && context.remote && !context.projectId) {
         throw new ClientContextError("Remote artifact access requires X-Cairn-Project.");
     }
@@ -936,6 +938,8 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             const { putArtifact } = await import("./artifact-store.js");
             const result = await putArtifact(projectRoot, { ...input, session_ref: sessionRef });
             const artifact = result.artifact;
+            const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
+            await linkActiveWorkEvidence(projectRoot, { kind: "artifact", artifact_id: artifact.artifact_id });
             const payload = {
                 schema_version: artifact.schema_version,
                 artifact_id: artifact.artifact_id,
@@ -1506,6 +1510,8 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
                     snapshot_key: snapshotKey,
                 };
             });
+            const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
+            await linkActiveWorkEvidence(process.cwd(), { kind: "reviewed_memory", scope, review_id, key });
             return {
                 content: [{ type: "text", text: asToolText(payload) }],
                 structuredContent: payload,
@@ -1929,6 +1935,27 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
         });
     }
+    if (workEvidenceToolsEnabled) {
+        registerTool("work_evidence_list", {
+            description: "List bounded local Git-linked work-evidence records for this project.",
+            inputSchema: z.object({
+                status: z.enum(["pending", "complete"]).optional(),
+                limit: z.number().int().min(1).max(100).optional(),
+            }).strict(),
+        }, async ({ status, limit }) => {
+            const { listWorkEvidence } = await import("./work-evidence-store.js");
+            const payload = listWorkEvidence(process.cwd(), { status, limit });
+            return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
+        });
+        registerTool("work_evidence_read", {
+            description: "Read one local Git-linked work-evidence record by exact ID or unambiguous prefix.",
+            inputSchema: z.object({ evidence_id: z.string().min(4).max(40).regex(/^wev_[0-9a-f-]*$/i) }).strict(),
+        }, async ({ evidence_id }) => {
+            const { readWorkEvidence } = await import("./work-evidence-store.js");
+            const payload = readWorkEvidence(evidence_id, process.cwd());
+            return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
+        });
+    }
     return server;
 }
 function createMemoryServer(context = {}) {

package/mcp-memory-server/dist/mcp-tool-catalog.js

@@ -35,6 +35,8 @@ export const MCP_TOOL_CATALOG = {
     context_pack_list: observation("List context packs"),
     context_pack_search: observation("Search context packs"),
     context_pack_read: observation("Read context pack file"),
+    work_evidence_list: observation("List work evidence"),
+    work_evidence_read: observation("Read work evidence"),
 };
 export const MCP_TOOL_NAMES = Object.freeze(Object.keys(MCP_TOOL_CATALOG));
 export function isCairnToolName(value) {

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

@@ -62,7 +62,9 @@ async function captureClaude(args) {
     const normalized = await normalizeClaudeTranscript(transcriptPath, projectRoot);
     const redacted = redactTrajectory(normalized, projectRoot);
     const fitted = fitTrajectoryToBytes(redacted, limits.sessionMaxBytes);
-    await putTrajectory(projectRoot, fitted, limits);
+    const stored = await putTrajectory(projectRoot, fitted, limits);
+    const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
+    await linkActiveWorkEvidence(projectRoot, { kind: "trajectory", trajectory_id: stored.session_id });
 }
 async function captureOpenCode(args) {
     const [projectRoot] = args;
@@ -72,7 +74,9 @@ async function captureOpenCode(args) {
     const normalized = normalizeOpenCodeSession(JSON.parse(await readStdin()), projectRoot);
     const redacted = redactTrajectory(normalized, projectRoot);
     const fitted = fitTrajectoryToBytes(redacted, limits.sessionMaxBytes);
-    await putTrajectory(projectRoot, fitted, limits);
+    const stored = await putTrajectory(projectRoot, fitted, limits);
+    const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
+    await linkActiveWorkEvidence(projectRoot, { kind: "trajectory", trajectory_id: stored.session_id });
 }
 async function capturePi(args) {
     const [projectRoot] = args;
@@ -82,7 +86,9 @@ async function capturePi(args) {
     const normalized = normalizePiSession(JSON.parse(await readStdin()), projectRoot);
     const redacted = redactTrajectory(normalized, projectRoot);
     const fitted = fitTrajectoryToBytes(redacted, limits.sessionMaxBytes);
-    await putTrajectory(projectRoot, fitted, limits);
+    const stored = await putTrajectory(projectRoot, fitted, limits);
+    const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
+    await linkActiveWorkEvidence(projectRoot, { kind: "trajectory", trajectory_id: stored.session_id });
 }
 async function main() {
     const [command = "help", ...args] = process.argv.slice(2);

package/mcp-memory-server/dist/work-evidence-cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { workEvidenceHarnessSchema } from "./work-evidence-schema.js";
+import { activeEvidenceEnvironment, deleteWorkEvidence, doctorWorkEvidence, finishWorkEvidence, listWorkEvidence, pruneWorkEvidence, readWorkEvidence, startWorkEvidence, } from "./work-evidence-store.js";
+import { getWorkEvidenceLimits, isWorkEvidenceEnabled } from "./work-evidence-schema.js";
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+function usage() {
+    return `cairn evidence — opt-in local Git-linked work evidence
+
+Usage:
+  cairn evidence list [--status pending|complete] [--json]
+  cairn evidence show <evidence-id-or-prefix> [--json]
+  cairn evidence delete <evidence-id-or-prefix> [--dry-run] [--json]
+  cairn evidence prune [--dry-run] [--json]
+  cairn evidence doctor [--repair] [--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;
+}
+function humanList(value) {
+    if (value.evidence.length === 0)
+        return "No local work evidence found.";
+    return value.evidence.map((row) => [row.evidence_id, row.status, row.harness, row.started_at, `${row.links.length} links`].join("\t")).join("\n");
+}
+async function runHarness(args) {
+    const separator = args.indexOf("--");
+    const harness = workEvidenceHarnessSchema.parse(option(args.slice(0, separator < 0 ? args.length : separator), "--harness"));
+    const command = separator >= 0 ? args[separator + 1] : undefined;
+    const commandArgs = separator >= 0 ? args.slice(separator + 2) : [];
+    if (!command)
+        throw new Error("run requires --harness NAME -- COMMAND [ARG...].");
+    let evidence;
+    if (isWorkEvidenceEnabled()) {
+        try {
+            evidence = startWorkEvidence(process.cwd(), harness);
+        }
+        catch {
+            process.stderr.write("cairn evidence: capture unavailable; launching without work evidence\n");
+        }
+    }
+    const env = evidence ? { ...process.env, ...activeEvidenceEnvironment(evidence, process.cwd()) } : process.env;
+    const result = spawnSync(command, commandArgs, { cwd: process.cwd(), env, stdio: "inherit", shell: false, windowsHide: false });
+    const signalNumber = result.signal ? osConstants.signals[result.signal] : undefined;
+    const status = result.status ?? (signalNumber ? 128 + signalNumber : 1);
+    if (evidence) {
+        try {
+            await finishWorkEvidence(process.cwd(), evidence.evidence_id, status);
+        }
+        catch {
+            process.stderr.write("cairn evidence: final capture failed; the evidence remains pending\n");
+        }
+    }
+    if (result.error)
+        throw result.error;
+    process.exitCode = status;
+}
+async function main() {
+    const [command = "help", ...args] = process.argv.slice(2);
+    try {
+        if (command === "run") {
+            await runHarness(args);
+            return;
+        }
+        if (command === "list") {
+            const status = option(args, "--status");
+            if (status && !["pending", "complete"].includes(status))
+                throw new Error("--status must be pending or complete.");
+            const value = listWorkEvidence(process.cwd(), { status });
+            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 evidence ID or unambiguous prefix.");
+            const value = readWorkEvidence(identifier, process.cwd());
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : JSON.stringify(value, null, 2)}\n`);
+            return;
+        }
+        if (command === "delete") {
+            const identifier = args.find((arg) => !arg.startsWith("-"));
+            if (!identifier)
+                throw new Error("delete requires an evidence ID or unambiguous prefix.");
+            const value = deleteWorkEvidence(identifier, process.cwd(), hasFlag(args, "--dry-run"));
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : `${value.dry_run ? "Would delete" : "Deleted"} ${value.evidence_id}.`}\n`);
+            return;
+        }
+        if (command === "prune") {
+            const value = pruneWorkEvidence(process.cwd(), getWorkEvidenceLimits(), { dryRun: hasFlag(args, "--dry-run") });
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : `${value.dry_run ? "Would remove" : "Removed"} ${value.removed.length} evidence record(s).`}\n`);
+            return;
+        }
+        if (command === "doctor") {
+            const value = doctorWorkEvidence(process.cwd(), hasFlag(args, "--repair"));
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : JSON.stringify(value, null, 2)}\n`);
+            if (!value.ok)
+                process.exitCode = 2;
+            return;
+        }
+        if (["help", "--help", "-h"].includes(command)) {
+            process.stdout.write(usage());
+            return;
+        }
+        throw new Error(`unknown evidence command "${command}".`);
+    }
+    catch (error) {
+        process.stderr.write(`cairn evidence: ${error instanceof Error ? error.message : "unknown error"}\n`);
+        process.exitCode = 2;
+    }
+}
+await main();

package/mcp-memory-server/dist/work-evidence-schema.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+export const WORK_EVIDENCE_SCHEMA_VERSION = 1;
+export const WORK_EVIDENCE_HARNESSES = ["claude", "opencode", "pi", "kimi", "qwen", "codex"];
+export const WORK_EVIDENCE_DEFAULT_RETENTION_DAYS = 30;
+export const WORK_EVIDENCE_DEFAULT_STORE_MAX_BYTES = 64 * 1024 * 1024;
+export const WORK_EVIDENCE_DEFAULT_MAX_TOUCHED_PATHS = 4096;
+export const WORK_EVIDENCE_DEFAULT_PATCH_MAX_BYTES = 1024 * 1024;
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const commitSchema = z.string().regex(/^[a-f0-9]{40,64}$/);
+const safeRefSchema = z.string().min(1).max(512).refine((value) => !/[\u0000-\u001f\u007f]/.test(value));
+const pathLabelSchema = z.string().min(1).max(4096).refine((value) => (!value.startsWith("/")
+    && !value.includes("\\")
+    && !value.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+    && !/[\u0000-\u001f\u007f]/.test(value)), "Touched paths must be safe repository-relative labels.");
+export const workEvidenceIdSchema = z.string().regex(/^wev_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+export const workEvidenceHarnessSchema = z.enum(WORK_EVIDENCE_HARNESSES);
+export const gitEvidenceSnapshotSchema = z.object({
+    head_commit: commitSchema.nullable(),
+    branch: safeRefSchema.nullable(),
+    detached: z.boolean(),
+    unborn: z.boolean(),
+    dirty: z.boolean(),
+    status_digest: digestSchema,
+    workspace_diff_digest: digestSchema,
+}).strict();
+const pathFingerprintSchema = z.object({
+    path: pathLabelSchema,
+    state_digest: digestSchema,
+}).strict();
+export const pendingWorkEvidenceSchema = z.object({
+    schema_version: z.literal(WORK_EVIDENCE_SCHEMA_VERSION),
+    evidence_id: workEvidenceIdSchema,
+    status: z.literal("pending"),
+    harness: workEvidenceHarnessSchema,
+    started_at: z.iso.datetime(),
+    start: gitEvidenceSnapshotSchema,
+    path_fingerprints: z.array(pathFingerprintSchema).max(WORK_EVIDENCE_DEFAULT_MAX_TOUCHED_PATHS),
+}).strict();
+export const workEvidencePatchSchema = z.object({
+    requested: z.boolean(),
+    scope: z.literal("end-worktree-vs-start-commit").nullable(),
+    artifact_id: z.string().regex(/^art_[0-9a-f-]{36}$/i).nullable(),
+    unavailable_reason: z.enum([
+        "not-requested",
+        "artifact-store-disabled",
+        "unborn-start",
+        "unchanged",
+        "capture-failed",
+    ]).nullable(),
+}).strict();
+export const completeWorkEvidenceSchema = z.object({
+    schema_version: z.literal(WORK_EVIDENCE_SCHEMA_VERSION),
+    evidence_id: workEvidenceIdSchema,
+    status: z.literal("complete"),
+    harness: workEvidenceHarnessSchema,
+    started_at: z.iso.datetime(),
+    ended_at: z.iso.datetime(),
+    exit_status: z.number().int().min(0).max(255),
+    start: gitEvidenceSnapshotSchema,
+    end: gitEvidenceSnapshotSchema,
+    touched_paths: z.array(pathLabelSchema).max(WORK_EVIDENCE_DEFAULT_MAX_TOUCHED_PATHS),
+    omitted_touched_paths: z.number().int().nonnegative(),
+    change_digest: digestSchema,
+    patch: workEvidencePatchSchema,
+}).strict();
+export const workEvidenceLinkSchema = z.discriminatedUnion("kind", [
+    z.object({
+        schema_version: z.literal(WORK_EVIDENCE_SCHEMA_VERSION),
+        link_id: digestSchema,
+        evidence_id: workEvidenceIdSchema,
+        kind: z.literal("trajectory"),
+        created_at: z.iso.datetime(),
+        trajectory_id: safeRefSchema,
+    }).strict(),
+    z.object({
+        schema_version: z.literal(WORK_EVIDENCE_SCHEMA_VERSION),
+        link_id: digestSchema,
+        evidence_id: workEvidenceIdSchema,
+        kind: z.literal("artifact"),
+        created_at: z.iso.datetime(),
+        artifact_id: z.string().regex(/^art_[0-9a-f-]{36}$/i),
+    }).strict(),
+    z.object({
+        schema_version: z.literal(WORK_EVIDENCE_SCHEMA_VERSION),
+        link_id: digestSchema,
+        evidence_id: workEvidenceIdSchema,
+        kind: z.literal("reviewed_memory"),
+        created_at: z.iso.datetime(),
+        scope: safeRefSchema,
+        review_id: safeRefSchema,
+        key: safeRefSchema,
+    }).strict(),
+]);
+export const storedWorkEvidenceSchema = z.discriminatedUnion("status", [pendingWorkEvidenceSchema, completeWorkEvidenceSchema]);
+function truthy(value) {
+    return /^(?:1|true|yes|on)$/i.test(value?.trim() ?? "");
+}
+function integerSetting(name, fallback, minimum) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        throw new Error(`${name} must be an integer greater than or equal to ${minimum}.`);
+    }
+    return value;
+}
+export function isWorkEvidenceEnabled(value = process.env.CAIRN_WORK_EVIDENCE) {
+    return truthy(value);
+}
+export function isWorkEvidencePatchEnabled(value = process.env.CAIRN_WORK_EVIDENCE_PATCH) {
+    return truthy(value);
+}
+export function getWorkEvidenceLimits() {
+    return {
+        retentionDays: integerSetting("CAIRN_WORK_EVIDENCE_RETENTION_DAYS", WORK_EVIDENCE_DEFAULT_RETENTION_DAYS, 0),
+        storeMaxBytes: integerSetting("CAIRN_WORK_EVIDENCE_STORE_MAX_BYTES", WORK_EVIDENCE_DEFAULT_STORE_MAX_BYTES, 1024),
+        maxTouchedPaths: Math.min(integerSetting("CAIRN_WORK_EVIDENCE_MAX_TOUCHED_PATHS", WORK_EVIDENCE_DEFAULT_MAX_TOUCHED_PATHS, 1), WORK_EVIDENCE_DEFAULT_MAX_TOUCHED_PATHS),
+        patchMaxBytes: integerSetting("CAIRN_WORK_EVIDENCE_PATCH_MAX_BYTES", WORK_EVIDENCE_DEFAULT_PATCH_MAX_BYTES, 1024),
+    };
+}