@isaacriehm/cairn-core 0.23.0 → 0.24.0

package/dist/mcp/tools/component-annotate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `cairn_component_annotate` — the context engine's stage-3 write path.
+ *
+ * The agent supplies JUDGMENT (category, purpose, aliases, which props
+ * are public); the server holds the MECHANICS + truth: it validates the
+ * export symbol against the code, validates the category against the
+ * project enum, formats the canonical `@cairn` header (block form for
+ * C-style langs, hash form for the rest), writes it above the export,
+ * and rebuilds the index + singleton §INV. The agent never sees the
+ * header grammar — the format is structurally impossible to get wrong.
+ *
+ * Committed mode writes the in-file header (the SoT). Ghost mode has no
+ * in-file SoT, so it delegates to `cairn_component_register` (registry
+ * write, no source edit).
+ *
+ * Spec: docs/CONTEXT_ENGINE.md ("semantics in, server writes"),
+ * CAIRN_REBUILD §8d / D7–D9.
+ */
+import type { ToolDef } from "./types.js";
+interface Input {
+    file: string;
+    export_name: string;
+    category: string;
+    purpose: string;
+    aliases: string[];
+    public_props?: string[];
+    uses?: string[];
+    status?: "stable" | "wip" | "deprecated";
+    singleton?: boolean;
+    workspace?: string;
+}
+export declare const componentAnnotateTool: ToolDef<Input>;
+export {};

package/dist/mcp/tools/component-annotate.js

@@ -0,0 +1,189 @@
+/**
+ * `cairn_component_annotate` — the context engine's stage-3 write path.
+ *
+ * The agent supplies JUDGMENT (category, purpose, aliases, which props
+ * are public); the server holds the MECHANICS + truth: it validates the
+ * export symbol against the code, validates the category against the
+ * project enum, formats the canonical `@cairn` header (block form for
+ * C-style langs, hash form for the rest), writes it above the export,
+ * and rebuilds the index + singleton §INV. The agent never sees the
+ * header grammar — the format is structurally impossible to get wrong.
+ *
+ * Committed mode writes the in-file header (the SoT). Ghost mode has no
+ * in-file SoT, so it delegates to `cairn_component_register` (registry
+ * write, no source edit).
+ *
+ * Spec: docs/CONTEXT_ENGINE.md ("semantics in, server writes"),
+ * CAIRN_REBUILD §8d / D7–D9.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractExportNames, hasComponentConfig, isGhost, loadComponentsConfig, parseComponentHeader, profileForFile, } from "@isaacriehm/cairn-state";
+import { emitComponentStore } from "../../components/emit.js";
+import { mcpError } from "../errors.js";
+import { componentAnnotateInput } from "../schemas.js";
+import { componentRegisterTool } from "./component-register.js";
+/** Allowed categories for the workspace owning `rel` (longest-prefix). */
+function categoriesForFile(config, rel) {
+    let best = null;
+    let bestLen = -1;
+    for (const ws of config.workspaces) {
+        for (const dir of ws.componentDirs) {
+            if ((rel === dir || rel.startsWith(`${dir}/`)) && dir.length > bestLen) {
+                bestLen = dir.length;
+                best = ws.categories;
+            }
+        }
+    }
+    return best ?? config.workspaces[0]?.categories ?? [];
+}
+/** Pick the header comment form from the file's language profile. */
+function commentFormFor(file) {
+    const forms = profileForFile(file)?.commentForms ?? [];
+    if (forms.includes("block"))
+        return "block";
+    if (forms.includes("hash"))
+        return "hash";
+    if (forms.includes("dash"))
+        return "dash";
+    return "block";
+}
+/** Format the canonical `@cairn` header in the given comment form. */
+function formatHeader(input, form) {
+    const tags = [
+        `@cairn ${input.export_name}`,
+        `@category ${input.category}`,
+        `@purpose ${input.purpose}`,
+        `@aliases ${input.aliases.join(", ")}`,
+    ];
+    if (input.public_props !== undefined && input.public_props.length > 0) {
+        tags.push(`@props ${input.public_props.join(", ")}`);
+    }
+    if (input.uses !== undefined && input.uses.length > 0) {
+        tags.push(`@uses ${input.uses.join(", ")}`);
+    }
+    if (input.status !== undefined)
+        tags.push(`@status ${input.status}`);
+    if (input.singleton === true)
+        tags.push("@singleton");
+    if (form === "block") {
+        return ["/**", ...tags.map((t) => ` * ${t}`), " */"].join("\n");
+    }
+    const marker = form === "dash" ? "--" : "#";
+    return tags.map((t) => `${marker} ${t}`).join("\n");
+}
+// A leading directive-prologue statement — `"use client"`, `"use server"`,
+// `"use strict"`. These MUST stay the file's first statement (React Server
+// Components / strict mode break if a comment-bearing header pushes them
+// down in some bundlers), so the header is inserted AFTER them.
+const DIRECTIVE_RE = /^\s*['"]use [\w-]+['"]\s*;?\s*$/;
+/**
+ * Insert `header` above the code, but below any shebang and leading
+ * directive prologue (`"use client"` etc.) — those must remain the
+ * file's first line / first statement.
+ */
+function insertHeader(source, header) {
+    const lines = source.split("\n");
+    let insertAt = 0;
+    if (lines.length > 0 && lines[0].startsWith("#!"))
+        insertAt = 1; // shebang
+    while (insertAt < lines.length) {
+        const line = lines[insertAt];
+        if (line.trim() === "" || DIRECTIVE_RE.test(line)) {
+            insertAt += 1;
+            continue;
+        }
+        break;
+    }
+    const before = lines.slice(0, insertAt);
+    const after = lines.slice(insertAt);
+    return [...before, header, ...after].join("\n");
+}
+async function handler(ctx, input) {
+    const abs = join(ctx.repoRoot, input.file);
+    if (!existsSync(abs)) {
+        return mcpError("FILE_NOT_FOUND", `${input.file} does not exist under the repo root — annotate an existing component file.`);
+    }
+    // Ghost mode has no in-file SoT — delegate to the registry write path.
+    if (isGhost(ctx.repoRoot)) {
+        return componentRegisterTool.handler(ctx, {
+            file: input.file,
+            export_name: input.export_name,
+            name: input.export_name,
+            category: input.category,
+            purpose: input.purpose,
+            aliases: input.aliases,
+            ...(input.workspace !== undefined ? { workspace: input.workspace } : {}),
+            ...(input.singleton !== undefined ? { singleton: input.singleton } : {}),
+            ...(input.status !== undefined ? { status: input.status } : {}),
+            ...(input.uses !== undefined ? { uses: input.uses } : {}),
+        });
+    }
+    const config = loadComponentsConfig(ctx.repoRoot);
+    if (!hasComponentConfig(config)) {
+        return mcpError("NOT_ALLOWED", "this repo has no components: config — nothing to annotate.");
+    }
+    // D9 — category must be in the owning workspace's enum (server owns it).
+    const categories = categoriesForFile(config, input.file);
+    if (categories.length > 0 && !categories.includes(input.category)) {
+        return mcpError("VALIDATION_FAILED", `category "${input.category}" is not one of this workspace's categories: ${categories.join(", ")}.`);
+    }
+    let source;
+    try {
+        source = readFileSync(abs, "utf8");
+    }
+    catch (err) {
+        return mcpError("INTERNAL_ERROR", `could not read ${input.file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Idempotent: a file that already carries a `@cairn` header is left
+    // untouched — re-writing would create a second header block.
+    if (parseComponentHeader(source) !== null) {
+        return {
+            ok: true,
+            file: input.file,
+            header_written: false,
+            already_headered: true,
+        };
+    }
+    // D7 — export_name must be a real export. When the language profile
+    // can detect exports and the claimed name isn't among them, reject;
+    // when detection yields nothing (unknown extension) accept best-effort.
+    const exports = extractExportNames(source, input.file);
+    if (exports.length > 0 && !exports.includes(input.export_name)) {
+        return mcpError("VALIDATION_FAILED", `export_name "${input.export_name}" is not an export of ${input.file}. Real exports: ${exports.join(", ")}.`);
+    }
+    const form = commentFormFor(input.file);
+    const header = formatHeader(input, form);
+    const next = insertHeader(source, header);
+    try {
+        writeFileSync(abs, next, "utf8");
+    }
+    catch (err) {
+        return mcpError("INTERNAL_ERROR", `could not write ${input.file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Rebuild the derived index + promote any @singleton to a hard §INV.
+    let indexed = 0;
+    try {
+        const emit = emitComponentStore(ctx.repoRoot);
+        indexed = emit.indexed;
+    }
+    catch {
+        // header is written + valid; index rebuild is best-effort here
+        // (the pre-commit sweep rebuilds deterministically anyway).
+    }
+    return {
+        ok: true,
+        name: input.export_name,
+        category: input.category,
+        file: input.file,
+        header_written: true,
+        indexed,
+    };
+}
+export const componentAnnotateTool = {
+    name: "cairn_component_annotate",
+    description: "Register a component by writing its canonical `@cairn` header. Supply judgment only — file, export_name, category (one of the workspace's categories), a one-line purpose, and ≥2 aliases; optional public_props/uses/status/singleton. The server validates the export + category against the code, formats + inserts the header, and rebuilds the registry. Committed projects write the in-file header; ghost projects route to the registry. This is the server-driven replacement for hand-writing `@cairn` headers.",
+    inputSchema: componentAnnotateInput,
+    handler,
+};
+//# sourceMappingURL=component-annotate.js.map

package/dist/mcp/tools/component-annotate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-annotate.js","sourceRoot":"","sources":["../../../src/mcp/tools/component-annotate.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/index.js

@@ -1,6 +1,7 @@
 import { attentionDedupTool } from "./attention-dedup.js";
 import { bootstrapRetryTool } from "./bootstrap-retry.js";
 import { canonicalForTopicTool } from "./canonical-for-topic.js";
+import { componentAnnotateTool } from "./component-annotate.js";
 import { componentGetTool } from "./component-get.js";
 import { componentRegisterTool } from "./component-register.js";
 import { componentReconfirmTool } from "./component-reconfirm.js";
@@ -46,7 +47,8 @@ export const allTools = [
     retireInvariantTool,
     // Write — apply pending review-class migrations inline
     migrateTool,
-    // Write — headerless component registry (ghost §3.8.1)
+    // Write — component registry (committed header + ghost §3.8.1)
+    componentAnnotateTool,
     componentRegisterTool,
     componentReconfirmTool,
     taskCreateTool,

package/dist/mcp/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,CAAC,MAAM,QAAQ,GAAqB;IACxC,yBAAyB;IACzB,eAAe;IACf,qBAAqB;IACrB,gBAAgB;IAChB,WAAW;IACX,4BAA4B;IAC5B,qBAAqB;IACrB,gBAAgB;IAChB,4BAA4B;IAC5B,UAAU;IACV,QAAQ;IACR,kBAAkB;IAClB,2CAA2C;IAC3C,kBAAkB;IAClB,mBAAmB;IACnB,uDAAuD;IACvD,WAAW;IACX,uDAAuD;IACvD,qBAAqB;IACrB,sBAAsB;IACtB,cAAc;IACd,gBAAgB;IAChB,cAAc;IACd,qBAAqB;IACrB,sBAAsB;IACtB,UAAU;IACV,qCAAqC;IACrC,oBAAoB;IACpB,kBAAkB;IAClB,2EAA2E;IAC3E,kBAAkB;IAClB,yDAAyD;IACzD,cAAc;IACd,WAAW;IACX,oCAAoC;IACpC,gBAAgB;IAChB,sBAAsB;IACtB,cAAc;IACd,oBAAoB;IACpB,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;IACjB,uBAAuB;IACvB,sBAAsB;CACvB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,CAAC,MAAM,QAAQ,GAAqB;IACxC,yBAAyB;IACzB,eAAe;IACf,qBAAqB;IACrB,gBAAgB;IAChB,WAAW;IACX,4BAA4B;IAC5B,qBAAqB;IACrB,gBAAgB;IAChB,4BAA4B;IAC5B,UAAU;IACV,QAAQ;IACR,kBAAkB;IAClB,2CAA2C;IAC3C,kBAAkB;IAClB,mBAAmB;IACnB,uDAAuD;IACvD,WAAW;IACX,+DAA+D;IAC/D,qBAAqB;IACrB,qBAAqB;IACrB,sBAAsB;IACtB,cAAc;IACd,gBAAgB;IAChB,cAAc;IACd,qBAAqB;IACrB,sBAAsB;IACtB,UAAU;IACV,qCAAqC;IACrC,oBAAoB;IACpB,kBAAkB;IAClB,2EAA2E;IAC3E,kBAAkB;IAClB,yDAAyD;IACzD,cAAc;IACd,WAAW;IACX,oCAAoC;IACpC,gBAAgB;IAChB,sBAAsB;IACtB,cAAc;IACd,oBAAoB;IACpB,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;IACjB,uBAAuB;IACvB,sBAAsB;CACvB,CAAC"}

package/dist/mcp/tools/resume.js

@@ -17,6 +17,7 @@ import { parse as parseYaml } from "yaml";
 import { mcpError } from "../errors.js";
 import { resumeInput } from "../schemas.js";
 import { findCurrentActiveTask, readTaskJournal, } from "../../tasks/index.js";
+import { readTaskSpec } from "../../tasks/spec-reader.js";
 import { cairnDir } from "@isaacriehm/cairn-state";
 async function handler(ctx, input) {
     const taskId = input.task_id ?? findCurrentActiveTask(ctx.repoRoot);
@@ -44,40 +45,15 @@ async function handler(ctx, input) {
     else {
         return mcpError("TASK_NOT_FOUND", `task directory missing in active/ and done/: ${taskId}`);
     }
-    const specPath = join(taskDir, "spec.tightened.md");
-    let title = taskId;
-    let goal = "(spec not found)";
-    let inScopeDecisions = [];
-    let inScopeInvariants = [];
-    let targetPathGlobs = [];
-    if (existsSync(specPath)) {
-        const raw = readFileSync(specPath, "utf8");
-        const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\n---\r?\n([\s\S]*)$/);
-        if (fmMatch) {
-            try {
-                const fm = parseYaml(fmMatch[1] ?? "");
-                if (typeof fm.title === "string")
-                    title = fm.title;
-                if (Array.isArray(fm.in_scope_decisions)) {
-                    inScopeDecisions = fm.in_scope_decisions.filter((x) => typeof x === "string");
-                }
-                if (Array.isArray(fm.in_scope_invariants)) {
-                    inScopeInvariants = fm.in_scope_invariants.filter((x) => typeof x === "string");
-                }
-                if (Array.isArray(fm.target_path_globs)) {
-                    targetPathGlobs = fm.target_path_globs.filter((x) => typeof x === "string");
-                }
-            }
-            catch {
-                // malformed frontmatter — fall through with defaults
-            }
-            const body = fmMatch[2] ?? "";
-            const goalMatch = body.match(/##\s+Goal\s*\r?\n+([\s\S]*?)(?:\r?\n##\s+|$)/);
-            if (goalMatch && goalMatch[1] !== undefined) {
-                goal = goalMatch[1].trim();
-            }
-        }
-    }
+    // Shared spec reader (tasks/spec-reader.ts) — same parse the
+    // UserPromptSubmit working-header uses. Preserve resume's historical
+    // fallbacks: title → taskId, goal → "(spec not found)" when absent.
+    const spec = readTaskSpec(taskDir);
+    const title = spec !== null && spec.title.length > 0 ? spec.title : taskId;
+    const goal = spec !== null && spec.goal.length > 0 ? spec.goal : "(spec not found)";
+    const inScopeDecisions = spec?.inScopeDecisions ?? [];
+    const inScopeInvariants = spec?.inScopeInvariants ?? [];
+    const targetPathGlobs = spec?.targetPathGlobs ?? [];
     const journal = readTaskJournal(ctx.repoRoot, taskId, scope);
     const cap = Math.max(1, Math.min(50, input.max_entries ?? 7));
     const recent = journal.slice(-cap);

package/dist/mcp/tools/resume.js.map

@@ -1 +1 @@
-{"version":3,"file":"resume.js","sourceRoot":"","sources":["../../../src/mcp/tools/resume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EACL,qBAAqB,EACrB,eAAe,GAEhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AA4CnD,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,KAAY;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,IAAI,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpE,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,QAAQ,CACb,gBAAgB,EAChB,0BAA0B,CAC3B,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxE,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpE,IAAI,KAAwB,CAAC;IAC7B,IAAI,OAAe,CAAC;IACpB,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,IAAI,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC9B,KAAK,GAAG,QAAQ,CAAC;QACjB,OAAO,GAAG,aAAa,CAAC;IAC1B,CAAC;SAAM,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QACnC,mEAAmE;QACnE,0EAA0E;QAC1E,kEAAkE;QAClE,qCAAqC;QACrC,KAAK,GAAG,MAAM,CAAC;QACf,OAAO,GAAG,WAAW,CAAC;QACtB,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC;IAClE,CAAC;SAAM,CAAC;QACN,OAAO,QAAQ,CACb,gBAAgB,EAChB,gDAAgD,MAAM,EAAE,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IACpD,IAAI,KAAK,GAAG,MAAM,CAAC;IACnB,IAAI,IAAI,GAAG,kBAAkB,CAAC;IAC9B,IAAI,gBAAgB,GAAa,EAAE,CAAC;IACpC,IAAI,iBAAiB,GAAa,EAAE,CAAC;IACrC,IAAI,eAAe,GAAa,EAAE,CAAC;IAEnC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACrE,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAoB,CAAC;gBAC1D,IAAI,OAAO,EAAE,CAAC,KAAK,KAAK,QAAQ;oBAAE,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;gBACnD,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,kBAAkB,CAAC,EAAE,CAAC;oBACzC,gBAAgB,GAAG,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAC7C,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC1C,CAAC;gBACJ,CAAC;gBACD,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,CAAC;oBAC1C,iBAAiB,GAAG,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAC/C,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC1C,CAAC;gBACJ,CAAC;gBACD,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,iBAAiB,CAAC,EAAE,CAAC;oBACxC,eAAe,GAAG,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAC3C,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC1C,CAAC;gBACJ,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,qDAAqD;YACvD,CAAC;YACD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;YAC7E,IAAI,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC5C,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC7B,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1E,MAAM,QAAQ,GAAG,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC;IAE9C,uEAAuE;IACvE,oEAAoE;IACpE,iEAAiE;IACjE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,EAAE,GAAG,KAAK,EAAE,aAAa,CAAC;QAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YAAE,SAAS;QACjC,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YACnB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACtD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAS;YAC1B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAkB;QAC7B,EAAE,EAAE,IAAI;QACR,OAAO,EAAE,MAAM;QACf,KAAK;QACL,YAAY,EAAE,WAAW;QACzB,KAAK;QACL,IAAI;QACJ,kBAAkB,EAAE,gBAAgB;QACpC,mBAAmB,EAAE,iBAAiB;QACtC,iBAAiB,EAAE,eAAe;QAClC,cAAc,EAAE,MAAM;QACtB,SAAS,EAAE,QAAQ;QACnB,aAAa,EAAE,OAAO,CAAC,MAAM;QAC7B,aAAa,EAAE,YAAY;KAC5B,CAAC;IACF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,eAAe,CAAC,UAAkB;IACzC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAsC,CAAC;QACnE,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC;YAC9B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,+cAA+c;IACjd,WAAW,EAAE,WAAW;IACxB,OAAO;CACR,CAAC"}
+{"version":3,"file":"resume.js","sourceRoot":"","sources":["../../../src/mcp/tools/resume.ts"],"names":[],"mappings":"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"}

package/dist/session/index.d.ts

@@ -12,3 +12,5 @@ export { cleanupSession, ensureSessionDir, gcStaleSessions, resolveSessionId, }
 export type { EnsureSessionDirArgs, EnsureSessionDirResult, GcStaleSessionsArgs, GcStaleSessionsResult, SessionIdSource, SessionMeta, } from "./id.js";
 export { eventsMarkerPath, readEventsMarker, seedEventsMarker, stampEventsPoll, } from "./events-marker.js";
 export type { EventsMarker } from "./events-marker.js";
+export { fingerprintText, filterUnshownIds, getSeenFingerprint, hasShownId, markShownIds, setSeenFingerprint, } from "./seen.js";
+export { appendTouched, readTouched } from "./touched.js";

package/dist/session/index.js

@@ -10,4 +10,6 @@
  */
 export { cleanupSession, ensureSessionDir, gcStaleSessions, resolveSessionId, } from "./id.js";
 export { eventsMarkerPath, readEventsMarker, seedEventsMarker, stampEventsPoll, } from "./events-marker.js";
+export { fingerprintText, filterUnshownIds, getSeenFingerprint, hasShownId, markShownIds, setSeenFingerprint, } from "./seen.js";
+export { appendTouched, readTouched } from "./touched.js";
 //# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,SAAS,CAAC;AASjB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,SAAS,CAAC;AASjB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/session/seen.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-session dedup store — `.cairn/sessions/<id>/seen.json`.
+ *
+ * The context engine injects scoped ground state as the agent works
+ * (working header, DEC/INV legends, component slices). Without dedup
+ * the injectors re-send unchanged context every turn and *become* the
+ * context-bloat problem they exist to solve. This module is the
+ * single source of "already shown this session":
+ *
+ *   - `fingerprints` — keyed text hashes (e.g. `working-header`). An
+ *     injector re-emits only when the hash changed.
+ *   - `shownIds` — flat set of opaque ids already surfaced once
+ *     (DEC-/INV- ids, component names, `annotate:<file>` debounce keys).
+ *
+ * Pure-FS read/modify/write. A missing or malformed file is treated as
+ * empty — callers run inside hooks that must never throw. The path is
+ * routed through `cairnDir` so `CAIRN_HOME` redirection holds
+ * (smoke-cairn-home).
+ *
+ * GC: the per-session dir (and this file with it) is removed by
+ * `gcStaleSessions` / `cleanupSession` (session/id.ts).
+ */
+/**
+ * Short content fingerprint for change-detection. sha256 hex sliced to
+ * 12 chars — collision-irrelevant for "did this exact text change".
+ */
+export declare function fingerprintText(text: string): string;
+/** Last fingerprint stored under `key`, or null when none. */
+export declare function getSeenFingerprint(repoRoot: string, sessionId: string, key: string): string | null;
+/** Record `fp` as the fingerprint for `key` (overwrites any prior). */
+export declare function setSeenFingerprint(repoRoot: string, sessionId: string, key: string, fp: string): void;
+/** Subset of `ids` not yet marked shown this session (order preserved). */
+export declare function filterUnshownIds(repoRoot: string, sessionId: string, ids: string[]): string[];
+/** Mark each id in `ids` as shown this session (idempotent, deduped). */
+export declare function markShownIds(repoRoot: string, sessionId: string, ids: string[]): void;
+/** True when `id` has already been surfaced this session. */
+export declare function hasShownId(repoRoot: string, sessionId: string, id: string): boolean;

package/dist/session/seen.js

@@ -0,0 +1,110 @@
+/**
+ * Per-session dedup store — `.cairn/sessions/<id>/seen.json`.
+ *
+ * The context engine injects scoped ground state as the agent works
+ * (working header, DEC/INV legends, component slices). Without dedup
+ * the injectors re-send unchanged context every turn and *become* the
+ * context-bloat problem they exist to solve. This module is the
+ * single source of "already shown this session":
+ *
+ *   - `fingerprints` — keyed text hashes (e.g. `working-header`). An
+ *     injector re-emits only when the hash changed.
+ *   - `shownIds` — flat set of opaque ids already surfaced once
+ *     (DEC-/INV- ids, component names, `annotate:<file>` debounce keys).
+ *
+ * Pure-FS read/modify/write. A missing or malformed file is treated as
+ * empty — callers run inside hooks that must never throw. The path is
+ * routed through `cairnDir` so `CAIRN_HOME` redirection holds
+ * (smoke-cairn-home).
+ *
+ * GC: the per-session dir (and this file with it) is removed by
+ * `gcStaleSessions` / `cleanupSession` (session/id.ts).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { bodyContentHash, cairnDir } from "@isaacriehm/cairn-state";
+function seenPath(repoRoot, sessionId) {
+    return cairnDir(repoRoot, "sessions", sessionId, "seen.json");
+}
+function readSeen(repoRoot, sessionId) {
+    const empty = { fingerprints: {}, shownIds: [] };
+    const path = seenPath(repoRoot, sessionId);
+    if (!existsSync(path))
+        return empty;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return empty;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return empty;
+    const p = parsed;
+    const fingerprints = typeof p.fingerprints === "object" && p.fingerprints !== null
+        ? p.fingerprints
+        : {};
+    const shownIds = Array.isArray(p.shownIds)
+        ? p.shownIds.filter((x) => typeof x === "string")
+        : [];
+    return { fingerprints, shownIds };
+}
+function writeSeen(repoRoot, sessionId, data) {
+    const path = seenPath(repoRoot, sessionId);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // best-effort — never throw inside a hook
+    }
+}
+/**
+ * Short content fingerprint for change-detection. sha256 hex sliced to
+ * 12 chars — collision-irrelevant for "did this exact text change".
+ */
+export function fingerprintText(text) {
+    return bodyContentHash(text).slice(0, 12);
+}
+/** Last fingerprint stored under `key`, or null when none. */
+export function getSeenFingerprint(repoRoot, sessionId, key) {
+    const seen = readSeen(repoRoot, sessionId);
+    return seen.fingerprints[key] ?? null;
+}
+/** Record `fp` as the fingerprint for `key` (overwrites any prior). */
+export function setSeenFingerprint(repoRoot, sessionId, key, fp) {
+    const seen = readSeen(repoRoot, sessionId);
+    seen.fingerprints[key] = fp;
+    writeSeen(repoRoot, sessionId, seen);
+}
+/** Subset of `ids` not yet marked shown this session (order preserved). */
+export function filterUnshownIds(repoRoot, sessionId, ids) {
+    const seen = readSeen(repoRoot, sessionId);
+    const shown = new Set(seen.shownIds);
+    const out = [];
+    const local = new Set();
+    for (const id of ids) {
+        if (shown.has(id) || local.has(id))
+            continue;
+        local.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/** Mark each id in `ids` as shown this session (idempotent, deduped). */
+export function markShownIds(repoRoot, sessionId, ids) {
+    if (ids.length === 0)
+        return;
+    const seen = readSeen(repoRoot, sessionId);
+    const set = new Set(seen.shownIds);
+    for (const id of ids)
+        set.add(id);
+    seen.shownIds = [...set];
+    writeSeen(repoRoot, sessionId, seen);
+}
+/** True when `id` has already been surfaced this session. */
+export function hasShownId(repoRoot, sessionId, id) {
+    const seen = readSeen(repoRoot, sessionId);
+    return seen.shownIds.includes(id);
+}
+//# sourceMappingURL=seen.js.map

package/dist/session/seen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seen.js","sourceRoot":"","sources":["../../src/session/seen.ts"],"names":[],"mappings":"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"}

package/dist/session/touched.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-session touched-file set — `.cairn/sessions/<id>/touched.json`.
+ *
+ * The PostToolUse(Write|Edit) hook appends every repo-relative path the
+ * agent writes this session (D6). The Stop capture-gate reads the set,
+ * filters to component-dir files missing a `@cairn` header, and surfaces
+ * a fully-specified `cairn_component_annotate` ask. This is the source
+ * for "what did this session touch" — NOT the task journal (which only
+ * carries explicitly-journaled work).
+ *
+ * Pure-FS dedup set. Missing/malformed file → empty. Routed through
+ * `cairnDir` (smoke-cairn-home). GC'd with the per-session dir.
+ */
+/** Repo-relative POSIX paths the agent has written this session. */
+export declare function readTouched(repoRoot: string, sessionId: string): string[];
+/** Add `relPath` (repo-relative POSIX) to the session's touched set. */
+export declare function appendTouched(repoRoot: string, sessionId: string, relPath: string): void;

package/dist/session/touched.js

@@ -0,0 +1,57 @@
+/**
+ * Per-session touched-file set — `.cairn/sessions/<id>/touched.json`.
+ *
+ * The PostToolUse(Write|Edit) hook appends every repo-relative path the
+ * agent writes this session (D6). The Stop capture-gate reads the set,
+ * filters to component-dir files missing a `@cairn` header, and surfaces
+ * a fully-specified `cairn_component_annotate` ask. This is the source
+ * for "what did this session touch" — NOT the task journal (which only
+ * carries explicitly-journaled work).
+ *
+ * Pure-FS dedup set. Missing/malformed file → empty. Routed through
+ * `cairnDir` (smoke-cairn-home). GC'd with the per-session dir.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { cairnDir } from "@isaacriehm/cairn-state";
+function touchedPath(repoRoot, sessionId) {
+    return cairnDir(repoRoot, "sessions", sessionId, "touched.json");
+}
+/** Repo-relative POSIX paths the agent has written this session. */
+export function readTouched(repoRoot, sessionId) {
+    const path = touchedPath(repoRoot, sessionId);
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const p = parsed;
+    return Array.isArray(p.paths)
+        ? p.paths.filter((x) => typeof x === "string")
+        : [];
+}
+/** Add `relPath` (repo-relative POSIX) to the session's touched set. */
+export function appendTouched(repoRoot, sessionId, relPath) {
+    if (relPath.length === 0)
+        return;
+    const norm = relPath.replace(/\\/g, "/");
+    const existing = readTouched(repoRoot, sessionId);
+    if (existing.includes(norm))
+        return;
+    existing.push(norm);
+    const path = touchedPath(repoRoot, sessionId);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify({ paths: existing }, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // best-effort — never throw inside a hook
+    }
+}
+//# sourceMappingURL=touched.js.map

package/dist/session/touched.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"touched.js","sourceRoot":"","sources":["../../src/session/touched.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAMnD,SAAS,WAAW,CAAC,QAAgB,EAAE,SAAiB;IACtD,OAAO,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;AACnE,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,SAAiB;IAC7D,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7D,MAAM,CAAC,GAAG,MAA8B,CAAC;IACzC,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QAC3D,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,SAAiB,EACjB,OAAe;IAEf,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAClD,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IACpC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;AACH,CAAC"}

package/dist/tasks/spec-reader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared `spec.tightened.md` frontmatter + `## Goal` reader.
+ *
+ * Factored out of `cairn_resume` (mcp/tools/resume.ts) so both the
+ * resume payload AND the UserPromptSubmit working-header (context
+ * engine, stage 1) read the spec the same way — one parse, no drift.
+ * The parse is verbatim from the original resume.ts implementation.
+ *
+ * Returns null when the task has no `spec.tightened.md` yet (e.g. a
+ * task still in `queued`/`tightening`). Malformed frontmatter degrades
+ * to defaults rather than throwing — callers run inside hooks that must
+ * never crash the agent loop.
+ */
+export interface TaskSpec {
+    title: string;
+    goal: string;
+    inScopeDecisions: string[];
+    inScopeInvariants: string[];
+    targetPathGlobs: string[];
+}
+/**
+ * Read `<taskDir>/spec.tightened.md`'s frontmatter (`title`,
+ * `in_scope_decisions[]`, `in_scope_invariants[]`, `target_path_globs[]`)
+ * and the body's `## Goal` section. `taskDir` is the absolute task
+ * directory (active or done). Returns null when the spec file is absent.
+ */
+export declare function readTaskSpec(taskDir: string): TaskSpec | null;