codecartographer-pi 0.6.0 → 0.8.0

package/dist/extensions/codecarto/dashboard-narrator.js

@@ -0,0 +1,182 @@
+// Optional LLM-narrated executive summary for the dashboard. Opt-in via
+// /codecarto-dashboard --narrate. Runs the orchestrator's model as a
+// one-shot in-memory AgentSession with no tools, reads recent closeouts +
+// status + usage totals, and produces a 200-400 word Markdown summary.
+//
+// The summary is cached to .codecarto/.dashboard-narration.local.md with a
+// YAML frontmatter recording when it was generated and the completed-phase
+// count at that time. Subsequent deterministic re-renders consult this
+// cache and surface a "<N> runs since" staleness note.
+//
+// Same one-shot pattern as agent-rewriter.ts:runRewriterOnce — different
+// system prompt, different output target. Never throws.
+import { readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { computeTotals, NARRATION_CACHE_RELATIVE_PATH, loadUsage, pathExists, stringifySimpleYaml, } from "../../core/index.js";
+// Per-closeout byte budget when stuffing the narrator's input. Three
+// closeouts × 4 KB each ≈ 12 KB of prompt context, which is well under any
+// reasonable model's input window.
+const CLOSEOUT_BYTE_BUDGET = 4000;
+const MAX_CLOSEOUTS = 3;
+export async function narrateDashboard(ctx, state) {
+    const closeouts = await readRecentCloseouts(state.workspaceDir);
+    if (closeouts.length === 0) {
+        return { used: false, skipReason: "no closeouts to narrate from" };
+    }
+    const usage = await loadUsage(state.workspaceDir);
+    const prompt = buildNarratorPrompt({
+        projectName: state.status.project_name || "(unnamed project)",
+        pipeline: state.status.pipeline,
+        currentPhase: state.status.current_phase || "—",
+        completedCount: completedPhaseCount(state),
+        totalPhases: state.pipeline.phase_order.length,
+        usageSummary: summarizeUsage(usage),
+        closeouts,
+    });
+    let narration;
+    try {
+        narration = await runNarratorOnce(ctx, prompt);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { used: false, skipReason: `narrator session failed: ${message}` };
+    }
+    const trimmed = narration.trim();
+    if (!trimmed) {
+        return { used: false, skipReason: "narrator returned empty output" };
+    }
+    await writeNarrationCache(state.workspaceDir, trimmed, completedPhaseCount(state));
+    return { narration: trimmed, used: true };
+}
+async function readRecentCloseouts(workspaceDir) {
+    const dir = join(workspaceDir, "closeouts");
+    if (!(await pathExists(dir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const matched = entries
+        .map((name) => {
+        const m = /^(\d{4}-\d{2}-\d{2})-(.+)\.md$/.exec(name);
+        return m ? { date: m[1], phaseOrModule: m[2], fileName: name } : null;
+    })
+        .filter((x) => x !== null)
+        .sort((a, b) => (a.date < b.date ? 1 : -1))
+        .slice(0, MAX_CLOSEOUTS);
+    const out = [];
+    for (const entry of matched) {
+        try {
+            const raw = await readFile(join(dir, entry.fileName), "utf8");
+            const truncated = raw.length > CLOSEOUT_BYTE_BUDGET
+                ? `${raw.slice(0, CLOSEOUT_BYTE_BUDGET)}\n\n[…truncated for narration budget…]`
+                : raw;
+            out.push({ ...entry, content: truncated });
+        }
+        catch {
+            // skip unreadable closeouts
+        }
+    }
+    return out;
+}
+function buildNarratorPrompt(input) {
+    const closeoutBlocks = input.closeouts.map((c) => [
+        `=== CLOSEOUT ${c.date} ${c.phaseOrModule} ===`,
+        c.content,
+        `=== END CLOSEOUT ${c.date} ${c.phaseOrModule} ===`,
+    ].join("\n")).join("\n\n");
+    return [
+        `You are writing a 200-400 word executive summary of a CodeCartographer run for a human reader (project owner, reviewer, or new team member).`,
+        "",
+        "Constraints:",
+        "- Cite specific findings from the closeouts below; quote phase IDs and artifact names verbatim.",
+        "- Do not invent findings the closeouts do not state.",
+        "- Lead with what the run discovered, not what it did mechanically. Findings > activity.",
+        "- Surface any cross-cutting risks or open questions worth pulling forward.",
+        "- Output Markdown only, no commentary, no preface, no fenced code blocks.",
+        "- 200-400 words; tight prose, no bullet-list-soup.",
+        "",
+        "=== RUN METADATA ===",
+        `Project: ${input.projectName}`,
+        `Pipeline: ${input.pipeline}`,
+        `Progress: ${input.completedCount}/${input.totalPhases} phases complete`,
+        `Current phase: ${input.currentPhase}`,
+        `Usage: ${input.usageSummary}`,
+        "=== END RUN METADATA ===",
+        "",
+        closeoutBlocks,
+    ].join("\n");
+}
+function summarizeUsage(usage) {
+    if (usage.runs.length === 0)
+        return "no runs recorded";
+    const totals = computeTotals(usage);
+    const tokensTotal = totals.tokens.input + totals.tokens.output;
+    return `${totals.runs} runs · ${formatK(tokensTotal)} tokens · ${totals.tool_uses} tool uses`;
+}
+function formatK(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(2)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return `${n}`;
+}
+function completedPhaseCount(state) {
+    return Object.values(state.status.phases).filter((p) => p.status === "complete").length;
+}
+async function writeNarrationCache(workspaceDir, content, phaseCount) {
+    const generatedAt = new Date().toISOString();
+    const frontmatter = stringifySimpleYaml({ generatedAt, phaseCountAtGeneration: phaseCount });
+    const body = `---\n${frontmatter}\n---\n${content}\n`;
+    const path = join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH);
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, body, "utf8");
+    await rename(tempPath, path);
+}
+async function runNarratorOnce(ctx, prompt) {
+    const cwd = ctx.cwd;
+    const agentDir = getAgentDir();
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir,
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const { session } = await createAgentSession({
+        cwd,
+        agentDir,
+        sessionManager: SessionManager.inMemory(cwd),
+        settingsManager: SettingsManager.create(cwd, agentDir),
+        modelRegistry: ctx.modelRegistry,
+        model: ctx.model,
+        tools: [],
+        resourceLoader: loader,
+    });
+    await session.prompt(prompt);
+    return getLastAssistantText(session);
+}
+function getLastAssistantText(session) {
+    for (let i = session.messages.length - 1; i >= 0; i--) {
+        const msg = session.messages[i];
+        if (msg.role !== "assistant")
+            continue;
+        const blocks = msg.content;
+        const parts = [];
+        for (const c of blocks) {
+            if (c.type === "text" && c.text)
+                parts.push(c.text);
+        }
+        const joined = parts.join("\n").trim();
+        if (joined)
+            return joined;
+    }
+    return "";
+}

package/dist/extensions/codecarto/dashboard-writer.d.ts

@@ -0,0 +1 @@
+export declare function writeDashboard(cwd: string, packageVersion: string): Promise<void>;

package/dist/extensions/codecarto/dashboard-writer.js

@@ -0,0 +1,123 @@
+// I/O wrapper that gathers all dashboard inputs and writes the rendered
+// HTML to `.codecarto/dashboard.html`. Best-effort — failures are swallowed
+// and never escalate to a phase error the user sees, mirroring the
+// recordUsage discipline at extensions/codecarto/index.ts.
+import { readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DASHBOARD_RELATIVE_PATH, getWorkspaceState, loadUsage, NARRATION_CACHE_RELATIVE_PATH, parseSimpleYaml, pathExists, renderDashboard, } from "../../core/index.js";
+const CLOSEOUT_FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(.+)\.md$/;
+export async function writeDashboard(cwd, packageVersion) {
+    try {
+        const state = await getWorkspaceState(cwd);
+        if (!state)
+            return;
+        const workspaceDir = state.workspaceDir;
+        const [usage, closeouts, outputsPresent, narration] = await Promise.all([
+            loadUsage(workspaceDir),
+            listCloseouts(workspaceDir),
+            buildOutputsPresent(state.workspaceDir, state.pipeline),
+            loadNarration(workspaceDir),
+        ]);
+        const inputs = {
+            status: state.status,
+            pipeline: state.pipeline,
+            usage,
+            closeouts,
+            outputsPresent,
+            packageVersion,
+            generatedAt: new Date().toISOString(),
+            narration,
+        };
+        const html = renderDashboard(inputs);
+        const path = join(workspaceDir, DASHBOARD_RELATIVE_PATH);
+        const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tempPath, html, "utf8");
+        await rename(tempPath, path);
+    }
+    catch {
+        // Best-effort: a failed dashboard write must not surface as a phase
+        // error. The user's pipeline state is unaffected; the next state
+        // change will trigger another render attempt.
+    }
+}
+async function listCloseouts(workspaceDir) {
+    const dir = join(workspaceDir, "closeouts");
+    if (!(await pathExists(dir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        const m = CLOSEOUT_FILENAME_RE.exec(name);
+        if (!m)
+            continue;
+        out.push({ date: m[1], phaseOrModule: m[2], fileName: name });
+    }
+    return out;
+}
+async function buildOutputsPresent(workspaceDir, pipeline) {
+    const out = new Map();
+    for (const phaseId of pipeline.phase_order) {
+        const phaseDef = pipeline.phases.find((p) => p.id === phaseId);
+        if (!phaseDef)
+            continue;
+        const entry = { secondary: [] };
+        if (phaseDef.primary_output) {
+            entry.primary = {
+                path: phaseDef.primary_output,
+                exists: await pathExists(join(workspaceDir, phaseDef.primary_output)),
+            };
+        }
+        for (const sec of phaseDef.secondary_outputs ?? []) {
+            entry.secondary.push({
+                path: sec.path,
+                exists: await pathExists(join(workspaceDir, sec.path)),
+            });
+        }
+        out.set(phaseId, entry);
+    }
+    return out;
+}
+async function loadNarration(workspaceDir) {
+    const path = join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH);
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const raw = await readFile(path, "utf8");
+        const { frontmatter, body } = splitFrontmatter(raw);
+        if (!frontmatter)
+            return undefined;
+        const generatedAt = typeof frontmatter.generatedAt === "string" ? frontmatter.generatedAt : "";
+        const phaseCountAtGeneration = typeof frontmatter.phaseCountAtGeneration === "number" ? frontmatter.phaseCountAtGeneration : 0;
+        if (!generatedAt)
+            return undefined;
+        return { content: body.trim(), generatedAt, phaseCountAtGeneration };
+    }
+    catch {
+        return undefined;
+    }
+}
+function splitFrontmatter(raw) {
+    if (!raw.startsWith("---\n"))
+        return { frontmatter: null, body: raw };
+    const end = raw.indexOf("\n---\n", 4);
+    if (end === -1)
+        return { frontmatter: null, body: raw };
+    const yamlText = raw.slice(4, end);
+    const body = raw.slice(end + 5);
+    try {
+        const parsed = parseSimpleYaml(yamlText);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return { frontmatter: parsed, body };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { frontmatter: null, body };
+}

package/dist/extensions/codecarto/index.js

@@ -1,36 +1,15 @@
 import { cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { runPhase } from "./agent-runner.js";
-import { rewritePhasePrompt } from "./agent-rewriter.js";
-import { clearPhase, finishPhase, getPhaseActivity, startPhase } from "./agent-state.js";
-import { buildPhaseSummary } from "./agent-summary.js";
-import { disposeAgentsWidget, getAgentsWidget } from "./agent-widget.js";
+import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
+import { disposeAgentsWidget } from "./agent-widget.js";
+import { parseDashboardFlags } from "./dashboard-flags.js";
+import { narrateDashboard } from "./dashboard-narrator.js";
+import { writeDashboard } from "./dashboard-writer.js";
 import { parseNextFlags } from "./next-flags.js";
-import { appendUsageRun, buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, computePerPhaseTotals, computeTotals, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, normalizeStatus, packagedWorkspaceDir, pathExists, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, validatePhaseOutput, } from "../../core/index.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
-async function recordUsage(workspaceDir, phaseId, status, activity) {
-    try {
-        await appendUsageRun(workspaceDir, {
-            timestamp: new Date().toISOString(),
-            phase: phaseId,
-            status,
-            turn_count: activity.turnCount,
-            tool_uses: activity.toolUses,
-            duration_ms: (activity.completedAt ?? Date.now()) - activity.startedAt,
-            tokens: {
-                input: activity.lifetimeUsage.input,
-                output: activity.lifetimeUsage.output,
-                cache_write: activity.lifetimeUsage.cacheWrite,
-            },
-        });
-    }
-    catch {
-        // Local usage logging is best-effort. A full disk or permission
-        // failure shouldn't surface as a phase error to the user.
-    }
-}
 function formatUsageTokens(count) {
     if (count >= 1_000_000)
         return `${(count / 1_000_000).toFixed(2)}M`;
@@ -203,6 +182,9 @@ export default function codeCartographerExtension(pi) {
             lastFeedbackLines = [`Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`];
             ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)})`, "info");
             await ctx.reload();
+            // Render the initial dashboard (empty usage, all phases pending) so
+            // the user sees the file exist immediately after /codecarto-init.
+            void writeDashboard(ctx.cwd, PACKAGE_VERSION);
             return;
         },
     });
@@ -219,15 +201,19 @@ export default function codeCartographerExtension(pi) {
         },
     });
     pi.registerCommand("codecarto-next", {
-        description: "Run the next eligible CodeCartographer phase as a sub-agent. Flags: --llm-steer / --no-llm-steer",
+        description: "Run the next eligible CodeCartographer phase as a sub-agent. Flags: --llm-steer / --no-llm-steer / --auto [--strict]",
         getArgumentCompletions: (prefix) => {
-            const items = ["--llm-steer", "--no-llm-steer"]
+            const items = ["--llm-steer", "--no-llm-steer", "--auto", "--strict"]
                 .filter((value) => value.startsWith(prefix))
                 .map((value) => ({ value, label: value }));
             return items.length > 0 ? items : null;
         },
         handler: async (args, ctx) => {
             const flags = parseNextFlags(args);
+            if (flags.error) {
+                ctx.ui.notify(flags.error, "error");
+                return;
+            }
             if (flags.unknown.length > 0) {
                 ctx.ui.notify(`Unknown /codecarto-next flag: ${flags.unknown.join(" ")}`, "error");
                 return;
@@ -235,6 +221,24 @@ export default function codeCartographerExtension(pi) {
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
+            if (flags.auto) {
+                ctx.ui.notify(`Auto pipeline${flags.strict ? " (strict)" : ""} running…`, "info");
+                const result = await runAuto(ctx, pi, state, {
+                    strict: flags.strict,
+                    llmSteerOverride: flags.llmSteerOverride,
+                    signal: ctx.signal,
+                });
+                const availableSkills = await listSkillNames(state.workspaceDir).catch(() => []);
+                pi.sendMessage({
+                    customType: "codecarto-auto-summary",
+                    content: buildAutoSummary(result, availableSkills),
+                    display: true,
+                });
+                lastFeedbackLines = [`Auto pipeline ${result.outcome}: ${result.reason}`];
+                await refreshWorkspaceUi(ctx, lastFeedbackLines);
+                ctx.ui.notify(`Auto pipeline ${result.outcome}: ${result.phasesRun.length}/${result.totalPhases} phases.`, result.outcome === "complete" ? "info" : "warning");
+                return;
+            }
             const phase = getNextEligiblePhase(state);
             if (!phase) {
                 lastFeedbackLines = ["All phases complete."];
@@ -244,108 +248,23 @@ export default function codeCartographerExtension(pi) {
             }
             // Reject re-entry: don't spawn a duplicate runner for a phase that's
             // already in flight from a previous /codecarto-next invocation.
-            const existing = getPhaseActivity(phase.id);
-            if (existing && existing.status === "running") {
+            if (isPhaseRunning(phase.id)) {
                 ctx.ui.notify(`Phase ${phase.id} is already running.`, "warning");
                 return;
             }
             const config = await loadCodecartoConfig(state.workspaceDir);
             const llmSteerEnabled = flags.llmSteerOverride ?? config.orchestrator.llm_steer_next_phase;
-            let prompt = await buildPhasePrompt(state, phase, false);
-            if (llmSteerEnabled) {
-                ctx.ui.notify(`Customizing ${phase.id} prompt via LLM rewriter…`, "info");
-                const rewrite = await rewritePhasePrompt({ ctx, state, originalPrompt: prompt, nextPhaseId: phase.id });
-                if (rewrite.used) {
-                    prompt = rewrite.prompt;
-                    ctx.ui.notify(`LLM rewriter customized ${phase.id} seed prompt.`, "info");
-                }
-                else {
-                    ctx.ui.notify(`LLM rewriter skipped (${rewrite.skipReason}); using stock prompt.`, "warning");
-                }
-            }
-            const activity = startPhase(phase.id);
             lastFeedbackLines = [`Running ${phase.id} phase as sub-agent`];
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify(`CodeCartographer phase: ${phase.id} (sub-agent running)`, "info");
-            // Attach the persistent "Agents" widget so the user can watch the
-            // phase's tool/turn/token counts live above the editor while the
-            // orchestrator's TUI stays responsive.
-            getAgentsWidget().attach(ctx.ui);
-            // Fire-and-forget: spawn the phase runner asynchronously so the
-            // orchestrator's TUI stays responsive. The runner mutates the shared
-            // agent-state map from event callbacks; M2 will read that map from a
-            // persistent widget. For M1 we just notify on completion.
-            void runPhase(ctx, prompt, {
-                onSessionCreated: (session) => { activity.session = session; },
-                onToolStart: (id, name) => { activity.activeTools.set(id, name); activity.toolUses++; },
-                onToolEnd: (id) => { activity.activeTools.delete(id); },
-                onTextDelta: (_delta, fullText) => { activity.responseText = fullText; },
-                onTurnEnd: (turnCount) => { activity.turnCount = turnCount; },
-                onMessageEnd: (usage) => {
-                    activity.lifetimeUsage.input += usage.input;
-                    activity.lifetimeUsage.output += usage.output;
-                    activity.lifetimeUsage.cacheWrite += usage.cacheWrite;
-                },
-            }, { sessionName: `CodeCartographer phase: ${phase.id}` })
-                .then((result) => {
-                const status = result.aborted ? "aborted" : "completed";
-                finishPhase(phase.id, { status });
-                if (ctx.hasUI) {
-                    ctx.ui.notify(result.aborted
-                        ? `Phase ${phase.id} aborted.`
-                        : `Phase ${phase.id} sub-agent finished (${result.toolUses} tool uses, ${result.turnCount} turns).`, result.aborted ? "warning" : "info");
-                }
-                // Inject a CustomMessageEntry into the orchestrator's session so
-                // the user sees a closeout summary in the TUI scrollback and the
-                // orchestrator's LLM picks up the phase result as context on the
-                // next turn. display:true renders in the TUI; no triggerTurn so
-                // the LLM doesn't auto-respond — the user remains in control.
-                pi.sendMessage({
-                    customType: "codecarto-phase-summary",
-                    content: buildPhaseSummary({
-                        phaseId: phase.id,
-                        status: result.aborted ? "aborted" : "completed",
-                        turnCount: activity.turnCount,
-                        toolUses: activity.toolUses,
-                        tokens: activity.lifetimeUsage,
-                        durationMs: (activity.completedAt ?? Date.now()) - activity.startedAt,
-                        responseText: result.responseText,
-                    }),
-                    display: true,
-                });
-                void recordUsage(state.workspaceDir, phase.id, status, activity);
-            })
-                .catch((err) => {
-                const message = err instanceof Error ? err.message : String(err);
-                finishPhase(phase.id, { status: "error", error: message });
-                if (ctx.hasUI) {
-                    ctx.ui.notify(`Phase ${phase.id} sub-agent failed: ${message}`, "error");
-                }
-                pi.sendMessage({
-                    customType: "codecarto-phase-summary",
-                    content: buildPhaseSummary({
-                        phaseId: phase.id,
-                        status: "error",
-                        turnCount: activity.turnCount,
-                        toolUses: activity.toolUses,
-                        tokens: activity.lifetimeUsage,
-                        durationMs: (activity.completedAt ?? Date.now()) - activity.startedAt,
-                        responseText: "",
-                        error: message,
-                    }),
-                    display: true,
-                });
-                void recordUsage(state.workspaceDir, phase.id, "error", activity);
-            })
+            // Fire-and-forget: keep the TUI responsive while the sub-agent works.
+            // runSinglePhase handles all side effects (steering message, notify,
+            // phase summary, recordUsage, dashboard regen, clearPhase linger).
+            void runSinglePhase(ctx, pi, state, phase, { llmSteerEnabled, signal: ctx.signal })
                 .finally(() => {
-                // Sub-agent may have written findings, owner_notes, or carry-forward
-                // items into status.yaml. Refresh the main status widget so the
-                // "Open questions / Carry-forward / Next" lines reflect the new
-                // state without waiting for the user to run /codecarto-status.
+                // Refresh the status widget after the phase resolves so the
+                // "Open questions / Carry-forward / Next" lines reflect any
+                // owner_notes the sub-agent wrote to status.yaml.
                 void refreshWorkspaceUi(ctx);
-                // Linger 30s in M1 so /codecarto-status can show that the phase ran;
-                // M2's widget owns the proper "linger N turns" lifecycle.
-                setTimeout(() => clearPhase(phase.id), 30_000);
             });
         },
     });
@@ -403,76 +322,7 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
-            const completionTimestamp = new Date().toISOString();
-            const updatedState = await updateStatusAtomically(ctx.cwd, (lockedState) => {
-                const phase = resolvePhase(lockedState, validation.phaseId);
-                if (!phase?.primary_output) {
-                    throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
-                }
-                const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
-                const existingPhase = nextStatus.phases[validation.phaseId] ?? {
-                    status: "pending",
-                    owner_notes: [],
-                    outputs_present: [],
-                    open_questions: [],
-                    carry_forward: [],
-                };
-                const gapEntries = validation.rows
-                    .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
-                    .map((row) => ({
-                    kind: "needs-maintainer-decision",
-                    description: row.criterion || "Partial validation gap",
-                    deferred_reason: row.evidence || "Marked PARTIAL by validation",
-                }));
-                const mergedOpenQuestions = [...existingPhase.open_questions];
-                for (const candidate of gapEntries) {
-                    const dupe = mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason);
-                    if (!dupe)
-                        mergedOpenQuestions.push(candidate);
-                }
-                nextStatus.phases[validation.phaseId] = {
-                    status: "complete",
-                    owner_notes: uniqueStrings([
-                        ...existingPhase.owner_notes,
-                        `Completed via /codecarto-complete on ${completionTimestamp}.`,
-                        `Primary output: .codecarto/${validation.primaryOutput}`,
-                        `Validation: ${validation.overall}`,
-                    ]).slice(-3),
-                    outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
-                    open_questions: mergedOpenQuestions,
-                    carry_forward: existingPhase.carry_forward ?? [],
-                };
-                nextStatus.last_updated = completionTimestamp;
-                const updatedWorkspaceState = {
-                    ...lockedState,
-                    status: nextStatus,
-                };
-                const nextEligible = getNextEligiblePhase(updatedWorkspaceState);
-                nextStatus.current_phase = nextEligible?.id ?? "complete";
-                nextStatus.next_actions = nextEligible
-                    ? [
-                        `Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`,
-                    ]
-                    : ["All phases complete. Review findings, open questions, and downstream implementation notes."];
-                return {
-                    state: {
-                        ...updatedWorkspaceState,
-                        status: nextStatus,
-                    },
-                    threadLogEntry: buildThreadLogEntry(validation.phaseId, validation, completionTimestamp),
-                };
-            });
-            let closeoutNotice;
-            try {
-                const created = await ensureCloseoutStub(updatedState.workspaceDir, validation.phaseId, completionTimestamp);
-                if (created) {
-                    closeoutNotice = `Closeout stub: .codecarto/closeouts/${closeoutFileName(dateOnly(completionTimestamp), validation.phaseId)} (fill it in)`;
-                }
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                closeoutNotice = `Closeout stub not created: ${message}`;
-            }
+            const { updatedState, closeoutNotice } = await autoCompletePhase(ctx, validation);
             lastFeedbackLines = [
                 `Completed phase: ${validation.phaseId}`,
                 `Validation: ${validation.overall}`,
@@ -553,4 +403,37 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`CodeCartographer usage: ${totals.runs} run${totals.runs === 1 ? "" : "s"}, ${formatUsageTokens(totals.tokens.input + totals.tokens.output)} tokens total`, "info");
         },
     });
+    pi.registerCommand("codecarto-dashboard", {
+        description: "Regenerate .codecarto/dashboard.html (use --narrate for an LLM executive summary)",
+        getArgumentCompletions: (prefix) => {
+            const items = ["--narrate"]
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const flags = parseDashboardFlags(args);
+            if (flags.unknown.length > 0) {
+                ctx.ui.notify(`Unknown /codecarto-dashboard flag: ${flags.unknown.join(" ")}`, "error");
+                return;
+            }
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            if (flags.narrate) {
+                ctx.ui.notify(`Narrating dashboard via LLM…`, "info");
+                const result = await narrateDashboard(ctx, state);
+                if (result.used) {
+                    ctx.ui.notify("Narration written to .codecarto/.dashboard-narration.local.md", "info");
+                }
+                else {
+                    ctx.ui.notify(`LLM narration skipped (${result.skipReason}); rendering deterministic dashboard.`, "warning");
+                }
+            }
+            await writeDashboard(ctx.cwd, PACKAGE_VERSION);
+            lastFeedbackLines = ["Dashboard regenerated: .codecarto/dashboard.html"];
+            setUiState(ctx, state, lastFeedbackLines);
+            ctx.ui.notify("Dashboard regenerated: .codecarto/dashboard.html", "info");
+        },
+    });
 }

package/dist/extensions/codecarto/next-flags.d.ts

@@ -1,6 +1,10 @@
 export interface NextFlags {
     llmSteerOverride?: boolean;
+    auto: boolean;
+    strict: boolean;
     unknown: string[];
+    /** Set when --strict is passed without --auto. Caller surfaces as an error. */
+    error?: string;
 }
 export declare function parseNextFlags(args: string): NextFlags;
 export declare const KNOWN_NEXT_FLAGS: readonly string[];