codecartographer-pi 0.19.6 → 0.21.0

package/dist/mcp-server/server.js

@@ -17,12 +17,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../core/index.js";
 import { applyAmendment } from "../core/amendment.js";
 import { appendUsageRun } from "../core/usage.js";
 import { initLibrary } from "../core/library.js";
-import { loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
-import { writeDashboard } from "../extensions/codecarto/dashboard-writer.js";
+import { describeConfigProblems, loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
 // ---------- input helpers ----------
 /**
  * Normalize an optional `phase` argument. A client can send any JSON, and
@@ -50,9 +49,32 @@ async function validateCwd(cwd) {
     }
     return cwd;
 }
+/**
+ * The library tools take `cwd` optionally: absent means "no workspace, use
+ * the user-global config alone". When it is given it becomes a containment
+ * root for spec_path and the source of the workspace config that gates the
+ * write, so it is validated exactly as a required cwd is — absolute and
+ * existing — before anything reads through it (#241). A relative path would
+ * resolve against the MCP server process's working directory, not the
+ * caller's, and widen the root to whatever `.codecarto/` sits there.
+ */
+async function optionalCwd(cwd) {
+    if (cwd === undefined || cwd === null)
+        return null;
+    if (typeof cwd !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, "cwd must be a string when given");
+    }
+    if (cwd.trim() === "")
+        return null;
+    return validateCwd(cwd.trim());
+}
 async function requireWorkspace(cwd) {
+    // What getWorkspaceState throws is the user's to fix — a status.yaml that
+    // does not parse, a missing `pipeline:`, a pipeline file that is not there
+    // — so it is InvalidRequest, not the InternalError a host would retry or
+    // report as a server bug (self-audit mech 2.8).
     const state = await getWorkspaceState(cwd).catch((error) => {
-        throw new McpError(ErrorCode.InternalError, error instanceof Error ? error.message : String(error));
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
     });
     if (!state) {
         throw new McpError(ErrorCode.InvalidRequest, `No CodeCartographer workspace at ${cwd}. Call codecarto_init first.`);
@@ -71,9 +93,9 @@ function textResult(text, structured) {
         structuredContent: { ...structured, text },
     };
 }
-async function buildMcpPhasePrompt(state, phase, forced) {
+async function buildMcpPhasePrompt(state, phase, forced, auto = false) {
     try {
-        return await buildPhasePrompt(state, phase, forced);
+        return await buildPhasePrompt(state, phase, forced, { auto });
     }
     catch (error) {
         if (error instanceof PhasePreflightError) {
@@ -109,12 +131,21 @@ export async function handleInit(args) {
         const entries = (await readdir(targetWorkspaceDir)).filter((entry) => entry !== BROADSIDE_DIR);
         broadsideOnly = entries.length === 0 && (await pathExists(join(targetWorkspaceDir, BROADSIDE_DIR)));
     }
-    if (targetExists && !sameWorkspace && !broadsideOnly) {
+    if (targetExists && !broadsideOnly) {
         if (!args.force) {
-            throw new McpError(ErrorCode.InvalidRequest, `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to back it up and reinitialize. Warning: this moves all existing findings, handoffs, usage data, closeouts, and phase progress to a .codecarto-backup-TIMESTAMP/ directory.`);
+            throw new McpError(ErrorCode.InvalidRequest, sameWorkspace
+                ? `The .codecarto/ at ${targetWorkspaceDir} is CodeCartographer's own packaged template (a checkout install), and it holds workspace state. Pass force: true to move that state — status, findings, handoffs, usage data, closeouts, dashboard — to a .codecarto-backup-TIMESTAMP/ directory and reinitialize; the framework files stay in place. Consider codecarto_open to reattach without resetting.`
+                : `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to back it up and reinitialize. Warning: this moves all existing findings, handoffs, usage data, closeouts, and phase progress to a .codecarto-backup-TIMESTAMP/ directory.`);
         }
         const backupDir = join(cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
-        await rename(targetWorkspaceDir, backupDir);
+        if (sameWorkspace) {
+            // The template cannot be renamed away — it is what init copies from —
+            // so its session state is moved out file by file instead (#245).
+            await backupWorkspaceState(targetWorkspaceDir, backupDir);
+        }
+        else {
+            await rename(targetWorkspaceDir, backupDir);
+        }
     }
     if (!(await pathExists(targetWorkspaceDir))) {
         await mkdir(cwd, { recursive: true });
@@ -161,17 +192,21 @@ export async function handleInit(args) {
 export async function handleStatus(args) {
     const cwd = await validateCwd(args.cwd);
     const state = await requireWorkspace(cwd);
-    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;
+    // "complete" is the terminal marker; a stuck pipeline sits on its first
+    // blocked phase and says so below (#228).
+    const currentPhase = outcome.kind === "eligible" ? outcome.phase.id : outcome.kind === "stuck" ? outcome.blocked[0].phaseId : "complete";
     const completed = state.pipeline.phase_order.filter((id) => state.status.phases[id]?.status === "complete").length;
     const totalCarryForward = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.carry_forward?.length ?? 0), 0);
     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 postPipelinePending = state.status.post_pipeline.filter((entry) => entry.status !== "resolved").length;
     const scaffoldNotice = describeScaffoldStaleness(state);
+    const missingOutputs = await listMissingCompletedOutputs(state);
     const summaryLines = [
         `Phase: ${currentPhase}`,
-        `Pipeline state: ${currentPhase === "complete" ? "complete" : "in progress"}`,
+        `Pipeline state: ${outcome.kind === "eligible" ? "in progress" : outcome.kind}`,
         `Pipeline: ${getPipelineLabel(state.status.pipeline)} (${state.status.pipeline})`,
         `Progress: ${completed}/${state.pipeline.phase_order.length} complete`,
         `Open questions (terminal unresolved): ${terminalOpenQuestions}`,
@@ -184,11 +219,17 @@ export async function handleStatus(args) {
             ? state.status.next_actions.map((action, index) => `${index === 0 ? "Next: " : "      "}${action}`)
             : [`Next: ${nextPhase ? `Begin ${nextPhase.id}` : "All phases complete."}`]),
     ];
+    if (outcome.kind === "stuck")
+        summaryLines.push(describeStuckPipeline(outcome.blocked));
     if (scaffoldNotice)
         summaryLines.push(`Scaffold: ${scaffoldNotice}`);
+    summaryLines.push(...describeMissingCompletedOutputs(missingOutputs));
     const summary = summaryLines.join("\n");
     return textResult(summary, {
         ...(scaffoldNotice ? { scaffoldNotice } : {}),
+        ...(missingOutputs.length > 0 ? { missingOutputs } : {}),
+        ...(outcome.kind === "stuck" ? { stuck: outcome.blocked } : {}),
+        pipelineState: outcome.kind === "eligible" ? "in progress" : outcome.kind,
         currentPhase,
         pipeline: state.status.pipeline,
         pipelineLabel: getPipelineLabel(state.status.pipeline),
@@ -212,6 +253,11 @@ export async function handleSwitchPipeline(args) {
         return textResult(`Already on pipeline: ${getPipelineLabel(pipelineChoice)}`, { pipeline: getPipelineLabel(pipelineChoice) });
     }
     const result = await switchPipeline(cwd, pipelineChoice);
+    // The dashboard is rendered from the pipeline the switch just replaced;
+    // Pi re-rendered here and MCP did not, so the file showed the old phase
+    // list until the next completion (#254). Same best-effort call as
+    // completion and amendment make.
+    const dashboardPath = (await writeDashboard(cwd, PACKAGE_VERSION)) ? ".codecarto/dashboard.html" : undefined;
     const lines = [`Switched pipeline: ${getPipelineLabel(pipelineChoice)}`];
     if (result.carried.length > 0)
         lines.push(`Phases preserved (completed): ${result.carried.join(", ")}`);
@@ -219,24 +265,41 @@ export async function handleSwitchPipeline(args) {
         lines.push(`New phases: ${result.newPhases.join(", ")}`);
     if (result.dropped.length > 0)
         lines.push(`Phases not in new pipeline: ${result.dropped.join(", ")} (findings remain on disk)`);
+    lines.push(...describeDanglingCarryForward(result.dangling));
+    lines.push(`Current phase: ${result.state.status.current_phase}`);
+    if (dashboardPath)
+        lines.push(`Dashboard refreshed: ${dashboardPath}`);
     return textResult(lines.join("\n"), {
         pipeline: getPipelineLabel(pipelineChoice),
+        currentPhase: result.state.status.current_phase,
         carried: result.carried,
         newPhases: result.newPhases,
         dropped: result.dropped,
+        dangling: result.dangling,
+        dashboardPath,
     });
 }
 export async function handleNext(args) {
     const cwd = await validateCwd(args.cwd);
     const state = await requireWorkspace(cwd);
-    const phase = getNextEligiblePhase(state);
-    if (!phase) {
+    const outcome = resolvePipelineOutcome(state);
+    if (outcome.kind === "stuck") {
+        // Not a result: a host looping on codecarto_next would read a text
+        // answer as "done" (#228). There is no prompt to hand out until the
+        // pipeline file is fixed.
+        throw new McpError(ErrorCode.InvalidRequest, describeStuckPipeline(outcome.blocked));
+    }
+    if (outcome.kind === "complete") {
         return textResult("All CodeCartographer phases are complete. Run codecarto_skill for post-pipeline work.", {
             complete: true,
         });
     }
-    const prompt = await buildMcpPhasePrompt(state, phase, false);
-    return textResult(prompt, { phase: phase.id, forced: false });
+    // `unattended` is the MCP spelling of Pi's --auto: nobody is there to
+    // answer the reimplementation-spec phase's Strategic Alignment Hook, so
+    // the prompt carries the auto-default instruction instead (#270).
+    const unattended = args.unattended === true;
+    const prompt = await buildMcpPhasePrompt(state, outcome.phase, false, unattended);
+    return textResult(prompt, { phase: outcome.phase.id, forced: false, unattended });
 }
 export async function handlePhase(args) {
     if (typeof args.phase !== "string" || !args.phase.trim()) {
@@ -248,8 +311,9 @@ export async function handlePhase(args) {
     if (!phase) {
         throw new McpError(ErrorCode.InvalidParams, `Unknown phase: ${args.phase}`);
     }
-    const prompt = await buildMcpPhasePrompt(state, phase, true);
-    return textResult(prompt, { phase: phase.id, forced: true });
+    const unattended = args.unattended === true;
+    const prompt = await buildMcpPhasePrompt(state, phase, true, unattended);
+    return textResult(prompt, { phase: phase.id, forced: true, unattended });
 }
 export async function handleValidate(args) {
     const cwd = await validateCwd(args.cwd);
@@ -349,21 +413,27 @@ export async function handleSkill(args) {
         return textResult(skill.content, { skill: BROADSIDE_SKILL_NAME, path: skill.path, postPipeline: false });
     }
     const state = await requireWorkspace(cwd);
-    const nextPhase = getNextEligiblePhase(state);
-    if (nextPhase) {
-        throw new McpError(ErrorCode.InvalidRequest, `Cannot run skill: pipeline is not complete (next phase: ${nextPhase.id}). Finish the pipeline first.`);
+    const outcome = resolvePipelineOutcome(state);
+    if (outcome.kind === "eligible") {
+        throw new McpError(ErrorCode.InvalidRequest, `Cannot run skill: pipeline is not complete (next phase: ${outcome.phase.id}). Finish the pipeline first.`);
     }
-    const skillFile = join(state.workspaceDir, "skills", args.name, "SKILL.md");
-    if (!(await pathExists(skillFile))) {
+    if (outcome.kind === "stuck") {
+        throw new McpError(ErrorCode.InvalidRequest, `Cannot run skill: the pipeline is not complete. ${describeStuckPipeline(outcome.blocked)}`);
+    }
+    // Resolve against the installed list only: the name is never joined onto a
+    // path, so a traversal like `../findings/architecture` cannot splice a
+    // phase SKILL.md (or anything else) into the post-pipeline prompt.
+    const skillName = await resolveSkillName(state.workspaceDir, args.name);
+    if (!skillName) {
         const available = await listSkillNames(state.workspaceDir);
         const hint = available.length > 0 ? ` Available: ${available.join(", ")}.` : " No skills installed.";
-        throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${args.name}.${hint} The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`);
+        throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${args.name.trim()}.${hint} The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`);
     }
-    const prompt = await buildSkillPrompt(state, args.name);
-    return textResult(prompt, { skill: args.name });
+    const prompt = await buildSkillPrompt(state, skillName);
+    return textResult(prompt, { skill: skillName });
 }
 // ---------- library helpers ----------
-async function resolveLibraryPath(args) {
+function resolveLibraryPath(args, config) {
     const explicit = typeof args.library_path === "string" && args.library_path.trim() !== ""
         ? args.library_path.trim()
         : null;
@@ -373,18 +443,8 @@ async function resolveLibraryPath(args) {
         }
         return explicit;
     }
-    if (typeof args.cwd === "string" && args.cwd.trim() !== "") {
-        const cwd = args.cwd.trim();
-        if (!isAbsolute(cwd)) {
-            throw new McpError(ErrorCode.InvalidParams, `cwd must be absolute, got: ${cwd}`);
-        }
-        // loadCodecartoConfig merges user-global under per-workspace and tolerates
-        // a missing workspace file, so a single call covers both cases.
-        const workspaceDir = join(cwd, ".codecarto");
-        const config = await loadCodecartoConfig(workspaceDir);
-        if (config.library.path)
-            return config.library.path;
-    }
+    if (config.library.path)
+        return config.library.path;
     throw new McpError(ErrorCode.InvalidParams, "library_path is required (pass it explicitly, or pass cwd and configure library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml).");
 }
 /**
@@ -394,17 +454,22 @@ async function resolveLibraryPath(args) {
  * the publish tool enforces.
  */
 async function loadEffectiveConfig(cwd) {
-    if (typeof cwd !== "string" || cwd.trim() === "")
+    // This config decides whether publish_confirm gates the write, so the cwd
+    // it is read through is the one optionalCwd validated, never a raw argument.
+    if (!cwd)
         return loadUserConfig();
-    // A relative path here resolves against the server process's working
-    // directory, not the caller's, so it would quietly read some other
-    // workspace's config — and this config decides whether publish_confirm
-    // gates the write. Refuse rather than answer from the wrong file.
-    const trimmed = cwd.trim();
-    if (!isAbsolute(trimmed)) {
-        throw new McpError(ErrorCode.InvalidParams, `cwd must be an absolute path, got: ${trimmed}`);
-    }
-    return loadCodecartoConfig(join(trimmed, ".codecarto"));
+    return loadCodecartoConfig(join(cwd, ".codecarto"));
+}
+/**
+ * The library tools answer from the config — its path, its namespace, its
+ * confirm gate — so a config file that could not be used in full is a
+ * refusal, not a silent fallback to whatever the other layer says (#242).
+ * The message names each file and key; codecarto_config shows the same list.
+ */
+function refuseOnConfigProblems(config, tool) {
+    if (config.problems.length === 0)
+        return;
+    throw new McpError(ErrorCode.InvalidRequest, [`${tool} refused: the configuration has problems. Fix or remove the offending file, then retry.`, ...describeConfigProblems(config)].join("\n"));
 }
 function asStringArray(value, fieldName) {
     if (!Array.isArray(value)) {
@@ -491,12 +556,12 @@ async function resolveDefaultsFromWorkspace(cwd, overrides) {
     let namespace = typeof overrides.namespace === "string" && overrides.namespace.trim() !== ""
         ? overrides.namespace.trim()
         : null;
-    if (typeof cwd === "string" && cwd.trim() !== "" && isAbsolute(cwd)) {
-        const workspaceDir = join(cwd.trim(), ".codecarto");
+    if (cwd) {
+        const workspaceDir = join(cwd, ".codecarto");
         if (await pathExists(workspaceDir)) {
             if (pipeline === "unknown") {
                 try {
-                    const state = await getWorkspaceState(cwd.trim());
+                    const state = await getWorkspaceState(cwd);
                     if (state?.status.pipeline)
                         pipeline = state.status.pipeline;
                 }
@@ -542,16 +607,20 @@ function provenanceConflictLines(conflicts) {
 }
 // ---------- library handlers ----------
 export async function handlePublish(args) {
-    const libraryPath = await resolveLibraryPath(args);
+    // First, before anything is read through it: cwd is a containment root
+    // for spec_path below and the source of the config that gates the write.
+    const cwd = await optionalCwd(args.cwd);
+    const config = await loadEffectiveConfig(cwd);
+    refuseOnConfigProblems(config, "codecarto_publish");
+    const libraryPath = resolveLibraryPath(args, config);
     const marker = await discoverLibrary(libraryPath);
     if (!marker) {
         throw new McpError(ErrorCode.InvalidParams, `No CodeCartographer library at ${libraryPath} (missing .codecarto-library marker). Create one before publishing.`);
     }
     // Build allowed roots for spec_path containment: workspace .codecarto/ and library path
     const allowedRoots = [libraryPath];
-    if (typeof args.cwd === "string" && args.cwd.trim() !== "") {
-        allowedRoots.push(join(args.cwd.trim(), ".codecarto"));
-    }
+    if (cwd)
+        allowedRoots.push(join(cwd, ".codecarto"));
     const spec = await readSpecArg(args, allowedRoots);
     if (typeof args.source_repo !== "string" || args.source_repo.trim() === "") {
         throw new McpError(ErrorCode.InvalidParams, "source_repo is required");
@@ -567,7 +636,7 @@ export async function handlePublish(args) {
     if (!isValidSlug(slug)) {
         throw new McpError(ErrorCode.InvalidParams, `Resolved slug "${slug}" is invalid. Provide an explicit slug (lowercase ASCII, starts with a letter, max 64 chars).`);
     }
-    const defaults = await resolveDefaultsFromWorkspace(args.cwd, {
+    const defaults = await resolveDefaultsFromWorkspace(cwd, {
         pipeline: args.pipeline,
         namespace: args.namespace,
     });
@@ -596,7 +665,6 @@ export async function handlePublish(args) {
     // opt-out, and a host that never configured the key keeps the behavior it
     // had. Runs after every argument check so the preview names the resolved
     // slug and namespace, and before publishEntry so nothing is written.
-    const config = await loadEffectiveConfig(args.cwd);
     if (config.library.publish_confirm && config.library.publish_confirm_configured && args.confirm !== true) {
         const preview = await previewPublishVersion(libraryPath, spec, { slug, namespace }, { forceNewVersion });
         const label = `${namespace ? `${namespace}/` : ""}${slug}`;
@@ -665,7 +733,9 @@ export async function handlePublish(args) {
     });
 }
 export async function handleLibraryList(args) {
-    const libraryPath = await resolveLibraryPath(args);
+    const config = await loadEffectiveConfig(await optionalCwd(args.cwd));
+    refuseOnConfigProblems(config, "codecarto_library_list");
+    const libraryPath = resolveLibraryPath(args, config);
     const marker = await discoverLibrary(libraryPath);
     if (!marker) {
         throw new McpError(ErrorCode.InvalidParams, `No CodeCartographer library at ${libraryPath} (missing .codecarto-library marker).`);
@@ -706,7 +776,9 @@ export async function handleLibraryList(args) {
     });
 }
 export async function handleLibraryReindex(args) {
-    const libraryPath = await resolveLibraryPath(args);
+    const config = await loadEffectiveConfig(await optionalCwd(args.cwd));
+    refuseOnConfigProblems(config, "codecarto_library_reindex");
+    const libraryPath = resolveLibraryPath(args, config);
     const marker = await discoverLibrary(libraryPath);
     if (!marker) {
         throw new McpError(ErrorCode.InvalidParams, `No CodeCartographer library at ${libraryPath} (missing .codecarto-library marker).`);
@@ -742,10 +814,17 @@ export async function handleLibraryInit(args) {
     });
     // Write config to user-global location
     const configPath = resolveUserConfigPath();
-    await writeLibraryConfig(configPath, libraryPath, args.namespace ?? null);
+    // Writes library.path (and library.namespace when given) and nothing else:
+    // in particular it does not set publish_confirm, so initializing a library
+    // does not switch the codecarto_publish confirm gate on (#244). A config
+    // file that cannot be parsed is left alone and reported.
+    await writeLibraryConfig(configPath, libraryPath, args.namespace ?? null).catch((error) => {
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+    });
+    const written = args.namespace ? "library.path and library.namespace" : "library.path";
     const msg = result.alreadyExisted
-        ? `Library already exists at ${libraryPath} (marker preserved). Config written to ${configPath}.`
-        : `Created library at ${libraryPath} with marker "${result.marker.name}". Config written to ${configPath}.`;
+        ? `Library already exists at ${libraryPath} (marker preserved). Wrote ${written} to ${configPath}; other keys untouched.`
+        : `Created library at ${libraryPath} with marker "${result.marker.name}". Wrote ${written} to ${configPath}; other keys untouched.`;
     return textResult(msg, {
         libraryPath,
         markerName: result.marker.name,
@@ -808,6 +887,9 @@ export async function handleConfig(args) {
         `  Library marker: ${markerStatus}`,
         `  User-global config: ${userConfigPath}`,
         `  Workspace config: ${workspaceConfigPath ?? "(no cwd provided)"}`,
+        // A file that could not be used is the one thing this tool exists
+        // to surface; the library tools refuse while any is listed (#242).
+        ...describeConfigProblems(config),
     ].join("\n"), {
         libraryPath: config.library.path,
         libraryNamespace: config.library.namespace,
@@ -815,6 +897,7 @@ export async function handleConfig(args) {
         llmSteerNextPhase: config.orchestrator.llm_steer_next_phase,
         userConfigPath,
         workspaceConfigPath,
+        problems: config.problems,
     });
 }
 // ---------- MCP parity handlers: open, usage, dashboard, list_skills ----------
@@ -825,8 +908,16 @@ export async function handleOpen(args) {
         throw new McpError(ErrorCode.InvalidRequest, "No existing CodeCartographer workspace found. Run codecarto_init first.");
     }
     const state = await requireWorkspace(cwd);
-    const nextPhase = getNextEligiblePhase(state)?.id ?? "complete";
-    return textResult(`Opened existing CodeCartographer workspace: ${getPipelineLabel(state.status.pipeline)}. Current phase: ${nextPhase}.`, { pipeline: getPipelineLabel(state.status.pipeline), currentPhase: nextPhase });
+    const outcome = resolvePipelineOutcome(state);
+    const nextPhase = outcome.kind === "eligible" ? outcome.phase.id : outcome.kind === "stuck" ? `${outcome.blocked[0].phaseId} (stuck)` : "complete";
+    const lines = [`Opened existing CodeCartographer workspace: ${getPipelineLabel(state.status.pipeline)}. Current phase: ${nextPhase}.`];
+    if (outcome.kind === "stuck")
+        lines.push(describeStuckPipeline(outcome.blocked));
+    return textResult(lines.join("\n"), {
+        pipeline: getPipelineLabel(state.status.pipeline),
+        currentPhase: nextPhase,
+        ...(outcome.kind === "stuck" ? { stuck: outcome.blocked } : {}),
+    });
 }
 export async function handleUsage(args) {
     const cwd = await validateCwd(args.cwd);
@@ -949,18 +1040,40 @@ export async function handleBroadside(args) {
     if (!["submit", "collect", "status", "models"].includes(action)) {
         throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${action}. Valid actions: submit, collect, status, models.`);
     }
-    const config = await loadBroadsideConfig(broadsideDirFor(cwd));
+    // 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. A corrupt state.json refuses even that:
+    // there is nothing trustworthy to report and nothing may write over it (#233).
+    let config;
+    let configWarning = null;
+    try {
+        config = await loadBroadsideConfig(broadsideDirFor(cwd));
+    }
+    catch (error) {
+        if (!(error instanceof BroadsideConfigError) || action !== "status") {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        }
+        config = defaultBroadsideConfig();
+        configWarning = error.message;
+    }
     if (action === "status") {
-        const { state } = await runBroadsideStatus(cwd);
-        return textResult(statusText(state), { state });
+        const { state } = await runBroadsideStatus(cwd).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        const lines = [statusText(state)];
+        if (configWarning)
+            lines.push(`Warning: ${configWarning}`);
+        return textResult(lines.join("\n"), { state, ...(configWarning ? { configWarning } : {}) });
     }
     const apiKey = resolveBroadsideApiKey(args.api_key, config);
     // Every run knob resolves the same way: explicit parameter, else the repo's
     // config.yaml default, else the shipped default baked into loadBroadsideConfig.
-    const waitSeconds = typeof args.wait_seconds === "number" && args.wait_seconds > 0
+    // An explicit 0 means "poll once and return": it used to fall through to
+    // the config default and, as undefined, to the 25-minute budget (#230).
+    const waitSeconds = typeof args.wait_seconds === "number" && args.wait_seconds >= 0
         ? args.wait_seconds
         : config.waitSeconds;
-    const waitMs = waitSeconds > 0 ? waitSeconds * 1000 : undefined;
+    const waitMs = waitSeconds * 1000;
     const includeSynthesis = args.include_synthesis ?? config.includeSynthesis;
     const includeTriage = args.include_triage ?? config.includeTriage;
     const retryTruncated = args.retry_truncated ?? config.retryTruncated;
@@ -989,7 +1102,9 @@ export async function handleBroadside(args) {
         else {
             lenses = config.defaultLenses;
         }
-        const maxCost = typeof args.max_cost === "number" && args.max_cost > 0 ? args.max_cost : config.maxCost;
+        // An explicit 0 is "no limit" (#231); absent falls back to config.yaml,
+        // whose own default is BROADSIDE_DEFAULT_MAX_COST.
+        const maxCost = typeof args.max_cost === "number" && args.max_cost >= 0 ? args.max_cost : config.maxCost;
         const result = await runBroadsideSubmit(cwd, apiKey, {
             lenses,
             model: config.model,
@@ -1026,11 +1141,13 @@ export async function handleBroadside(args) {
         });
     }
     // action === "collect"
+    const runId = typeof args.run_id === "string" && args.run_id.trim() ? args.run_id.trim() : undefined;
     const collect = await runBroadsideCollect(cwd, apiKey, {
         waitMs,
         includeSynthesis,
         includeTriage,
         retryTruncated,
+        ...(runId && { runId }),
     }).catch((error) => {
         throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
     });
@@ -1098,7 +1215,13 @@ const TOOLS = [
         description: "Return the prompt text for the next eligible CodeCartographer phase. The host should feed this prompt back to the agent or display it to the user.",
         inputSchema: {
             type: "object",
-            properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
+            properties: {
+                cwd: { type: "string", description: "Absolute path to the target repository." },
+                unattended: {
+                    type: "boolean",
+                    description: "Set when no user is in the loop to answer the prompt's questions (an autonomous run). The reimplementation-spec prompt then defaults to the language-agnostic variant and records selection: auto-default instead of asking which variant to build, and every interactive hook is suppressed. Same as Pi's /codecarto-next --auto.",
+                },
+            },
             required: ["cwd"],
         },
     },
@@ -1110,13 +1233,14 @@ const TOOLS = [
             properties: {
                 cwd: { type: "string", description: "Absolute path to the target repository." },
                 phase: { type: "string", description: "Phase id from the active pipeline." },
+                unattended: { type: "boolean", description: "As for codecarto_next: no user is in the loop, so interactive hooks default and record their choice instead of asking." },
             },
             required: ["cwd", "phase"],
         },
     },
     {
         name: "codecarto_validate",
-        description: "Validate a phase's primary output against the validation block in the produced markdown. Returns overall PASS/PASS WITH GAPS/FAIL/MISSING plus the parsed criteria rows. If phase is omitted, validates the next eligible phase.",
+        description: "Read the ## Validation table a phase wrote at the end of its primary output — the phase's own PASS/PARTIAL/FAIL per completion criterion — apply two cross-checks (findings evidence/action pairing; declared secondary outputs present), and return PASS/PASS WITH GAPS/FAIL/MISSING plus the parsed rows. It does not judge the criteria itself. If phase is omitted, validates the next eligible phase.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1128,7 +1252,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_complete",
-        description: "Mark a phase complete. Requires the phase output's validation to be PASS or PASS WITH GAPS. Atomically updates status.yaml under a file lock, appends to THREAD_LOG.md, and creates a closeout stub from the template if one does not yet exist. If phase is omitted, completes the next eligible phase.",
+        description: "Mark a phase complete. Requires the phase output's validation to be PASS or PASS WITH GAPS and applies the phase handoff at scratch/handoffs/<phase>.yaml. Atomically updates status.yaml under a file lock, appends one THREAD_LOG.md entry, and writes the phase's closeout: the handoff's closeout_content (plus its decisions) overwrites the canonical <date>-<phase>.md when supplied; otherwise a stub is copied from the template only if no closeout exists yet. If phase is omitted, completes the next eligible phase.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1354,11 +1478,15 @@ const TOOLS = [
                 },
                 api_key: {
                     type: "string",
-                    description: "OpenRouter API key. Prefer the OPENROUTER_API_KEY environment variable or .codecarto/broadside/config.yaml.",
+                    description: "OpenRouter API key. A value passed here is recorded wherever the host logs tool calls; prefer the OPENROUTER_API_KEY environment variable of the server process. (api_key in .codecarto/broadside/config.yaml also works, but that file is tracked, so a key there is committed with it.)",
+                },
+                run_id: {
+                    type: "string",
+                    description: "For collect: the run to collect, as listed by the status action. Defaults to the most recent run; pass this to collect an older run that is still in flight after a newer submit.",
                 },
                 wait_seconds: {
                     type: "number",
-                    description: "For submit: after submitting, poll up to this many seconds before returning. For collect: poll up to this many seconds before returning with partial state. Falls back to wait_seconds in .codecarto/broadside/config.yaml.",
+                    description: "For submit: after submitting, poll up to this many seconds before returning. For collect: poll up to this many seconds before returning with partial state. 0 polls each in-flight batch once and returns without waiting. Falls back to wait_seconds in .codecarto/broadside/config.yaml (default 0).",
                 },
                 include_synthesis: {
                     type: "boolean",
@@ -1374,7 +1502,7 @@ const TOOLS = [
                 },
                 max_cost: {
                     type: "number",
-                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. Falls back to max_cost in .codecarto/broadside/config.yaml.",
+                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. Falls back to max_cost in .codecarto/broadside/config.yaml, whose default is $1.00; pass 0 for no limit.",
                 },
                 force: {
                     type: "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.19.6",
+  "version": "0.21.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",
@@ -76,6 +76,7 @@
     "typescript": "^5.9.3"
   },
   "overrides": {
-    "undici": "^8.10.0"
+    "undici": "^8.10.0",
+    "hono": "^4.13.5"
   }
 }