codecartographer-pi 0.10.0 → 0.12.0

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

@@ -17,7 +17,7 @@ import { buildSteeringMessage, rewritePhasePrompt } from "./agent-rewriter.js";
 import { buildPhaseSummary } from "./agent-summary.js";
 import { getAgentsWidget } from "./agent-widget.js";
 import { writeDashboard } from "./dashboard-writer.js";
-import { appendUsageRun, buildPhasePrompt, buildThreadLogEntry, buildValidationSummary, closeoutFileName, dateOnly, ensureCloseoutStub, formatMillis, formatTokenCount, getNextEligiblePhase, getWorkspaceState, loadCodecartoConfig, normalizeStatus, PACKAGE_VERSION, resolvePhase, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../../core/index.js";
+import { appendUsageRun, buildPhasePrompt, buildValidationSummary, completeValidatedPhase, formatMillis, formatTokenCount, getNextEligiblePhase, getWorkspaceState, loadCodecartoConfig, PACKAGE_VERSION, PhasePreflightError, runPhasePreflight, validatePhaseOutput, } from "../../core/index.js";
 /**
  * Run one phase end to end: optional LLM-steered rewrite, spawn the sub-agent,
  * wait for it, then emit the side effects the historical /codecarto-next chain
@@ -29,7 +29,10 @@ import { appendUsageRun, buildPhasePrompt, buildThreadLogEntry, buildValidationS
  * getPhaseActivity) and attached the agents widget if it wanted live progress.
  */
 export async function runSinglePhase(ctx, pi, state, phase, options) {
-    let prompt = await buildPhasePrompt(state, phase, false, { auto: options.auto === true });
+    let prompt = await buildPhasePrompt(state, phase, false, {
+        auto: options.auto === true,
+        preflight: options.preflight,
+    });
     if (options.llmSteerEnabled) {
         if (ctx.hasUI)
             ctx.ui.notify(`Customizing ${phase.id} prompt via LLM rewriter…`, "info");
@@ -69,7 +72,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 +97,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 +126,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,
@@ -138,73 +152,9 @@ export function isPhaseRunning(phaseId) {
     return existing?.status === "running";
 }
 export async function autoCompletePhase(ctx, validation) {
-    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 result = await completeValidatedPhase(ctx.cwd, validation, "/codecarto-complete");
     void writeDashboard(ctx.cwd, PACKAGE_VERSION);
-    return { updatedState, closeoutNotice };
+    return result;
 }
 export function decideAfterPhase(phaseStatus, phaseError, validation, strict) {
     if (phaseStatus === "aborted")
@@ -255,6 +205,18 @@ export async function runAuto(ctx, pi, initialState, options) {
                 reason: "Pipeline complete.",
             });
         }
+        let preflight;
+        try {
+            preflight = await runPhasePreflight(state, phase);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return finish({
+                outcome: "stopped",
+                reason: message,
+                stoppedAt: { phaseId: phase.id, error: err instanceof PhasePreflightError ? undefined : message },
+            });
+        }
         if (isPhaseRunning(phase.id)) {
             return finish({
                 outcome: "stopped",
@@ -266,6 +228,7 @@ export async function runAuto(ctx, pi, initialState, options) {
             llmSteerEnabled,
             signal: options.signal,
             auto: true,
+            preflight,
         });
         // Accumulate tokens whether the phase succeeded, was aborted, or errored.
         totalTokens.input += phaseResult.activity.lifetimeUsage.input;
@@ -394,6 +357,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 } : {}),
         });
     }

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

@@ -155,7 +155,6 @@ async function runNarratorOnce(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/index.d.ts

@@ -1,2 +1,2 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 export default function codeCartographerExtension(pi: ExtensionAPI): void;

package/dist/extensions/codecarto/index.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
 import { disposeAgentsWidget } from "./agent-widget.js";
@@ -6,10 +6,32 @@ 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 { 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";
+import { phaseCompactionExtension } from "./phase-compaction.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, 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"];
+function derivePublishHeadline(spec, cwd) {
+    const summary = spec.split(/^##\s+System Summary\s*$/mi)[1]?.split(/^##\s+/m)[0] ?? "";
+    const candidate = summary
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line && !line.startsWith("<!--") && !line.startsWith("-->") && !line.startsWith("#"));
+    return candidate?.replace(/\s+/g, " ").slice(0, 280) || `Reimplementation specification for ${basename(cwd)}.`;
+}
+function piGeneration(ctx) {
+    return {
+        surface: "pi-extension",
+        agent: "pi",
+        agent_version: "unknown",
+        model: ctx.model?.id ?? "unknown",
+        model_vendor: ctx.model?.provider ?? "unknown",
+        // Pi's extension context exposes the selected model but not the active
+        // thinking level. Preserve that uncertainty instead of inferring it.
+        reasoning: "unknown",
+        notes: "",
+    };
+}
 function formatUsageTokens(count) {
     if (count >= 1_000_000)
         return `${(count / 1_000_000).toFixed(2)}M`;
@@ -31,16 +53,19 @@ function buildStatusLines(state, extraLines = []) {
     const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "complete";
     const pipelineLabel = getPipelineLabel(state.status.pipeline);
     const completedCount = state.pipeline.phase_order.filter((phaseId) => state.status.phases[phaseId]?.status === "complete").length;
-    const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions.length ?? 0;
+    const terminalOpenQuestions = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
     const totalCarryForward = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.carry_forward?.length ?? 0), 0);
+    const postPipelinePending = state.status.post_pipeline.filter((entry) => entry.status !== "resolved").length;
     const nextAction = state.status.next_actions[0] ?? (nextPhase ? `Next: ${nextPhase.id}` : "All phases complete.");
     const lines = [
         "CodeCartographer",
         `Phase: ${currentPhase}`,
+        `Pipeline state: ${currentPhase === "complete" ? "complete" : "in progress"}`,
         `Pipeline: ${pipelineLabel}`,
         `Progress: ${completedCount}/${state.pipeline.phase_order.length} complete`,
-        `Open questions: ${currentOpenQuestions}`,
-        `Carry-forward: ${totalCarryForward}`,
+        `Open questions (terminal unresolved): ${terminalOpenQuestions}`,
+        `Carry-forward (pipeline phases): ${totalCarryForward}`,
+        `Post-pipeline work: ${postPipelinePending} pending`,
         `Next: ${nextAction}`,
     ];
     if (extraLines.length > 0) {
@@ -62,6 +87,7 @@ function setUiState(ctx, state, extraLines = []) {
     ctx.ui.setWidget(STATUS_WIDGET_ID, buildStatusLines(state, extraLines));
 }
 export default function codeCartographerExtension(pi) {
+    phaseCompactionExtension(pi);
     let lastFeedbackLines = [];
     let codecartoModeActive = false;
     const readWorkspaceState = async (ctx, notifyOnError = true) => {
@@ -133,16 +159,42 @@ export default function codeCartographerExtension(pi) {
             const inputPath = typeof event.input.path === "string" ? event.input.path : "";
             const strippedPath = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
             const targetPath = await canonicalPath(resolve(ctx.cwd, strippedPath));
-            const allowedRoot = await canonicalPath(workspaceDir);
-            if (!isWithinPath(targetPath, allowedRoot)) {
+            const allowedRoots = [await canonicalPath(workspaceDir)];
+            const config = await loadCodecartoConfig(workspaceDir);
+            if (config.library.path && await discoverLibrary(config.library.path)) {
+                allowedRoots.push(await canonicalPath(config.library.path));
+            }
+            if (!allowedRoots.some((allowedRoot) => isWithinPath(targetPath, allowedRoot))) {
                 if (ctx.hasUI) {
-                    ctx.ui.notify(`Blocked ${event.toolName} outside .codecarto/: ${inputPath}`, "warning");
+                    ctx.ui.notify(`Blocked ${event.toolName} outside .codecarto/ or configured library: ${inputPath}`, "warning");
                 }
-                return { block: true, reason: `CodeCartographer mode only allows ${event.toolName} within .codecarto/` };
+                return { block: true, reason: `CodeCartographer mode only allows ${event.toolName} within .codecarto/ or the configured CodeCartographer library.` };
             }
         }
         return undefined;
     });
+    pi.registerCommand("codecarto-open", {
+        description: "Activate an existing .codecarto workspace without resetting durable state",
+        handler: async (_args, ctx) => {
+            const workspaceDir = join(ctx.cwd, ".codecarto");
+            if (!(await pathExists(join(workspaceDir, "workflow", "status.yaml")))) {
+                ctx.ui.notify("No existing CodeCartographer workspace found. Run /codecarto-init first.", "warning");
+                return;
+            }
+            try {
+                const state = await getWorkspaceState(ctx.cwd);
+                codecartoModeActive = true;
+                lastFeedbackLines = [`Opened existing workspace: ${getPipelineLabel(state.status.pipeline)}`];
+                pi.setActiveTools(SAFE_TOOL_NAMES);
+                await refreshWorkspaceUi(ctx, lastFeedbackLines);
+                ctx.ui.notify("Opened existing CodeCartographer workspace without resetting state.", "info");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(`Unable to open CodeCartographer workspace: ${message}`, "error");
+            }
+        },
+    });
     pi.registerCommand("codecarto-init", {
         description: "Initialize .codecarto/ in the current repository",
         getArgumentCompletions: (prefix) => {
@@ -268,6 +320,17 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify("All CodeCartographer phases are complete.", "info");
                 return;
             }
+            let preflight;
+            try {
+                preflight = await runPhasePreflight(state, phase);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lastFeedbackLines = [message];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(message, error instanceof PhasePreflightError ? "warning" : "error");
+                return;
+            }
             // Reject re-entry: don't spawn a duplicate runner for a phase that's
             // already in flight from a previous /codecarto-next invocation.
             if (isPhaseRunning(phase.id)) {
@@ -281,7 +344,7 @@ export default function codeCartographerExtension(pi) {
             // 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 })
+            void runSinglePhase(ctx, pi, state, phase, { llmSteerEnabled, signal: ctx.signal, preflight })
                 .finally(() => {
                 // Refresh the status widget after the phase resolves so the
                 // "Open questions / Carry-forward / Next" lines reflect any
@@ -306,7 +369,15 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Unknown phase: ${phaseId}`, "error");
                 return;
             }
-            const prompt = await buildPhasePrompt(state, phase, true);
+            let prompt;
+            try {
+                prompt = await buildPhasePrompt(state, phase, true);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(message, error instanceof PhasePreflightError ? "warning" : "error");
+                return;
+            }
             if (ctx.isIdle()) {
                 pi.sendUserMessage(prompt);
             }
@@ -407,6 +478,73 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
         },
     });
+    pi.registerCommand("codecarto-publish", {
+        description: "Publish the completed reimplementation spec to the configured CodeCartographer library",
+        handler: async (_args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const config = await loadCodecartoConfig(state.workspaceDir);
+            if (!config.library.path) {
+                ctx.ui.notify("No library.path is configured. Set it in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.", "error");
+                return;
+            }
+            const marker = await discoverLibrary(config.library.path);
+            if (!marker) {
+                ctx.ui.notify(`No CodeCartographer library at ${config.library.path} (missing .codecarto-library).`, "error");
+                return;
+            }
+            const phase = resolvePhase(state, "reimplementation-spec");
+            if (!phase?.primary_output) {
+                ctx.ui.notify("The active pipeline does not produce a reimplementation spec to publish.", "error");
+                return;
+            }
+            const specPath = join(state.workspaceDir, phase.primary_output);
+            if (!(await pathExists(specPath))) {
+                ctx.ui.notify(`Reimplementation spec is missing: .codecarto/${phase.primary_output}`, "error");
+                return;
+            }
+            const spec = await readFile(specPath, "utf8");
+            const slug = deriveSlug(ctx.cwd);
+            const headline = derivePublishHeadline(spec, ctx.cwd);
+            const namespace = marker.namespaced ? config.library.namespace ?? undefined : undefined;
+            if (marker.namespaced && !namespace) {
+                ctx.ui.notify("The configured library is namespaced; set library.namespace before publishing.", "error");
+                return;
+            }
+            const preview = [
+                `Publish ${namespace ? `${namespace}/` : ""}${slug} to ${config.library.path}`,
+                `Source: ${ctx.cwd}`,
+                `Spec: .codecarto/${phase.primary_output}`,
+                `Headline: ${headline}`,
+                `Provenance: Pi / ${ctx.model?.provider ?? "unknown"} / ${ctx.model?.id ?? "unknown"}`,
+            ].join("\n");
+            if (config.library.publish_confirm && !(await ctx.ui.confirm("Publish reimplementation spec", preview)))
+                return;
+            try {
+                const result = await publishEntry(config.library.path, spec, {
+                    slug,
+                    namespace,
+                    source_repo: ctx.cwd,
+                    analyzed_at: new Date().toISOString(),
+                    pipeline: state.status.pipeline,
+                    codecarto_version: PACKAGE_VERSION,
+                    headline,
+                    tags: [],
+                    capabilities: [],
+                    generation: piGeneration(ctx),
+                });
+                lastFeedbackLines = [`Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version}`, result.isNewVersion ? "New content version." : "Metadata-only update (content unchanged)."];
+                await writeDashboard(ctx.cwd, PACKAGE_VERSION);
+                await refreshWorkspaceUi(ctx, lastFeedbackLines);
+                ctx.ui.notify(`Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version}.`, "info");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(`Unable to publish: ${message}`, "error");
+            }
+        },
+    });
     pi.registerCommand("codecarto-usage", {
         description: "Show cumulative + per-phase token usage from local phase runs",
         handler: async (_args, ctx) => {
@@ -426,11 +564,14 @@ export default function codeCartographerExtension(pi) {
             lines.push(`Total runs: ${totals.runs}`);
             lines.push(`Total tokens: ${formatUsageTokens(totals.tokens.input)} in · ${formatUsageTokens(totals.tokens.output)} out · ${formatUsageTokens(totals.tokens.cache_write)} cache-write`);
             lines.push(`Total duration: ${formatUsageDuration(totals.duration_ms)} · ${totals.tool_uses} tool uses`);
+            lines.push(totals.compaction_runs > 0
+                ? `Compactions: ${totals.compactions.successful} successful · ${totals.compactions.failed} failed · ${totals.compactions.aborted} aborted`
+                : "Compactions: unavailable — historical or host usage records did not report compaction events");
             lines.push("");
             lines.push("Per-phase totals:");
             for (const [phaseId, t] of perPhase) {
                 const tokensTotal = t.tokens.input + t.tokens.output;
-                lines.push(`  ${phaseId}: ${t.runs} run${t.runs === 1 ? "" : "s"} · ${formatUsageTokens(tokensTotal)} tokens · ${t.tool_uses} tool uses · ${formatUsageDuration(t.duration_ms)}`);
+                lines.push(`  ${phaseId}: ${t.runs} run${t.runs === 1 ? "" : "s"} · ${formatUsageTokens(tokensTotal)} tokens · ${t.tool_uses} tool uses · ${t.compaction_runs > 0 ? `${t.compactions.successful + t.compactions.failed + t.compactions.aborted} compactions` : "compactions unavailable"} · ${formatUsageDuration(t.duration_ms)}`);
             }
             lastFeedbackLines = lines;
             setUiState(ctx, state, lastFeedbackLines);

package/dist/extensions/codecarto/phase-compaction.d.ts

@@ -0,0 +1,11 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function phaseIdFromSessionName(sessionName: string | undefined): string | null;
+export declare function buildPhaseCompactionInstructions(phaseId: string, primaryOutput?: string): string;
+export declare function writePhaseCheckpoint(cwd: string, phaseId: string, summary: string, tokensBefore: number): Promise<string>;
+/**
+ * Phase-only compaction hooks shared by the parent extension and isolated
+ * child sessions. Keeping this as a standalone inline extension ensures that
+ * children spawned from an explicitly loaded (`pi -e ...`) CodeCartographer
+ * extension receive the same checkpoint behavior as globally installed runs.
+ */
+export declare function phaseCompactionExtension(pi: ExtensionAPI): void;

package/dist/extensions/codecarto/phase-compaction.js

@@ -0,0 +1,115 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { compact } from "@earendil-works/pi-coding-agent";
+import { canonicalPath, getWorkspaceState, isWithinPath } from "../../core/index.js";
+const PHASE_SESSION_PREFIX = "CodeCartographer phase: ";
+export function phaseIdFromSessionName(sessionName) {
+    if (!sessionName?.startsWith(PHASE_SESSION_PREFIX))
+        return null;
+    const phaseId = sessionName.slice(PHASE_SESSION_PREFIX.length).trim();
+    return /^[a-z0-9][a-z0-9-]*$/.test(phaseId) ? phaseId : null;
+}
+export function buildPhaseCompactionInstructions(phaseId, primaryOutput) {
+    const output = primaryOutput ? `.codecarto/${primaryOutput}` : "the phase's declared primary output";
+    return [
+        `This is a CodeCartographer phase session for ${phaseId}.`,
+        `Produce a phase-aware continuation summary for ${output}.`,
+        "Preserve these details explicitly:",
+        "- phase goal and constraints",
+        "- evidence-backed conclusions and their evidence levels",
+        "- files inspected and subsystems covered or skipped",
+        "- primary-output sections already written and sections still missing",
+        "- edits already made under .codecarto/",
+        "- open questions and carry-forward candidates",
+        "- validation criteria already satisfied and validation criteria still at risk",
+        "- exact next steps needed to finish and validate the phase.",
+        "Do not turn an inference into an observed fact. Retain file paths, finding IDs, and unresolved gaps verbatim where possible.",
+    ].join("\n");
+}
+export async function writePhaseCheckpoint(cwd, phaseId, summary, tokensBefore) {
+    const dir = join(cwd, ".codecarto", "scratch", "checkpoints");
+    const target = join(dir, `${phaseId}.md`);
+    const temp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    await mkdir(dir, { recursive: true });
+    const content = [
+        "---",
+        `phase: ${phaseId}`,
+        `updated_at: ${new Date().toISOString()}`,
+        `tokens_before: ${tokensBefore}`,
+        "source: pi-compaction",
+        "---",
+        "",
+        "# Phase checkpoint",
+        "",
+        summary.trim(),
+        "",
+    ].join("\n");
+    await writeFile(temp, content, "utf8");
+    await rename(temp, target);
+    return target;
+}
+/**
+ * Phase-only compaction hooks shared by the parent extension and isolated
+ * child sessions. Keeping this as a standalone inline extension ensures that
+ * children spawned from an explicitly loaded (`pi -e ...`) CodeCartographer
+ * extension receive the same checkpoint behavior as globally installed runs.
+ */
+export function phaseCompactionExtension(pi) {
+    pi.on("tool_call", async (event, ctx) => {
+        if (!phaseIdFromSessionName(ctx.sessionManager.getSessionName()))
+            return undefined;
+        if (event.toolName === "bash") {
+            return { block: true, reason: "CodeCartographer phase sessions disable bash to keep source analysis read-only." };
+        }
+        if (event.toolName === "edit" || event.toolName === "write") {
+            const inputPath = typeof event.input.path === "string" ? event.input.path : "";
+            const strippedPath = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
+            const targetPath = await canonicalPath(resolve(ctx.cwd, strippedPath));
+            const allowedRoot = await canonicalPath(join(ctx.cwd, ".codecarto"));
+            if (!isWithinPath(targetPath, allowedRoot)) {
+                return {
+                    block: true,
+                    reason: `CodeCartographer phase sessions only allow ${event.toolName} within .codecarto/`,
+                };
+            }
+        }
+        return undefined;
+    });
+    pi.on("session_before_compact", async (event, ctx) => {
+        const phaseId = phaseIdFromSessionName(ctx.sessionManager.getSessionName());
+        if (!phaseId || !ctx.model)
+            return undefined;
+        try {
+            const state = await getWorkspaceState(ctx.cwd);
+            const phase = state.pipeline.phases.find((candidate) => candidate.id === phaseId);
+            const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+            if (!auth.ok || !auth.apiKey)
+                return undefined;
+            const instructions = buildPhaseCompactionInstructions(phaseId, phase?.primary_output);
+            const result = await compact(event.preparation, ctx.model, auth.apiKey, auth.headers, instructions, event.signal);
+            return { compaction: result };
+        }
+        catch (error) {
+            if (ctx.hasUI) {
+                const message = error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(`Phase-aware compaction unavailable (${message}); using host default.`, "warning");
+            }
+            return undefined;
+        }
+    });
+    pi.on("session_compact", async (event, ctx) => {
+        const phaseId = phaseIdFromSessionName(ctx.sessionManager.getSessionName());
+        if (!phaseId)
+            return;
+        try {
+            await writePhaseCheckpoint(ctx.cwd, phaseId, event.compactionEntry.summary, event.compactionEntry.tokensBefore);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (ctx.hasUI)
+                ctx.ui.notify(`Phase checkpoint could not be written: ${message}`, "warning");
+            else
+                console.warn(`[codecarto] Phase checkpoint could not be written: ${message}`);
+        }
+    });
+}