codecartographer-pi 0.19.4 → 0.19.6

package/dist/extensions/codecarto/index.js

@@ -9,8 +9,9 @@ import { writeDashboard } from "./dashboard-writer.js";
 import { parseBroadsideFlags, KNOWN_BROADSIDE_TOKENS } from "./broadside-flags.js";
 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, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listSkillNames, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, 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, } from "../../core/index.js";
+import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, resolveExistingPrefix, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listSkillNames, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, 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, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
@@ -84,40 +85,6 @@ 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 (!isCtxLive(ctx) || !ctx.hasUI)
         return;
@@ -310,8 +277,8 @@ export default function codeCartographerExtension(pi) {
             setUiState(ctx, null);
             // 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");
+            if (notifyOnError)
+                notifyCtx(ctx, message, "error");
             return null;
         }
     };
@@ -370,24 +337,25 @@ export default function codeCartographerExtension(pi) {
         if (!(await pathExists(workspaceDir)))
             return undefined;
         if (event.toolName === "bash") {
-            if (ctx.hasUI)
-                ctx.ui.notify("Blocked bash in CodeCartographer mode", "warning");
+            notifyCtx(ctx, "Blocked bash in CodeCartographer mode", "warning");
             return { block: true, reason: "CodeCartographer mode disables bash to keep source analysis read-only." };
         }
         if (event.toolName === "edit" || event.toolName === "write") {
             const inputPath = typeof event.input.path === "string" ? event.input.path : "";
             const strippedPath = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
-            const targetPath = await canonicalPath(resolve(ctx.cwd, strippedPath));
+            // Resolve through whatever already exists on disk — symlinks included —
+            // before appending the unborn tail. `resolve()` would collapse
+            // `link/..` lexically and `realpath()` throws on a file that is not
+            // there yet, and either gap let a write escape the workspace (#223).
+            const targetPath = await resolveExistingPrefix(strippedPath, ctx.cwd);
             const allowedRoots = [await canonicalPath(workspaceDir)];
             const config = await loadCodecartoConfig(workspaceDir);
             if (config.library.path && await discoverLibrary(config.library.path)) {
                 allowedRoots.push(await canonicalPath(config.library.path));
             }
-            const withinAllowed = await Promise.all(allowedRoots.map((allowedRoot) => isWithinPathResolved(targetPath, allowedRoot)));
+            const withinAllowed = allowedRoots.map((allowedRoot) => isWithinPath(targetPath, allowedRoot));
             if (!withinAllowed.some((result) => result)) {
-                if (ctx.hasUI) {
-                    ctx.ui.notify(`Blocked ${event.toolName} outside .codecarto/ or configured library: ${inputPath}`, "warning");
-                }
+                notifyCtx(ctx, `Blocked ${event.toolName} outside .codecarto/ or configured library: ${inputPath}`, "warning");
                 return { block: true, reason: `CodeCartographer mode only allows ${event.toolName} within .codecarto/ or the configured CodeCartographer library.` };
             }
         }
@@ -398,7 +366,7 @@ export default function codeCartographerExtension(pi) {
         handler: async (_args, ctx) => {
             const workspaceDir = join(ctx.cwd, ".codecarto");
             if (!(await pathExists(join(workspaceDir, "workflow", "status.yaml")))) {
-                ctx.ui.notify("No existing CodeCartographer workspace found. Run /codecarto-init first.", "warning");
+                notifyCtx(ctx, "No existing CodeCartographer workspace found. Run /codecarto-init first.", "warning");
                 return;
             }
             try {
@@ -407,11 +375,11 @@ export default function codeCartographerExtension(pi) {
                 lastFeedbackLines = [`Opened existing workspace: ${getPipelineLabel(state.status.pipeline)}`];
                 pi.setActiveTools(SAFE_TOOL_NAMES);
                 await refreshWorkspaceUi(ctx, lastFeedbackLines);
-                ctx.ui.notify("Opened existing CodeCartographer workspace without resetting state.", "info");
+                notifyCtx(ctx, "Opened existing CodeCartographer workspace without resetting state.", "info");
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                ctx.ui.notify(`Unable to open CodeCartographer workspace: ${message}`, "error");
+                notifyCtx(ctx, `Unable to open CodeCartographer workspace: ${message}`, "error");
             }
         },
     });
@@ -420,7 +388,7 @@ export default function codeCartographerExtension(pi) {
         handler: async (_args, ctx) => {
             const interviewPath = join(ctx.cwd, ".codecarto", "findings", "vision-capture", "INTERVIEW.md");
             if (!(await pathExists(interviewPath))) {
-                ctx.ui.notify("Vision interview skill not found. Run /codecarto-init synthesis first.", "warning");
+                notifyCtx(ctx, "Vision interview skill not found. Run /codecarto-init synthesis first.", "warning");
                 return;
             }
             const interviewSkill = await readFile(interviewPath, "utf8");
@@ -442,7 +410,7 @@ export default function codeCartographerExtension(pi) {
                 pi.sendUserMessage(prompt, { deliverAs: "followUp" });
             }
             lastFeedbackLines = ["Vision interview started — answer the questions in chat."];
-            ctx.ui.notify("Vision interview queued — answer the questions in the chat.", "info");
+            notifyCtx(ctx, "Vision interview queued — answer the questions in the chat.", "info");
         },
     });
     pi.registerCommand("codecarto-init", {
@@ -457,13 +425,13 @@ export default function codeCartographerExtension(pi) {
             const trimmedArgs = args.trim();
             const pipelineChoice = resolvePipelineChoice(trimmedArgs);
             if (trimmedArgs && !pipelineChoice) {
-                ctx.ui.notify(`Unknown pipeline: ${trimmedArgs}`, "error");
+                notifyCtx(ctx, `Unknown pipeline: ${trimmedArgs}`, "error");
                 return;
             }
             const targetWorkspaceDir = join(ctx.cwd, ".codecarto");
             const sourceWorkspaceDir = packagedWorkspaceDir;
             if (!(await pathExists(sourceWorkspaceDir))) {
-                ctx.ui.notify("Packaged .codecarto assets are missing.", "error");
+                notifyCtx(ctx, "Packaged .codecarto assets are missing.", "error");
                 return;
             }
             const targetExists = await pathExists(targetWorkspaceDir);
@@ -475,8 +443,7 @@ export default function codeCartographerExtension(pi) {
                         return;
                     const backupDir = join(ctx.cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
                     await rename(targetWorkspaceDir, backupDir);
-                    if (ctx.hasUI)
-                        ctx.ui.notify(`Backed up existing workspace to ${basename(backupDir)}/`, "info");
+                    notifyCtx(ctx, `Backed up existing workspace to ${basename(backupDir)}/`, "info");
                 }
             }
             if (!(await pathExists(targetWorkspaceDir))) {
@@ -484,11 +451,12 @@ export default function codeCartographerExtension(pi) {
                 await copyPackagedWorkspace(targetWorkspaceDir);
             }
             const rawStatusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
-            const rawStatus = (await loadYamlFile(rawStatusPath)) ?? {};
+            // Absent on a fresh copy: the template ships no status.yaml.
+            const rawStatus = (await pathExists(rawStatusPath)) ? ((await loadYamlFile(rawStatusPath)) ?? {}) : {};
             const selectedPipelinePath = pipelineChoice ?? rawStatus.pipeline?.trim() ?? DEFAULT_PIPELINE_PATH;
             const resolvedPipelinePath = join(targetWorkspaceDir, selectedPipelinePath);
             if (!(await pathExists(resolvedPipelinePath))) {
-                ctx.ui.notify(`Pipeline not found: ${selectedPipelinePath}`, "error");
+                notifyCtx(ctx, `Pipeline not found: ${selectedPipelinePath}`, "error");
                 return;
             }
             const pipeline = await loadYamlFile(resolvedPipelinePath);
@@ -506,7 +474,7 @@ export default function codeCartographerExtension(pi) {
                 `Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`,
                 "Full run: `/codecarto-next --auto --llm-steer` — or `/codecarto-next` to watch one phase first.",
             ];
-            ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)}). Full run: /codecarto-next --auto --llm-steer`, "info");
+            notifyCtx(ctx, `Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)}). Full run: /codecarto-next --auto --llm-steer`, "info");
             // Render the initial dashboard (empty usage, all phases pending) so
             // the user sees the file exist immediately after /codecarto-init.
             void writeDashboard(ctx.cwd, PACKAGE_VERSION);
@@ -524,7 +492,7 @@ export default function codeCartographerExtension(pi) {
             const nextPhase = getNextEligiblePhase(state)?.id ?? "complete";
             lastFeedbackLines = [`Current phase: ${nextPhase}`, `Pipeline: ${getPipelineLabel(state.status.pipeline)}`];
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify(`CodeCartographer phase: ${nextPhase}`, "info");
+            notifyCtx(ctx, `CodeCartographer phase: ${nextPhase}`, "info");
         },
     });
     pi.registerCommand("codecarto-switch-pipeline", {
@@ -538,12 +506,12 @@ export default function codeCartographerExtension(pi) {
         handler: async (args, ctx) => {
             const trimmedArgs = args.trim();
             if (!trimmedArgs) {
-                ctx.ui.notify("Usage: /codecarto-switch-pipeline <variant> (e.g. lite, full, synthesis)", "warning");
+                notifyCtx(ctx, "Usage: /codecarto-switch-pipeline <variant> (e.g. lite, full, synthesis)", "warning");
                 return;
             }
             const pipelineChoice = resolvePipelineChoice(trimmedArgs);
             if (!pipelineChoice) {
-                ctx.ui.notify(`Unknown pipeline: ${trimmedArgs}`, "error");
+                notifyCtx(ctx, `Unknown pipeline: ${trimmedArgs}`, "error");
                 return;
             }
             const state = await ensureWorkspaceState(ctx);
@@ -551,7 +519,7 @@ export default function codeCartographerExtension(pi) {
                 return;
             const currentPipeline = state.status.pipeline;
             if (currentPipeline === pipelineChoice) {
-                ctx.ui.notify(`Already on pipeline: ${getPipelineLabel(pipelineChoice)}`, "info");
+                notifyCtx(ctx, `Already on pipeline: ${getPipelineLabel(pipelineChoice)}`, "info");
                 return;
             }
             try {
@@ -567,14 +535,14 @@ export default function codeCartographerExtension(pi) {
                     lines.push(`Phases not in new pipeline: ${result.dropped.join(", ")} (findings remain on disk)`);
                 lastFeedbackLines = lines;
                 await refreshWorkspaceUi(ctx, lastFeedbackLines);
-                ctx.ui.notify(`Switched to pipeline: ${getPipelineLabel(pipelineChoice)}`, "info");
+                notifyCtx(ctx, `Switched to pipeline: ${getPipelineLabel(pipelineChoice)}`, "info");
                 void writeDashboard(ctx.cwd, PACKAGE_VERSION);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 lastFeedbackLines = [message];
                 setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify(message, "error");
+                notifyCtx(ctx, message, "error");
             }
         },
     });
@@ -601,18 +569,18 @@ export default function codeCartographerExtension(pi) {
         handler: async (args, ctx) => {
             const flags = parseNextFlags(args);
             if (flags.error) {
-                ctx.ui.notify(flags.error, "error");
+                notifyCtx(ctx, flags.error, "error");
                 return;
             }
             if (flags.unknown.length > 0) {
-                ctx.ui.notify(`Unknown /codecarto-next flag: ${flags.unknown.join(" ")}`, "error");
+                notifyCtx(ctx, `Unknown /codecarto-next flag: ${flags.unknown.join(" ")}`, "error");
                 return;
             }
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
             if (flags.auto) {
-                ctx.ui.notify(`Auto pipeline${flags.strict ? " (strict)" : ""} running…`, "info");
+                notifyCtx(ctx, `Auto pipeline${flags.strict ? " (strict)" : ""} running…`, "info");
                 const result = await runAuto(ctx, pi, state, {
                     strict: flags.strict,
                     llmSteerOverride: flags.llmSteerOverride,
@@ -635,14 +603,14 @@ export default function codeCartographerExtension(pi) {
                 });
                 lastFeedbackLines = [`Auto pipeline ${result.outcome}: ${result.reason}`];
                 await refreshWorkspaceUi(ctx, lastFeedbackLines);
-                ctx.ui.notify(`Auto pipeline ${result.outcome}: ${result.phasesRun.length}/${result.totalPhases} phases.`, result.outcome === "complete" ? "info" : "warning");
+                notifyCtx(ctx, `Auto pipeline ${result.outcome}: ${result.phasesRun.length}/${result.totalPhases} phases.`, result.outcome === "complete" ? "info" : "warning");
                 return;
             }
             const phase = getNextEligiblePhase(state);
             if (!phase) {
                 lastFeedbackLines = ["All phases complete."];
                 setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify("All CodeCartographer phases are complete.", "info");
+                notifyCtx(ctx, "All CodeCartographer phases are complete.", "info");
                 return;
             }
             let preflight;
@@ -653,13 +621,13 @@ export default function codeCartographerExtension(pi) {
                 const message = error instanceof Error ? error.message : String(error);
                 lastFeedbackLines = [message];
                 setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify(message, error instanceof PhasePreflightError ? "warning" : "error");
+                notifyCtx(ctx, message, error instanceof PhasePreflightError ? "warning" : "error");
                 return;
             }
             // Reject re-entry: don't spawn a duplicate runner for a phase that's
             // already in flight from a previous /codecarto-next invocation.
             if (isPhaseRunning(phase.id)) {
-                ctx.ui.notify(`Phase ${phase.id} is already running.`, "warning");
+                notifyCtx(ctx, `Phase ${phase.id} is already running.`, "warning");
                 return;
             }
             const config = await loadCodecartoConfig(state.workspaceDir);
@@ -735,7 +703,7 @@ export default function codeCartographerExtension(pi) {
         handler: async (args, ctx) => {
             const phaseId = args.trim();
             if (!phaseId) {
-                ctx.ui.notify("Usage: /codecarto-phase <phase>", "warning");
+                notifyCtx(ctx, "Usage: /codecarto-phase <phase>", "warning");
                 return;
             }
             const state = await ensureWorkspaceState(ctx);
@@ -743,7 +711,7 @@ export default function codeCartographerExtension(pi) {
                 return;
             const phase = resolvePhase(state, phaseId);
             if (!phase) {
-                ctx.ui.notify(`Unknown phase: ${phaseId}`, "error");
+                notifyCtx(ctx, `Unknown phase: ${phaseId}`, "error");
                 return;
             }
             let prompt;
@@ -752,7 +720,7 @@ export default function codeCartographerExtension(pi) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                ctx.ui.notify(message, error instanceof PhasePreflightError ? "warning" : "error");
+                notifyCtx(ctx, message, error instanceof PhasePreflightError ? "warning" : "error");
                 return;
             }
             if (ctx.isIdle()) {
@@ -763,7 +731,7 @@ export default function codeCartographerExtension(pi) {
             }
             lastFeedbackLines = [`Queued explicit phase prompt for ${phase.id}`];
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+            notifyCtx(ctx, `Queued CodeCartographer phase: ${phase.id}`, "info");
         },
     });
     pi.registerCommand("codecarto-validate", {
@@ -776,13 +744,13 @@ export default function codeCartographerExtension(pi) {
             if (validation instanceof Error) {
                 lastFeedbackLines = [validation.message];
                 setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify(validation.message, "error");
+                notifyCtx(ctx, validation.message, "error");
                 return;
             }
             lastFeedbackLines = buildValidationSummary(validation);
             setUiState(ctx, state, lastFeedbackLines);
             const level = validation.overall === "FAIL" || validation.overall === "MISSING" ? "error" : validation.overall === "PASS WITH GAPS" ? "warning" : "info";
-            ctx.ui.notify(`Validation ${validation.phaseId}: ${validation.overall}`, level);
+            notifyCtx(ctx, `Validation ${validation.phaseId}: ${validation.overall}`, level);
         },
     });
     pi.registerCommand("codecarto-complete", {
@@ -795,13 +763,13 @@ export default function codeCartographerExtension(pi) {
             if (validation instanceof Error) {
                 lastFeedbackLines = [validation.message];
                 setUiState(ctx, currentState, lastFeedbackLines);
-                ctx.ui.notify(validation.message, "error");
+                notifyCtx(ctx, validation.message, "error");
                 return;
             }
             if (validation.overall === "FAIL" || validation.overall === "MISSING") {
                 lastFeedbackLines = buildValidationSummary(validation);
                 setUiState(ctx, currentState, lastFeedbackLines);
-                ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
+                notifyCtx(ctx, `Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
             // Completion refuses for reasons the framework words carefully — a
@@ -819,7 +787,7 @@ export default function codeCartographerExtension(pi) {
                 const message = error instanceof Error ? error.message : String(error);
                 lastFeedbackLines = [`Completion refused: ${message}`];
                 setUiState(ctx, currentState, lastFeedbackLines);
-                ctx.ui.notify(message, "error");
+                notifyCtx(ctx, message, "error");
                 return;
             }
             const { updatedState, closeoutNotice, warnings } = completion;
@@ -834,11 +802,11 @@ export default function codeCartographerExtension(pi) {
             for (const note of notes)
                 lastFeedbackLines.push(`NOTE: ${note} Non-gating.`);
             setUiState(ctx, updatedState, lastFeedbackLines);
-            ctx.ui.notify(`Marked ${validation.phaseId} complete`, validation.overall === "PASS WITH GAPS" || notes.length > 0 ? "warning" : "info");
+            notifyCtx(ctx, `Marked ${validation.phaseId} complete`, validation.overall === "PASS WITH GAPS" || notes.length > 0 ? "warning" : "info");
             if (closeoutNotice)
-                ctx.ui.notify(closeoutNotice, "info");
+                notifyCtx(ctx, closeoutNotice, "info");
             for (const note of notes)
-                ctx.ui.notify(note, "warning");
+                notifyCtx(ctx, note, "warning");
         },
     });
     pi.registerCommand("codecarto-skill", {
@@ -848,7 +816,7 @@ export default function codeCartographerExtension(pi) {
             if (!skillName) {
                 const available = await listSkillNames(join(ctx.cwd, ".codecarto"));
                 const hint = available.length > 0 ? ` (available: ${available.join(", ")})` : "";
-                ctx.ui.notify(`Usage: /codecarto-skill <name>${hint}`, "warning");
+                notifyCtx(ctx, `Usage: /codecarto-skill <name>${hint}`, "warning");
                 return;
             }
             // Broad-Side is a reading guide for batch reconnaissance output, not a
@@ -858,7 +826,7 @@ export default function codeCartographerExtension(pi) {
             if (skillName === BROADSIDE_SKILL_NAME) {
                 const skill = await readBroadsideSkill(ctx.cwd).catch(() => null);
                 if (!skill) {
-                    ctx.ui.notify("Broad-Side reading guide not found. Reinstall codecartographer-pi.", "error");
+                    notifyCtx(ctx, "Broad-Side reading guide not found. Reinstall codecartographer-pi.", "error");
                     return;
                 }
                 const message = [
@@ -872,7 +840,7 @@ export default function codeCartographerExtension(pi) {
                 else {
                     pi.sendUserMessage(message, { deliverAs: "followUp" });
                 }
-                ctx.ui.notify("Queued the Broad-Side reading guide", "info");
+                notifyCtx(ctx, "Queued the Broad-Side reading guide", "info");
                 return;
             }
             const state = await ensureWorkspaceState(ctx);
@@ -880,14 +848,14 @@ export default function codeCartographerExtension(pi) {
                 return;
             const nextPhase = getNextEligiblePhase(state);
             if (nextPhase) {
-                ctx.ui.notify(`Cannot run skill: pipeline is not complete (next phase: ${nextPhase.id}). Finish the pipeline before running post-pipeline skills.`, "error");
+                notifyCtx(ctx, `Cannot run skill: pipeline is not complete (next phase: ${nextPhase.id}). Finish the pipeline before running post-pipeline skills.`, "error");
                 return;
             }
             const skillFile = join(state.workspaceDir, "skills", skillName, "SKILL.md");
             if (!(await pathExists(skillFile))) {
                 const available = await listSkillNames(state.workspaceDir);
                 const hint = available.length > 0 ? ` (available: ${available.join(", ")})` : " (no skills installed)";
-                ctx.ui.notify(`Unknown skill: ${skillName}${hint}. The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`, "error");
+                notifyCtx(ctx, `Unknown skill: ${skillName}${hint}. The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`, "error");
                 return;
             }
             const prompt = await buildSkillPrompt(state, skillName);
@@ -899,7 +867,7 @@ export default function codeCartographerExtension(pi) {
             }
             lastFeedbackLines = [`Queued post-pipeline skill: ${skillName}`];
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
+            notifyCtx(ctx, `Queued CodeCartographer skill: ${skillName}`, "info");
         },
     });
     pi.registerCommand("codecarto-list-skills", {
@@ -928,7 +896,7 @@ export default function codeCartographerExtension(pi) {
             }
             lastFeedbackLines = lines;
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify(skills.length > 0
+            notifyCtx(ctx, skills.length > 0
                 ? `${skills.length} post-pipeline skill${skills.length === 1 ? "" : "s"}: ${skills.join(", ")}`
                 : "No post-pipeline skills installed.", "info");
         },
@@ -952,7 +920,7 @@ export default function codeCartographerExtension(pi) {
                 document = await readGuide(args.trim() || undefined);
             }
             catch (error) {
-                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+                notifyCtx(ctx, error instanceof Error ? error.message : String(error), "error");
                 return;
             }
             const other = topics.filter((name) => name !== document.topic);
@@ -969,7 +937,7 @@ export default function codeCartographerExtension(pi) {
             lastFeedbackLines = [`Queued the CodeCartographer guide: ${document.topic}`];
             if (codecartoModeActive)
                 void refreshWorkspaceUi(ctx, lastFeedbackLines).catch(() => undefined);
-            ctx.ui.notify(`Queued the CodeCartographer guide (${document.topic})`, "info");
+            notifyCtx(ctx, `Queued the CodeCartographer guide (${document.topic})`, "info");
         },
     });
     pi.registerCommand("codecarto-broadside", {
@@ -983,12 +951,12 @@ export default function codeCartographerExtension(pi) {
         handler: async (args, ctx) => {
             const flags = parseBroadsideFlags(args);
             if (flags.unknown.length > 0) {
-                ctx.ui.notify(`Unknown /codecarto-broadside argument: ${flags.unknown.join(" ")}. ` +
+                notifyCtx(ctx, `Unknown /codecarto-broadside argument: ${flags.unknown.join(" ")}. ` +
                     `Actions: submit, collect, status, models. Lenses: ${BROADSIDE_LENS_IDS.join(", ")}.`, "error");
                 return;
             }
             if (flags.error) {
-                ctx.ui.notify(flags.error, "error");
+                notifyCtx(ctx, flags.error, "error");
                 return;
             }
             // Broad-Side runs on any git repository, with or without a workspace —
@@ -1008,7 +976,7 @@ export default function codeCartographerExtension(pi) {
                     // the result can live, so it holds it instead of being cleared.
                     ctx.ui.setWidget(BROADSIDE_WIDGET_ID, ["Broad-Side", ...lines]);
                 }
-                ctx.ui.notify(notice, level);
+                notifyCtx(ctx, notice, level);
             };
             if (flags.action === "status") {
                 const { state } = await runBroadsideStatus(ctx.cwd);
@@ -1018,12 +986,12 @@ export default function codeCartographerExtension(pi) {
             }
             const apiKey = resolveBroadsideKey(config.apiKey);
             if (!apiKey) {
-                ctx.ui.notify("No OpenRouter API key. Set OPENROUTER_API_KEY in the environment, or add api_key to " +
+                notifyCtx(ctx, "No OpenRouter API key. Set OPENROUTER_API_KEY in the environment, or add api_key to " +
                     ".codecarto/broadside/config.yaml. (A slash command takes no key: it would land in the transcript.)", "error");
                 return;
             }
             if (flags.action === "models") {
-                ctx.ui.notify("Fetching the OpenRouter batch-model catalog…", "info");
+                notifyCtx(ctx, "Fetching the OpenRouter batch-model catalog…", "info");
                 try {
                     const { entries, benchmarks } = await listBatchModels(broadsideDir, config, apiKey, {
                         includeBenchmarks: flags.benchmarks,
@@ -1031,7 +999,7 @@ export default function codeCartographerExtension(pi) {
                     finish(modelsText(entries, { benchmarks, defaultModel: config.model }).split("\n"), `Broad-Side: ${entries.length} batch model${entries.length === 1 ? "" : "s"} listed`);
                 }
                 catch (error) {
-                    ctx.ui.notify(`Model catalog lookup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                    notifyCtx(ctx, `Model catalog lookup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
                 }
                 return;
             }
@@ -1077,10 +1045,10 @@ export default function codeCartographerExtension(pi) {
                     if (ctx.hasUI)
                         ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
                     if (error instanceof BroadsideCancelledError) {
-                        ctx.ui.notify("Broad-Side cancelled. Nothing was submitted.", "info");
+                        notifyCtx(ctx, "Broad-Side cancelled. Nothing was submitted.", "info");
                         return;
                     }
-                    ctx.ui.notify(`Broad-Side submit failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                    notifyCtx(ctx, `Broad-Side submit failed: ${error instanceof Error ? error.message : String(error)}`, "error");
                     return;
                 }
                 const lines = estimateSubmitText(submit, lenses.map(getLens)).split("\n");
@@ -1089,7 +1057,7 @@ export default function codeCartographerExtension(pi) {
                     finish(lines, `Broad-Side submitted: run ${submit.runId} (~$${submit.estimatedTotalCost.toFixed(4)})`);
                     return;
                 }
-                ctx.ui.notify(`Broad-Side submitted run ${submit.runId}; polling for up to ${waitSeconds}s…`, "info");
+                notifyCtx(ctx, `Broad-Side submitted run ${submit.runId}; polling for up to ${waitSeconds}s…`, "info");
                 try {
                     const collect = await runBroadsideCollect(ctx.cwd, apiKey, {
                         waitMs,
@@ -1105,7 +1073,7 @@ export default function codeCartographerExtension(pi) {
                         ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
                     // The batches are submitted and paid for either way — say so, so
                     // nobody re-submits a run that is already in flight.
-                    ctx.ui.notify(`Broad-Side submitted run ${submit.runId}, but collect failed: ` +
+                    notifyCtx(ctx, `Broad-Side submitted run ${submit.runId}, but collect failed: ` +
                         `${error instanceof Error ? error.message : String(error)}. Retry with /codecarto-broadside collect.`, "error");
                 }
                 return;
@@ -1129,7 +1097,7 @@ export default function codeCartographerExtension(pi) {
             catch (error) {
                 if (ctx.hasUI)
                     ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
-                ctx.ui.notify(`Broad-Side collect failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                notifyCtx(ctx, `Broad-Side collect failed: ${error instanceof Error ? error.message : String(error)}`, "error");
             }
         },
     });
@@ -1141,22 +1109,22 @@ export default function codeCartographerExtension(pi) {
                 return;
             const config = await loadCodecartoConfig(state.workspaceDir);
             if (!config.library.path) {
-                ctx.ui.notify("No library.path is configured. Create a library directory with a .codecarto-library marker, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.", "error");
+                notifyCtx(ctx, "No library.path is configured. Create a library directory with a .codecarto-library marker, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.", "error");
                 return;
             }
             const marker = await discoverLibrary(config.library.path);
             if (!marker) {
-                ctx.ui.notify(`No CodeCartographer library at ${config.library.path} (missing .codecarto-library). Create a .codecarto-library marker file in that directory.`, "error");
+                notifyCtx(ctx, `No CodeCartographer library at ${config.library.path} (missing .codecarto-library). Create a .codecarto-library marker file in that directory.`, "error");
                 return;
             }
             const phase = resolvePhase(state, "reimplementation-spec");
             if (!phase?.primary_output) {
-                ctx.ui.notify("The active pipeline does not produce a reimplementation spec to publish.", "error");
+                notifyCtx(ctx, "The active pipeline does not produce a reimplementation spec to publish.", "error");
                 return;
             }
             const specPath = join(state.workspaceDir, phase.primary_output);
             if (!(await pathExists(specPath))) {
-                ctx.ui.notify(`Reimplementation spec is missing: .codecarto/${phase.primary_output}`, "error");
+                notifyCtx(ctx, `Reimplementation spec is missing: .codecarto/${phase.primary_output}`, "error");
                 return;
             }
             const spec = await readFile(specPath, "utf8");
@@ -1167,7 +1135,7 @@ export default function codeCartographerExtension(pi) {
             const headline = derivePublishHeadline(spec, ctx.cwd);
             const namespace = marker.namespaced ? config.library.namespace ?? undefined : undefined;
             if (marker.namespaced && !namespace) {
-                ctx.ui.notify("The configured library is namespaced; set library.namespace before publishing.", "error");
+                notifyCtx(ctx, "The configured library is namespaced; set library.namespace before publishing.", "error");
                 return;
             }
             const label = `${namespace ? `${namespace}/` : ""}${slug}`;
@@ -1212,7 +1180,7 @@ export default function codeCartographerExtension(pi) {
                             // recorded the directory to one that records the git remote.
                             const moved = await ctx.ui.confirm("Source repository changed — did it move?", `Library entry ${label} records source_repo "${error.recorded}", but this publish carries "${error.incoming}". If the repository genuinely moved (rename, org transfer, host change — or this is the first publish since CodeCartographer began recording the git remote instead of the local directory), answer yes and this spec is appended as the entry's next version. If these are two different projects that share a directory name, answer no: nothing is written, and the second project needs a distinct slug (codecarto_publish on MCP accepts one). Did the repository move?`);
                             if (!moved) {
-                                ctx.ui.notify("Publish cancelled. Nothing was written.", "info");
+                                notifyCtx(ctx, "Publish cancelled. Nothing was written.", "info");
                                 return;
                             }
                             options.allowSourceRepoChange = true;
@@ -1222,7 +1190,7 @@ export default function codeCartographerExtension(pi) {
                             // default; whether it may go into a wider library is the user's call.
                             const publishAnyway = await ctx.ui.confirm("Confidentiality mismatch — publish anyway?", `This spec's confidentiality is "${error.entryConfidentiality}" (CodeCartographer's default; /codecarto-publish declares none), but the library "${marker.name}" has visibility "${error.libraryVisibility}". Publishing would expose it to everyone that library reaches. Publish anyway?`);
                             if (!publishAnyway) {
-                                ctx.ui.notify("Publish cancelled. Nothing was written.", "info");
+                                notifyCtx(ctx, "Publish cancelled. Nothing was written.", "info");
                                 return;
                             }
                             options.allowConfidentialityMismatch = true;
@@ -1235,11 +1203,11 @@ export default function codeCartographerExtension(pi) {
                 lastFeedbackLines = [`Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version}`, result.isNewVersion ? "New content version." : "Metadata-only update (content unchanged)."];
                 await writeDashboard(ctx.cwd, PACKAGE_VERSION);
                 await refreshWorkspaceUi(ctx, lastFeedbackLines);
-                ctx.ui.notify(`Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version}.`, "info");
+                notifyCtx(ctx, `Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version}.`, "info");
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                ctx.ui.notify(`Unable to publish: ${message}`, "error");
+                notifyCtx(ctx, `Unable to publish: ${message}`, "error");
             }
         },
     });
@@ -1251,7 +1219,7 @@ export default function codeCartographerExtension(pi) {
             const namespaceIdx = parts.indexOf("--namespace");
             const namespace = namespaceIdx >= 0 ? parts[namespaceIdx + 1] : null;
             if (!pathArg) {
-                ctx.ui.notify("Usage: /codecarto-library-init <path> [--namespace <name>]", "warning");
+                notifyCtx(ctx, "Usage: /codecarto-library-init <path> [--namespace <name>]", "warning");
                 return;
             }
             const libraryPath = pathArg.startsWith("~") ? join(homedir(), pathArg.slice(1)) : resolve(pathArg);
@@ -1267,14 +1235,12 @@ export default function codeCartographerExtension(pi) {
                     ? `Library already exists at ${libraryPath} (marker preserved). Config updated.`
                     : `Created library at ${libraryPath} with marker "${result.marker.name}".`;
                 lastFeedbackLines = [msg, `Config written to ${configPath}`];
-                if (ctx.hasUI) {
-                    ctx.ui.notify(msg, "info");
-                    ctx.ui.notify(`Config written to ${configPath}`, "info");
-                }
+                notifyCtx(ctx, msg, "info");
+                notifyCtx(ctx, `Config written to ${configPath}`, "info");
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                ctx.ui.notify(`Library init failed: ${message}`, "error");
+                notifyCtx(ctx, `Library init failed: ${message}`, "error");
             }
         },
     });
@@ -1300,7 +1266,7 @@ export default function codeCartographerExtension(pi) {
             lastFeedbackLines = lines;
             if (state)
                 setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify("Configuration shown in status widget.", "info");
+            notifyCtx(ctx, "Configuration shown in status widget.", "info");
         },
     });
     pi.registerCommand("codecarto-usage", {
@@ -1313,7 +1279,7 @@ export default function codeCartographerExtension(pi) {
             if (usage.runs.length === 0) {
                 lastFeedbackLines = ["No phase runs recorded yet."];
                 setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify("No phase runs recorded yet.", "info");
+                notifyCtx(ctx, "No phase runs recorded yet.", "info");
                 return;
             }
             const totals = computeTotals(usage);
@@ -1333,7 +1299,7 @@ export default function codeCartographerExtension(pi) {
             }
             lastFeedbackLines = lines;
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify(`CodeCartographer usage: ${totals.runs} run${totals.runs === 1 ? "" : "s"}, ${formatUsageTokens(totals.tokens.input + totals.tokens.output)} tokens total`, "info");
+            notifyCtx(ctx, `CodeCartographer usage: ${totals.runs} run${totals.runs === 1 ? "" : "s"}, ${formatUsageTokens(totals.tokens.input + totals.tokens.output)} tokens total`, "info");
         },
     });
     pi.registerCommand("codecarto-dashboard", {
@@ -1347,26 +1313,26 @@ export default function codeCartographerExtension(pi) {
         handler: async (args, ctx) => {
             const flags = parseDashboardFlags(args);
             if (flags.unknown.length > 0) {
-                ctx.ui.notify(`Unknown /codecarto-dashboard flag: ${flags.unknown.join(" ")}`, "error");
+                notifyCtx(ctx, `Unknown /codecarto-dashboard flag: ${flags.unknown.join(" ")}`, "error");
                 return;
             }
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
             if (flags.narrate) {
-                ctx.ui.notify(`Narrating dashboard via LLM…`, "info");
+                notifyCtx(ctx, `Narrating dashboard via LLM…`, "info");
                 const result = await narrateDashboard(ctx, state);
                 if (result.used) {
-                    ctx.ui.notify("Narration written to .codecarto/.dashboard-narration.local.md", "info");
+                    notifyCtx(ctx, "Narration written to .codecarto/.dashboard-narration.local.md", "info");
                 }
                 else {
-                    ctx.ui.notify(`LLM narration skipped (${result.skipReason}); rendering deterministic dashboard.`, "warning");
+                    notifyCtx(ctx, `LLM narration skipped (${result.skipReason}); rendering deterministic dashboard.`, "warning");
                 }
             }
             await writeDashboard(ctx.cwd, PACKAGE_VERSION);
             lastFeedbackLines = ["Dashboard regenerated: .codecarto/dashboard.html"];
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify("Dashboard regenerated: .codecarto/dashboard.html", "info");
+            notifyCtx(ctx, "Dashboard regenerated: .codecarto/dashboard.html", "info");
         },
     });
     pi.registerCommand("codecarto-refresh-scaffold", {
@@ -1382,12 +1348,12 @@ export default function codeCartographerExtension(pi) {
                 files = await listScaffoldRefreshFiles();
             }
             catch (error) {
-                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+                notifyCtx(ctx, error instanceof Error ? error.message : String(error), "error");
                 return;
             }
             const approved = await ctx.ui.confirm("Refresh the .codecarto/ scaffold from the packaged template?", describeScaffoldRefreshPreview(files, state.scaffoldVersion));
             if (!approved) {
-                ctx.ui.notify("Scaffold refresh cancelled. Nothing was written.", "info");
+                notifyCtx(ctx, "Scaffold refresh cancelled. Nothing was written.", "info");
                 return;
             }
             try {
@@ -1400,13 +1366,13 @@ export default function codeCartographerExtension(pi) {
                 ];
                 // Re-read state so the widget's staleness line clears with the marker.
                 await refreshWorkspaceUi(ctx, lastFeedbackLines);
-                ctx.ui.notify(`Refreshed ${result.written.length} framework-owned file(s) (${transition}).`, "info");
+                notifyCtx(ctx, `Refreshed ${result.written.length} framework-owned file(s) (${transition}).`, "info");
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 lastFeedbackLines = [message];
                 setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify(`Scaffold refresh failed: ${message}`, "error");
+                notifyCtx(ctx, `Scaffold refresh failed: ${message}`, "error");
             }
         },
     });
@@ -1428,12 +1394,12 @@ export default function codeCartographerExtension(pi) {
                 const hint = staged.length > 0
                     ? ` (staged: ${staged.join(", ")})`
                     : " — write .codecarto/scratch/amendments/<name>.yaml first (see templates/amendment.yaml)";
-                ctx.ui.notify(`Usage: /codecarto-amend <name>${hint}`, "warning");
+                notifyCtx(ctx, `Usage: /codecarto-amend <name>${hint}`, "warning");
                 return;
             }
             const name = resolveAmendmentName(args, ctx.cwd);
             if (!name) {
-                ctx.ui.notify(`Amendments are read from .codecarto/scratch/amendments/ only; pass the amendment name or a path inside that directory, not ${args.trim()}.`, "error");
+                notifyCtx(ctx, `Amendments are read from .codecarto/scratch/amendments/ only; pass the amendment name or a path inside that directory, not ${args.trim()}.`, "error");
                 return;
             }
             // The same refusals codecarto_amend surfaces, raised before the
@@ -1443,12 +1409,12 @@ export default function codeCartographerExtension(pi) {
                 amendment = await loadAmendmentFile(name, state.workspaceDir);
             }
             catch (error) {
-                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+                notifyCtx(ctx, error instanceof Error ? error.message : String(error), "error");
                 return;
             }
             const nextPhase = getNextEligiblePhase(state);
             if (nextPhase) {
-                ctx.ui.notify(`Cannot amend: the pipeline is not complete (next phase: ${nextPhase.id}). `
+                notifyCtx(ctx, `Cannot amend: the pipeline is not complete (next phase: ${nextPhase.id}). `
                     + "Resolve open questions and routed items through that phase's handoff (open_question_closures / carry_forward_closures) instead.", "error");
                 return;
             }
@@ -1456,7 +1422,7 @@ export default function codeCartographerExtension(pi) {
             // before anything is written — MCP's codecarto_amend applies on call.
             const approved = await ctx.ui.confirm(`Apply amendment "${amendment.slug}"?`, describeAmendmentPreview(amendment, state));
             if (!approved) {
-                ctx.ui.notify(`Amendment ${amendment.slug} cancelled. Nothing was written.`, "info");
+                notifyCtx(ctx, `Amendment ${amendment.slug} cancelled. Nothing was written.`, "info");
                 return;
             }
             try {
@@ -1477,14 +1443,14 @@ export default function codeCartographerExtension(pi) {
                 lastFeedbackLines = lines;
                 await refreshWorkspaceUi(ctx, lastFeedbackLines);
                 const closed = applied.openQuestionsClosed.length + applied.postPipelineClosed.length;
-                ctx.ui.notify(`Amendment ${amendment.slug} applied: ${applied.openQuestionsClosed.length} open question(s) and ${applied.postPipelineClosed.length} post-pipeline item(s) closed`
+                notifyCtx(ctx, `Amendment ${amendment.slug} applied: ${applied.openQuestionsClosed.length} open question(s) and ${applied.postPipelineClosed.length} post-pipeline item(s) closed`
                     + `${applied.unknownIds.length > 0 ? `; ${applied.unknownIds.length} id(s) matched nothing` : ""}.`, closed === 0 || applied.unknownIds.length > 0 ? "warning" : "info");
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 lastFeedbackLines = [message];
                 setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify(`Amendment failed: ${message}`, "error");
+                notifyCtx(ctx, `Amendment failed: ${message}`, "error");
             }
         },
     });