codecartographer-pi 0.19.0 → 0.19.2

package/dist/core/yaml.js

@@ -126,6 +126,19 @@ export function parseSimpleYaml(raw) {
     };
     const parseMapping = (indent) => {
         const result = {};
+        // Duplicate detection tracks keys explicitly rather than testing
+        // `key in result`. A bare object inherits from Object.prototype, so
+        // `"constructor" in result` is already true before anything is parsed —
+        // a document whose key is `constructor`, `toString`, `valueOf` or any
+        // other prototype member was rejected as a duplicate on first sight.
+        const seen = new Set();
+        // Assignment goes through defineProperty for the same reason: plain
+        // `result[key] = value` with the key `__proto__` invokes the prototype
+        // setter instead of creating an entry, so a hand-edited YAML file could
+        // change the shape of every object in the process rather than parse.
+        const assign = (key, value) => {
+            Object.defineProperty(result, key, { value, writable: true, enumerable: true, configurable: true });
+        };
         while (index < lines.length) {
             skipBlank();
             if (index >= lines.length)
@@ -147,9 +160,10 @@ export function parseSimpleYaml(raw) {
             const key = trimmed.slice(0, separator).trim();
             const rawValue = trimmed.slice(separator + 1).trim();
             index++;
-            if (key in result) {
+            if (seen.has(key)) {
                 throw new Error(`Duplicate YAML key: ${key} near line: ${line.trim()}`);
             }
+            seen.add(key);
             if (rawValue === "|" || rawValue === "|-") {
                 const blockLines = [];
                 let contentIndent = null;
@@ -168,19 +182,19 @@ export function parseSimpleYaml(raw) {
                     index++;
                 }
                 const content = blockLines.join("\n").replace(/\n+$/, "");
-                result[key] = rawValue === "|" ? `${content}\n` : content;
+                assign(key, rawValue === "|" ? `${content}\n` : content);
                 continue;
             }
             if (rawValue !== "") {
-                result[key] = parseYamlScalar(rawValue);
+                assign(key, parseYamlScalar(rawValue));
                 continue;
             }
             skipBlank();
             if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
-                result[key] = parseBlock(countIndent(lines[index] ?? ""));
+                assign(key, parseBlock(countIndent(lines[index] ?? "")));
             }
             else {
-                result[key] = null;
+                assign(key, null);
             }
         }
         return result;
@@ -198,7 +212,13 @@ export function parseSimpleYaml(raw) {
             const trimmed = line.slice(lineIndent);
             if (lineIndent !== indent || (!trimmed.startsWith("- ") && trimmed !== "-"))
                 break;
-            const rawItem = trimmed === "-" ? "" : trimmed.slice(2).trim();
+            const afterDash = trimmed === "-" ? "" : trimmed.slice(2);
+            const rawItem = afterDash.trim();
+            // A sequence item's mapping continues at the column where its own
+            // content starts, which is not always two past the dash: `-   id: x`
+            // aligns its siblings under the `i`, four columns in. Hardcoding two
+            // rejected that valid layout as bad indentation.
+            const itemIndent = indent + 2 + (afterDash.length - afterDash.trimStart().length);
             index++;
             if (rawItem === "") {
                 skipBlank();
@@ -221,7 +241,7 @@ export function parseSimpleYaml(raw) {
                     item[key] = parseBlock(countIndent(lines[index] ?? ""));
                 }
                 if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
-                    const nested = parseMapping(indent + 2);
+                    const nested = parseMapping(itemIndent);
                     for (const [nestedKey, nestedValue] of Object.entries(nested))
                         item[nestedKey] = nestedValue;
                 }

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

@@ -11,6 +11,7 @@ import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { closeoutFileName, pathExists } from "../../core/index.js";
+import { createChildModelRuntime } from "./child-model-runtime.js";
 /** Closeout content over this many bytes is truncated before being passed to
  *  the rewriter. Keeps the orchestrator-side cost predictable. */
 const CLOSEOUT_BYTE_BUDGET = 8000;
@@ -143,6 +144,7 @@ async function runRewriterOnce(ctx, prompt) {
     const { session } = await createAgentSession({
         cwd,
         agentDir,
+        modelRuntime: await createChildModelRuntime(ctx, agentDir),
         sessionManager: SessionManager.inMemory(cwd),
         settingsManager: SettingsManager.create(cwd, agentDir),
         model: ctx.model,

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

@@ -13,6 +13,7 @@ import { access } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { canonicalPath, isWithinPath } from "../../core/index.js";
+import { createChildModelRuntime } from "./child-model-runtime.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
 // Tools available to the phase sub-agent. Matches the codecarto interception
 // allowlist (SAFE_TOOL_NAMES in extensions/codecarto/index.ts), minus bash.
@@ -104,6 +105,7 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
     const { session } = await createAgentSession({
         cwd,
         agentDir,
+        modelRuntime: await createChildModelRuntime(ctx, agentDir),
         sessionManager,
         settingsManager: SettingsManager.create(cwd, agentDir),
         model: ctx.model,

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

@@ -44,7 +44,7 @@ export interface AutoCompleteResult {
     /** Non-gating closure-integrity notes from completion (#122). */
     warnings: string[];
 }
-export declare function autoCompletePhase(ctx: ExtensionContext, validation: ValidationResult): Promise<AutoCompleteResult>;
+export declare function autoCompletePhase(cwd: string, validation: ValidationResult): Promise<AutoCompleteResult>;
 export type AutoOutcome = "complete" | "stopped" | "aborted";
 export interface AutoRunOptions {
     strict: boolean;

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

@@ -151,9 +151,13 @@ export function isPhaseRunning(phaseId) {
     const existing = getPhaseActivity(phaseId);
     return existing?.status === "running";
 }
-export async function autoCompletePhase(ctx, validation) {
-    const result = await completeValidatedPhase(ctx.cwd, validation, "/codecarto-complete");
-    void writeDashboard(ctx.cwd, PACKAGE_VERSION);
+export async function autoCompletePhase(
+// A directory, not a ctx: this only ever needed `ctx.cwd`, and its callers
+// run after a sub-agent has invalidated the ctx they captured, where every
+// property access throws.
+cwd, validation) {
+    const result = await completeValidatedPhase(cwd, validation, "/codecarto-complete");
+    void writeDashboard(cwd, PACKAGE_VERSION);
     return result;
 }
 export function decideAfterPhase(phaseStatus, phaseError, validation, strict) {
@@ -185,6 +189,9 @@ export function decideAfterPhase(phaseStatus, phaseError, validation, strict) {
 }
 export async function runAuto(ctx, pi, initialState, options) {
     const startedAt = Date.now();
+    // Captured once: the loop below spawns a sub-agent per phase, and each one
+    // invalidates this ctx, after which reading `ctx.cwd` throws.
+    const autoCwd = ctx.cwd;
     const phasesRun = [];
     const totalTokens = { input: 0, output: 0, cacheWrite: 0 };
     const totalPhases = initialState.pipeline.phase_order.length;
@@ -262,7 +269,7 @@ export async function runAuto(ctx, pi, initialState, options) {
         // decision.action === "continue" → auto-complete and loop.
         // validation is guaranteed non-null on the continue branch.
         try {
-            const { updatedState } = await autoCompletePhase(ctx, validation);
+            const { updatedState } = await autoCompletePhase(autoCwd, validation);
             state = updatedState;
             phasesRun.push(phase.id);
             options.onPhaseAdvanced?.(state);

package/dist/extensions/codecarto/child-model-runtime.d.ts

@@ -0,0 +1,2 @@
+import { type ExtensionContext, ModelRuntime } from "@earendil-works/pi-coding-agent";
+export declare function createChildModelRuntime(ctx: ExtensionContext, agentDir: string): Promise<ModelRuntime>;

package/dist/extensions/codecarto/child-model-runtime.js

@@ -0,0 +1,44 @@
+// Model runtime for codecarto's child sessions (phase sub-agents, the
+// next-phase rewriter, the dashboard narrator).
+//
+// All three child sessions load with `noExtensions: true` so a globally
+// installed codecarto doesn't register its commands and tool guards twice
+// inside its own sub-agent. That isolation has a side effect: providers
+// registered by *other* global extensions via `pi.registerProvider()` — an
+// Ollama Cloud bridge, a company gateway, any custom `streamSimple` provider —
+// are registered onto the parent's ModelRuntime by the resource loader that
+// loaded them. A child that builds a fresh ModelRuntime never sees them, so
+// the parent's selected model resolves to a provider the child does not know,
+// and the session throws `No API key found for <provider>` before its first
+// turn.
+//
+// Carrying the parent's registered provider configs across keeps the child on
+// the same model the user picked without reloading (and re-registering) the
+// extensions themselves.
+import { join } from "node:path";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+export async function createChildModelRuntime(ctx, agentDir) {
+    const runtime = await ModelRuntime.create({
+        authPath: join(agentDir, "auth.json"),
+        modelsPath: join(agentDir, "models.json"),
+    });
+    for (const providerId of ctx.modelRegistry.getRegisteredProviderIds()) {
+        const config = ctx.modelRegistry.getRegisteredProviderConfig(providerId);
+        if (!config)
+            continue;
+        try {
+            runtime.registerProvider(providerId, config);
+        }
+        catch {
+            // A provider the child can't accept is not worth failing the phase
+            // over: the child either doesn't need it (the user's model comes
+            // from a different provider) or fails later with the provider-
+            // specific error, which is more useful than one thrown here.
+        }
+    }
+    // Recompose the provider table so the newly registered providers land in
+    // the availability snapshot that `hasConfiguredAuth` reads. Offline: the
+    // parent already paid for any network catalog refresh.
+    await runtime.refresh({ allowNetwork: false });
+    return runtime;
+}

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

@@ -14,6 +14,7 @@ import { readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { computeTotals, NARRATION_CACHE_RELATIVE_PATH, loadUsage, pathExists, stringifySimpleYaml, } from "../../core/index.js";
+import { createChildModelRuntime } from "./child-model-runtime.js";
 // Per-closeout byte budget when stuffing the narrator's input. Three
 // closeouts × 4 KB each ≈ 12 KB of prompt context, which is well under any
 // reasonable model's input window.
@@ -153,6 +154,7 @@ async function runNarratorOnce(ctx, prompt) {
     const { session } = await createAgentSession({
         cwd,
         agentDir,
+        modelRuntime: await createChildModelRuntime(ctx, agentDir),
         sessionManager: SessionManager.inMemory(cwd),
         settingsManager: SettingsManager.create(cwd, agentDir),
         model: ctx.model,

package/dist/extensions/codecarto/index.js

@@ -83,8 +83,42 @@ function buildStatusLines(state, extraLines = []) {
     }
     return lines;
 }
+/**
+ * Whether `ctx` still belongs to the live session.
+ *
+ * Pi invalidates an extension ctx when the session is replaced, and from then
+ * on *every* property access on it throws — `ctx.cwd` and `ctx.hasUI` included.
+ * A phase runs as a sub-agent, so by the time post-phase work fires, the ctx
+ * captured when the command started may already be dead. That is an ordinary
+ * outcome rather than an error: the UI it would have refreshed is gone with the
+ * session. Callers skip their UI work instead of throwing into a `void` call
+ * that nothing is waiting on.
+ */
+function isCtxLive(ctx) {
+    try {
+        return typeof ctx.cwd === "string";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Notify through `ctx`, dropping the message if the session it belonged to is
+ * gone.
+ *
+ * `ctx.hasUI` throws on a stale ctx rather than returning false, so the usual
+ * `if (ctx.hasUI) ctx.ui.notify(...)` guard was itself a throw site. Inside a
+ * promise chain that was worse than a lost message: the `.catch` handler threw
+ * while reporting the original failure, and that second rejection had nothing
+ * left to catch it.
+ */
+function notifyCtx(ctx, message, level) {
+    if (!isCtxLive(ctx) || !ctx.hasUI)
+        return;
+    ctx.ui.notify(message, level);
+}
 function setUiState(ctx, state, extraLines = []) {
-    if (!ctx.hasUI)
+    if (!isCtxLive(ctx) || !ctx.hasUI)
         return;
     if (!state) {
         ctx.ui.setStatus(STATUS_LINE_ID, undefined);
@@ -260,6 +294,11 @@ export default function codeCartographerExtension(pi) {
     // remembered here for the completers that list files under .codecarto/.
     let sessionCwd;
     const readWorkspaceState = async (ctx, notifyOnError = true) => {
+        // `ctx.cwd` was read before the try, so a stale ctx made this reject
+        // rather than return null as its signature promises — and the callers
+        // that fire it without awaiting turned that into an unhandled rejection.
+        if (!isCtxLive(ctx))
+            return null;
         sessionCwd = ctx.cwd;
         try {
             return await getWorkspaceState(ctx.cwd);
@@ -268,12 +307,16 @@ export default function codeCartographerExtension(pi) {
             const message = error instanceof Error ? error.message : String(error);
             lastFeedbackLines = [message];
             setUiState(ctx, null);
-            if (notifyOnError && ctx.hasUI)
+            // The ctx can die between the read above and here, so the error
+            // path must not assume it is still usable either.
+            if (notifyOnError && isCtxLive(ctx) && ctx.hasUI)
                 ctx.ui.notify(message, "error");
             return null;
         }
     };
     const refreshWorkspaceUi = async (ctx, extraLines) => {
+        if (!isCtxLive(ctx))
+            return null;
         if (!codecartoModeActive) {
             setUiState(ctx, null);
             return null;
@@ -290,15 +333,19 @@ export default function codeCartographerExtension(pi) {
     const ensureWorkspaceState = async (ctx) => {
         if (!codecartoModeActive) {
             setUiState(ctx, null);
-            ctx.ui.notify("CodeCartographer is not active in this session. Run /codecarto-init first.", "warning");
+            notifyCtx(ctx, "CodeCartographer is not active in this session. Run /codecarto-init first.", "warning");
             return null;
         }
         const state = await readWorkspaceState(ctx);
         if (state)
             return state;
+        // Reached when the ctx is stale as well as when there is no workspace,
+        // so neither `ctx.cwd` nor the notify below may assume a live ctx.
+        if (!isCtxLive(ctx))
+            return null;
         const hasWorkspace = await pathExists(join(ctx.cwd, ".codecarto", "workflow", "status.yaml"));
         if (!hasWorkspace)
-            ctx.ui.notify("No .codecarto/ workspace found. Run /codecarto-init first.", "warning");
+            notifyCtx(ctx, "No .codecarto/ workspace found. Run /codecarto-init first.", "warning");
         return null;
     };
     pi.on("session_start", async (_event, ctx) => {
@@ -607,34 +654,36 @@ export default function codeCartographerExtension(pi) {
             // phase so status.yaml advances without requiring the user to manually
             // run /codecarto-validate then /codecarto-complete. This mirrors what
             // the auto loop (runAuto) does after each phase.
+            // The sub-agent replaces the session, which invalidates this ctx —
+            // every later property access on it throws. Capture the directory
+            // now so the post-phase work below does not depend on the ctx
+            // surviving, and route UI updates through notifyCtx, which drops
+            // them if it has not.
+            const phaseCwd = ctx.cwd;
             void runSinglePhase(ctx, pi, state, phase, { llmSteerEnabled, signal: ctx.signal, preflight })
                 .then(async (result) => {
                 if (result.status !== "completed")
                     return;
                 // Refresh state from disk — the sub-agent may have written
                 // findings that the validator needs to read.
-                const stateForValidation = (await getWorkspaceState(ctx.cwd)) ?? state;
+                const stateForValidation = (await getWorkspaceState(phaseCwd)) ?? state;
                 const validation = await validatePhaseOutput(stateForValidation, phase.id).catch((error) => (error instanceof Error ? error : new Error(String(error))));
                 if (validation instanceof Error) {
-                    if (ctx.hasUI)
-                        ctx.ui.notify(`Auto-validation error for ${phase.id}: ${validation.message}`, "warning");
+                    notifyCtx(ctx, `Auto-validation error for ${phase.id}: ${validation.message}`, "warning");
                     lastFeedbackLines = [`Validation error: ${validation.message}`, "Run `/codecarto-validate` then `/codecarto-complete` manually."];
                     return;
                 }
                 if (validation.overall === "FAIL" || validation.overall === "MISSING") {
-                    if (ctx.hasUI)
-                        ctx.ui.notify(`Phase ${phase.id} validation: ${validation.overall}. Fix the output, then re-run /codecarto-next.`, "warning");
+                    notifyCtx(ctx, `Phase ${phase.id} validation: ${validation.overall}. Fix the output, then re-run /codecarto-next.`, "warning");
                     lastFeedbackLines = buildValidationSummary(validation);
                     return;
                 }
                 // PASS or PASS WITH GAPS — auto-complete the phase.
                 try {
-                    const { updatedState, closeoutNotice } = await autoCompletePhase(ctx, validation);
-                    if (ctx.hasUI) {
-                        ctx.ui.notify(`Phase ${phase.id} auto-completed (validation: ${validation.overall}).`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
-                        if (closeoutNotice)
-                            ctx.ui.notify(closeoutNotice, "info");
-                    }
+                    const { updatedState, closeoutNotice } = await autoCompletePhase(phaseCwd, validation);
+                    notifyCtx(ctx, `Phase ${phase.id} auto-completed (validation: ${validation.overall}).`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
+                    if (closeoutNotice)
+                        notifyCtx(ctx, closeoutNotice, "info");
                     lastFeedbackLines = [
                         `Completed phase: ${validation.phaseId}`,
                         `Validation: ${validation.overall}`,
@@ -645,22 +694,20 @@ export default function codeCartographerExtension(pi) {
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    if (ctx.hasUI)
-                        ctx.ui.notify(`Auto-completion failed for ${phase.id}: ${message}. Run /codecarto-complete manually.`, "warning");
+                    notifyCtx(ctx, `Auto-completion failed for ${phase.id}: ${message}. Run /codecarto-complete manually.`, "warning");
                     lastFeedbackLines = [`Auto-completion failed: ${message}`, "Run `/codecarto-complete` manually."];
                 }
             })
                 .catch((error) => {
                 const message = error instanceof Error ? error.message : String(error);
-                if (ctx.hasUI)
-                    ctx.ui.notify(`Post-phase processing error for ${phase.id}: ${message}`, "warning");
+                notifyCtx(ctx, `Post-phase processing error for ${phase.id}: ${message}`, "warning");
                 lastFeedbackLines = [`Post-phase error: ${message}`];
             })
                 .finally(() => {
                 // Refresh the status widget after the phase resolves so the
                 // "Open questions / Carry-forward / Next" lines reflect any
                 // owner_notes the sub-agent wrote to status.yaml.
-                void refreshWorkspaceUi(ctx);
+                void refreshWorkspaceUi(ctx).catch(() => undefined);
             });
         },
     });
@@ -738,7 +785,25 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
-            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx, validation);
+            // Completion refuses for reasons the framework words carefully — a
+            // missing phase handoff, a carry-forward without `derives_from`, a
+            // closure lacking runtime evidence. Those messages are the whole
+            // point of the refusal, and this was the one call in this file that
+            // let them escape as a rejection instead of showing them. The
+            // irony was sharp: /codecarto-next catches this same throw and tells
+            // the user to run /codecarto-complete manually, which then threw.
+            let completion;
+            try {
+                completion = await autoCompletePhase(ctx.cwd, validation);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lastFeedbackLines = [`Completion refused: ${message}`];
+                setUiState(ctx, currentState, lastFeedbackLines);
+                ctx.ui.notify(message, "error");
+                return;
+            }
+            const { updatedState, closeoutNotice, warnings } = completion;
             lastFeedbackLines = [
                 `Completed phase: ${validation.phaseId}`,
                 `Validation: ${validation.overall}`,
@@ -884,7 +949,7 @@ export default function codeCartographerExtension(pi) {
             }
             lastFeedbackLines = [`Queued the CodeCartographer guide: ${document.topic}`];
             if (codecartoModeActive)
-                void refreshWorkspaceUi(ctx, lastFeedbackLines);
+                void refreshWorkspaceUi(ctx, lastFeedbackLines).catch(() => undefined);
             ctx.ui.notify(`Queued the CodeCartographer guide (${document.topic})`, "info");
         },
     });
@@ -917,7 +982,7 @@ export default function codeCartographerExtension(pi) {
                     // A workspace session already has a widget; fold the result into it.
                     if (ctx.hasUI)
                         ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
-                    void refreshWorkspaceUi(ctx, lines);
+                    void refreshWorkspaceUi(ctx, lines).catch(() => undefined);
                 }
                 else if (ctx.hasUI) {
                     // Scout-only repository: the Broad-Side widget is the only place

package/dist/mcp-server/server.js

@@ -24,6 +24,20 @@ import { initLibrary } from "../core/library.js";
 import { loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
 import { writeDashboard } from "../extensions/codecarto/dashboard-writer.js";
 // ---------- input helpers ----------
+/**
+ * Normalize an optional `phase` argument. A client can send any JSON, and
+ * `args.phase?.trim()` throws a bare TypeError on a number or an object —
+ * surfacing as an opaque InternalError rather than telling the caller which
+ * argument was wrong. Sibling handlers already guard the required case.
+ */
+function requireOptionalPhase(phase) {
+    if (phase === undefined || phase === null)
+        return undefined;
+    if (typeof phase !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, `phase must be a string when provided, got ${typeof phase}`);
+    }
+    return phase.trim() || undefined;
+}
 async function validateCwd(cwd) {
     if (typeof cwd !== "string" || !cwd.trim()) {
         throw new McpError(ErrorCode.InvalidParams, "cwd is required");
@@ -148,7 +162,7 @@ export async function handleStatus(args) {
     const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "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 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);
@@ -237,7 +251,7 @@ export async function handlePhase(args) {
 export async function handleValidate(args) {
     const cwd = await validateCwd(args.cwd);
     const state = await requireWorkspace(cwd);
-    const validation = await validatePhaseOutput(state, args.phase?.trim() || undefined).catch((error) => {
+    const validation = await validatePhaseOutput(state, requireOptionalPhase(args.phase)).catch((error) => {
         throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
     });
     const summary = buildValidationSummary(validation).join("\n");
@@ -256,7 +270,7 @@ export async function handleValidate(args) {
 export async function handleComplete(args) {
     const cwd = await validateCwd(args.cwd);
     const initialState = await requireWorkspace(cwd);
-    const validation = await validatePhaseOutput(initialState, args.phase?.trim() || undefined).catch((error) => {
+    const validation = await validatePhaseOutput(initialState, requireOptionalPhase(args.phase)).catch((error) => {
         throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
     });
     if (validation.overall === "FAIL" || validation.overall === "MISSING") {
@@ -377,9 +391,17 @@ async function resolveLibraryPath(args) {
  * the publish tool enforces.
  */
 async function loadEffectiveConfig(cwd) {
-    return typeof cwd === "string" && cwd.trim() !== ""
-        ? loadCodecartoConfig(join(cwd.trim(), ".codecarto"))
-        : loadUserConfig();
+    if (typeof cwd !== "string" || cwd.trim() === "")
+        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"));
 }
 function asStringArray(value, fieldName) {
     if (!Array.isArray(value)) {
@@ -731,6 +753,13 @@ export async function handleLibraryInit(args) {
 }
 export async function handleVision(args) {
     const cwd = await validateCwd(args.cwd);
+    // raw_text is interpolated straight into the returned prompt, so an absent
+    // value silently becomes the literal string "undefined" for the agent to
+    // synthesize a vision brief from. Every sibling handler validates its
+    // required string argument; this one did not.
+    if (typeof args.raw_text !== "string" || !args.raw_text.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, "raw_text is required (the user's raw product description)");
+    }
     const workspaceDir = join(cwd, ".codecarto");
     const interviewPath = join(workspaceDir, "findings", "vision-capture", "INTERVIEW.md");
     const visionPath = join(workspaceDir, "inputs", "vision.md");
@@ -757,8 +786,8 @@ export async function handleVision(args) {
     });
 }
 export async function handleConfig(args) {
-    const config = args.cwd
-        ? await loadCodecartoConfig(join(args.cwd, ".codecarto"))
+    const config = args.cwd !== undefined && args.cwd !== null
+        ? await loadCodecartoConfig(join(await validateCwd(args.cwd), ".codecarto"))
         : await loadUserConfig();
     const userConfigPath = resolveUserConfigPath();
     const workspaceConfigPath = args.cwd ? join(args.cwd, ".codecarto", "workflow", "config.yaml") : null;
@@ -976,6 +1005,11 @@ export async function handleBroadside(args) {
                 includeTriage,
                 retryTruncated,
                 onStatus: (lensId, status, counts) => lines.push(`  ${lensId}: ${status} (${counts.completed ?? 0}/${counts.total ?? "?"})`),
+            }).catch((error) => {
+                // The `collect` action normalizes this same call; without it here,
+                // a failure during submit-with-wait reached the client as an
+                // opaque InternalError instead of naming its cause.
+                throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
             });
             lines.push("", collectResultText(collect));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "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",