@crewhaus/continuity-store 0.3.0

package/dist/index.js

@@ -0,0 +1,765 @@
+/**
+ * v0.3.0 Goal 1 — `continuity-store` (design §2.2–§2.7, PR 7).
+ *
+ * Human-readable, user-clearable continuity artifacts under
+ * `.crewhaus/state/<specName>/`:
+ *
+ *   focus.md                  — marker-gated (`<!-- crewhaus:focus -->`),
+ *                               focus body capped at `focusMaxChars`, plus the
+ *                               REQ-nnn requirements ledger and the active
+ *                               plan pointer
+ *   plans/plan-NNNN-<slug>.md — YAML frontmatter + numbered steps carrying the
+ *                               open → in_progress → claimed → proven ladder
+ *   goals.yaml                — {id, title, status, target?, current?, unit?}
+ *   handoff.md                — deterministic teardown render (NO model call
+ *                               anywhere in this package)
+ *   .lock                     — advisory single-writer lock (see lock.ts)
+ *
+ * Why files + markers: matches project-memory's LESSONS.md precedent — a
+ * user-authored focus.md without the marker is NEVER overwritten (and never
+ * injected), so crewhaus-managed state cannot hijack a human file.
+ *
+ * Proof ladder (§2.4): `claimed` is always free; `proven` is machine-checked
+ * against the append-only session event logs (including sub-agent child
+ * sessions via the `sub_agent_start` brackets). On a proven transition the
+ * store (a) pins the cited session in `.crewhaus/retention.json` and (b)
+ * freezes a `{toolName, inputHash, resultDigest}` proof excerpt into the
+ * plan/goal record, so evidence outlives the transcript TTL.
+ *
+ * Clearing (§2.6): `clear()` moves files to `.crewhaus/trash/<ts>/…` — never
+ * hard-deletes — and `restore(ts)` undoes it. `moveToTrash` is exported for
+ * other stores to adopt.
+ *
+ * Scoping (§2.7): one store per spec by default; `scope: {kind: "session"}`
+ * nests under `<spec>/sessions/<sessionId>/` for per-conversation state
+ * (channel daemons). Tenant contexts use the same fail-closed path fencing
+ * session-store enforces (CWE-1230): with a tenant present, any resolved
+ * path outside the tenant's root throws.
+ */
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+import { assertSamePath, currentTenantContext } from "@crewhaus/tenancy";
+import YAML from "yaml";
+import { appendRetentionPins, verifyEvidence, } from "./evidence";
+import { HANDOFF_MARKER, renderHandoff } from "./handoff";
+import { withLock } from "./lock";
+import { listTrash as listTrashDir, moveToTrash, restoreFromTrash, } from "./trash";
+export { ContinuityLockError, DEFAULT_LOCK_POLICY, acquireLock, withLock, } from "./lock";
+export { TRASH_DIR_NAME, TRASH_PURGE_AFTER_MS, TrashError, listTrash, moveToTrash, parseTrashTimestamp, purgeTrash, restoreFromTrash, } from "./trash";
+export { DEFAULT_SESSION_ROOT_DIR, EvidenceError, appendRetentionPins, resolveEvidence, verifyEvidence, } from "./evidence";
+export { HANDOFF_MARKER, renderHandoff, renderStatus } from "./handoff";
+export const DEFAULT_ROOT_DIR = ".crewhaus/state";
+export const DEFAULT_FOCUS_MAX_CHARS = 4096;
+/** §2.3 ledger cap: oldest-first eviction with a `[ledger truncated]` marker. */
+export const REQUIREMENTS_LEDGER_MAX_BYTES = 16_384;
+export const FOCUS_MARKER = "<!-- crewhaus:focus -->";
+const ACTIVE_PLAN_MARKER = "<!-- crewhaus:active-plan -->";
+const REQUIREMENTS_MARKER = "<!-- crewhaus:requirements -->";
+const LEDGER_TRUNCATED_LINE = "[ledger truncated]";
+const NONE_LINE = "_none_";
+const SPEC_NAME_REGEX = /^[a-zA-Z0-9_\-.]+$/;
+const SESSION_ID_REGEX = /^sess_[0-9a-f]{16}$/;
+const PLAN_ID_REGEX = /^plan-\d{4}$/;
+const GOAL_ID_REGEX = /^goal-\d{4}$/;
+const REQ_ID_REGEX = /^REQ-\d{3,}$/;
+const REQ_LINE_REGEX = /^- (REQ-\d{3,}) \[(open|confirmed|dropped)\] (".*") \(user, (sess_[0-9a-f]{16}), turn (\d+)\)$/;
+const STEP_LINE_REGEX = /^(\d+)\. \[(open|in_progress|claimed|proven)\] (.+)$/;
+export class ContinuityStoreError extends CrewhausError {
+    name = "ContinuityStoreError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+// ---------------------------------------------------------------------------
+// focus.md rendering + parsing
+// ---------------------------------------------------------------------------
+function renderRequirementLine(req) {
+    return `- ${req.id} [${req.status}] ${JSON.stringify(req.text)} (user, ${req.source.sessionId}, turn ${req.source.turn})`;
+}
+function renderFocusFile(state) {
+    const reqLines = state.requirements.map(renderRequirementLine);
+    const ledgerLines = reqLines.length > 0
+        ? state.ledgerTruncated
+            ? [LEDGER_TRUNCATED_LINE, ...reqLines]
+            : reqLines
+        : [NONE_LINE];
+    return [
+        FOCUS_MARKER,
+        "# Focus",
+        "",
+        state.body,
+        "",
+        "## Active plan",
+        ACTIVE_PLAN_MARKER,
+        state.activePlanId ?? NONE_LINE,
+        "",
+        "## Requirements",
+        REQUIREMENTS_MARKER,
+        ...ledgerLines,
+        "",
+    ].join("\n");
+}
+function parseFocusFile(raw) {
+    if (!raw.trimStart().startsWith(FOCUS_MARKER))
+        return null;
+    const activeHeader = `## Active plan\n${ACTIVE_PLAN_MARKER}`;
+    const reqHeader = `## Requirements\n${REQUIREMENTS_MARKER}`;
+    const activeIdx = raw.indexOf(activeHeader);
+    const reqIdx = raw.indexOf(reqHeader);
+    const afterMarker = raw.indexOf(FOCUS_MARKER) + FOCUS_MARKER.length;
+    const bodyEnd = activeIdx >= 0 ? activeIdx : reqIdx >= 0 ? reqIdx : raw.length;
+    let body = raw.slice(afterMarker, bodyEnd);
+    body = body.replace(/^\s*# Focus\s*\n/, "").trim();
+    let activePlanId = null;
+    if (activeIdx >= 0) {
+        const sectionStart = activeIdx + activeHeader.length;
+        const sectionEnd = reqIdx >= 0 ? reqIdx : raw.length;
+        const line = raw.slice(sectionStart, sectionEnd).trim().split("\n")[0]?.trim() ?? "";
+        if (PLAN_ID_REGEX.test(line))
+            activePlanId = line;
+    }
+    const requirements = [];
+    let ledgerTruncated = false;
+    if (reqIdx >= 0) {
+        for (const line of raw
+            .slice(reqIdx + reqHeader.length)
+            .split("\n")
+            .map((l) => l.trim())) {
+            if (line === LEDGER_TRUNCATED_LINE) {
+                ledgerTruncated = true;
+                continue;
+            }
+            const m = REQ_LINE_REGEX.exec(line);
+            if (m === null)
+                continue;
+            let text;
+            try {
+                text = JSON.parse(m[3]);
+            }
+            catch {
+                continue; // A hand-mangled line — skip rather than mis-attribute.
+            }
+            requirements.push({
+                id: m[1],
+                status: m[2],
+                text,
+                source: { sessionId: m[4], turn: Number(m[5]) },
+            });
+        }
+    }
+    return { body, activePlanId, requirements, ledgerTruncated };
+}
+function slugify(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return slug !== "" ? slug : "plan";
+}
+function renderPlanFile(plan) {
+    const proofs = {};
+    for (const step of plan.steps) {
+        if (step.proofs.length > 0)
+            proofs[String(step.index)] = [...step.proofs];
+    }
+    const frontmatter = {
+        id: plan.id,
+        slug: plan.slug,
+        title: plan.title,
+        createdAt: plan.createdAt,
+        updatedAt: plan.updatedAt,
+        ...(Object.keys(proofs).length > 0 ? { proofs } : {}),
+    };
+    const stepLines = plan.steps.map((s) => `${s.index}. [${s.status}] ${s.text}`);
+    return [
+        "---",
+        YAML.stringify(frontmatter).trimEnd(),
+        "---",
+        "",
+        `# ${plan.title}`,
+        "",
+        "## Steps",
+        "",
+        ...(stepLines.length > 0 ? stepLines : ["_no steps yet_"]),
+        "",
+    ].join("\n");
+}
+function isFrozenProofShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v["toolUseId"] === "string" &&
+        typeof v["sessionId"] === "string" &&
+        typeof v["toolName"] === "string" &&
+        typeof v["inputHash"] === "string" &&
+        typeof v["resultDigest"] === "string" &&
+        typeof v["verifiedAt"] === "string");
+}
+function parsePlanFile(raw, path) {
+    const fmMatch = /^---\n([\s\S]*?)\n---\n?/.exec(raw);
+    if (fmMatch === null) {
+        throw new ContinuityStoreError(`continuity-store: ${path} has no YAML frontmatter`);
+    }
+    let fm;
+    try {
+        fm = YAML.parse(fmMatch[1]);
+    }
+    catch (err) {
+        throw new ContinuityStoreError(`continuity-store: ${path} has malformed frontmatter`, err);
+    }
+    if (typeof fm !== "object" || fm === null) {
+        throw new ContinuityStoreError(`continuity-store: ${path} frontmatter is not a mapping`);
+    }
+    const f = fm;
+    const id = typeof f["id"] === "string" ? f["id"] : "";
+    if (!PLAN_ID_REGEX.test(id)) {
+        throw new ContinuityStoreError(`continuity-store: ${path} has an invalid plan id "${id}"`);
+    }
+    const proofsByStep = new Map();
+    if (typeof f["proofs"] === "object" && f["proofs"] !== null) {
+        for (const [key, value] of Object.entries(f["proofs"])) {
+            const index = Number(key);
+            if (!Number.isInteger(index) || !Array.isArray(value))
+                continue;
+            proofsByStep.set(index, value.filter(isFrozenProofShape));
+        }
+    }
+    const body = raw.slice(fmMatch[0].length);
+    const steps = [];
+    for (const line of body.split("\n")) {
+        const m = STEP_LINE_REGEX.exec(line.trim());
+        if (m === null)
+            continue;
+        const index = steps.length + 1;
+        steps.push({
+            index,
+            status: m[2],
+            text: m[3].trim(),
+            proofs: proofsByStep.get(index) ?? [],
+        });
+    }
+    return {
+        id,
+        slug: typeof f["slug"] === "string" ? f["slug"] : slugify(String(f["title"] ?? "")),
+        title: typeof f["title"] === "string" ? f["title"] : id,
+        createdAt: typeof f["createdAt"] === "string" ? f["createdAt"] : "",
+        updatedAt: typeof f["updatedAt"] === "string" ? f["updatedAt"] : "",
+        steps,
+    };
+}
+// ---------------------------------------------------------------------------
+// goals.yaml
+// ---------------------------------------------------------------------------
+function isGoalShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v["id"] === "string" &&
+        typeof v["title"] === "string" &&
+        typeof v["status"] === "string" &&
+        ["open", "in_progress", "claimed", "proven"].includes(v["status"]));
+}
+// ---------------------------------------------------------------------------
+// the store
+// ---------------------------------------------------------------------------
+/**
+ * Construct a continuity store. Lazy: directories and files are created on
+ * the first write. Reads never take the lock; every mutation runs under the
+ * advisory `.lock` (§7.6) and lands via tmp+rename.
+ */
+export function createContinuityStore(opts) {
+    if (!opts.specName) {
+        throw new ContinuityStoreError("specName is required");
+    }
+    if (!SPEC_NAME_REGEX.test(opts.specName) || /^\.+$/.test(opts.specName)) {
+        throw new ContinuityStoreError(`invalid specName "${opts.specName}" — must match [a-zA-Z0-9_\\-.]+ and not be dots only`);
+    }
+    const scope = opts.scope ?? { kind: "spec" };
+    if (scope.kind === "session" && !SESSION_ID_REGEX.test(scope.sessionId)) {
+        throw new ContinuityStoreError(`invalid scope.sessionId "${scope.sessionId}" — expected sess_<16 hex>`);
+    }
+    const now = opts.now ?? (() => new Date());
+    const focusMaxChars = opts.focusMaxChars ?? DEFAULT_FOCUS_MAX_CHARS;
+    // Tenant fencing (§2.7): honor BOTH an explicit `tenant` option and the
+    // ambient AsyncLocalStorage context, exactly like session-store — with a
+    // tenant present, any resolved path outside the tenant's root fails closed
+    // (CWE-1230). The fence root is the tenant's directory (the parent of its
+    // sessionRoot), because state, trash, retention.json, and sessions all
+    // live as siblings under it.
+    function tenantRootOf(tenant) {
+        return resolve(tenant.sessionRoot, "..");
+    }
+    function fence(absPath) {
+        if (opts.tenant !== undefined)
+            assertSamePath(absPath, tenantRootOf(opts.tenant));
+        const ctx = currentTenantContext();
+        if (ctx !== undefined)
+            assertSamePath(absPath, tenantRootOf(ctx.tenant));
+        return absPath;
+    }
+    const constructionTenant = opts.tenant ?? currentTenantContext()?.tenant;
+    const rootDir = resolve(opts.rootDir ??
+        (constructionTenant !== undefined
+            ? join(tenantRootOf(constructionTenant), "state")
+            : DEFAULT_ROOT_DIR));
+    const crewhausDir = resolve(rootDir, "..");
+    const storeDir = scope.kind === "session"
+        ? join(rootDir, opts.specName, "sessions", scope.sessionId)
+        : join(rootDir, opts.specName);
+    const plansDir = join(storeDir, "plans");
+    const focusPath = join(storeDir, "focus.md");
+    const goalsPath = join(storeDir, "goals.yaml");
+    const handoffPath = join(storeDir, "handoff.md");
+    const lockPath = join(storeDir, ".lock");
+    const retentionPath = join(crewhausDir, "retention.json");
+    const sessionRootDir = resolve(opts.sessionRootDir ?? join(crewhausDir, "sessions"));
+    // Fail closed at construction, not just on first I/O.
+    fence(storeDir);
+    async function writeAtomic(path, content) {
+        fence(path);
+        await mkdir(dirname(path), { recursive: true });
+        const tmpPath = `${path}.tmp`;
+        await writeFile(tmpPath, content, { mode: 0o600 });
+        await rename(tmpPath, path);
+    }
+    async function readText(path) {
+        fence(path);
+        try {
+            return await readFile(path, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+    function locked(fn) {
+        return withLock(fence(lockPath), fn, opts.lock ?? {});
+    }
+    // ---- focus internals ----
+    const emptyFocus = {
+        body: "",
+        activePlanId: null,
+        requirements: [],
+        ledgerTruncated: false,
+    };
+    async function readFocusState() {
+        const raw = await readText(focusPath);
+        if (raw === null)
+            return null;
+        return parseFocusFile(raw);
+    }
+    async function requireWritableFocus() {
+        const raw = await readText(focusPath);
+        if (raw === null)
+            return emptyFocus;
+        const parsed = parseFocusFile(raw);
+        if (parsed === null) {
+            throw new ContinuityStoreError(`continuity-store: ${focusPath} exists but is missing the "${FOCUS_MARKER}" marker — refusing to overwrite a user-authored file. Move it aside (or add the marker) to let crewhaus manage it.`);
+        }
+        return parsed;
+    }
+    function capLedger(requirements) {
+        const kept = [...requirements];
+        let truncated = false;
+        const bytes = () => Buffer.byteLength(kept.map(renderRequirementLine).join("\n"), "utf8");
+        while (kept.length > 1 && bytes() > REQUIREMENTS_LEDGER_MAX_BYTES) {
+            kept.shift(); // oldest-first eviction (§2.3)
+            truncated = true;
+        }
+        return { requirements: kept, truncated };
+    }
+    async function writeFocusState(state) {
+        await writeAtomic(focusPath, renderFocusFile(state));
+    }
+    // ---- plan internals ----
+    async function planFiles() {
+        fence(plansDir);
+        let entries;
+        try {
+            entries = await readdir(plansDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        return entries.filter((e) => /^plan-\d{4}-.*\.md$/.test(e)).sort();
+    }
+    async function readPlans() {
+        const files = await planFiles();
+        const plans = [];
+        for (const file of files) {
+            const raw = await readText(join(plansDir, file));
+            if (raw === null)
+                continue;
+            plans.push(parsePlanFile(raw, join(plansDir, file)));
+        }
+        return plans;
+    }
+    async function planPathFor(planId) {
+        const files = await planFiles();
+        const match = files.find((f) => f.startsWith(`${planId}-`));
+        return match !== undefined ? join(plansDir, match) : null;
+    }
+    async function readPlan(planId) {
+        if (!PLAN_ID_REGEX.test(planId)) {
+            throw new ContinuityStoreError(`invalid planId "${planId}" — expected plan-NNNN`);
+        }
+        const path = await planPathFor(planId);
+        if (path === null)
+            return null;
+        const raw = await readText(path);
+        if (raw === null)
+            return null;
+        return { plan: parsePlanFile(raw, path), path };
+    }
+    async function requirePlan(planId) {
+        const found = await readPlan(planId);
+        if (found === null) {
+            throw new ContinuityStoreError(`continuity-store: no plan "${planId}" — create one first (PlanUpdate {action: "create"}).`);
+        }
+        return found;
+    }
+    function requireStep(plan, step) {
+        const found = plan.steps.find((s) => s.index === step);
+        if (found === undefined) {
+            throw new ContinuityStoreError(`continuity-store: ${plan.id} has no step ${step} (steps 1–${plan.steps.length}).`);
+        }
+        return found;
+    }
+    async function writePlan(plan) {
+        const path = (await planPathFor(plan.id)) ?? join(plansDir, `${plan.id}-${plan.slug}.md`);
+        await writeAtomic(path, renderPlanFile(plan));
+    }
+    function withStep(plan, step, update) {
+        return {
+            ...plan,
+            updatedAt: now().toISOString(),
+            steps: plan.steps.map((s) => (s.index === step ? update(s) : s)),
+        };
+    }
+    // ---- goal internals ----
+    async function readGoals() {
+        const raw = await readText(goalsPath);
+        if (raw === null)
+            return [];
+        let parsed;
+        try {
+            parsed = YAML.parse(raw);
+        }
+        catch (err) {
+            throw new ContinuityStoreError(`continuity-store: ${goalsPath} is malformed YAML`, err);
+        }
+        const list = parsed?.goals;
+        if (!Array.isArray(list))
+            return [];
+        return list.filter(isGoalShape);
+    }
+    async function writeGoals(goals) {
+        await writeAtomic(goalsPath, YAML.stringify({ version: 1, goals }));
+    }
+    function nextId(prefix, existing, width = 4) {
+        let max = 0;
+        for (const id of existing) {
+            const n = Number(id.slice(prefix.length + 1));
+            if (Number.isInteger(n) && n > max)
+                max = n;
+        }
+        return `${prefix}-${String(max + 1).padStart(width, "0")}`;
+    }
+    async function verify(refs) {
+        return verifyEvidence(refs, {
+            sessionRootDir,
+            ...(opts.sessionId !== undefined ? { defaultSessionId: opts.sessionId } : {}),
+            now,
+        });
+    }
+    function mergeProofs(existing, incoming) {
+        const seen = new Set(existing.map((p) => p.toolUseId));
+        return [...existing, ...incoming.filter((p) => !seen.has(p.toolUseId))];
+    }
+    async function gatherHandoffInput(lastSessionId) {
+        const focus = (await readFocusState()) ?? emptyFocus;
+        const plans = await readPlans();
+        const activePlan = focus.activePlanId !== null ? (plans.find((p) => p.id === focus.activePlanId) ?? null) : null;
+        const goals = await readGoals();
+        return {
+            focusBody: focus.body,
+            activePlan,
+            plans,
+            goals,
+            requirements: focus.requirements,
+            ...(lastSessionId !== undefined ? { lastSessionId } : {}),
+        };
+    }
+    return {
+        dir() {
+            return storeDir;
+        },
+        async readFocus() {
+            return readFocusState();
+        },
+        async writeFocus(body) {
+            if (body.length > focusMaxChars) {
+                throw new ContinuityStoreError(`continuity-store: focus body is ${body.length} chars — the cap is ${focusMaxChars} (focusMaxChars). Keep focus.md short; details belong in plan steps.`);
+            }
+            await locked(async () => {
+                const state = await requireWritableFocus();
+                await writeFocusState({ ...state, body: body.trim() });
+            });
+        },
+        async setActivePlan(planId) {
+            if (planId !== null)
+                await requirePlan(planId);
+            await locked(async () => {
+                const state = await requireWritableFocus();
+                await writeFocusState({ ...state, activePlanId: planId });
+            });
+        },
+        async appendRequirement(input) {
+            if (input.text.trim() === "") {
+                throw new ContinuityStoreError("appendRequirement(): text must be non-empty (verbatim)");
+            }
+            if (!SESSION_ID_REGEX.test(input.source.sessionId)) {
+                throw new ContinuityStoreError(`appendRequirement(): invalid source.sessionId "${input.source.sessionId}" — expected sess_<16 hex>`);
+            }
+            if (input.id !== undefined && !REQ_ID_REGEX.test(input.id)) {
+                throw new ContinuityStoreError(`appendRequirement(): invalid id "${input.id}" — expected REQ-nnn`);
+            }
+            return locked(async () => {
+                const state = await requireWritableFocus();
+                const requirements = [...state.requirements];
+                let entry;
+                const existingIdx = input.id !== undefined ? requirements.findIndex((r) => r.id === input.id) : -1;
+                if (existingIdx >= 0) {
+                    const existing = requirements[existingIdx];
+                    if (existing.text !== input.text) {
+                        throw new ContinuityStoreError(`appendRequirement(): ${existing.id} already exists with different text — the ledger is verbatim-only; append a NEW requirement instead of paraphrasing an old one.`);
+                    }
+                    entry = { ...existing, status: input.status ?? existing.status };
+                    requirements[existingIdx] = entry;
+                }
+                else {
+                    const id = input.id ??
+                        nextId("REQ", requirements.map((r) => r.id), 3);
+                    entry = {
+                        id,
+                        text: input.text,
+                        status: input.status ?? "open",
+                        source: { sessionId: input.source.sessionId, turn: input.source.turn },
+                    };
+                    requirements.push(entry);
+                }
+                const capped = capLedger(requirements);
+                await writeFocusState({
+                    ...state,
+                    requirements: capped.requirements,
+                    ledgerTruncated: state.ledgerTruncated || capped.truncated,
+                });
+                return entry;
+            });
+        },
+        async listRequirements() {
+            return (await readFocusState())?.requirements ?? [];
+        },
+        async createPlan(input) {
+            if (input.title.trim() === "") {
+                throw new ContinuityStoreError("createPlan(): title must be non-empty");
+            }
+            return locked(async () => {
+                const existing = await readPlans();
+                const id = nextId("plan", existing.map((p) => p.id));
+                const iso = now().toISOString();
+                const plan = {
+                    id,
+                    slug: slugify(input.title),
+                    title: input.title.trim(),
+                    createdAt: iso,
+                    updatedAt: iso,
+                    steps: (input.steps ?? []).map((text, i) => ({
+                        index: i + 1,
+                        text: text.replace(/\s+/g, " ").trim(),
+                        status: "open",
+                        proofs: [],
+                    })),
+                };
+                await writePlan(plan);
+                // First plan becomes the active plan (the §2.2 pointer) so PlanRead
+                // and the handoff have a default without an extra tool call.
+                const focus = await requireWritableFocus();
+                if (focus.activePlanId === null) {
+                    await writeFocusState({ ...focus, activePlanId: id });
+                }
+                return plan;
+            });
+        },
+        async getPlan(planId) {
+            return (await readPlan(planId))?.plan ?? null;
+        },
+        async listPlans() {
+            return readPlans();
+        },
+        async getActivePlan() {
+            const focus = await readFocusState();
+            if (focus === null || focus.activePlanId === null)
+                return null;
+            return (await readPlan(focus.activePlanId))?.plan ?? null;
+        },
+        async addStep(planId, text) {
+            if (text.trim() === "") {
+                throw new ContinuityStoreError("addStep(): text must be non-empty");
+            }
+            return locked(async () => {
+                const { plan } = await requirePlan(planId);
+                const next = {
+                    ...plan,
+                    updatedAt: now().toISOString(),
+                    steps: [
+                        ...plan.steps,
+                        {
+                            index: plan.steps.length + 1,
+                            text: text.replace(/\s+/g, " ").trim(),
+                            status: "open",
+                            proofs: [],
+                        },
+                    ],
+                };
+                await writePlan(next);
+                return next;
+            });
+        },
+        async setStepStatus(planId, step, status) {
+            if (!["open", "in_progress", "claimed"].includes(status)) {
+                throw new ContinuityStoreError(`setStepStatus(): "${status}" is not claimable — the proven transition requires evidence; use proveStep() (PlanComplete).`);
+            }
+            return locked(async () => {
+                const { plan } = await requirePlan(planId);
+                requireStep(plan, step);
+                const next = withStep(plan, step, (s) => ({ ...s, status }));
+                await writePlan(next);
+                return next;
+            });
+        },
+        async proveStep(planId, step, evidence) {
+            // Verify BEFORE taking the lock — verification reads foreign session
+            // logs and can be slow; the store lock protects only our own writes.
+            const { plan: preflight } = await requirePlan(planId);
+            requireStep(preflight, step);
+            const proofs = await verify(evidence);
+            return locked(async () => {
+                const { plan } = await requirePlan(planId);
+                const current = requireStep(plan, step);
+                const next = withStep(plan, step, (s) => ({
+                    ...s,
+                    status: "proven",
+                    proofs: mergeProofs(current.proofs, proofs),
+                }));
+                await writePlan(next);
+                // Proof lifetime (§2.4): pin every cited session so TTL eviction
+                // cannot orphan a live proven record.
+                await appendRetentionPins(proofs.map((p) => p.sessionId), fence(retentionPath));
+                return next;
+            });
+        },
+        async writeGoal(input) {
+            if (input.title.trim() === "") {
+                throw new ContinuityStoreError("writeGoal(): title must be non-empty");
+            }
+            return locked(async () => {
+                const goals = await readGoals();
+                const iso = now().toISOString();
+                const goal = {
+                    id: nextId("goal", goals.map((g) => g.id)),
+                    title: input.title.trim(),
+                    status: "open",
+                    ...(input.target !== undefined ? { target: input.target } : {}),
+                    ...(input.current !== undefined ? { current: input.current } : {}),
+                    ...(input.unit !== undefined ? { unit: input.unit } : {}),
+                    createdAt: iso,
+                    updatedAt: iso,
+                };
+                await writeGoals([...goals, goal]);
+                return goal;
+            });
+        },
+        async updateGoal(goalId, patch) {
+            if (!GOAL_ID_REGEX.test(goalId)) {
+                throw new ContinuityStoreError(`invalid goalId "${goalId}" — expected goal-NNNN`);
+            }
+            // The proven transition is machine-checked for goals exactly like plan
+            // steps (§2.4: plan steps AND goals carry the ladder).
+            let proofs = [];
+            if (patch.status === "proven") {
+                if (patch.evidence === undefined || patch.evidence.length === 0) {
+                    throw new ContinuityStoreError(`continuity-store: marking ${goalId} proven requires evidence — run the action first, then cite its toolUseId(s).`);
+                }
+                proofs = await verify(patch.evidence);
+            }
+            return locked(async () => {
+                const goals = await readGoals();
+                const idx = goals.findIndex((g) => g.id === goalId);
+                if (idx < 0) {
+                    throw new ContinuityStoreError(`continuity-store: no goal "${goalId}"`);
+                }
+                const existing = goals[idx];
+                const mergedProofs = proofs.length > 0 ? mergeProofs(existing.proofs ?? [], proofs) : existing.proofs;
+                const next = {
+                    ...existing,
+                    ...(patch.title !== undefined ? { title: patch.title } : {}),
+                    ...(patch.status !== undefined ? { status: patch.status } : {}),
+                    ...(patch.target !== undefined ? { target: patch.target } : {}),
+                    ...(patch.current !== undefined ? { current: patch.current } : {}),
+                    ...(patch.unit !== undefined ? { unit: patch.unit } : {}),
+                    ...(mergedProofs !== undefined ? { proofs: mergedProofs } : {}),
+                    updatedAt: now().toISOString(),
+                };
+                const nextGoals = [...goals];
+                nextGoals[idx] = next;
+                await writeGoals(nextGoals);
+                if (proofs.length > 0) {
+                    await appendRetentionPins(proofs.map((p) => p.sessionId), fence(retentionPath));
+                }
+                return next;
+            });
+        },
+        async listGoals() {
+            return readGoals();
+        },
+        async verifyEvidence(refs) {
+            return verify(refs);
+        },
+        async renderHandoff(handoffOpts = {}) {
+            return renderHandoff(await gatherHandoffInput(handoffOpts.lastSessionId));
+        },
+        async writeHandoff(handoffOpts = {}) {
+            const rendered = renderHandoff(await gatherHandoffInput(handoffOpts.lastSessionId));
+            await locked(async () => {
+                const existing = await readText(handoffPath);
+                if (existing !== null && !existing.trimStart().startsWith(HANDOFF_MARKER)) {
+                    throw new ContinuityStoreError(`continuity-store: ${handoffPath} exists but is missing the "${HANDOFF_MARKER}" marker — refusing to overwrite a user-authored file.`);
+                }
+                await writeAtomic(handoffPath, rendered);
+            });
+            return handoffPath;
+        },
+        async clear(clearScope) {
+            const targets = {
+                focus: [focusPath],
+                plans: [plansDir],
+                goals: [goalsPath],
+                all: [focusPath, plansDir, goalsPath, handoffPath],
+            };
+            return locked(async () => moveToTrash(targets[clearScope], fence(crewhausDir), { now }));
+        },
+        async restore(ts) {
+            return locked(async () => restoreFromTrash(ts, fence(crewhausDir)));
+        },
+        async listTrash() {
+            return listTrashDir(fence(crewhausDir));
+        },
+    };
+}