codecartographer-pi 0.18.0 → 0.19.1

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,7 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
-            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx, validation);
+            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx.cwd, validation);
             lastFeedbackLines = [
                 `Completed phase: ${validation.phaseId}`,
                 `Validation: ${validation.overall}`,
@@ -884,7 +931,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 +964,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.18.0",
+  "version": "0.19.1",
   "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",