codecartographer-pi 0.10.0 → 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

@@ -369,7 +369,8 @@ function renderPhaseLastRun(run) {
     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(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;
@@ -382,10 +383,11 @@ function renderUsagePanel(inputs) {
         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>—</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(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>${usagePhaseNote(phaseId, status)}</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">`,
@@ -393,7 +395,7 @@ function renderUsagePanel(inputs) {
         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><th>State</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>`,
@@ -405,7 +407,18 @@ function renderUsageTotalsList(totals, 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>`;
-    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>`].join("");
+    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)

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,

package/dist/extensions/codecarto/agent-runner.d.ts

@@ -1,4 +1,15 @@
 import { type AgentSession, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+export declare function needsPhaseContinuation(messages: ReadonlyArray<{
+    role: string;
+    stopReason?: string;
+}>): boolean;
+export declare function shouldContinuePhase(messages: ReadonlyArray<{
+    role: string;
+    stopReason?: string;
+}>, primaryOutputPresent: boolean): boolean;
+export declare function primaryOutputExists(cwd: string, primaryOutput: string): Promise<boolean>;
+export declare function buildPhaseContinuationPrompt(compacted: boolean): string;
+export declare function waitForCompaction(compactionCompleted: Promise<boolean>, timeoutMs?: number): Promise<boolean>;
 export interface PhaseRunCallbacks {
     onSessionCreated?: (session: AgentSession) => void;
     onToolStart?: (toolCallId: string, toolName: string) => void;
@@ -10,12 +21,20 @@ export interface PhaseRunCallbacks {
         output: number;
         cacheWrite: number;
     }) => void;
+    onCompactionEnd?: (event: {
+        reason: "manual" | "threshold" | "overflow";
+        successful: boolean;
+        aborted: boolean;
+    }) => void;
 }
 export interface PhaseRunOptions {
     /** Display name written via appendSessionInfo so the session shows up in
      *  /resume's picker as e.g. "CodeCartographer phase: blueprint". Pi reads
      *  it via SessionManager.getSessionName(). */
     sessionName?: string;
+    /** Primary output relative to `.codecarto/`; used to detect provider runs
+     * that stop normally before writing their required artifact. */
+    primaryOutput?: string;
 }
 export interface PhaseRunResult {
     session: AgentSession;

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

@@ -9,11 +9,51 @@
 // system prompt, no parent-context inheritance, no turn-limit grace logic.
 // Codecarto phases are bounded by their phase prompt and validation gate;
 // they don't need the full subagent-framework machinery.
+import { access } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { canonicalPath, isWithinPath } from "../../core/index.js";
+import { phaseCompactionExtension } from "./phase-compaction.js";
 // Tools available to the phase sub-agent. Matches the codecarto interception
 // allowlist (SAFE_TOOL_NAMES in extensions/codecarto/index.ts), minus bash.
 // Phases analyze source code and write findings; they don't need a shell.
 const PHASE_TOOL_NAMES = ["read", "edit", "write", "grep", "find", "ls"];
+const COMPACTION_SETTLE_TIMEOUT_MS = 30_000;
+export function needsPhaseContinuation(messages) {
+    const last = messages.at(-1);
+    if (!last)
+        return false;
+    return last.role === "toolResult" || (last.role === "assistant" && last.stopReason === "toolUse");
+}
+export function shouldContinuePhase(messages, primaryOutputPresent) {
+    return !primaryOutputPresent || needsPhaseContinuation(messages);
+}
+export async function primaryOutputExists(cwd, primaryOutput) {
+    const workspaceRoot = await canonicalPath(join(cwd, ".codecarto"));
+    const candidate = await canonicalPath(resolve(workspaceRoot, primaryOutput));
+    if (!isWithinPath(candidate, workspaceRoot))
+        return false;
+    return access(candidate).then(() => true, () => false);
+}
+export function buildPhaseContinuationPrompt(compacted) {
+    const recovery = compacted
+        ? "Continue the current CodeCartographer phase from the compacted context and durable checkpoint."
+        : "The previous phase run stopped before finalizing its required output. Continue from the current session context.";
+    return `${recovery} Finish the declared primary output, validation block, status updates, and closeout before ending.`;
+}
+export async function waitForCompaction(compactionCompleted, timeoutMs = COMPACTION_SETTLE_TIMEOUT_MS) {
+    let timer;
+    try {
+        return await Promise.race([
+            compactionCompleted,
+            new Promise((resolve) => { timer = setTimeout(() => resolve(false), timeoutMs); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
  * Run one CodeCartographer phase as an isolated AgentSession. Awaiting this
  * function blocks until the phase completes (or aborts via signal). The
@@ -30,17 +70,19 @@ const PHASE_TOOL_NAMES = ["read", "edit", "write", "grep", "find", "ls"];
 export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal) {
     const cwd = ctx.cwd;
     const agentDir = getAgentDir();
-    // Resource loader: load Pi extensions and skills (so codecarto's own tool
-    // interception applies to the child) but skip prompt templates, themes,
-    // and project context files — they'd just bloat the system prompt.
+    // Resource loader: isolate the child from global extensions/skills and load
+    // only CodeCartographer's inline phase guards and compaction hooks. This
+    // avoids duplicate registration when CodeCartographer is globally installed
+    // while preserving the same safety when it was loaded explicitly with -e.
     const loader = new DefaultResourceLoader({
         cwd,
         agentDir,
-        noExtensions: false,
-        noSkills: false,
+        noExtensions: true,
+        noSkills: true,
         noPromptTemplates: true,
         noThemes: true,
         noContextFiles: true,
+        extensionFactories: [phaseCompactionExtension],
     });
     await loader.reload();
     // File-backed session in the same directory the orchestrator's TUI uses.
@@ -64,7 +106,6 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
         agentDir,
         sessionManager,
         settingsManager: SettingsManager.create(cwd, agentDir),
-        modelRegistry: ctx.modelRegistry,
         model: ctx.model,
         tools: PHASE_TOOL_NAMES,
         resourceLoader: loader,
@@ -75,6 +116,8 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
     let turnCount = 0;
     let currentMessageText = "";
     let aborted = false;
+    let resolveCompaction;
+    const compactionCompleted = new Promise((resolve) => { resolveCompaction = resolve; });
     const unsubscribe = session.subscribe((event) => {
         switch (event.type) {
             case "tool_execution_start": {
@@ -117,6 +160,16 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
                 }
                 break;
             }
+            case "compaction_end": {
+                const compactEvent = event;
+                callbacks.onCompactionEnd?.({
+                    reason: compactEvent.reason,
+                    successful: compactEvent.result !== undefined && compactEvent.result !== null && !compactEvent.aborted && !compactEvent.errorMessage,
+                    aborted: compactEvent.aborted,
+                });
+                resolveCompaction?.(true);
+                break;
+            }
         }
     });
     let abortCleanup = () => { };
@@ -130,6 +183,15 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
     }
     try {
         await session.prompt(prompt);
+        let primaryOutputPresent = true;
+        if (options.primaryOutput) {
+            primaryOutputPresent = await primaryOutputExists(cwd, options.primaryOutput);
+        }
+        if (!aborted && shouldContinuePhase(session.messages, primaryOutputPresent)) {
+            const compacted = await waitForCompaction(compactionCompleted);
+            if (!aborted)
+                await session.prompt(buildPhaseContinuationPrompt(compacted));
+        }
     }
     finally {
         unsubscribe();

package/dist/extensions/codecarto/agent-state.d.ts

@@ -1,4 +1,5 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { type CompactionTelemetry } from "../../core/usage.ts";
 export type PhaseStatus = "running" | "completed" | "error" | "aborted";
 export interface PhaseActivity {
     phaseId: string;
@@ -17,6 +18,8 @@ export interface PhaseActivity {
         output: number;
         cacheWrite: number;
     };
+    /** Compaction outcomes observed during this phase session. */
+    compactions: CompactionTelemetry;
     session?: AgentSession;
     error?: string;
 }

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

@@ -2,6 +2,7 @@
 // it from session-event callbacks; the agents widget (M2) reads it on each
 // render. Module-scoped Map so different command handlers can hand work to
 // the runner and the widget sees the same state without explicit plumbing.
+import { emptyCompactionTelemetry } from "../../core/usage.js";
 const phaseActivity = new Map();
 export function getPhaseActivity(phaseId) {
     return phaseActivity.get(phaseId);
@@ -22,6 +23,7 @@ export function startPhase(phaseId) {
         activeTools: new Map(),
         responseText: "",
         lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+        compactions: emptyCompactionTelemetry(),
     };
     phaseActivity.set(phaseId, activity);
     return activity;

package/dist/extensions/codecarto/agent-summary.d.ts

@@ -9,6 +9,11 @@ export interface PhaseSummaryInput {
         output: number;
         cacheWrite: number;
     };
+    compactions?: {
+        successful: number;
+        failed: number;
+        aborted: number;
+    };
     durationMs: number;
     responseText: string;
     sessionFile?: string;

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

@@ -39,6 +39,15 @@ function formatStats(input) {
     const totalTokens = input.tokens.input + input.tokens.output;
     if (totalTokens > 0)
         parts.push(formatTokens(totalTokens));
+    const compact = input.compactions;
+    if (compact && compact.successful + compact.failed + compact.aborted > 0) {
+        const details = [`${compact.successful} compaction${compact.successful === 1 ? "" : "s"}`];
+        if (compact.failed > 0)
+            details.push(`${compact.failed} failed`);
+        if (compact.aborted > 0)
+            details.push(`${compact.aborted} aborted`);
+        parts.push(details.join(", "));
+    }
     if (input.durationMs > 0)
         parts.push(formatDuration(input.durationMs));
     return parts.length > 0 ? `_${parts.join(" · ")}_` : "_(no activity recorded)_";

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

@@ -186,6 +186,9 @@ function formatRunningStats(a) {
     const tokens = a.lifetimeUsage.input + a.lifetimeUsage.output;
     if (tokens > 0)
         parts.push(formatTokens(tokens));
+    const compactions = a.compactions.successful + a.compactions.failed + a.compactions.aborted;
+    if (compactions > 0)
+        parts.push(`${compactions} compact`);
     parts.push(formatDuration(Date.now() - a.startedAt));
     return parts.join(" · ");
 }
@@ -198,6 +201,9 @@ function formatFinishedStats(a) {
     const tokens = a.lifetimeUsage.input + a.lifetimeUsage.output;
     if (tokens > 0)
         parts.push(formatTokens(tokens));
+    const compactions = a.compactions.successful + a.compactions.failed + a.compactions.aborted;
+    if (compactions > 0)
+        parts.push(`${compactions} compact`);
     const dur = a.completedAt ? a.completedAt - a.startedAt : 0;
     if (dur > 0)
         parts.push(formatDuration(dur));

package/dist/extensions/codecarto/auto-runner.js

@@ -69,7 +69,16 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
                 activity.lifetimeUsage.output += usage.output;
                 activity.lifetimeUsage.cacheWrite += usage.cacheWrite;
             },
-        }, { sessionName: `CodeCartographer phase: ${phase.id}` }, options.signal);
+            onCompactionEnd: (event) => {
+                activity.compactions.reasons[event.reason]++;
+                if (event.aborted)
+                    activity.compactions.aborted++;
+                else if (event.successful)
+                    activity.compactions.successful++;
+                else
+                    activity.compactions.failed++;
+            },
+        }, { sessionName: `CodeCartographer phase: ${phase.id}`, primaryOutput: phase.primary_output }, options.signal);
         const status = result.aborted ? "aborted" : "completed";
         finishPhase(phase.id, { status });
         if (ctx.hasUI) {
@@ -85,6 +94,7 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
                 turnCount: activity.turnCount,
                 toolUses: activity.toolUses,
                 tokens: activity.lifetimeUsage,
+                compactions: activity.compactions,
                 durationMs: (activity.completedAt ?? Date.now()) - activity.startedAt,
                 responseText: result.responseText,
                 sessionFile: result.sessionFile,
@@ -113,6 +123,7 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
                 turnCount: activity.turnCount,
                 toolUses: activity.toolUses,
                 tokens: activity.lifetimeUsage,
+                compactions: activity.compactions,
                 durationMs: (activity.completedAt ?? Date.now()) - activity.startedAt,
                 responseText: "",
                 error: message,
@@ -394,6 +405,7 @@ async function recordUsage(workspaceDir, phaseId, status, activity, sessionFile)
                 output: activity.lifetimeUsage.output,
                 cache_write: activity.lifetimeUsage.cacheWrite,
             },
+            compactions: activity.compactions,
             ...(sessionFile ? { session_file: sessionFile } : {}),
         });
     }