codecartographer-pi 0.20.0 → 0.21.0

package/dist/core/broadside.js

@@ -31,11 +31,12 @@
 // executable surfaces (Pi and MCP), not the pure template. What the template does
 // carry is the reading guide for its output — `.codecarto/broadside/SKILL.md`,
 // served by codecarto_skill under the name `broadside` (see readBroadsideSkill).
+import { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { join, relative } from "node:path";
-import { atomicWriteFile, pathExists, sleep } from "./utils.js";
+import { atomicWriteFile, GIT_TIMEOUT_MS, pathExists, sleep } from "./utils.js";
 import { describeRedactions, isSecretFile, redactSecrets } from "./secrets.js";
 import { acquireLock } from "./status.js";
 import { loadYamlFile } from "./yaml.js";
@@ -75,6 +76,16 @@ export const BROADSIDE_LENS_IDS = [
 ];
 export const BROADSIDE_POLL_INTERVAL_MS = 15_000;
 export const BROADSIDE_DEFAULT_POLL_BUDGET_MS = 25 * 60 * 1000;
+/**
+ * The run expense limit in USD a repository gets before it configures one.
+ * Pi asks a human before submitting over the estimate; the MCP surface cannot,
+ * and shipped with no limit at all, so a host calling submit with the stock
+ * config spent whatever the estimate came to (#231). One dollar covers a
+ * six-lens run of a repository this size with room to spare; a larger one
+ * raises `max_cost` in config.yaml, passes `max_cost` on the call, or sets it
+ * to 0 for no limit.
+ */
+export const BROADSIDE_DEFAULT_MAX_COST = 1;
 /**
  * The share of a lens's output budget reasoning may spend.
  *
@@ -120,6 +131,37 @@ export class BroadsideAuthError extends Error {
         this.detail = detail;
     }
 }
+/**
+ * `broadside/config.yaml` exists but cannot be used. A file that failed to
+ * parse used to be treated exactly like an absent one — defaults, including
+ * no spend cap and no lens routing, with no message — so a typo removed the
+ * user's own guard (#232). Only an absent file yields defaults now.
+ */
+export class BroadsideConfigError extends Error {
+    path;
+    constructor(path, detail) {
+        super(`Broad-Side config ${path} ${detail}. Fix or remove the file; nothing runs on defaults while it is unreadable.`);
+        this.name = "BroadsideConfigError";
+        this.path = path;
+    }
+}
+/**
+ * `broadside/state.json` exists but cannot be read. It used to be read as
+ * empty and the next checkpoint wrote that empty state over it, losing the
+ * batch ids of every in-flight, already-paid run (#233). The corrupt file is
+ * preserved beside itself and nothing writes over it until someone looks.
+ */
+export class BroadsideStateError extends Error {
+    path;
+    backupPath;
+    constructor(path, backupPath, detail) {
+        super(`Broad-Side state ${path} ${detail}. A copy is preserved at ${backupPath}; the file is not overwritten. ` +
+            "Repair state.json from the copy (each run's batch ids are what collect needs), or move it aside to start fresh.");
+        this.name = "BroadsideStateError";
+        this.path = path;
+        this.backupPath = backupPath;
+    }
+}
 /** Thrown when a confirm hook declines a run. Nothing was submitted. */
 export class BroadsideCancelledError extends Error {
     constructor(message = "Broad-Side submission cancelled. Nothing was submitted.") {
@@ -851,9 +893,10 @@ const SOURCE_SPECS = {
  */
 async function listRepoFiles(targetDir) {
     try {
-        const listed = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 64 * 1024 * 1024 });
+        const listed = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 64 * 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         const deleted = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--deleted"], {
             maxBuffer: 64 * 1024 * 1024,
+            timeout: GIT_TIMEOUT_MS,
         });
         const gone = new Set(deleted.stdout.split("\0").filter(Boolean));
         const files = listed.stdout.split("\0").filter((path) => path && !gone.has(path));
@@ -865,7 +908,7 @@ async function listRepoFiles(targetDir) {
 }
 async function gitHead(targetDir) {
     try {
-        const { stdout } = await execFileAsync("git", ["-C", targetDir, "rev-parse", "HEAD"], { maxBuffer: 1024 * 1024 });
+        const { stdout } = await execFileAsync("git", ["-C", targetDir, "rev-parse", "HEAD"], { maxBuffer: 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         return stdout.trim() || null;
     }
     catch {
@@ -874,7 +917,7 @@ async function gitHead(targetDir) {
 }
 async function gitDirty(targetDir) {
     try {
-        const { stdout } = await execFileAsync("git", ["-C", targetDir, "status", "--porcelain"], { maxBuffer: 1024 * 1024 });
+        const { stdout } = await execFileAsync("git", ["-C", targetDir, "status", "--porcelain"], { maxBuffer: 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         return stdout.trim().length > 0;
     }
     catch {
@@ -890,7 +933,7 @@ async function changedFilesSince(targetDir, baseHead) {
     if (!baseHead)
         return null;
     try {
-        const { stdout } = await execFileAsync("git", ["-C", targetDir, "diff", "--name-only", baseHead, "HEAD"], { maxBuffer: 64 * 1024 * 1024 });
+        const { stdout } = await execFileAsync("git", ["-C", targetDir, "diff", "--name-only", baseHead, "HEAD"], { maxBuffer: 64 * 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         return new Set(stdout.split("\n").filter(Boolean));
     }
     catch {
@@ -909,7 +952,7 @@ async function walkFiles(rootDir, dir, depth, remaining) {
         return out;
     }
     for (const entry of entries) {
-        if (entry.name.startsWith(".") && entry.name !== ".github")
+        if (entry.name.startsWith("."))
             continue;
         if (entry.isDirectory()) {
             if (SKIP_DIR_NAMES.has(entry.name))
@@ -1371,15 +1414,30 @@ export async function loadBroadsideState(broadsideDir) {
     const statePath = join(broadsideDir, BROADSIDE_STATE_FILE);
     if (!(await pathExists(statePath)))
         return defaultBroadsideState();
+    const text = await readFile(statePath, "utf8");
+    let raw;
     try {
-        const raw = JSON.parse(await readFile(statePath, "utf8"));
-        if (!raw || typeof raw !== "object" || !Array.isArray(raw.runs))
-            return defaultBroadsideState();
-        return raw;
+        raw = JSON.parse(text);
     }
-    catch {
-        return defaultBroadsideState();
+    catch (error) {
+        throw new BroadsideStateError(statePath, await preserveCorruptState(statePath, text), `could not be parsed (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (!raw || typeof raw !== "object" || !Array.isArray(raw.runs)) {
+        throw new BroadsideStateError(statePath, await preserveCorruptState(statePath, text), "is not a state file (expected an object with a runs array)");
     }
+    return raw;
+}
+/**
+ * Copy an unreadable state file to `state.json.corrupt-<hash>` beside it,
+ * named by content so repeated loads do not multiply copies. Returns the
+ * copy's path (the existing one, when the same content was preserved before).
+ */
+async function preserveCorruptState(statePath, text) {
+    const digest = createHash("sha1").update(text).digest("hex").slice(0, 8);
+    const backupPath = `${statePath}.corrupt-${digest}`;
+    if (!(await pathExists(backupPath)))
+        await writeFile(backupPath, text, "utf8");
+    return backupPath;
 }
 /**
  * Overwrite `state.json` wholesale with `state`.
@@ -1472,13 +1530,26 @@ export async function loadBroadsideConfig(broadsideDir) {
     const configPath = join(broadsideDir, BROADSIDE_CONFIG_FILE);
     let raw = {};
     if (await pathExists(configPath)) {
+        let parsed;
         try {
-            raw = (await loadYamlFile(configPath)) ?? {};
+            parsed = await loadYamlFile(configPath);
         }
-        catch {
-            raw = {};
+        catch (error) {
+            throw new BroadsideConfigError(configPath, `could not be parsed (${error instanceof Error ? error.message : String(error)})`);
+        }
+        if (parsed !== null && parsed !== undefined) {
+            if (typeof parsed !== "object" || Array.isArray(parsed))
+                throw new BroadsideConfigError(configPath, "is not a YAML mapping");
+            raw = parsed;
         }
     }
+    return buildBroadsideConfig(raw);
+}
+/** The shipped defaults: what an absent config.yaml means. */
+export function defaultBroadsideConfig() {
+    return buildBroadsideConfig({});
+}
+function buildBroadsideConfig(raw) {
     const lenses = Array.isArray(raw.default_lenses)
         ? (raw.default_lenses.filter((l) => BROADSIDE_LENS_IDS.includes(l)))
         : [];
@@ -1503,7 +1574,9 @@ export async function loadBroadsideConfig(broadsideDir) {
         model: typeof raw.model === "string" && raw.model.trim() ? raw.model.trim() : BROADSIDE_MODEL,
         apiKey: typeof raw.api_key === "string" ? raw.api_key.trim() : "",
         defaultLenses: lenses.length > 0 ? lenses : [...BROADSIDE_LENS_IDS],
-        maxCost: typeof raw.max_cost === "number" && raw.max_cost > 0 ? raw.max_cost : 0,
+        // Absent: the shipped default. An explicit 0 is "no limit", spelled out
+        // on purpose; a negative or non-numeric value is not a limit at all.
+        maxCost: typeof raw.max_cost === "number" && raw.max_cost >= 0 ? raw.max_cost : BROADSIDE_DEFAULT_MAX_COST,
         pricing: inputOverride !== undefined && outputOverride !== undefined
             ? { inputPerM: inputOverride, outputPerM: outputOverride }
             : null,
@@ -1520,13 +1593,18 @@ export async function loadBroadsideConfig(broadsideDir) {
         redactSecrets: flag("redact_secrets", true),
     };
 }
+// ---------- model catalog, pricing, benchmarks ----------
+/** The catalog cache schema this build writes; a file from another is not read. */
+export const BROADSIDE_CATALOG_CACHE_SCHEMA = 3;
 async function readCatalogCache(broadsideDir) {
     const cachePath = join(broadsideDir, BROADSIDE_CATALOG_CACHE_FILE);
     if (!(await pathExists(cachePath)))
         return null;
     try {
         const parsed = JSON.parse(await readFile(cachePath, "utf8"));
-        if (!parsed || typeof parsed !== "object" || typeof parsed.models !== "object")
+        if (!parsed || typeof parsed !== "object" || !parsed.models || typeof parsed.models !== "object")
+            return null;
+        if (parsed.schema_version !== BROADSIDE_CATALOG_CACHE_SCHEMA && parsed.schema_version !== 2)
             return null;
         return parsed;
     }
@@ -1534,6 +1612,11 @@ async function readCatalogCache(broadsideDir) {
         return null;
     }
 }
+/** When a cached entry was fetched: its own stamp, or the file's for a schema-2 cache. */
+function catalogEntryFetchedAt(cache, model) {
+    const stamp = cache.models[model]?.fetched_at ?? cache.fetched_at;
+    return new Date(stamp).getTime();
+}
 async function writeCatalogCache(broadsideDir, cache) {
     await mkdir(broadsideDir, { recursive: true });
     await writeFile(join(broadsideDir, BROADSIDE_CATALOG_CACHE_FILE), `${JSON.stringify(cache, null, "\t")}\n`, "utf8");
@@ -1613,7 +1696,7 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
     // constants below are what we fall back to when the network is unavailable.
     const cache = await readCatalogCache(broadsideDir);
     const cached = cache?.models[model];
-    if (cached && Date.now() - new Date(cache.fetched_at).getTime() < BROADSIDE_CATALOG_CACHE_TTL_MS) {
+    if (cache && cached && Date.now() - catalogEntryFetchedAt(cache, model) < BROADSIDE_CATALOG_CACHE_TTL_MS) {
         return { model, source: "cache", entry: cached };
     }
     // What went wrong when the live lookup produced nothing, for the error
@@ -1649,12 +1732,15 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
         catalogFailure = `the model catalog could not be fetched (${error instanceof Error ? error.message : String(error)})`;
     }
     if (live) {
+        const now = new Date().toISOString();
         const updated = {
-            schema_version: 2,
-            fetched_at: new Date().toISOString(),
-            models: { ...(cache?.models ?? {}) },
+            schema_version: BROADSIDE_CATALOG_CACHE_SCHEMA,
+            fetched_at: now,
+            // Other entries keep their own stamps (a schema-2 file's entries
+            // inherit the file's, once, on this upgrade); only this model is fresh.
+            models: Object.fromEntries(Object.entries(cache?.models ?? {}).map(([id, entry]) => [id, { ...entry, fetched_at: entry.fetched_at ?? cache.fetched_at }])),
         };
-        updated.models[model] = live;
+        updated.models[model] = { ...live, fetched_at: now };
         await writeCatalogCache(broadsideDir, updated);
         return { model, source: "live", entry: live };
     }
@@ -1751,9 +1837,10 @@ export async function listBatchModels(broadsideDir, config, apiKey, opts = {}) {
     }
     entries.sort((a, b) => a.inputPerM + a.outputPerM - (b.inputPerM + b.outputPerM));
     // Persist the catalog so the next submit's pricing resolution hits cache.
-    const cache = { schema_version: 2, fetched_at: new Date().toISOString(), models: {} };
+    const fetchedAt = new Date().toISOString();
+    const cache = { schema_version: BROADSIDE_CATALOG_CACHE_SCHEMA, fetched_at: fetchedAt, models: {} };
     for (const entry of entries)
-        cache.models[entry.id] = entry;
+        cache.models[entry.id] = { ...entry, fetched_at: fetchedAt };
     await writeCatalogCache(broadsideDir, cache);
     const benchmarks = opts.includeBenchmarks ? await fetchCodingBenchmarks(apiKey, fetcher) : null;
     return { entries, source: "live", benchmarks, defaultModel: config.model };
@@ -1811,6 +1898,14 @@ export async function fetchBatch(batchId, apiKey, fetcher = fetch) {
  * charged, so callers must come back for it rather than retire it.
  */
 export const BROADSIDE_DEAD_BATCH_STATUSES = ["failed", "expired", "cancelled", "auth-failed"];
+/**
+ * Batch entry statuses collect never polls again: the dead ones above, plus
+ * `completed`, plus the two a submit assigns without a batch (`skipped`: no
+ * matching files; `rejected`: the provider refused it). The 0.19.1 changelog
+ * called the dead set "a named constant rather than two hand-maintained
+ * lists"; this set was still three literal copies (self-audit sem 5.8).
+ */
+export const BROADSIDE_TERMINAL_ENTRY_STATUSES = ["completed", ...BROADSIDE_DEAD_BATCH_STATUSES, "skipped", "rejected"];
 export async function pollBatchUntilTerminal(batchId, apiKey, opts = {}) {
     const deadline = Date.now() + (opts.deadlineMs ?? BROADSIDE_DEFAULT_POLL_BUDGET_MS);
     const intervalMs = opts.pollIntervalMs ?? BROADSIDE_POLL_INTERVAL_MS;
@@ -2042,7 +2137,9 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
             `$${limit.toFixed(2)}. Nothing was submitted.\nBreakdown:\n${breakdown}\n` +
             `Pass force: true to submit anyway, or raise max_cost in .codecarto/broadside/config.yaml.`);
     }
-    const state = await loadBroadsideState(broadsideDir);
+    // Read before anything is posted: a state.json that cannot be read refuses
+    // the run here (#233), while persistBroadsideRun below merges by run id.
+    await loadBroadsideState(broadsideDir);
     const runId = new Date().toISOString().replace(/[:.]/g, "-");
     const run = {
         id: runId,
@@ -2069,7 +2166,6 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
             skippedFiles: info.secretFilesSkipped.length,
         },
     };
-    state.runs.push(run);
     await persistBroadsideRun(broadsideDir, run);
     const requestsByCustomId = {};
     const submissions = [];
@@ -2364,8 +2460,13 @@ function parseTriageItems(content) {
 export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     const broadsideDir = broadsideDirFor(cwd);
     const state = await loadBroadsideState(broadsideDir);
-    const run = state.runs[state.runs.length - 1];
+    const run = opts.runId ? state.runs.find((candidate) => candidate.id === opts.runId) : state.runs[state.runs.length - 1];
     if (!run) {
+        if (opts.runId) {
+            const known = state.runs.map((candidate) => candidate.id);
+            throw new Error(`No Broad-Side run with id ${opts.runId}. ` +
+                (known.length > 0 ? `Recorded runs: ${known.join(", ")}.` : "No runs are recorded; call codecarto_broadside with action 'submit' first."));
+        }
         throw new Error("No Broad-Side run recorded. Call codecarto_broadside with action 'submit' first.");
     }
     const runDir = join(broadsideDir, run.outputDir);
@@ -2386,7 +2487,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             lensOutcomes[lensId] = { status: entry?.status ?? "failed", resultCount: 0 };
             continue;
         }
-        if (["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status)) {
+        if (BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status)) {
             totalCost += entry.cost ?? 0;
             resultCount += entry.resultCount ?? 0;
             lensOutcomes[lensId] = { status: entry.status, cost: entry.cost, resultCount: entry.resultCount };
@@ -2526,7 +2627,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     if ((wantSynthesis || wantTriage) && allLensResults.length > 0) {
         const allTerminal = run.lenses.every((lensId) => {
             const entry = run.batches[lensId];
-            return entry && ["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status);
+            return entry && BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status);
         });
         if (allTerminal && (postPassUnfinished(run.synthesis) || postPassUnfinished(run.triage))) {
             const findingsText = allLensResults
@@ -2638,7 +2739,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     }
     const terminal = run.lenses.every((lensId) => {
         const entry = run.batches[lensId];
-        return entry && ["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status);
+        return entry && BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status);
     });
     run.status = terminal ? (resultCount > 0 ? "completed" : "failed") : "partial";
     run.totalCost = totalCost;

package/dist/core/completion.js

@@ -110,7 +110,13 @@ async function appendDecisionLog(workspaceDir, phaseId, closeoutFile, decisions)
         const number = String(nextNumber + index).padStart(3, "0");
         return `D${number} | ${decision.trim()} | ${source} | closeouts/${closeoutFile} §Decisions Beyond Prompt (${phaseId})`;
     });
-    content += `${content.endsWith("\n") ? "" : "\n"}${rows.join("\n")}\n`;
+    // A row appended straight after the section's explanatory paragraph is
+    // rendered as part of that paragraph by most Markdown renderers; a blank
+    // line makes the rows their own block (self-audit F4). Rows already
+    // present stay contiguous with the new ones.
+    const trailing = content.replace(/\n+$/, "").split("\n").pop() ?? "";
+    const separator = /^D\d+\s*\|/.test(trailing) || trailing.trim() === "" ? "" : "\n";
+    content += `${content.endsWith("\n") ? "" : "\n"}${separator}${rows.join("\n")}\n`;
     await writeFile(join(workspaceDir, "DECISIONS.md"), content, "utf8");
     return fresh.length;
 }

package/dist/core/library.js

@@ -33,7 +33,7 @@ import { spawn } from "node:child_process";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { acquireLock } from "./status.js";
-import { atomicWriteFile, canonicalPath, isPlainObject, normalizeForComparison, pathExists, uniqueTempSuffix } from "./utils.js";
+import { atomicWriteFile, canonicalPath, GIT_TIMEOUT_MS, isPlainObject, normalizeForComparison, pathExists, uniqueTempSuffix } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 // ─── Constants ──────────────────────────────────────────────────────────────
 export const LIBRARY_MARKER_FILE = ".codecarto-library";
@@ -830,7 +830,7 @@ async function writeIndexMarkdown(libraryRoot, index, marker) {
     const lines = [];
     lines.push(`# ${escapeMd(marker.name)} — Library Index`);
     lines.push("");
-    lines.push(`_Generated ${index.generated_at}. Do not edit by hand — regenerate with \`codecarto library-reindex\`._`);
+    lines.push(`_Generated ${index.generated_at}. Do not edit by hand — regenerate with the \`codecarto_library_reindex\` MCP tool._`);
     lines.push("");
     // A single-tenant library has no namespaces but is still one namespace's
     // worth of entries; count once so the noun agrees with the number shown.
@@ -1041,7 +1041,9 @@ export async function commitPublish(libraryRoot, message, opts = {}) {
 }
 function runGit(cwd, args) {
     return new Promise((resolvePromise) => {
-        const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        // Bounded like every fetch: a credential helper waiting on a prompt
+        // used to hang publish or source-repo resolution for good (sem 3.12).
+        const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], timeout: GIT_TIMEOUT_MS });
         let stdout = "";
         let stderr = "";
         child.stdout.on("data", (b) => {

package/dist/core/pipeline.d.ts

@@ -4,11 +4,47 @@ export declare const DEFAULT_PIPELINE_PATH = "workflow/pipeline-full-with-deep-a
 export declare function getPhaseMap(pipeline: PipelineFile): Map<string, PipelinePhase>;
 export declare function getPipelineLabel(pipelinePath: string): string;
 export declare function getNextEligiblePhase(state: WorkspaceState): PipelinePhase | null;
+/** One phase the pipeline cannot reach, and the dependencies keeping it there. */
+export interface BlockedPhase {
+    phaseId: string;
+    /** Each unmet `depends_on` entry, with why it will not clear on its own. */
+    missing: Array<{
+        dependencyId: string;
+        reason: "not-in-pipeline" | "blocked";
+    }>;
+}
+/**
+ * What the pipeline can do next. `getNextEligiblePhase` returned null both
+ * when every phase was complete and when the remaining phases waited on a
+ * dependency that would never clear, and every consumer read null as
+ * complete: a DAG with an unmet dependency reported 1/2 complete and unlocked
+ * the post-pipeline skills (#228). The third outcome is the difference.
+ */
+export type PipelineOutcome = {
+    kind: "eligible";
+    phase: PipelinePhase;
+} | {
+    kind: "complete";
+} | {
+    kind: "stuck";
+    blocked: BlockedPhase[];
+};
+export declare function resolvePipelineOutcome(state: WorkspaceState): PipelineOutcome;
+/** True when every phase in the active pipeline is complete. */
+export declare function isPipelineComplete(state: WorkspaceState): boolean;
+/**
+ * One sentence both surfaces print for a stuck pipeline, naming each blocked
+ * phase and the dependency keeping it there. The pipeline file is the thing to
+ * fix — or switch away from — so the sentence says so.
+ */
+export declare function describeStuckPipeline(blocked: BlockedPhase[]): string;
 /**
  * Point `current_phase` and `next_actions` at whatever the engine finds
- * eligible now, or at the terminal routing when nothing is. Completion and a
- * pipeline switch both derive the cursor this way (#236), so status.yaml never
- * disagrees with the phase records it sits beside. Returns the eligible phase.
+ * eligible now, at the terminal routing when every phase is complete, or at
+ * the first blocked phase with the stuck sentence when nothing can run.
+ * Completion and a pipeline switch both derive the cursor this way (#236), so
+ * status.yaml never disagrees with the phase records it sits beside. Returns
+ * the eligible phase, or null.
  */
 export declare function recomputeCursor(state: WorkspaceState): PipelinePhase | null;
 /**

package/dist/core/pipeline.js

@@ -40,17 +40,71 @@ export function getNextEligiblePhase(state) {
     }
     return null;
 }
+export function resolvePipelineOutcome(state) {
+    const phase = getNextEligiblePhase(state);
+    if (phase)
+        return { kind: "eligible", phase };
+    const phaseMap = getPhaseMap(state.pipeline);
+    const isComplete = (phaseId) => state.status.phases[phaseId]?.status === "complete";
+    const incomplete = state.pipeline.phase_order.filter((phaseId) => !isComplete(phaseId));
+    if (incomplete.length === 0)
+        return { kind: "complete" };
+    // Nothing is eligible and something is incomplete, so every incomplete
+    // phase has an unmet dependency. Each one is either a phase this pipeline
+    // does not declare, or one of the blocked phases themselves (a cycle, or a
+    // chain back to one).
+    const blocked = incomplete.map((phaseId) => ({
+        phaseId,
+        missing: (phaseMap.get(phaseId)?.depends_on ?? [])
+            .filter((dependencyId) => !isComplete(dependencyId))
+            .map((dependencyId) => ({
+            dependencyId,
+            reason: state.pipeline.phase_order.includes(dependencyId) ? "blocked" : "not-in-pipeline",
+        })),
+    }));
+    return { kind: "stuck", blocked };
+}
+/** True when every phase in the active pipeline is complete. */
+export function isPipelineComplete(state) {
+    return resolvePipelineOutcome(state).kind === "complete";
+}
+/**
+ * One sentence both surfaces print for a stuck pipeline, naming each blocked
+ * phase and the dependency keeping it there. The pipeline file is the thing to
+ * fix — or switch away from — so the sentence says so.
+ */
+export function describeStuckPipeline(blocked) {
+    const parts = blocked.map((entry) => {
+        const deps = entry.missing.map((m) => m.reason === "not-in-pipeline" ? `${m.dependencyId}, which is not in this pipeline` : `${m.dependencyId}, which is itself blocked`);
+        return `${entry.phaseId} depends on ${deps.join(" and ") || "nothing it can reach"}`;
+    });
+    return `Pipeline is stuck: ${parts.join("; ")}. No phase can run until the pipeline file's depends_on is fixed (or switch pipelines with codecarto_switch_pipeline / /codecarto-switch-pipeline).`;
+}
 /**
  * Point `current_phase` and `next_actions` at whatever the engine finds
- * eligible now, or at the terminal routing when nothing is. Completion and a
- * pipeline switch both derive the cursor this way (#236), so status.yaml never
- * disagrees with the phase records it sits beside. Returns the eligible phase.
+ * eligible now, at the terminal routing when every phase is complete, or at
+ * the first blocked phase with the stuck sentence when nothing can run.
+ * Completion and a pipeline switch both derive the cursor this way (#236), so
+ * status.yaml never disagrees with the phase records it sits beside. Returns
+ * the eligible phase, or null.
  */
 export function recomputeCursor(state) {
-    const next = getNextEligiblePhase(state);
-    state.status.current_phase = next?.id ?? "complete";
-    state.status.next_actions = next ? [beginPhaseAction(next)] : buildTerminalNextActions(state.status);
-    return next;
+    const outcome = resolvePipelineOutcome(state);
+    if (outcome.kind === "eligible") {
+        state.status.current_phase = outcome.phase.id;
+        state.status.next_actions = [beginPhaseAction(outcome.phase)];
+        return outcome.phase;
+    }
+    if (outcome.kind === "stuck") {
+        // The cursor stays on the first phase that cannot run; "complete" is
+        // reserved for the state where nothing is left (#228).
+        state.status.current_phase = outcome.blocked[0]?.phaseId ?? "complete";
+        state.status.next_actions = [describeStuckPipeline(outcome.blocked)];
+        return null;
+    }
+    state.status.current_phase = "complete";
+    state.status.next_actions = buildTerminalNextActions(state.status);
+    return null;
 }
 /**
  * Phases status.yaml records as complete whose primary output is not on disk.

package/dist/core/prompts.js

@@ -120,6 +120,13 @@ export async function buildPhasePrompt(state, phase, forced, options = {}) {
     const preflight = options.preflight ?? await runPhasePreflight(state, phase);
     const synthesisWorkflow = state.pipeline.workflow_name === "evidence-backed-project-synthesis";
     const handoffTemplateExists = await pathExists(join(state.workspaceDir, "templates", "phase-handoff.yaml"));
+    // The framework's own three files are the first reads on every phase, and
+    // after the first phase they are the same three files. Say so, so a host
+    // that carries context across phases spends it on the phase's inputs
+    // rather than re-reading the guide (self-audit F5). status.yaml is the
+    // exception: completion rewrote it, and it is the cursor.
+    const laterPhase = Object.values(state.status.phases).some((phaseState) => phaseState.status === "complete");
+    const unchangedNote = laterPhase ? " (framework-owned; unchanged since your last phase unless the scaffold was refreshed — skim rather than re-read if you still hold it)" : "";
     const lines = [
         `Read .codecarto/GUIDE.md and continue the CodeCartographer workflow for the phase \`${phase.id}\`.`,
         synthesisWorkflow
@@ -127,11 +134,11 @@ export async function buildPhasePrompt(state, phase, forced, options = {}) {
             : "Work on this phase only. The analyzed source code is the repository outside .codecarto/.",
         "",
         "Required reads before analysis:",
-        "- .codecarto/GUIDE.md",
-        "- .codecarto/workflow/status.yaml",
+        `- .codecarto/GUIDE.md${unchangedNote}`,
+        `- .codecarto/workflow/status.yaml${laterPhase ? " (rewritten by the last completion; read it)" : ""}`,
     ];
     if (handoffTemplateExists) {
-        lines.push("- .codecarto/templates/phase-handoff.yaml");
+        lines.push(`- .codecarto/templates/phase-handoff.yaml${unchangedNote}`);
     }
     const primaryOutput = phase.primary_output ? `.codecarto/${phase.primary_output}` : undefined;
     if (primaryOutput) {

package/dist/core/status.d.ts

@@ -3,6 +3,14 @@ export declare const LOCK_RETRY_MS = 125;
 export declare const LOCK_TIMEOUT_MS = 5000;
 export declare const STALE_LOCK_MS = 60000;
 export declare function assertSafePhaseId(phaseId: string): void;
+/**
+ * A YAML scalar as text: strings as written, numbers and booleans spelled
+ * back out. Files written before #225 hold owner notes such as `2048` or
+ * `true` bare, which the reader returns as a number or a boolean; dropping
+ * or crashing on those would lose real state, so they are read as the text
+ * they were. Anything else (null, arrays, objects) has no text.
+ */
+export declare function textOf(value: unknown): string | null;
 export declare function ensureArray(value: unknown): string[];
 /**
  * Normalize a handoff's `open_question_closures` (#122, #186). Accepts both

package/dist/core/status.js

@@ -13,8 +13,28 @@ export function assertSafePhaseId(phaseId) {
         throw new Error(`Invalid phase id: ${phaseId}`);
     }
 }
+/**
+ * A YAML scalar as text: strings as written, numbers and booleans spelled
+ * back out. Files written before #225 hold owner notes such as `2048` or
+ * `true` bare, which the reader returns as a number or a boolean; dropping
+ * or crashing on those would lose real state, so they are read as the text
+ * they were. Anything else (null, arrays, objects) has no text.
+ */
+export function textOf(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return null;
+}
+/** Like {@link textOf}, trimmed, and "" for a value that has no text. */
+function trimmedText(value) {
+    return (textOf(value) ?? "").trim();
+}
 export function ensureArray(value) {
-    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+    if (!Array.isArray(value))
+        return [];
+    return value.map(textOf).filter((entry) => entry !== null);
 }
 function coerceEntry(value, allowTargetPhase) {
     if (typeof value === "string") {
@@ -27,22 +47,22 @@ function coerceEntry(value, allowTargetPhase) {
         return null;
     const raw = value;
     const entry = {};
-    if (typeof raw.id === "string" && raw.id.trim())
-        entry.id = raw.id.trim();
-    if (typeof raw.kind === "string" && raw.kind.trim())
-        entry.kind = raw.kind.trim();
-    if (typeof raw.description === "string" && raw.description.trim())
-        entry.description = raw.description.trim();
-    if (typeof raw.deferred_reason === "string" && raw.deferred_reason.trim())
-        entry.deferred_reason = raw.deferred_reason.trim();
-    if (allowTargetPhase && typeof raw.target_phase === "string" && raw.target_phase.trim())
-        entry.target_phase = raw.target_phase.trim();
+    if (trimmedText(raw.id))
+        entry.id = trimmedText(raw.id);
+    if (trimmedText(raw.kind))
+        entry.kind = trimmedText(raw.kind);
+    if (trimmedText(raw.description))
+        entry.description = trimmedText(raw.description);
+    if (trimmedText(raw.deferred_reason))
+        entry.deferred_reason = trimmedText(raw.deferred_reason);
+    if (allowTargetPhase && trimmedText(raw.target_phase))
+        entry.target_phase = trimmedText(raw.target_phase);
     // derives_from rides the same flag as target_phase: it is a carry-forward
     // concept only — the id of the open question this routed item answers one
     // candidate of (#122, #186). An open_questions entry has nothing to derive
     // from, so the field is dropped there rather than silently carried.
-    if (allowTargetPhase && typeof raw.derives_from === "string" && raw.derives_from.trim())
-        entry.derives_from = raw.derives_from.trim();
+    if (allowTargetPhase && trimmedText(raw.derives_from))
+        entry.derives_from = trimmedText(raw.derives_from);
     return Object.keys(entry).length > 0 ? entry : null;
 }
 /**
@@ -218,11 +238,13 @@ export function normalizeStatus(status, pipeline, pipelinePath, cwd) {
             };
         }
     }
+    // Coerced, not assumed: a status.yaml written before #225 spells a
+    // digit-named project bare, and the reader returns a number for it.
     return {
-        project_name: status.project_name?.trim() || basename(cwd),
-        pipeline: status.pipeline?.trim() || pipelinePath,
-        current_phase: status.current_phase?.trim() || pipeline.phase_order[0] || "complete",
-        last_updated: status.last_updated?.trim() || "",
+        project_name: trimmedText(status.project_name) || basename(cwd),
+        pipeline: trimmedText(status.pipeline) || pipelinePath,
+        current_phase: trimmedText(status.current_phase) || pipeline.phase_order[0] || "complete",
+        last_updated: trimmedText(status.last_updated) || "",
         schema_version: typeof status.schema_version === "number" ? status.schema_version : 1,
         phases,
         next_actions: ensureArray(status.next_actions),