codecartographer-pi 0.20.0 → 0.22.0

package/dist/extensions/codecarto/index.js

@@ -1,5 +1,4 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
 import { disposeAgentsWidget } from "./agent-widget.js";
@@ -10,7 +9,7 @@ import { parseNextFlags } from "./next-flags.js";
 import { buildPiGuideMessage } from "./guide-framing.js";
 import { isCtxLive, notifyCtx } from "./notify.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, describeDanglingCarryForward, describeMissingCompletedOutputs, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, resolveExistingPrefix, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listMissingCompletedOutputs, listSkillNames, resolveSkillName, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, describeConfigProblems, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../../core/index.js";
+import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, expandTilde, getPipelineLabel, getWorkspaceState, isWithinPath, resolveExistingPrefix, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, describeConfigProblems, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
@@ -56,9 +55,23 @@ function formatUsageDuration(ms) {
     const seconds = Math.floor((ms % 60_000) / 1000);
     return `${minutes}m${seconds.toString().padStart(2, "0")}s`;
 }
+/**
+ * The phase the status line and session name show: the eligible phase, the
+ * first blocked phase when the pipeline is stuck, or "complete" — never
+ * "complete" for a pipeline that cannot finish (#228).
+ */
+function currentPhaseLabel(state) {
+    const outcome = resolvePipelineOutcome(state);
+    if (outcome.kind === "eligible")
+        return outcome.phase.id;
+    if (outcome.kind === "stuck")
+        return outcome.blocked[0]?.phaseId ?? "stuck";
+    return "complete";
+}
 function buildStatusLines(state, extraLines = []) {
-    const nextPhase = getNextEligiblePhase(state);
-    const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "complete";
+    const outcome = resolvePipelineOutcome(state);
+    const nextPhase = outcome.kind === "eligible" ? outcome.phase : null;
+    const currentPhase = currentPhaseLabel(state);
     const pipelineLabel = getPipelineLabel(state.status.pipeline);
     const completedCount = state.pipeline.phase_order.filter((phaseId) => state.status.phases[phaseId]?.status === "complete").length;
     const terminalOpenQuestions = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
@@ -68,7 +81,7 @@ function buildStatusLines(state, extraLines = []) {
     const lines = [
         "CodeCartographer",
         `Phase: ${currentPhase}`,
-        `Pipeline state: ${currentPhase === "complete" ? "complete" : "in progress"}`,
+        `Pipeline state: ${outcome.kind === "eligible" ? "in progress" : outcome.kind}`,
         `Pipeline: ${pipelineLabel}`,
         `Progress: ${completedCount}/${state.pipeline.phase_order.length} complete`,
         `Open questions (terminal unresolved): ${terminalOpenQuestions}`,
@@ -76,6 +89,8 @@ function buildStatusLines(state, extraLines = []) {
         `Post-pipeline work: ${postPipelinePending} pending`,
         `Next: ${nextAction}`,
     ];
+    if (outcome.kind === "stuck")
+        lines.push(describeStuckPipeline(outcome.blocked));
     const scaffoldNotice = describeScaffoldStaleness(state);
     if (scaffoldNotice)
         lines.push(`Scaffold: ${scaffoldNotice}`);
@@ -93,7 +108,7 @@ function setUiState(ctx, state, extraLines = []) {
         return;
     }
     const theme = ctx.ui.theme;
-    const currentPhase = getNextEligiblePhase(state)?.id ?? state.status.current_phase ?? "complete";
+    const currentPhase = currentPhaseLabel(state);
     ctx.ui.setStatus(STATUS_LINE_ID, `${theme.fg("accent", "CC")} ${theme.fg("dim", currentPhase)}`);
     ctx.ui.setWidget(STATUS_WIDGET_ID, buildStatusLines(state, extraLines));
 }
@@ -291,7 +306,7 @@ export default function codeCartographerExtension(pi) {
         const state = await readWorkspaceState(ctx, false);
         setUiState(ctx, state, extraLines ?? lastFeedbackLines);
         if (state) {
-            const phaseId = getNextEligiblePhase(state)?.id ?? state.status.current_phase;
+            const phaseId = currentPhaseLabel(state);
             if (phaseId)
                 pi.setSessionName(`CodeCartographer: ${phaseId}`);
         }
@@ -498,13 +513,17 @@ export default function codeCartographerExtension(pi) {
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
-            const nextPhase = getNextEligiblePhase(state)?.id ?? "complete";
+            const outcome = resolvePipelineOutcome(state);
+            const nextPhase = currentPhaseLabel(state);
             // Same check codecarto_status makes: a phase complete in status.yaml
             // whose report is not on disk (#259).
             const missingOutputs = describeMissingCompletedOutputs(await listMissingCompletedOutputs(state));
             lastFeedbackLines = [`Current phase: ${nextPhase}`, `Pipeline: ${getPipelineLabel(state.status.pipeline)}`, ...missingOutputs];
             setUiState(ctx, state, lastFeedbackLines);
-            if (missingOutputs.length > 0) {
+            if (outcome.kind === "stuck") {
+                notifyCtx(ctx, `CodeCartographer phase: ${nextPhase}. ${describeStuckPipeline(outcome.blocked)}`, "error");
+            }
+            else if (missingOutputs.length > 0) {
                 notifyCtx(ctx, `CodeCartographer phase: ${nextPhase}. ${missingOutputs[0]}`, "warning");
             }
             else {
@@ -608,7 +627,7 @@ export default function codeCartographerExtension(pi) {
                         // the readout tracks progress live instead of staying frozen
                         // at the initial phase until the whole auto run finishes.
                         setUiState(ctx, advancedState, [`Auto pipeline${flags.strict ? " (strict)" : ""} running…`]);
-                        const phaseId = getNextEligiblePhase(advancedState)?.id ?? advancedState.status.current_phase;
+                        const phaseId = currentPhaseLabel(advancedState);
                         if (phaseId)
                             pi.setSessionName(`CodeCartographer: ${phaseId}`);
                     },
@@ -624,13 +643,21 @@ export default function codeCartographerExtension(pi) {
                 notifyCtx(ctx, `Auto pipeline ${result.outcome}: ${result.phasesRun.length}/${result.totalPhases} phases.`, result.outcome === "complete" ? "info" : "warning");
                 return;
             }
-            const phase = getNextEligiblePhase(state);
-            if (!phase) {
+            const outcome = resolvePipelineOutcome(state);
+            if (outcome.kind === "stuck") {
+                const message = describeStuckPipeline(outcome.blocked);
+                lastFeedbackLines = [message];
+                setUiState(ctx, state, lastFeedbackLines);
+                notifyCtx(ctx, message, "error");
+                return;
+            }
+            if (outcome.kind === "complete") {
                 lastFeedbackLines = ["All phases complete."];
                 setUiState(ctx, state, lastFeedbackLines);
                 notifyCtx(ctx, "All CodeCartographer phases are complete.", "info");
                 return;
             }
+            const phase = outcome.phase;
             let preflight;
             try {
                 preflight = await runPhasePreflight(state, phase);
@@ -868,9 +895,13 @@ export default function codeCartographerExtension(pi) {
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
-            const nextPhase = getNextEligiblePhase(state);
-            if (nextPhase) {
-                notifyCtx(ctx, `Cannot run skill: pipeline is not complete (next phase: ${nextPhase.id}). Finish the pipeline before running post-pipeline skills.`, "error");
+            const outcome = resolvePipelineOutcome(state);
+            if (outcome.kind === "eligible") {
+                notifyCtx(ctx, `Cannot run skill: pipeline is not complete (next phase: ${outcome.phase.id}). Finish the pipeline before running post-pipeline skills.`, "error");
+                return;
+            }
+            if (outcome.kind === "stuck") {
+                notifyCtx(ctx, `Cannot run skill: the pipeline is not complete. ${describeStuckPipeline(outcome.blocked)}`, "error");
                 return;
             }
             // Resolve against the installed list only: the name is never joined
@@ -908,11 +939,13 @@ export default function codeCartographerExtension(pi) {
             const lines = skills.length > 0
                 ? [`Available skills (${skills.length}):`, ...skills.map((name) => `  - ${name}`)]
                 : ["No skills installed."];
-            const nextPhase = getNextEligiblePhase(state);
+            const outcome = resolvePipelineOutcome(state);
             if (skills.length > 0) {
-                lines.push(nextPhase
-                    ? `Post-pipeline skills unlock when the pipeline completes (next phase: ${nextPhase.id}).`
-                    : "Run one with /codecarto-skill <name>.");
+                lines.push(outcome.kind === "eligible"
+                    ? `Post-pipeline skills unlock when the pipeline completes (next phase: ${outcome.phase.id}).`
+                    : outcome.kind === "stuck"
+                        ? `Post-pipeline skills unlock when the pipeline completes, and it cannot: ${describeStuckPipeline(outcome.blocked)}`
+                        : "Run one with /codecarto-skill <name>.");
             }
             // Broad-Side is listed apart from the post-pipeline set because it
             // answers to /codecarto-skill without the completion gate.
@@ -967,7 +1000,7 @@ export default function codeCartographerExtension(pi) {
         },
     });
     pi.registerCommand("codecarto-broadside", {
-        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [flags]",
+        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [--model=ID] [--lens-model=LENS:ID] [flags]",
         getArgumentCompletions: (prefix) => {
             const items = KNOWN_BROADSIDE_TOKENS
                 .filter((value) => value.startsWith(prefix))
@@ -988,7 +1021,23 @@ export default function codeCartographerExtension(pi) {
             // Broad-Side runs on any git repository, with or without a workspace —
             // so this command never goes through ensureWorkspaceState.
             const broadsideDir = broadsideDirFor(ctx.cwd);
-            const config = await loadBroadsideConfig(broadsideDir);
+            // A config.yaml that exists but cannot be read refuses every action
+            // that would act on it (#232); status only reads recorded runs, so it
+            // answers and says the file is unreadable.
+            let config;
+            let configWarning = null;
+            try {
+                config = await loadBroadsideConfig(broadsideDir);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (!(error instanceof BroadsideConfigError) || flags.action !== "status") {
+                    notifyCtx(ctx, `Broad-Side ${flags.action} refused: ${message}`, "error");
+                    return;
+                }
+                config = defaultBroadsideConfig();
+                configWarning = message;
+            }
             const finish = (lines, notice, level = "info") => {
                 lastFeedbackLines = lines;
                 if (codecartoModeActive) {
@@ -1005,9 +1054,18 @@ export default function codeCartographerExtension(pi) {
                 notifyCtx(ctx, notice, level);
             };
             if (flags.action === "status") {
-                const { state } = await runBroadsideStatus(ctx.cwd);
+                let state;
+                try {
+                    ({ state } = await runBroadsideStatus(ctx.cwd));
+                }
+                catch (error) {
+                    // A corrupt state.json: nothing trustworthy to report, and the
+                    // error names the preserved copy (#233).
+                    notifyCtx(ctx, `Broad-Side status failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                    return;
+                }
                 const runs = state.runs.length;
-                finish(statusText(state).split("\n"), runs > 0 ? `Broad-Side: ${runs} recorded run${runs === 1 ? "" : "s"}` : "Broad-Side: no runs recorded yet");
+                finish([...statusText(state).split("\n"), ...(configWarning ? [`Warning: ${configWarning}`] : [])], runs > 0 ? `Broad-Side: ${runs} recorded run${runs === 1 ? "" : "s"}` : "Broad-Side: no runs recorded yet", configWarning ? "warning" : "info");
                 return;
             }
             const apiKey = resolveBroadsideKey(config.apiKey);
@@ -1019,10 +1077,10 @@ export default function codeCartographerExtension(pi) {
             if (flags.action === "models") {
                 notifyCtx(ctx, "Fetching the OpenRouter batch-model catalog…", "info");
                 try {
-                    const { entries, benchmarks } = await listBatchModels(broadsideDir, config, apiKey, {
+                    const { entries, benchmarks, endpoints } = await listBatchModels(broadsideDir, config, apiKey, {
                         includeBenchmarks: flags.benchmarks,
                     });
-                    finish(modelsText(entries, { benchmarks, defaultModel: config.model }).split("\n"), `Broad-Side: ${entries.length} batch model${entries.length === 1 ? "" : "s"} listed`);
+                    finish(modelsText(entries, { benchmarks, defaultModel: config.model, endpoints }).split("\n"), `Broad-Side: ${entries.length} batch model${entries.length === 1 ? "" : "s"} listed`);
                 }
                 catch (error) {
                     notifyCtx(ctx, `Model catalog lookup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -1045,8 +1103,10 @@ export default function codeCartographerExtension(pi) {
                 progress.set(lensId, `${status} (${counts.completed ?? 0}/${counts.total ?? "?"})`);
                 renderProgress("Polling batches…");
             };
+            // An explicit --wait=0 polls once and returns; it used to become
+            // undefined and, in core, the 25-minute budget (#230).
             const waitSeconds = flags.waitSeconds ?? config.waitSeconds;
-            const waitMs = waitSeconds > 0 ? waitSeconds * 1000 : undefined;
+            const waitMs = waitSeconds * 1000;
             const includeSynthesis = flags.includeSynthesis ?? config.includeSynthesis;
             const includeTriage = flags.includeTriage ?? config.includeTriage;
             const retryTruncated = flags.retryTruncated ?? config.retryTruncated;
@@ -1057,7 +1117,11 @@ export default function codeCartographerExtension(pi) {
                 try {
                     submit = await runBroadsideSubmit(ctx.cwd, apiKey, {
                         lenses,
-                        model: config.model,
+                        // --model= and --lens-model= select for this run; the file's
+                        // values are the fallback, and core pre-flights either the
+                        // same way (#141).
+                        model: flags.model ?? config.model,
+                        lensModels: flags.lensModels,
                         maxCost: flags.maxCost ?? config.maxCost,
                         // `??`, not `||`: --no-incremental parses to false and must beat a
                         // config-set true, exactly as MCP's `incremental: false` does (#163).
@@ -1113,6 +1177,7 @@ export default function codeCartographerExtension(pi) {
                     includeTriage,
                     retryTruncated,
                     onStatus,
+                    ...(flags.runId && { runId: flags.runId }),
                 });
                 const lines = collectResultText(collect).split("\n");
                 const done = collect.status === "completed";
@@ -1255,12 +1320,11 @@ export default function codeCartographerExtension(pi) {
                 notifyCtx(ctx, "Usage: /codecarto-library-init <path> [--namespace <name>]", "warning");
                 return;
             }
-            const libraryPath = pathArg.startsWith("~") ? join(homedir(), pathArg.slice(1)) : resolve(pathArg);
+            // The same expansion the config loader applies, so `~user/x` and a
+            // bare `~` mean the same thing everywhere (self-audit mech 6.14).
+            const libraryPath = resolve(expandTilde(pathArg));
             try {
-                const result = await initLibrary(libraryPath, {
-                    namespaced: !!namespace,
-                    ...(namespace ? {} : {}),
-                });
+                const result = await initLibrary(libraryPath, { namespaced: !!namespace });
                 // Write library.path (and library.namespace when given) to the
                 // user-global config and nothing else — not publish_confirm, so
                 // initializing a library does not change how publish behaves on
@@ -1459,9 +1523,13 @@ export default function codeCartographerExtension(pi) {
                 notifyCtx(ctx, error instanceof Error ? error.message : String(error), "error");
                 return;
             }
-            const nextPhase = getNextEligiblePhase(state);
-            if (nextPhase) {
-                notifyCtx(ctx, `Cannot amend: the pipeline is not complete (next phase: ${nextPhase.id}). `
+            const outcome = resolvePipelineOutcome(state);
+            if (outcome.kind === "stuck") {
+                notifyCtx(ctx, `Cannot amend: the pipeline is not complete. ${describeStuckPipeline(outcome.blocked)}`, "error");
+                return;
+            }
+            if (outcome.kind === "eligible") {
+                notifyCtx(ctx, `Cannot amend: the pipeline is not complete (next phase: ${outcome.phase.id}). `
                     + "Resolve open questions and routed items through that phase's handoff (open_question_closures / carry_forward_closures) instead.", "error");
                 return;
             }

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

@@ -7,7 +7,11 @@ 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;
+    // The same alphabet assertSafePhaseId admits (core/status.ts). A narrower
+    // match here silently dropped the bash block, write confinement, and
+    // checkpointing for a custom pipeline whose ids used `.`, `_`, or a capital
+    // (self-audit mech 6.11).
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(phaseId) ? phaseId : null;
 }
 export function buildPhaseCompactionInstructions(phaseId, primaryOutput) {
     const output = primaryOutput ? `.codecarto/${primaryOutput}` : "the phase's declared primary output";

package/dist/mcp-server/server.d.ts

@@ -37,6 +37,7 @@ export declare function handleSwitchPipeline(args: {
 }>;
 export declare function handleNext(args: {
     cwd: string;
+    unattended?: boolean;
 }): Promise<{
     content: {
         type: "text";
@@ -49,6 +50,7 @@ export declare function handleNext(args: {
 export declare function handlePhase(args: {
     cwd: string;
     phase: string;
+    unattended?: boolean;
 }): Promise<{
     content: {
         type: "text";
@@ -130,7 +132,6 @@ export declare function handleLibraryInit(args: {
     library_path: string;
     name?: string;
     namespace?: string;
-    cwd?: string;
 }): Promise<{
     content: {
         type: "text";
@@ -236,6 +237,7 @@ export declare function handleBroadside(args: {
     lenses?: string[];
     api_key?: string;
     wait_seconds?: number;
+    run_id?: string;
     include_synthesis?: boolean;
     include_triage?: boolean;
     retry_truncated?: boolean;
@@ -243,6 +245,8 @@ export declare function handleBroadside(args: {
     force?: boolean;
     include_benchmarks?: boolean;
     incremental?: boolean;
+    model?: string;
+    lens_models?: Record<string, string>;
 }): Promise<{
     content: {
         type: "text";