@isaacriehm/cairn-core 0.22.6 → 0.24.0

package/dist/cites/expand.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Inline cite expander — the inverse of sot-align's strip-replace.
+ *
+ * sot-align replaces a prose block with a bare `// §DEC-<hash>` /
+ * `// §INV-<hash>` citation. This expands such a citation back into the
+ * entity's body, rendered as a plain comment in the file's own comment
+ * style. Two uses:
+ *
+ *   1. Uninstall — un-cite a repo so removing `.cairn/` leaves the source
+ *      self-documenting, with no dangling `§DEC-/§INV-` references.
+ *   2. General "expand cites" tooling.
+ *
+ * Only a PURE cite line — one whose entire content (after the comment
+ * leader) is citation tokens — is expanded. A citation that shares a line
+ * with code is left untouched (counted as `inlineSkipped`); a citation
+ * whose entity is missing on disk is left as-is (`danglingSkipped`).
+ */
+export interface ExpandResult {
+    text: string;
+    /** Citations replaced with their entity body. */
+    expanded: number;
+    /** Citation ids with no entity on disk — left in place. */
+    danglingSkipped: number;
+    /** Citations sharing a line with code — left in place. */
+    inlineSkipped: number;
+}
+/**
+ * Pure transform: expand every pure-cite line in `text`. `resolve` returns
+ * an entity body (post-frontmatter) by id, or null when it doesn't exist.
+ */
+export declare function expandCitesInText(text: string, resolve: (id: string) => string | null): ExpandResult;
+export interface ExpandCitesFileOptions {
+    repoRoot: string;
+    /** Repo-relative path. */
+    filePath: string;
+    /** When true, compute the result but don't write. */
+    dryRun?: boolean;
+}
+export interface ExpandCitesFileResult extends ExpandResult {
+    filePath: string;
+    changed: boolean;
+}
+/**
+ * Expand every pure-cite line in one source file, resolving ids against the
+ * live `.cairn/ground/{decisions,invariants}/` store. Writes in place unless
+ * `dryRun`.
+ */
+export declare function expandCitesInFile(opts: ExpandCitesFileOptions): ExpandCitesFileResult;
+/**
+ * Walk the working tree for files that contain a `§DEC-/§INV-` token. The
+ * source of truth for un-citing is the source itself, NOT the scope-index —
+ * a stale/missing scope-index would silently leave dangling cites behind.
+ */
+export declare function findCitedFiles(repoRoot: string): string[];
+export interface ExpandCitesRepoOptions {
+    repoRoot: string;
+    /**
+     * Explicit repo-relative files to expand. When omitted, the working tree
+     * is scanned for every file carrying a `§DEC-/§INV-` token.
+     */
+    files?: string[];
+    dryRun?: boolean;
+}
+export interface ExpandCitesRepoResult {
+    files: ExpandCitesFileResult[];
+    filesChanged: number;
+    expanded: number;
+    danglingSkipped: number;
+    inlineSkipped: number;
+}
+/**
+ * Expand cites across many files. Defaults to the scope-index's cited-file
+ * set; pass `files` to target a subset (or when the scope-index is absent).
+ */
+export declare function expandCitesInRepo(opts: ExpandCitesRepoOptions): ExpandCitesRepoResult;

package/dist/cites/expand.js

@@ -0,0 +1,197 @@
+/**
+ * Inline cite expander — the inverse of sot-align's strip-replace.
+ *
+ * sot-align replaces a prose block with a bare `// §DEC-<hash>` /
+ * `// §INV-<hash>` citation. This expands such a citation back into the
+ * entity's body, rendered as a plain comment in the file's own comment
+ * style. Two uses:
+ *
+ *   1. Uninstall — un-cite a repo so removing `.cairn/` leaves the source
+ *      self-documenting, with no dangling `§DEC-/§INV-` references.
+ *   2. General "expand cites" tooling.
+ *
+ * Only a PURE cite line — one whose entire content (after the comment
+ * leader) is citation tokens — is expanded. A citation that shares a line
+ * with code is left untouched (counted as `inlineSkipped`); a citation
+ * whose entity is missing on disk is left as-is (`danglingSkipped`).
+ */
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readEntityBody } from "../hooks/sot-align-common.js";
+const CITE_RE = /§(DEC|INV)-([0-9a-f]{7,})/g;
+/** A line that, with all cite tokens removed, is only indent + comment leader. */
+const PURE_CITE_LEADER_RE = /^(\s*)(\/\/+|#+|;+|--+|\*)?\s*$/;
+/**
+ * Pure transform: expand every pure-cite line in `text`. `resolve` returns
+ * an entity body (post-frontmatter) by id, or null when it doesn't exist.
+ */
+export function expandCitesInText(text, resolve) {
+    let expanded = 0;
+    let danglingSkipped = 0;
+    let inlineSkipped = 0;
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    for (const line of lines) {
+        const cites = [...line.matchAll(CITE_RE)];
+        if (cites.length === 0) {
+            out.push(line);
+            continue;
+        }
+        const stripped = line.replace(CITE_RE, "").replace(/\s+$/, "");
+        const leaderMatch = stripped.match(PURE_CITE_LEADER_RE);
+        if (leaderMatch === null) {
+            // Citation shares the line with code — don't touch it.
+            inlineSkipped += cites.length;
+            out.push(line);
+            continue;
+        }
+        const indent = leaderMatch[1] ?? "";
+        const leader = leaderMatch[2] ?? "//";
+        const replacement = [];
+        let expandedAny = false;
+        cites.forEach((m, idx) => {
+            const id = `${m[1]}-${m[2]}`;
+            const body = resolve(id);
+            if (body === null) {
+                danglingSkipped += 1;
+                replacement.push(`${indent}${leader} §${id}`); // keep dangling cite verbatim
+                return;
+            }
+            if (expandedAny)
+                replacement.push(`${indent}${leader}`); // separator between bodies
+            for (const bl of body.split(/\r?\n/)) {
+                replacement.push(bl.length > 0 ? `${indent}${leader} ${bl}` : `${indent}${leader}`);
+            }
+            expanded += 1;
+            expandedAny = true;
+            void idx;
+        });
+        out.push(...replacement);
+    }
+    return { text: out.join(eol), expanded, danglingSkipped, inlineSkipped };
+}
+/**
+ * Expand every pure-cite line in one source file, resolving ids against the
+ * live `.cairn/ground/{decisions,invariants}/` store. Writes in place unless
+ * `dryRun`.
+ */
+export function expandCitesInFile(opts) {
+    const abs = join(opts.repoRoot, opts.filePath);
+    const empty = {
+        filePath: opts.filePath,
+        text: "",
+        expanded: 0,
+        danglingSkipped: 0,
+        inlineSkipped: 0,
+        changed: false,
+    };
+    if (!existsSync(abs))
+        return empty;
+    let source;
+    try {
+        source = readFileSync(abs, "utf8");
+    }
+    catch {
+        return empty;
+    }
+    const result = expandCitesInText(source, (id) => readEntityBody(opts.repoRoot, id));
+    const changed = result.text !== source;
+    if (changed && opts.dryRun !== true) {
+        writeFileSync(abs, result.text, "utf8");
+    }
+    return { ...result, filePath: opts.filePath, changed };
+}
+/** Dirs the cited-file scan never descends into. */
+const SCAN_SKIP_DIRS = new Set([
+    ".git",
+    ".cairn",
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".vercel",
+]);
+const CITE_SCAN_RE = /§(?:DEC|INV)-[0-9a-f]{7,}/;
+const SCAN_SKIP_EXT = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".pdf", ".zip", ".gz",
+    ".woff", ".woff2", ".ttf", ".eot", ".mp4", ".mov", ".wasm", ".lock", ".map",
+]);
+const SCAN_MAX_BYTES = 2_000_000;
+/**
+ * Walk the working tree for files that contain a `§DEC-/§INV-` token. The
+ * source of truth for un-citing is the source itself, NOT the scope-index —
+ * a stale/missing scope-index would silently leave dangling cites behind.
+ */
+export function findCitedFiles(repoRoot) {
+    const out = [];
+    const walk = (absDir, relDir) => {
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const rel = relDir.length > 0 ? `${relDir}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (SCAN_SKIP_DIRS.has(e.name))
+                    continue;
+                walk(join(absDir, e.name), rel);
+            }
+            else if (e.isFile()) {
+                const dot = e.name.lastIndexOf(".");
+                if (dot !== -1 && SCAN_SKIP_EXT.has(e.name.slice(dot).toLowerCase()))
+                    continue;
+                const abs = join(absDir, e.name);
+                try {
+                    if (statSync(abs).size > SCAN_MAX_BYTES)
+                        continue;
+                    if (CITE_SCAN_RE.test(readFileSync(abs, "utf8")))
+                        out.push(rel);
+                }
+                catch {
+                    /* unreadable — skip */
+                }
+            }
+        }
+    };
+    walk(repoRoot, "");
+    return out;
+}
+/**
+ * Expand cites across many files. Defaults to the scope-index's cited-file
+ * set; pass `files` to target a subset (or when the scope-index is absent).
+ */
+export function expandCitesInRepo(opts) {
+    const targets = opts.files ?? findCitedFiles(opts.repoRoot);
+    const out = {
+        files: [],
+        filesChanged: 0,
+        expanded: 0,
+        danglingSkipped: 0,
+        inlineSkipped: 0,
+    };
+    for (const filePath of targets) {
+        const r = expandCitesInFile({
+            repoRoot: opts.repoRoot,
+            filePath,
+            ...(opts.dryRun !== undefined ? { dryRun: opts.dryRun } : {}),
+        });
+        if (r.expanded === 0 && r.danglingSkipped === 0 && r.inlineSkipped === 0) {
+            continue; // no cites in this file
+        }
+        out.files.push(r);
+        if (r.changed)
+            out.filesChanged += 1;
+        out.expanded += r.expanded;
+        out.danglingSkipped += r.danglingSkipped;
+        out.inlineSkipped += r.inlineSkipped;
+    }
+    return out;
+}
+//# sourceMappingURL=expand.js.map

package/dist/cites/expand.js.map

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

package/dist/context/index.d.ts

@@ -9,3 +9,5 @@ export { buildSpecDelta } from "./spec-delta.js";
 export type { SpecDelta } from "./spec-delta.js";
 export { readActiveTaskSummary } from "./task-summary.js";
 export type { ActiveTaskSummary } from "./task-summary.js";
+export { buildWorkingHeader } from "./working-header.js";
+export type { WorkingHeader } from "./working-header.js";

package/dist/context/index.js

@@ -7,4 +7,5 @@
 export { buildHandoffBlock } from "./handoff-builder.js";
 export { buildSpecDelta } from "./spec-delta.js";
 export { readActiveTaskSummary } from "./task-summary.js";
+export { buildWorkingHeader } from "./working-header.js";
 //# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/context/task-summary.d.ts

@@ -16,3 +16,21 @@ export interface ActiveTaskSummary {
     taskModule: string;
 }
 export declare function readActiveTaskSummary(repoRoot: string): ActiveTaskSummary | null;
+/**
+ * Summary for one specific active task id, or null when it is not
+ * in-flight. Used by the working-context header to render the task this
+ * session is actually on (resolved by session affinity) rather than the
+ * first/arbitrary active task.
+ */
+export declare function readTaskSummaryById(repoRoot: string, taskId: string): ActiveTaskSummary | null;
+/**
+ * Resolve which active task THIS session is on, for multi-task /
+ * multi-window correctness. Among in-flight tasks, prefer one this
+ * session created or last journaled (`created_by_session` /
+ * `last_journal_session` on status.yaml); fall back to the most-recently
+ * touched active task. Returns null when nothing is in flight.
+ *
+ * Without this, two Claude windows on one checkout would both surface
+ * whichever task was globally first/most-recent — wrong frame.
+ */
+export declare function resolveSessionTaskId(repoRoot: string, sessionId: string | null): string | null;

package/dist/context/task-summary.js

@@ -8,7 +8,7 @@
  * unrecognized values collapse to `idle` so the surface stays quiet
  * when nothing is actually in flight.
  */
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { cairnDir, parseFrontmatter } from "@isaacriehm/cairn-state";
@@ -52,8 +52,48 @@ export function readActiveTaskSummary(repoRoot) {
     for (const e of dirents) {
         if (!e.isDirectory())
             continue;
-        const taskDir = join(activeDir, e.name);
-        const statusPath = join(taskDir, "status.yaml");
+        const summary = summarizeActiveTask(join(activeDir, e.name), e.name);
+        if (summary !== null)
+            return summary;
+    }
+    return null;
+}
+/**
+ * Summary for one specific active task id, or null when it is not
+ * in-flight. Used by the working-context header to render the task this
+ * session is actually on (resolved by session affinity) rather than the
+ * first/arbitrary active task.
+ */
+export function readTaskSummaryById(repoRoot, taskId) {
+    return summarizeActiveTask(cairnDir(repoRoot, "tasks", "active", taskId), taskId);
+}
+/**
+ * Resolve which active task THIS session is on, for multi-task /
+ * multi-window correctness. Among in-flight tasks, prefer one this
+ * session created or last journaled (`created_by_session` /
+ * `last_journal_session` on status.yaml); fall back to the most-recently
+ * touched active task. Returns null when nothing is in flight.
+ *
+ * Without this, two Claude windows on one checkout would both surface
+ * whichever task was globally first/most-recent — wrong frame.
+ */
+export function resolveSessionTaskId(repoRoot, sessionId) {
+    const activeDir = cairnDir(repoRoot, "tasks", "active");
+    if (!existsSync(activeDir))
+        return null;
+    let dirents;
+    try {
+        dirents = readdirSync(activeDir, { withFileTypes: true, encoding: "utf8" });
+    }
+    catch {
+        return null;
+    }
+    const sid = sessionId !== null && sessionId.length > 0 ? sessionId : null;
+    const candidates = [];
+    for (const e of dirents) {
+        if (!e.isDirectory())
+            continue;
+        const statusPath = join(activeDir, e.name, "status.yaml");
         if (!existsSync(statusPath))
             continue;
         let parsed;
@@ -65,29 +105,60 @@ export function readActiveTaskSummary(repoRoot) {
         }
         if (typeof parsed !== "object" || parsed === null)
             continue;
-        const phase = parsed.phase;
+        const o = parsed;
+        const phase = o["phase"];
         if (typeof phase !== "string" || !ACTIVE_PHASES.has(phase))
             continue;
-        let title = e.name;
-        const specPath = join(taskDir, "spec.tightened.md");
-        if (existsSync(specPath)) {
-            try {
-                const specText = readFileSync(specPath, "utf8");
-                const body = parseFrontmatter(specText).body;
-                const m = body.match(/^#\s+(.+)$/m);
-                if (m && m[1])
-                    title = m[1].trim();
-            }
-            catch {
-                // fall through to taskId
-            }
+        let mtimeMs = 0;
+        try {
+            mtimeMs = statSync(statusPath).mtimeMs;
         }
-        return {
-            taskId: e.name,
-            taskState: mapPhase(phase),
-            taskModule: title,
-        };
+        catch {
+            // keep 0 — undated tasks sort last
+        }
+        const owned = sid !== null &&
+            (o["last_journal_session"] === sid || o["created_by_session"] === sid);
+        candidates.push({ taskId: e.name, mtimeMs, owned });
     }
-    return null;
+    if (candidates.length === 0)
+        return null;
+    const byRecent = (a, b) => b.mtimeMs - a.mtimeMs;
+    const owned = candidates.filter((c) => c.owned).sort(byRecent);
+    if (owned.length > 0)
+        return owned[0].taskId;
+    return candidates.sort(byRecent)[0].taskId;
+}
+/** Read one active task dir into a summary, or null when not in-flight. */
+function summarizeActiveTask(taskDir, taskId) {
+    const statusPath = join(taskDir, "status.yaml");
+    if (!existsSync(statusPath))
+        return null;
+    let parsed;
+    try {
+        parsed = parseYaml(readFileSync(statusPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const phase = parsed.phase;
+    if (typeof phase !== "string" || !ACTIVE_PHASES.has(phase))
+        return null;
+    let title = taskId;
+    const specPath = join(taskDir, "spec.tightened.md");
+    if (existsSync(specPath)) {
+        try {
+            const specText = readFileSync(specPath, "utf8");
+            const body = parseFrontmatter(specText).body;
+            const m = body.match(/^#\s+(.+)$/m);
+            if (m && m[1])
+                title = m[1].trim();
+        }
+        catch {
+            // fall through to taskId
+        }
+    }
+    return { taskId, taskState: mapPhase(phase), taskModule: title };
 }
 //# sourceMappingURL=task-summary.js.map

package/dist/context/task-summary.js.map

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

package/dist/context/working-header.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Working-context header — the context engine's stage-1 surface.
+ *
+ * Per prompt (UserPromptSubmit), the server injects a compact "what am
+ * I working on" frame so the agent never has to call `cairn_in_scope` /
+ * `cairn_mission_get` to know its frame. This module builds that text +
+ * a fingerprint; the runner injects it only when the fingerprint
+ * changed (per-session dedup via session/seen.ts).
+ *
+ * The header is the PERSISTENT in-scope id INDEX (every prompt) — ids
+ * only, no bodies. The stage-2 read-enricher shows each DEC/INV/
+ * component BODY once per session. So the agent always knows WHAT is in
+ * scope (this header) even after a body scrolled off (D13).
+ *
+ * Pure-FS, zero LLM — safe to run on every prompt inside a hook.
+ *
+ * Spec: docs/CONTEXT_ENGINE.md (stage 1), CAIRN_REBUILD §6 / D11–D13.
+ */
+export interface WorkingHeader {
+    text: string;
+    fingerprint: string;
+}
+/**
+ * Build the working-context header for the repo's current frame, or
+ * null when there is no active task AND no active mission (D11 — inject
+ * nothing extra). When a task is active but has no in-scope ids, the
+ * "In scope" line is omitted (active-task line only).
+ */
+export declare function buildWorkingHeader(repoRoot: string, sessionId: string | null): WorkingHeader | null;

package/dist/context/working-header.js

@@ -0,0 +1,125 @@
+/**
+ * Working-context header — the context engine's stage-1 surface.
+ *
+ * Per prompt (UserPromptSubmit), the server injects a compact "what am
+ * I working on" frame so the agent never has to call `cairn_in_scope` /
+ * `cairn_mission_get` to know its frame. This module builds that text +
+ * a fingerprint; the runner injects it only when the fingerprint
+ * changed (per-session dedup via session/seen.ts).
+ *
+ * The header is the PERSISTENT in-scope id INDEX (every prompt) — ids
+ * only, no bodies. The stage-2 read-enricher shows each DEC/INV/
+ * component BODY once per session. So the agent always knows WHAT is in
+ * scope (this header) even after a body scrolled off (D13).
+ *
+ * Pure-FS, zero LLM — safe to run on every prompt inside a hook.
+ *
+ * Spec: docs/CONTEXT_ENGINE.md (stage 1), CAIRN_REBUILD §6 / D11–D13.
+ */
+import { cairnDir, findActiveMission, readMissionState, readRoadmap, } from "@isaacriehm/cairn-state";
+import { resolveSessionTaskId, readTaskSummaryById } from "./task-summary.js";
+import { readTaskMissionAnchor } from "../missions/index.js";
+import { readTaskSpec } from "../tasks/spec-reader.js";
+import { fingerprintText } from "../session/seen.js";
+const GOAL_MAX = 120;
+const ID_LIST_CAP = 12;
+/** Truncate at a word boundary, appending `…` when cut. */
+function truncateAtWord(s, max) {
+    const flat = s.replace(/\s+/g, " ").trim();
+    if (flat.length <= max)
+        return flat;
+    const slice = flat.slice(0, max);
+    const lastSpace = slice.lastIndexOf(" ");
+    const cut = lastSpace > max * 0.6 ? slice.slice(0, lastSpace) : slice;
+    return `${cut.trimEnd()}…`;
+}
+/** Render up to `cap` ids, then `(+N more)`. Empty → "". */
+function renderIdList(ids, cap) {
+    if (ids.length === 0)
+        return "";
+    const head = ids.slice(0, cap);
+    const extra = ids.length - head.length;
+    const base = head.join(", ");
+    return extra > 0 ? `${base} (+${extra} more)` : base;
+}
+/**
+ * Build the working-context header for the repo's current frame, or
+ * null when there is no active task AND no active mission (D11 — inject
+ * nothing extra). When a task is active but has no in-scope ids, the
+ * "In scope" line is omitted (active-task line only).
+ */
+export function buildWorkingHeader(repoRoot, sessionId) {
+    // Resolve the task THIS session is on (affinity), not a global pick —
+    // correct when multiple tasks are active across windows.
+    const taskId = resolveSessionTaskId(repoRoot, sessionId);
+    const active = taskId !== null ? readTaskSummaryById(repoRoot, taskId) : null;
+    // Mission: prefer the resolved task's own anchor (the mission + phase
+    // this session is working) over a global scan — correct when several
+    // missions are active. Fall back to the single active mission only
+    // when there's no task to anchor on.
+    const anchor = active !== null ? readTaskMissionAnchor(repoRoot, active.taskId) : null;
+    const missionId = anchor?.mission_id ?? findActiveMission(repoRoot);
+    const preferredPhaseId = anchor?.phase_id ?? null;
+    if (active === null && missionId === null)
+        return null;
+    const lines = ["## Cairn — working context"];
+    let hasInScope = false;
+    if (active !== null) {
+        const spec = readTaskSpec(cairnDir(repoRoot, "tasks", "active", active.taskId));
+        const goal = spec !== null && spec.goal.length > 0 ? spec.goal : "";
+        const parts = [`Active: ${active.taskId} (${active.taskState})`];
+        if (goal.length > 0)
+            parts.push(`— ${truncateAtWord(goal, GOAL_MAX)}`);
+        if (active.taskModule.length > 0 && active.taskModule !== active.taskId) {
+            parts.push(`· module ${active.taskModule}`);
+        }
+        lines.push(parts.join(" "));
+        const decs = spec?.inScopeDecisions ?? [];
+        const invs = spec?.inScopeInvariants ?? [];
+        if (decs.length > 0 || invs.length > 0) {
+            hasInScope = true;
+            const segs = [];
+            if (decs.length > 0)
+                segs.push(renderIdList(decs, ID_LIST_CAP));
+            if (invs.length > 0)
+                segs.push(renderIdList(invs, ID_LIST_CAP));
+            lines.push(`In scope: ${segs.join(" · ")}`);
+        }
+    }
+    if (missionId !== null) {
+        const missionLine = renderMissionLine(repoRoot, missionId, preferredPhaseId);
+        if (missionLine !== null)
+            lines.push(missionLine);
+    }
+    if (hasInScope) {
+        lines.push("Bodies on demand: cairn_decision_get / cairn_invariant_get.");
+    }
+    const text = lines.join("\n");
+    return { text, fingerprint: fingerprintText(text) };
+}
+/**
+ * `Mission: <title> — phase <i>/<n> "<phase title>"`. Degrades to a
+ * title-only line when the cursor phase can't be located, and to null
+ * when the mission state/roadmap is unreadable (D-graceful: never throw).
+ */
+function renderMissionLine(repoRoot, missionId, preferredPhaseId) {
+    const roadmap = readRoadmap(repoRoot, missionId);
+    const state = readMissionState(repoRoot, missionId);
+    if (roadmap === null)
+        return null;
+    const title = roadmap.frontmatter.title;
+    const phases = roadmap.frontmatter.phases;
+    // The task anchor's phase wins (the phase THIS session is working);
+    // fall back to the mission cursor when there's no task anchor.
+    const activePhase = preferredPhaseId ?? state?.cursor.active_phase ?? null;
+    if (activePhase !== null) {
+        const idx = phases.findIndex((p) => p.id === activePhase);
+        if (idx >= 0) {
+            const phase = phases[idx];
+            const phaseTitle = phase !== undefined ? phase.title : activePhase;
+            return `Mission: ${title} — phase ${idx + 1}/${phases.length} "${phaseTitle}"`;
+        }
+    }
+    return `Mission: ${title}`;
+}
+//# sourceMappingURL=working-header.js.map

package/dist/context/working-header.js.map

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