codecartographer-pi 0.9.1 → 0.11.0

package/README.md

@@ -114,6 +114,39 @@ For multi-session work, every new session reads `.codecarto/GUIDE.md` (or the li
 
 ---
 
+## Progressive distillation and context resilience
+
+CodeCartographer is a progressive, evidence-tagged distillation of a codebase. It does not ask one context window to retain the entire investigation. Instead, each phase turns a large body of source evidence into a smaller, more task-specific artifact that the next phase can read:
+
+```text
+source code
+  → architecture map
+  → behavioral contracts + protocols + defect findings
+  → porting bundle
+  → reimplementation spec
+```
+
+This is deliberate distillation, not incidental chat summarization. Each artifact follows a template, preserves evidence levels and known unknowns, and must pass validation before it becomes an input to downstream phases.
+
+### What happens when conversation context is compacted?
+
+The filesystem, not the conversation, is the durable memory of a run:
+
+- Each phase gets a fresh context window. In the Pi extension it runs as an isolated phase sub-agent; MCP and drop-in hosts should use the same one-session-per-phase pattern.
+- Completed findings live under `.codecarto/findings/`. Later phases re-read the specific upstream artifacts declared by the active pipeline instead of relying on conversational recall.
+- `workflow/status.yaml` records progress, `open_questions`, and `carry_forward` items routed to later phases. `CONVENTIONS.md`, `DECISIONS.md`, closeouts, and `THREAD_LOG.md` preserve cross-session knowledge and handoffs.
+- Pi phase transcripts are file-backed and remain available through `/resume`, `/tree`, and `/export`, even when the active model context has been compacted.
+- For isolated Pi phase sessions, compaction uses a phase-aware continuation summary that explicitly preserves evidence, files inspected, output progress, open questions, and validation gaps. The resulting summary is also checkpointed atomically at `.codecarto/scratch/checkpoints/<phase>.md`.
+- Pi records successful, failed, and aborted compactions plus their trigger (`threshold`, `overflow`, or `manual`) in local usage data and exposes the totals in the widget, `/codecarto-usage`, completion summaries, and dashboard.
+
+As a result, compaction—or even replacement—of the orchestrator session does not erase pipeline progress. A new session can reconstruct the relevant state from disk and continue.
+
+The remaining limit is **within a single oversized phase**. Even Pi's phase-aware summary is still a lossy distillation, and MCP/drop-in compaction remains entirely host-controlled. Phase instructions therefore prioritize targeted reads, durable checkpoints, and explicit coverage accounting; if full coverage will not fit, the phase records `PARTIAL` validation and places unresolved work in `open_questions` or `carry_forward`. Cross-phase context loss is largely designed out; intra-phase context pressure is observed and bounded rather than hidden.
+
+The porting bundle is the final intentional compression boundary. It carries a source index, load-bearing invariants, defect dispositions, and deep-read triggers. `reimplementation-spec` reads that bundle by default and opens lower-level reports only for a named gap, conflict, missing acceptance detail, or defect rationale.
+
+---
+
 ## Phases produce these artifacts
 
 | Artifact | Description |
@@ -164,7 +197,7 @@ Every state change re-renders `.codecarto/dashboard.html` — a self-contained s
 
 - Pipeline progress strip with per-phase status badges
 - Per-phase cards with output links, open questions, carry-forward routing, owner notes, last-run usage
-- Aggregate token usage panel + per-phase breakdown
+- Aggregate token and compaction telemetry + per-phase breakdown
 - Activity timeline with session-file links
 - Open questions roll-up grouped by source phase
 - Closeouts list (reverse-chronological) with relative-path links
@@ -191,11 +224,13 @@ Beyond the slash commands, the Pi extension layers on:
 
 **File-backed phase sessions.** Phase transcripts persist to the same Pi session directory the orchestrator uses, so `/resume`, `/tree`, and `/export` browse them as first-class sessions. Each appears as `CodeCartographer phase: <id>` with lineage back to the orchestrator's session.
 
+**Phase-aware compaction and checkpoints.** Only isolated sessions named `CodeCartographer phase: <id>` receive the specialized compaction prompt. It preserves the phase goal, evidence, inspected files, output progress, open questions, and validation gaps, then writes the resulting summary to `.codecarto/scratch/checkpoints/<phase>.md`. Orchestrator and unrelated Pi sessions retain normal host compaction.
+
 **Phase-completion summary in the orchestrator transcript.** When a phase finishes, a Markdown closeout block is appended to the orchestrator's session via `pi.sendMessage(...)`. Visible in the TUI scrollback; available to the orchestrator's LLM as context on your next message. No auto-trigger — you stay in control.
 
 **Opt-in LLM-steered seed prompts.** Set `orchestrator.llm_steer_next_phase: true` in `.codecarto/workflow/config.yaml` (or pass `--llm-steer` per invocation), and the orchestrator's LLM rewrites the next phase's seed prompt to highlight relevant prior findings. Off by default — extra orchestrator-side tokens, opt-in. The rewritten prompt is injected into the orchestrator transcript so you can audit what the rewriter chose to emphasize.
 
-**Per-phase usage tracking.** Each phase run is appended to `.codecarto/workflow/.usage.local.yaml`. `/codecarto-usage` reports cumulative + per-phase totals.
+**Per-phase usage tracking.** Each phase run is appended to `.codecarto/workflow/.usage.local.yaml`. `/codecarto-usage` reports cumulative + per-phase token, runtime, tool-use, and compaction totals, including threshold/overflow/manual triggers and successful/failed/aborted outcomes.
 
 **Tool interception.** `bash` is blocked outright; `edit` and `write` are confined to `.codecarto/`. Same rules apply to phase sub-agents.
 
@@ -204,6 +239,7 @@ Beyond the slash commands, the Pi extension layers on:
 | Command | Purpose |
 |---|---|
 | `/codecarto-init [variant]` | Copy `.codecarto/` into the current repository, select pipeline variant |
+| `/codecarto-open` | Activate an existing `.codecarto/` workspace in a new Pi session without resetting durable state |
 | `/codecarto-status` | Current phase, progress, open questions |
 | `/codecarto-next [--auto [--strict]] [--llm-steer \| --no-llm-steer]` | Spawn the next eligible phase as a sub-agent. `--auto` walks the full pipeline end-to-end (auto-validate + auto-complete + advance); `--strict` flips the `PASS WITH GAPS` rule from "advance" to "pause". |
 | `/codecarto-phase <id>` | Force a specific phase, even out of pipeline order |

package/dist/core/dashboard.js

@@ -14,6 +14,7 @@ export function renderDashboard(inputs) {
         `<div class="cc-main">`,
         renderHeader(inputs),
         renderStalenessWarning(inputs),
+        renderHealthPanel(inputs),
         inputs.narration ? renderNarration(inputs.narration, completedPhaseCount(inputs.status)) : "",
         renderKeyResults(inputs),
         renderProgressBar(inputs.pipeline, inputs.status),
@@ -84,7 +85,7 @@ function renderHeader(inputs) {
     const { status, pipeline, packageVersion, generatedAt } = inputs;
     const projectName = status.project_name || "(unnamed project)";
     const pipelineLabel = pipeline.workflow_name || status.pipeline;
-    const currentPhase = status.current_phase || "—";
+    const currentPhase = displayCurrentPhase(status);
     const totals = computeTotals(inputs.usage);
     const completed = completedPhaseCount(status);
     const total = pipeline.phase_order.length;
@@ -100,7 +101,7 @@ function renderHeader(inputs) {
         renderStat("Pipeline", pipelineLabel),
         renderStat("Current phase", currentPhase),
         renderStat("Progress", `${completed}/${total} phases`),
-        renderStat("Recorded tokens", formatTokenCount(totals.tokens.input + totals.tokens.output)),
+        renderStat("Recorded tokens", formatTokensForDashboard(inputs.usage)),
         renderStat("Tool uses", String(totals.tool_uses)),
         renderStat("Package", `v${packageVersion}`),
         `</div>`,
@@ -125,6 +126,66 @@ function renderStalenessWarning(inputs) {
         return "";
     return `<section class="cc-warning" data-section><strong>Dashboard may be stale.</strong> Status was updated at ${escapeHtml(inputs.status.last_updated)} after this dashboard was generated at ${escapeHtml(inputs.generatedAt)}. Regenerate with <code>/codecarto-dashboard</code>.</section>`;
 }
+function renderHealthPanel(inputs) {
+    const { status, pipeline, usage } = inputs;
+    const completed = completedPhaseCount(status);
+    const total = pipeline.phase_order.length;
+    const totals = computeTotals(usage);
+    const issues = collectDashboardIssues(inputs);
+    const openQuestionCount = countOpenQuestions(status);
+    const carryForwardCount = countCarryForward(status);
+    const health = issues.some((i) => i.severity === "blocker") ? "attention required" : issues.length ? "review recommended" : completed === total ? "complete" : "on track";
+    const healthClass = issues.some((i) => i.severity === "blocker") ? "bad" : issues.length ? "warn" : "ok";
+    const tokenText = usageHasTokenAccounting(usage) ? formatTokenCount(totals.tokens.input + totals.tokens.output) : usage.runs.length ? "unavailable" : "0";
+    const issueMarkup = issues.length
+        ? `<div class="cc-health-issues">${issues.map(renderDashboardIssue).join("\n")}</div>`
+        : `<p class="cc-health-ok">No blocking artifact gaps detected.</p>`;
+    return [
+        `<section class="cc-card cc-health cc-health-${healthClass}" aria-label="Dashboard health" data-section data-search-text="health status blockers missing artifacts open questions">`,
+        `<div class="cc-health-hero">`,
+        `<div><div class="cc-eyebrow">Pipeline health</div><h2>${escapeHtml(health)}</h2><p>${escapeHtml(status.current_phase && status.current_phase !== "complete" ? `Current phase: ${status.current_phase}` : "Pipeline complete — all phases have finished.")}</p></div>`,
+        `<div class="cc-health-ring" aria-label="${completed} of ${total} phases complete"><strong>${completed}/${total}</strong><span>phases</span></div>`,
+        `</div>`,
+        `<div class="cc-health-grid">`,
+        renderHealthMetric("Artifacts needing attention", String(issues.length), issues.length ? "bad" : "ok"),
+        renderHealthMetric("Open questions", String(openQuestionCount), openQuestionCount ? "warn" : "ok"),
+        renderHealthMetric("Carry-forward items", String(carryForwardCount), carryForwardCount ? "warn" : "ok"),
+        renderHealthMetric("Tool uses", String(totals.tool_uses), "neutral"),
+        renderHealthMetric("Runtime", formatMillis(totals.duration_ms), "neutral"),
+        renderHealthMetric("Tokens", tokenText, tokenText === "unavailable" ? "warn" : "neutral"),
+        `</div>`,
+        issueMarkup,
+        `</section>`,
+    ].join("\n");
+}
+function renderHealthMetric(label, value, tone) {
+    return `<div class="cc-health-metric cc-tone-${tone}"><span>${escapeHtml(label)}</span><strong>${escapeHtml(value)}</strong></div>`;
+}
+function renderDashboardIssue(issue) {
+    const path = issue.path ? `<code>${escapeHtml(issue.path)}</code>` : "";
+    return `<article class="cc-health-issue cc-issue-${issue.severity}"><div><span class="cc-pill ${issue.severity === "blocker" ? "cc-pill-bad" : ""}">${escapeHtml(issue.severity)}</span><a href="#${phaseAnchor(issue.phaseId)}">${escapeHtml(issue.phaseId)}</a></div><strong>${escapeHtml(issue.title)}</strong><p>${escapeHtml(issue.detail)} ${path}</p></article>`;
+}
+function collectDashboardIssues(inputs) {
+    const out = [];
+    for (const phaseId of inputs.pipeline.phase_order) {
+        const phase = getPhase(inputs.pipeline, phaseId);
+        if (!phase?.primary_output)
+            continue;
+        const state = phaseRenderState(inputs.status, phaseId);
+        const primary = inputs.outputsPresent.get(phaseId)?.primary;
+        const shouldExist = state === "complete" || state === "current" || state === "running";
+        if (shouldExist && primary?.exists === false) {
+            out.push({
+                severity: state === "complete" || state === "current" ? "blocker" : "warning",
+                phaseId,
+                title: "Required primary output is missing",
+                detail: state === "complete" ? "Phase is marked complete but the dashboard cannot find its primary artifact at" : "This phase is active or ready, but its required artifact is not present at",
+                path: phase.primary_output,
+            });
+        }
+    }
+    return out;
+}
 function renderNarration(narration, currentCompletedCount) {
     const runsSince = Math.max(0, currentCompletedCount - narration.phaseCountAtGeneration);
     const staleness = runsSince === 0 ? "current" : `${runsSince} run${runsSince === 1 ? "" : "s"} since`;
@@ -305,38 +366,84 @@ function renderPhaseOwnerNotes(phaseState) {
 function renderPhaseLastRun(run) {
     if (!run)
         return `<div class="cc-phase-section"><h3>Last run</h3><p class="cc-muted">No usage record for this phase.</p></div>`;
-    const tokensTotal = (run.tokens?.input ?? 0) + (run.tokens?.output ?? 0);
+    const tokensTotal = formatRunTokens(run);
     const sessionLink = run.session_file ? renderSafeLink(run.session_file, "transcript") : undefined;
     const session = sessionLink ? `<dt>Session</dt><dd>${sessionLink}</dd>` : "";
-    return [`<div class="cc-phase-section">`, `<h3>Last run</h3>`, `<dl class="cc-run-meta">`, `<dt>Timestamp</dt><dd>${escapeHtml(run.timestamp)}</dd>`, `<dt>Status</dt><dd>${escapeHtml(run.status)}</dd>`, `<dt>Turns</dt><dd>${run.turn_count}</dd>`, `<dt>Tool uses</dt><dd>${run.tool_uses}</dd>`, `<dt>Tokens</dt><dd>${escapeHtml(formatTokenCount(tokensTotal))}</dd>`, `<dt>Duration</dt><dd>${escapeHtml(formatMillis(run.duration_ms))}</dd>`, session, `</dl>`, `</div>`].join("");
+    const compactions = run.compactions ? `<dt>Compactions</dt><dd>${formatCompactionCounts(run.compactions)}</dd>` : "";
+    return [`<div class="cc-phase-section">`, `<h3>Last run</h3>`, `<dl class="cc-run-meta">`, `<dt>Timestamp</dt><dd>${escapeHtml(run.timestamp)}</dd>`, `<dt>Status</dt><dd>${escapeHtml(run.status)}</dd>`, `<dt>Turns</dt><dd>${run.turn_count}</dd>`, `<dt>Tool uses</dt><dd>${run.tool_uses}</dd>`, `<dt>Tokens</dt><dd>${escapeHtml(tokensTotal)}</dd>`, `<dt>Duration</dt><dd>${escapeHtml(formatMillis(run.duration_ms))}</dd>`, compactions, session, `</dl>`, `</div>`].join("");
 }
 function renderUsagePanel(inputs) {
     const { usage, pipeline, status } = inputs;
     const totals = computeTotals(usage);
     const perPhase = computePerPhaseTotals(usage);
+    const tokenAccounting = usageHasTokenAccounting(usage);
+    const maxTools = Math.max(1, ...[...perPhase.values()].map((t) => t.tool_uses));
+    const maxDuration = Math.max(1, ...[...perPhase.values()].map((t) => t.duration_ms));
     const rows = pipeline.phase_order.map((phaseId) => {
         const t = perPhase.get(phaseId);
         if (!t) {
             const complete = status.phases[phaseId]?.status === "complete";
-            return `<tr class="${complete ? "cc-usage-missing" : ""}"><td><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a></td><td>0</td><td>—</td><td>—</td><td>${complete ? "usage not recorded" : "not run"}</td></tr>`;
+            return `<tr class="${complete ? "cc-usage-missing" : ""}"><td><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a></td><td>0</td><td>—</td><td>—</td><td>—</td><td>—</td><td>${complete ? "usage not recorded" : "not run"}</td></tr>`;
         }
         const tokensTotal = t.tokens.input + t.tokens.output;
-        return `<tr><td><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a></td><td>${t.runs}</td><td>${escapeHtml(formatTokenCount(tokensTotal))}</td><td>${t.tool_uses}</td><td>${escapeHtml(formatMillis(t.duration_ms))}</td></tr>`;
+        const compactions = t.compaction_runs > 0 ? formatCompactionTriplet(t.compactions) : "unavailable";
+        return `<tr><td><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a></td><td>${t.runs}</td><td>${escapeHtml(tokenAccounting ? formatTokenCount(tokensTotal) : "unavailable")}</td><td>${renderUsageBar(t.tool_uses, maxTools, String(t.tool_uses))}</td><td>${renderUsageBar(t.duration_ms, maxDuration, formatMillis(t.duration_ms))}</td><td>${compactions}</td><td>${usagePhaseNote(phaseId, status)}</td></tr>`;
     }).join("");
     return [
         `<section class="cc-card cc-usage" id="usage" aria-label="Token usage" data-section data-search-text="usage tokens tool duration">`,
         `<div class="cc-section-head"><h2>Usage</h2><span>${totals.runs} runs</span></div>`,
-        usage.runs.length === 0 ? `<p class="cc-empty">No phase runs recorded yet.</p>` : `<dl class="cc-usage-totals">${renderUsageTotalsList(totals)}</dl>`,
+        usage.runs.length === 0 ? `<p class="cc-empty">No phase runs recorded yet.</p>` : `<dl class="cc-usage-totals">${renderUsageTotalsList(totals, tokenAccounting)}</dl>`,
+        renderUsageInsights(perPhase, status),
         `<table class="cc-usage-table">`,
-        `<thead><tr><th>Phase</th><th>Runs</th><th>Tokens</th><th>Tools</th><th>Duration</th></tr></thead>`,
+        `<thead><tr><th>Phase</th><th>Runs</th><th>Tokens</th><th>Tools</th><th>Duration</th><th>Compactions</th><th>State</th></tr></thead>`,
         `<tbody>${rows}</tbody>`,
         `</table>`,
         `</section>`,
     ].join("\n");
 }
-function renderUsageTotalsList(totals) {
+function renderUsageTotalsList(totals, tokenAccounting) {
     const tokensTotal = totals.tokens.input + totals.tokens.output;
-    return [`<dt>Total runs</dt><dd>${totals.runs}</dd>`, `<dt>Tokens (in / out / cache)</dt><dd>${escapeHtml(formatTokenCount(totals.tokens.input))} / ${escapeHtml(formatTokenCount(totals.tokens.output))} / ${escapeHtml(formatTokenCount(totals.tokens.cache_write))}</dd>`, `<dt>Total tokens</dt><dd>${escapeHtml(formatTokenCount(tokensTotal))}</dd>`, `<dt>Tool uses</dt><dd>${totals.tool_uses}</dd>`, `<dt>Total duration</dt><dd>${escapeHtml(formatMillis(totals.duration_ms))}</dd>`].join("");
+    const tokenDetail = tokenAccounting
+        ? `${escapeHtml(formatTokenCount(totals.tokens.input))} / ${escapeHtml(formatTokenCount(totals.tokens.output))} / ${escapeHtml(formatTokenCount(totals.tokens.cache_write))}`
+        : `<span class="cc-muted">unavailable — host did not report token counts</span>`;
+    const tokenTotal = tokenAccounting ? escapeHtml(formatTokenCount(tokensTotal)) : `<span class="cc-muted">unavailable</span>`;
+    const compactionCounts = totals.compaction_runs > 0 ? formatCompactionCounts(totals.compactions) : `<span class="cc-muted">unavailable — host did not report compaction events</span>`;
+    const compactionReasons = totals.compaction_runs > 0 ? `<dt>Reasons</dt><dd>${formatCompactionReasons(totals.compactions)}</dd>` : "";
+    return [`<dt>Total runs</dt><dd>${totals.runs}</dd>`, `<dt>Tokens (in / out / cache)</dt><dd>${tokenDetail}</dd>`, `<dt>Total tokens</dt><dd>${tokenTotal}</dd>`, `<dt>Tool uses</dt><dd>${totals.tool_uses}</dd>`, `<dt>Total duration</dt><dd>${escapeHtml(formatMillis(totals.duration_ms))}</dd>`, `<dt>Compactions</dt><dd>${compactionCounts}</dd>`, compactionReasons].join("");
+}
+function formatCompactionCounts(value) {
+    return `${value.successful} successful · ${value.failed} failed · ${value.aborted} aborted`;
+}
+function formatCompactionReasons(value) {
+    return `threshold ${value.reasons.threshold} · overflow ${value.reasons.overflow} · manual ${value.reasons.manual}`;
+}
+function formatCompactionTriplet(value) {
+    return `${value.successful} / ${value.failed} / ${value.aborted}`;
+}
+function renderUsageInsights(perPhase, status) {
+    if (perPhase.size === 0)
+        return "";
+    const entries = [...perPhase.entries()];
+    const longest = entries.reduce((best, entry) => entry[1].duration_ms > best[1].duration_ms ? entry : best, entries[0]);
+    const mostTools = entries.reduce((best, entry) => entry[1].tool_uses > best[1].tool_uses ? entry : best, entries[0]);
+    const current = status.current_phase ? perPhase.get(status.current_phase) : undefined;
+    return [
+        `<div class="cc-usage-insights">`,
+        renderInsight("Longest phase", longest[0], formatMillis(longest[1].duration_ms)),
+        renderInsight("Most tool-heavy", mostTools[0], `${mostTools[1].tool_uses} tools`),
+        current && status.current_phase ? renderInsight("Current phase usage", status.current_phase, `${current.runs} run${current.runs === 1 ? "" : "s"} · ${formatMillis(current.duration_ms)}`) : "",
+        `</div>`,
+    ].filter(Boolean).join("\n");
+}
+function renderInsight(label, phaseId, value) {
+    return `<article class="cc-insight"><span>${escapeHtml(label)}</span><a href="#${phaseAnchor(phaseId)}">${escapeHtml(phaseId)}</a><strong>${escapeHtml(value)}</strong></article>`;
+}
+function renderUsageBar(value, max, label) {
+    const pct = Math.max(3, Math.min(100, Math.round((value / max) * 100)));
+    return `<span class="cc-bar-cell"><span class="cc-bar" style="--cc-bar:${pct}%"></span><span>${escapeHtml(label)}</span></span>`;
+}
+function usagePhaseNote(phaseId, status) {
+    return escapeHtml(phaseRenderState(status, phaseId));
 }
 function renderActivityTimeline(runs) {
     if (runs.length === 0)
@@ -344,17 +451,19 @@ function renderActivityTimeline(runs) {
     const sorted = [...runs].sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1));
     const visible = sorted.slice(0, TIMELINE_VISIBLE_COUNT);
     const overflow = sorted.slice(TIMELINE_VISIBLE_COUNT);
+    const hasSessionLinks = sorted.some((run) => Boolean(run.session_file && safeRelativeHref(run.session_file)));
     const rowOf = (run) => {
-        const tokensTotal = (run.tokens?.input ?? 0) + (run.tokens?.output ?? 0);
+        const tokensTotal = formatRunTokens(run);
         const sessionCell = run.session_file ? (renderSafeLink(run.session_file, "session") ?? "—") : "—";
-        return `<tr><td>${escapeHtml(run.timestamp)}</td><td><a href="#${phaseAnchor(run.phase)}">${escapeHtml(run.phase)}</a></td><td>${escapeHtml(run.status)}</td><td>${run.turn_count}</td><td>${run.tool_uses}</td><td>${escapeHtml(formatTokenCount(tokensTotal))}</td><td>${escapeHtml(formatMillis(run.duration_ms))}</td><td>${sessionCell}</td></tr>`;
+        return `<tr><td>${escapeHtml(run.timestamp)}</td><td><a href="#${phaseAnchor(run.phase)}">${escapeHtml(run.phase)}</a></td><td>${escapeHtml(run.status)}</td><td>${run.turn_count}</td><td>${run.tool_uses}</td><td>${escapeHtml(tokensTotal)}</td><td>${escapeHtml(formatMillis(run.duration_ms))}</td>${hasSessionLinks ? `<td>${sessionCell}</td>` : ""}</tr>`;
     };
     const overflowBlock = overflow.length === 0 ? "" : [`<details class="cc-timeline-older">`, `<summary>Older runs (${overflow.length})</summary>`, `<table class="cc-timeline-table">`, `<tbody>${overflow.map(rowOf).join("")}</tbody>`, `</table>`, `</details>`].join("\n");
-    return [`<section class="cc-card cc-timeline" aria-label="Activity timeline" data-section data-search-text="activity timeline sessions">`, `<div class="cc-section-head"><h2>Activity timeline</h2><span>newest first</span></div>`, `<table class="cc-timeline-table">`, `<thead><tr><th>When</th><th>Phase</th><th>Status</th><th>⟳</th><th>Tools</th><th>Tokens</th><th>Duration</th><th>Session</th></tr></thead>`, `<tbody>${visible.map(rowOf).join("")}</tbody>`, `</table>`, overflowBlock, `</section>`].join("\n");
+    return [`<section class="cc-card cc-timeline" aria-label="Activity timeline" data-section data-search-text="activity timeline sessions">`, `<div class="cc-section-head"><h2>Activity timeline</h2><span>newest first</span></div>`, `<table class="cc-timeline-table">`, `<thead><tr><th>When</th><th>Phase</th><th>Status</th><th>Turns</th><th>Tools</th><th>Tokens</th><th>Duration</th>${hasSessionLinks ? "<th>Session</th>" : ""}</tr></thead>`, `<tbody>${visible.map(rowOf).join("")}</tbody>`, `</table>`, overflowBlock, `</section>`].join("\n");
 }
 function renderOpenQuestionsRollup(status) {
     const buckets = [];
     const seen = new Set();
+    const byKind = new Map();
     let total = 0;
     for (const [phaseId, phaseState] of Object.entries(status.phases)) {
         const questions = [];
@@ -363,6 +472,8 @@ function renderOpenQuestionsRollup(status) {
             if (seen.has(key))
                 continue;
             seen.add(key);
+            const kind = String(q.kind ?? "unspecified");
+            byKind.set(kind, (byKind.get(kind) ?? 0) + 1);
             questions.push(renderOpenQuestion(q));
         }
         if (questions.length === 0)
@@ -372,7 +483,8 @@ function renderOpenQuestionsRollup(status) {
     }
     if (total === 0)
         return "";
-    return [`<section class="cc-card cc-rollup" aria-label="Open questions roll-up" data-section data-search-text="open questions">`, `<div class="cc-section-head"><h2>Open questions</h2><span>${total} unique</span></div>`, buckets.join("\n"), `</section>`].join("\n");
+    const kindSummary = [...byKind.entries()].sort((a, b) => b[1] - a[1]).map(([kind, count]) => `<span class="cc-kind-chip"><strong>${count}</strong>${escapeHtml(kind)}</span>`).join("");
+    return [`<section class="cc-card cc-rollup" aria-label="Open questions roll-up" data-section data-search-text="open questions">`, `<div class="cc-section-head"><h2>Open questions</h2><span>${total} unique</span></div>`, `<div class="cc-kind-summary">${kindSummary}</div>`, buckets.join("\n"), `</section>`].join("\n");
 }
 function renderCloseoutsList(inputs) {
     const closeouts = inputs.closeouts;
@@ -478,9 +590,32 @@ function phaseRenderState(status, phaseId) {
         return "current";
     return "pending";
 }
+function displayCurrentPhase(status) {
+    return status.current_phase === "complete" ? "Pipeline complete" : status.current_phase || "—";
+}
 function completedPhaseCount(status) {
     return Object.values(status.phases).filter((p) => p.status === "complete").length;
 }
+function countOpenQuestions(status) {
+    return Object.values(status.phases).reduce((sum, p) => sum + (p.open_questions?.length ?? 0), 0);
+}
+function countCarryForward(status) {
+    return Object.values(status.phases).reduce((sum, p) => sum + (p.carry_forward?.length ?? 0), 0);
+}
+function usageHasTokenAccounting(usage) {
+    return usage.runs.some((run) => (run.tokens?.input ?? 0) > 0 || (run.tokens?.output ?? 0) > 0 || (run.tokens?.cache_write ?? 0) > 0);
+}
+function formatTokensForDashboard(usage) {
+    const totals = computeTotals(usage);
+    if (usage.runs.length > 0 && !usageHasTokenAccounting(usage))
+        return "unavailable";
+    return formatTokenCount(totals.tokens.input + totals.tokens.output);
+}
+function formatRunTokens(run) {
+    const total = (run.tokens?.input ?? 0) + (run.tokens?.output ?? 0);
+    const hasAccounting = total > 0 || (run.tokens?.cache_write ?? 0) > 0;
+    return hasAccounting ? formatTokenCount(total) : "unavailable";
+}
 function lastRunPerPhase(runs) {
     const out = new Map();
     for (const r of runs) {
@@ -586,6 +721,24 @@ h2 { margin: 0; font-size: 18px; } h3 { margin: var(--s-2) 0 var(--s-1); color:
 .cc-meta-details { margin-top: var(--s-3); } .cc-header-meta, .cc-run-meta, .cc-usage-totals { display: grid; grid-template-columns: max-content 1fr; gap: var(--s-1) var(--s-3); margin: var(--s-2) 0; } dt { color: var(--fg-dim); } dd { margin: 0; }
 .cc-card, .cc-warning { padding: var(--s-3); margin-bottom: var(--s-4); }
 .cc-warning { border-color: var(--status-running); background: color-mix(in srgb, var(--status-running) 9%, var(--bg-card)); }
+.cc-health { border-width: 1px; position: relative; overflow: hidden; }
+.cc-health::before { content: ""; position: absolute; inset: 0 0 auto 0; height: 4px; background: var(--accent-2); }
+.cc-health-bad::before { background: var(--status-error); } .cc-health-warn::before { background: var(--status-running); } .cc-health-ok::before { background: var(--status-complete); }
+.cc-health-hero { display: flex; justify-content: space-between; align-items: center; gap: var(--s-3); margin-bottom: var(--s-3); }
+.cc-health-hero h2 { font-size: clamp(24px, 3vw, 38px); text-transform: capitalize; margin: 2px 0; }
+.cc-health-hero p { color: var(--fg-dim); margin: 0; }
+.cc-health-ring { width: 112px; height: 112px; border-radius: 999px; display: grid; place-items: center; align-content: center; background: radial-gradient(circle at center, var(--bg-card) 58%, transparent 59%), conic-gradient(var(--accent-3), var(--accent-2)); border: 1px solid var(--border); flex: 0 0 auto; }
+.cc-health-ring strong { font-size: 24px; line-height: 1; } .cc-health-ring span { color: var(--fg-dim); font-size: 12px; text-transform: uppercase; letter-spacing: .08em; }
+.cc-health-grid { display: grid; grid-template-columns: repeat(6, minmax(0, 1fr)); gap: var(--s-2); margin-bottom: var(--s-3); }
+.cc-health-metric { padding: var(--s-2); border: 1px solid var(--border); border-radius: 14px; background: var(--bg); min-width: 0; }
+.cc-health-metric span { display: block; color: var(--fg-dim); font-size: 12px; } .cc-health-metric strong { display: block; margin-top: 2px; font-size: 18px; overflow-wrap: anywhere; }
+.cc-tone-ok strong { color: var(--status-complete); } .cc-tone-warn strong { color: var(--status-running); } .cc-tone-bad strong { color: var(--status-error); }
+.cc-health-issues { display: grid; gap: var(--s-2); }
+.cc-health-issue { padding: var(--s-2); border: 1px solid var(--border); border-radius: 14px; background: var(--bg); }
+.cc-health-issue div { display: flex; flex-wrap: wrap; gap: var(--s-1); align-items: center; margin-bottom: 2px; }
+.cc-health-issue strong { display: block; font-size: 15px; } .cc-health-issue p { color: var(--fg-dim); margin: 2px 0 0; }
+.cc-issue-blocker { border-color: color-mix(in srgb, var(--status-error) 55%, var(--border)); background: color-mix(in srgb, var(--status-error) 8%, var(--bg-card)); }
+.cc-health-ok { color: var(--status-complete); margin: 0; }
 .cc-section-head { display: flex; justify-content: space-between; gap: var(--s-2); align-items: baseline; padding-bottom: var(--s-2); margin-bottom: var(--s-2); border-bottom: 1px solid var(--border); }
 .cc-section-head span, .cc-muted, .cc-empty { color: var(--fg-dim); }
 .cc-narration pre { white-space: pre-wrap; word-wrap: break-word; margin: 0; font-family: inherit; }
@@ -616,6 +769,15 @@ h2 { margin: 0; font-size: 18px; } h3 { margin: var(--s-2) 0 var(--s-1); color:
 .cc-usage-table th, .cc-usage-table td, .cc-timeline-table th, .cc-timeline-table td { padding: var(--s-1) var(--s-2); text-align: left; border-bottom: 1px solid var(--border); font-variant-numeric: tabular-nums; }
 .cc-usage-table th, .cc-timeline-table th { color: var(--fg-dim); font-weight: 700; text-transform: uppercase; font-size: 11px; letter-spacing: .04em; }
 .cc-usage-missing td:last-child { color: var(--status-running); }
+.cc-usage-insights { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: var(--s-2); margin: var(--s-3) 0; }
+.cc-insight { padding: var(--s-2); border: 1px solid var(--border); border-radius: 12px; background: var(--bg); display: grid; gap: 2px; }
+.cc-insight span { color: var(--fg-dim); font-size: 12px; } .cc-insight a { font-weight: 800; } .cc-insight strong { font-size: 15px; }
+.cc-bar-cell { min-width: 120px; display: grid; grid-template-columns: minmax(42px, 1fr) auto; align-items: center; gap: var(--s-2); }
+.cc-bar-cell > span:last-child { min-width: 48px; text-align: right; }
+.cc-bar { height: 8px; border-radius: 999px; background: linear-gradient(90deg, var(--accent-2) var(--cc-bar), var(--bg-soft) var(--cc-bar)); border: 1px solid var(--border); }
+.cc-kind-summary { display: flex; flex-wrap: wrap; gap: var(--s-1); margin: var(--s-2) 0 var(--s-3); }
+.cc-kind-chip { display: inline-flex; align-items: center; gap: 6px; padding: 5px 9px; border: 1px solid var(--border); border-radius: 999px; background: var(--bg); color: var(--fg-dim); font-size: 12px; }
+.cc-kind-chip strong { color: var(--fg); }
 .cc-timeline-older { margin-top: var(--s-2); }
 .cc-footer { margin-top: var(--s-5); padding-top: var(--s-3); border-top: 1px solid var(--border); color: var(--fg-dim); font-size: 13px; }
 @media (max-width: 900px) {
@@ -624,7 +786,8 @@ h2 { margin: 0; font-size: 18px; } h3 { margin: var(--s-2) 0 var(--s-1); color:
   body.cc-sidebar-open .cc-sidebar { transform: translateX(0); }
   .cc-menu-button { display: block; }
   .cc-main { padding: var(--s-3); padding-top: var(--s-5); }
-  .cc-stat-grid, .cc-artifact-row, .cc-closeout-row { grid-template-columns: 1fr; }
+  .cc-stat-grid, .cc-artifact-row, .cc-closeout-row, .cc-health-grid, .cc-usage-insights { grid-template-columns: 1fr; }
+  .cc-health-hero { align-items: flex-start; } .cc-health-ring { width: 88px; height: 88px; }
   .cc-header-meta, .cc-run-meta, .cc-usage-totals { grid-template-columns: 1fr; }
   table { display: block; overflow-x: auto; white-space: nowrap; }
 }

package/dist/core/prompts.js

@@ -48,6 +48,10 @@ export async function buildPhasePrompt(state, phase, forced, options = {}) {
     for (const path of phaseReads) {
         lines.push(`- .codecarto/${path}`);
     }
+    const checkpointRelativePath = `scratch/checkpoints/${phase.id}.md`;
+    if (await pathExists(join(state.workspaceDir, checkpointRelativePath))) {
+        lines.push(`- .codecarto/${checkpointRelativePath} (resume from durable in-phase progress after compaction or interruption)`);
+    }
     const conventionsPath = join(state.workspaceDir, "CONVENTIONS.md");
     if (await pathExists(conventionsPath)) {
         lines.push("- .codecarto/CONVENTIONS.md (cross-cutting patterns the orchestrator has promoted)");
@@ -85,6 +89,8 @@ export async function buildPhasePrompt(state, phase, forced, options = {}) {
     lines.push("- Do not modify source files outside .codecarto/.");
     lines.push("- Follow the active pipeline and validation protocol.");
     lines.push("- Update findings under .codecarto/findings/ for this phase.");
+    lines.push(`- For long phases, checkpoint resumable progress at .codecarto/scratch/checkpoints/${phase.id}.md; Pi writes this automatically after phase compaction.`);
+    lines.push("- Include a Coverage and limits section that names inspected scope, skipped scope, evidence basis, and blind spots; route material gaps through PARTIAL validation and open_questions/carry_forward.");
     lines.push("- Distinguish open_questions (genuinely unknown) from carry_forward (routed to a specific later phase) when updating workflow/status.yaml — see GUIDE.md \"Open Questions vs Carry-Forward\".");
     if (forced) {
         lines.push("- The user explicitly requested this phase even if it is not the next eligible phase.");

package/dist/core/usage.d.ts

@@ -1,10 +1,18 @@
 export declare const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
 export type UsageRunStatus = "completed" | "aborted" | "error";
+export type CompactionReason = "threshold" | "overflow" | "manual";
 export interface UsageTokens {
     input: number;
     output: number;
     cache_write: number;
 }
+export interface CompactionTelemetry {
+    successful: number;
+    failed: number;
+    aborted: number;
+    reasons: Record<CompactionReason, number>;
+}
+export declare function emptyCompactionTelemetry(): CompactionTelemetry;
 export interface UsageRun {
     timestamp: string;
     phase: string;
@@ -14,6 +22,7 @@ export interface UsageRun {
     duration_ms: number;
     tokens: UsageTokens;
     session_file?: string;
+    compactions?: CompactionTelemetry;
 }
 export interface UsageFile {
     version: number;
@@ -21,9 +30,11 @@ export interface UsageFile {
 }
 export interface UsageTotals {
     runs: number;
+    compaction_runs: number;
     tokens: UsageTokens;
     tool_uses: number;
     duration_ms: number;
+    compactions: CompactionTelemetry;
 }
 export declare function loadUsage(workspaceDir: string): Promise<UsageFile>;
 export declare function appendUsageRun(workspaceDir: string, run: UsageRun): Promise<void>;

package/dist/core/usage.js

@@ -13,6 +13,9 @@ import { pathExists } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 export const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
 const SCHEMA_VERSION = 1;
+export function emptyCompactionTelemetry() {
+    return { successful: 0, failed: 0, aborted: 0, reasons: { threshold: 0, overflow: 0, manual: 0 } };
+}
 export async function loadUsage(workspaceDir) {
     const path = join(workspaceDir, USAGE_RELATIVE_PATH);
     if (!(await pathExists(path)))
@@ -23,8 +26,6 @@ export async function loadUsage(workspaceDir) {
         return normalize(parsed);
     }
     catch {
-        // Malformed file: treat as empty rather than blocking the user. They
-        // can fix or delete the file; corrupt local state shouldn't stop work.
         return emptyUsage();
     }
 }
@@ -33,45 +34,56 @@ export async function appendUsageRun(workspaceDir, run) {
     current.runs.push(run);
     const path = join(workspaceDir, USAGE_RELATIVE_PATH);
     const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    const serialized = `${stringifySimpleYaml(current)}\n`;
-    await writeFile(tempPath, serialized, "utf8");
+    await writeFile(tempPath, `${stringifySimpleYaml(current)}\n`, "utf8");
     await rename(tempPath, path);
 }
 export function computeTotals(file) {
-    const totals = {
-        runs: file.runs.length,
-        tokens: { input: 0, output: 0, cache_write: 0 },
-        tool_uses: 0,
-        duration_ms: 0,
-    };
-    for (const r of file.runs) {
-        totals.tokens.input += r.tokens?.input ?? 0;
-        totals.tokens.output += r.tokens?.output ?? 0;
-        totals.tokens.cache_write += r.tokens?.cache_write ?? 0;
-        totals.tool_uses += r.tool_uses ?? 0;
-        totals.duration_ms += r.duration_ms ?? 0;
-    }
+    const totals = emptyTotals();
+    totals.runs = file.runs.length;
+    for (const run of file.runs)
+        addRun(totals, run);
     return totals;
 }
 export function computePerPhaseTotals(file) {
     const byPhase = new Map();
-    for (const r of file.runs) {
-        const t = byPhase.get(r.phase) ?? {
-            runs: 0,
-            tokens: { input: 0, output: 0, cache_write: 0 },
-            tool_uses: 0,
-            duration_ms: 0,
-        };
-        t.runs += 1;
-        t.tokens.input += r.tokens?.input ?? 0;
-        t.tokens.output += r.tokens?.output ?? 0;
-        t.tokens.cache_write += r.tokens?.cache_write ?? 0;
-        t.tool_uses += r.tool_uses ?? 0;
-        t.duration_ms += r.duration_ms ?? 0;
-        byPhase.set(r.phase, t);
+    for (const run of file.runs) {
+        const totals = byPhase.get(run.phase) ?? emptyTotals();
+        totals.runs += 1;
+        addRun(totals, run);
+        byPhase.set(run.phase, totals);
     }
     return byPhase;
 }
+function emptyTotals() {
+    return {
+        runs: 0,
+        compaction_runs: 0,
+        tokens: { input: 0, output: 0, cache_write: 0 },
+        tool_uses: 0,
+        duration_ms: 0,
+        compactions: emptyCompactionTelemetry(),
+    };
+}
+function addRun(totals, run) {
+    totals.tokens.input += run.tokens?.input ?? 0;
+    totals.tokens.output += run.tokens?.output ?? 0;
+    totals.tokens.cache_write += run.tokens?.cache_write ?? 0;
+    totals.tool_uses += run.tool_uses ?? 0;
+    totals.duration_ms += run.duration_ms ?? 0;
+    if (run.compactions)
+        totals.compaction_runs += 1;
+    addCompactions(totals.compactions, run.compactions);
+}
+function addCompactions(target, source) {
+    if (!source)
+        return;
+    target.successful += source.successful;
+    target.failed += source.failed;
+    target.aborted += source.aborted;
+    target.reasons.threshold += source.reasons.threshold;
+    target.reasons.overflow += source.reasons.overflow;
+    target.reasons.manual += source.reasons.manual;
+}
 function emptyUsage() {
     return { version: SCHEMA_VERSION, runs: [] };
 }
@@ -79,29 +91,35 @@ function normalize(raw) {
     if (!raw || typeof raw !== "object")
         return emptyUsage();
     const runs = Array.isArray(raw.runs) ? raw.runs.filter(isUsageRun) : [];
-    return {
-        version: typeof raw.version === "number" ? raw.version : SCHEMA_VERSION,
-        runs,
-    };
+    return { version: typeof raw.version === "number" ? raw.version : SCHEMA_VERSION, runs };
 }
 function isUsageRun(x) {
     if (!x || typeof x !== "object")
         return false;
-    const r = x;
-    return (typeof r.timestamp === "string" &&
-        typeof r.phase === "string" &&
-        (r.status === "completed" || r.status === "aborted" || r.status === "error") &&
-        isFiniteNumber(r.turn_count) &&
-        isFiniteNumber(r.tool_uses) &&
-        isFiniteNumber(r.duration_ms) &&
-        isUsageTokens(r.tokens) &&
-        (r.session_file === undefined || typeof r.session_file === "string"));
+    const run = x;
+    return (typeof run.timestamp === "string" &&
+        typeof run.phase === "string" &&
+        (run.status === "completed" || run.status === "aborted" || run.status === "error") &&
+        isFiniteNumber(run.turn_count) &&
+        isFiniteNumber(run.tool_uses) &&
+        isFiniteNumber(run.duration_ms) &&
+        isUsageTokens(run.tokens) &&
+        (run.session_file === undefined || typeof run.session_file === "string") &&
+        (run.compactions === undefined || isCompactionTelemetry(run.compactions)));
 }
 function isUsageTokens(x) {
     if (!x || typeof x !== "object")
         return false;
-    const t = x;
-    return isFiniteNumber(t.input) && isFiniteNumber(t.output) && isFiniteNumber(t.cache_write);
+    const tokens = x;
+    return isFiniteNumber(tokens.input) && isFiniteNumber(tokens.output) && isFiniteNumber(tokens.cache_write);
+}
+function isCompactionTelemetry(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const telemetry = x;
+    const reasons = telemetry.reasons;
+    return isFiniteNumber(telemetry.successful) && isFiniteNumber(telemetry.failed) && isFiniteNumber(telemetry.aborted) &&
+        Boolean(reasons) && isFiniteNumber(reasons?.threshold) && isFiniteNumber(reasons?.overflow) && isFiniteNumber(reasons?.manual);
 }
 function isFiniteNumber(x) {
     return typeof x === "number" && Number.isFinite(x);

package/dist/extensions/codecarto/agent-rewriter.js

@@ -145,7 +145,6 @@ async function runRewriterOnce(ctx, prompt) {
         agentDir,
         sessionManager: SessionManager.inMemory(cwd),
         settingsManager: SettingsManager.create(cwd, agentDir),
-        modelRegistry: ctx.modelRegistry,
         model: ctx.model,
         tools: [],
         resourceLoader: loader,