codecartographer-pi 0.19.3 → 0.19.5

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.19.3
+scaffold_version: 0.19.5

package/dist/core/yaml.js

@@ -167,6 +167,31 @@ export function parseSimpleYaml(raw) {
         while (index < lines.length && isBlankOrComment(lines[index] ?? ""))
             index++;
     };
+    /**
+     * Read the body of a block scalar that opened on the line just consumed.
+     * Shared by mapping values (`key: >-`) and sequence items (`- >-`): when only
+     * the mapping path had it, a handoff whose `decisions:` list used `- >-`
+     * still failed with the indentation error that #211 was supposed to end.
+     */
+    const collectBlockScalarLines = (baseIndent) => {
+        const blockLines = [];
+        let contentIndent = null;
+        while (index < lines.length) {
+            const blockLine = lines[index] ?? "";
+            if (blockLine.trim() === "") {
+                blockLines.push("");
+                index++;
+                continue;
+            }
+            const blockIndent = countIndent(blockLine);
+            if (blockIndent <= baseIndent)
+                break;
+            contentIndent ??= blockIndent;
+            blockLines.push(blockLine.slice(Math.min(contentIndent, blockIndent)));
+            index++;
+        }
+        return blockLines;
+    };
     const parseBlock = (indent) => {
         skipBlank();
         if (index >= lines.length)
@@ -221,23 +246,7 @@ export function parseSimpleYaml(raw) {
             seen.add(key);
             const blockHeader = parseBlockScalarHeader(rawValue);
             if (blockHeader) {
-                const blockLines = [];
-                let contentIndent = null;
-                while (index < lines.length) {
-                    const blockLine = lines[index] ?? "";
-                    if (blockLine.trim() === "") {
-                        blockLines.push("");
-                        index++;
-                        continue;
-                    }
-                    const blockIndent = countIndent(blockLine);
-                    if (blockIndent <= indent)
-                        break;
-                    contentIndent ??= blockIndent;
-                    blockLines.push(blockLine.slice(Math.min(contentIndent, blockIndent)));
-                    index++;
-                }
-                assign(key, applyBlockScalar(blockLines, blockHeader));
+                assign(key, applyBlockScalar(collectBlockScalarLines(indent), blockHeader));
                 continue;
             }
             if (rawValue !== "") {
@@ -285,6 +294,11 @@ export function parseSimpleYaml(raw) {
                 }
                 continue;
             }
+            const itemBlockHeader = parseBlockScalarHeader(rawItem);
+            if (itemBlockHeader) {
+                result.push(applyBlockScalar(collectBlockScalarLines(indent), itemBlockHeader));
+                continue;
+            }
             const separator = findKeySeparator(rawItem);
             if (separator !== -1) {
                 const key = rawItem.slice(0, separator).trim();

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

@@ -12,6 +12,7 @@
 // write, closeout-stub creation, dashboard regen. UI notifications stay in
 // the calling handler.
 import { runPhase } from "./agent-runner.js";
+import { notifyCtx } from "./notify.js";
 import { clearPhase, finishPhase, getPhaseActivity, startPhase } from "./agent-state.js";
 import { buildSteeringMessage, rewritePhasePrompt } from "./agent-rewriter.js";
 import { buildPhaseSummary } from "./agent-summary.js";
@@ -34,13 +35,11 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
         preflight: options.preflight,
     });
     if (options.llmSteerEnabled) {
-        if (ctx.hasUI)
-            ctx.ui.notify(`Customizing ${phase.id} prompt via LLM rewriter…`, "info");
+        notifyCtx(ctx, `Customizing ${phase.id} prompt via LLM rewriter…`, "info");
         const rewrite = await rewritePhasePrompt({ ctx, state, originalPrompt: prompt, nextPhaseId: phase.id });
         if (rewrite.used) {
             prompt = rewrite.prompt;
-            if (ctx.hasUI)
-                ctx.ui.notify(`LLM rewriter customized ${phase.id} seed prompt.`, "info");
+            notifyCtx(ctx, `LLM rewriter customized ${phase.id} seed prompt.`, "info");
             pi.sendMessage({
                 customType: "codecarto-steering",
                 content: buildSteeringMessage({
@@ -51,15 +50,14 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
                 display: true,
             });
         }
-        else if (ctx.hasUI) {
-            ctx.ui.notify(`LLM rewriter skipped (${rewrite.skipReason}); using stock prompt.`, "warning");
+        else {
+            notifyCtx(ctx, `LLM rewriter skipped (${rewrite.skipReason}); using stock prompt.`, "warning");
         }
     }
     const activity = startPhase(phase.id);
-    if (ctx.hasUI) {
-        ctx.ui.notify(`CodeCartographer phase: ${phase.id} (sub-agent running)`, "info");
+    notifyCtx(ctx, `CodeCartographer phase: ${phase.id} (sub-agent running)`, "info");
+    if (ctx.hasUI)
         getAgentsWidget().attach(ctx.ui);
-    }
     try {
         const result = await runPhase(ctx, prompt, {
             onSessionCreated: (session) => { activity.session = session; },
@@ -84,11 +82,9 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
         }, { sessionName: `CodeCartographer phase: ${phase.id}`, primaryOutput: phase.primary_output }, options.signal);
         const status = result.aborted ? "aborted" : "completed";
         finishPhase(phase.id, { status });
-        if (ctx.hasUI) {
-            ctx.ui.notify(result.aborted
-                ? `Phase ${phase.id} aborted.`
-                : `Phase ${phase.id} sub-agent finished (${result.toolUses} tool uses, ${result.turnCount} turns).`, result.aborted ? "warning" : "info");
-        }
+        notifyCtx(ctx, result.aborted
+            ? `Phase ${phase.id} aborted.`
+            : `Phase ${phase.id} sub-agent finished (${result.toolUses} tool uses, ${result.turnCount} turns).`, result.aborted ? "warning" : "info");
         pi.sendMessage({
             customType: "codecarto-phase-summary",
             content: buildPhaseSummary({
@@ -115,9 +111,7 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         finishPhase(phase.id, { status: "error", error: message });
-        if (ctx.hasUI) {
-            ctx.ui.notify(`Phase ${phase.id} sub-agent failed: ${message}`, "error");
-        }
+        notifyCtx(ctx, `Phase ${phase.id} sub-agent failed: ${message}`, "error");
         pi.sendMessage({
             customType: "codecarto-phase-summary",
             content: buildPhaseSummary({

package/dist/extensions/codecarto/guide-framing.js

@@ -40,6 +40,27 @@ export const PI_SURFACE_ADDENDUM = [
     `- **Every tool name maps to a slash command the user runs**, mechanically: \`codecarto_status\` → \`/codecarto-status\`, \`codecarto_next\` → \`/codecarto-next\`, and so on. Two have no Pi equivalent: ${MCP_ONLY_TOOLS.map((name) => `\`${name}\``).join(" and ")}.`,
     "- **Ignore \"every tool takes an absolute `cwd`\".** Slash commands act on the session's own directory; there is no `cwd` argument to pass.",
     "- **The drive loop is different.** `/codecarto-next` executes the phase itself, as an isolated sub-agent, and then auto-validates and auto-completes it. The guide's hand-written loop — take the prompt, execute it, write the handoff, then validate and complete yourself — describes the MCP surface. On Pi the user drives and the extension executes; your job is to explain what the framework is doing and answer questions about it, not to reproduce that loop by hand.",
+    "",
+    "### How to drive a run",
+    "",
+    "`/codecarto-next` takes flags that change how much runs and how each phase is seeded. They are independent: `--auto` decides *how many phases run*, `--llm-steer` decides *what prompt each one gets*.",
+    "",
+    "| Invocation | What it does |",
+    "| --- | --- |",
+    "| `/codecarto-next` | Runs the next eligible phase, once. Good for watching a single phase or retrying one that stopped. |",
+    "| `/codecarto-next --auto` | Runs every remaining phase back to back, validating and completing each before starting the next. Stops on a validation failure or a sub-agent error. |",
+    "| `/codecarto-next --auto --llm-steer` | The same, with each phase's prompt rewritten from the previous phase's closeout. **This is the usual choice for a full run** — it is what makes phase N+1 aware of what phase N found. |",
+    "| `/codecarto-next --auto --strict --llm-steer` | The same, but also stops on `PASS WITH GAPS` instead of advancing through it. Use when gaps should be reviewed rather than carried forward. |",
+    "",
+    "Notes worth passing on when the user asks:",
+    "",
+    "- **The first phase is never steered** — there is no previous closeout to steer from, so it reports `LLM rewriter skipped (no previous phase to steer from)` and uses the stock prompt. That message is normal, not a failure.",
+    "- **Steering costs an extra model call per phase**, on top of the phase sub-agent itself.",
+    "- `--strict` is only valid with `--auto`; on its own it is an error.",
+    "- `--no-llm-steer` forces steering off for one invocation when the workspace config has it on (`orchestrator.llm_steer_next_phase`, default off).",
+    "- **An auto run that stops says why in its summary block.** If a phase produced its artifact but the pipeline still shows it incomplete, read the `Auto pipeline stopped at …` message rather than assuming the phase failed — the phase usually succeeded and something after it did not.",
+    "",
+    "If the user has just initialized a workspace and has not said what they want, tell them the run command rather than waiting to be asked: `/codecarto-next --auto --llm-steer` for a full pass, or plain `/codecarto-next` to watch one phase first.",
 ].join("\n");
 /**
  * Assemble the message /codecarto-guide queues. The guide document is embedded

package/dist/extensions/codecarto/index.js

@@ -9,6 +9,7 @@ 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 { initLibrary } from "../../core/library.js";
@@ -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,8 +337,7 @@ 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") {
@@ -385,9 +351,7 @@ export default function codeCartographerExtension(pi) {
             }
             const withinAllowed = await Promise.all(allowedRoots.map((allowedRoot) => isWithinPathResolved(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 +362,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 +371,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 +384,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 +406,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 +421,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 +439,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))) {
@@ -488,7 +451,7 @@ export default function codeCartographerExtension(pi) {
             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);
@@ -499,8 +462,14 @@ export default function codeCartographerExtension(pi) {
             // duties maintain so they exist from the first phase.
             await seedOrchestratorFiles(targetWorkspaceDir);
             codecartoModeActive = true;
-            lastFeedbackLines = [`Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`];
-            ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)})`, "info");
+            // Name the run command here: init is the moment someone needs it, and
+            // the flags that make a full run useful are not guessable from the
+            // command name alone.
+            lastFeedbackLines = [
+                `Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`,
+                "Full run: `/codecarto-next --auto --llm-steer` — or `/codecarto-next` to watch one phase first.",
+            ];
+            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);
@@ -518,7 +487,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", {
@@ -532,12 +501,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);
@@ -545,7 +514,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 {
@@ -561,40 +530,52 @@ 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");
             }
         },
     });
     pi.registerCommand("codecarto-next", {
-        description: "Run the next eligible CodeCartographer phase as a sub-agent. Flags: --llm-steer / --no-llm-steer / --auto [--strict]",
+        description: "Run the next phase as a sub-agent. Full run: --auto --llm-steer. Add --strict to stop on PASS WITH GAPS.",
         getArgumentCompletions: (prefix) => {
-            const items = ["--llm-steer", "--no-llm-steer", "--auto", "--strict"]
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
+            // Descriptions, not bare flag names: the completion list is the only
+            // place most users will ever see what these do, and the useful
+            // combination (--auto --llm-steer) is not guessable from the names.
+            // --strict is offered only once --auto is present, because on its own
+            // it is rejected — suggesting it standalone invites the one error the
+            // parser has.
+            const autoAlreadyTyped = prefix.includes("--auto");
+            const items = [
+                { value: "--auto", label: "--auto", description: "run every remaining phase back to back (recommended with --llm-steer)" },
+                { value: "--llm-steer", label: "--llm-steer", description: "seed each phase from the previous phase's closeout; no effect on the first phase" },
+                { value: "--no-llm-steer", label: "--no-llm-steer", description: "force steering off when the workspace config turns it on" },
+                ...(autoAlreadyTyped
+                    ? [{ value: "--strict", label: "--strict", description: "with --auto: stop on PASS WITH GAPS instead of advancing" }]
+                    : []),
+            ].filter((item) => item.value.startsWith(prefix.split(/\s+/).pop() ?? prefix));
             return items.length > 0 ? items : null;
         },
         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,
@@ -617,14 +598,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;
@@ -635,13 +616,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);
@@ -717,7 +698,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);
@@ -725,7 +706,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;
@@ -734,7 +715,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()) {
@@ -745,7 +726,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", {
@@ -758,13 +739,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", {
@@ -777,13 +758,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
@@ -801,7 +782,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;
@@ -816,11 +797,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", {
@@ -830,7 +811,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
@@ -840,7 +821,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 = [
@@ -854,7 +835,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);
@@ -862,14 +843,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);
@@ -881,7 +862,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", {
@@ -910,7 +891,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");
         },
@@ -934,7 +915,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);
@@ -951,7 +932,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", {
@@ -965,12 +946,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 —
@@ -990,7 +971,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);
@@ -1000,12 +981,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,
@@ -1013,7 +994,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;
             }
@@ -1059,10 +1040,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");
@@ -1071,7 +1052,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,
@@ -1087,7 +1068,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;
@@ -1111,7 +1092,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");
             }
         },
     });
@@ -1123,22 +1104,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");
@@ -1149,7 +1130,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}`;
@@ -1194,7 +1175,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;
@@ -1204,7 +1185,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;
@@ -1217,11 +1198,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");
             }
         },
     });
@@ -1233,7 +1214,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);
@@ -1249,14 +1230,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");
             }
         },
     });
@@ -1282,7 +1261,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", {
@@ -1295,7 +1274,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);
@@ -1315,7 +1294,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", {
@@ -1329,26 +1308,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", {
@@ -1364,12 +1343,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 {
@@ -1382,13 +1361,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");
             }
         },
     });
@@ -1410,12 +1389,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
@@ -1425,12 +1404,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;
             }
@@ -1438,7 +1417,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 {
@@ -1459,14 +1438,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");
             }
         },
     });

package/dist/extensions/codecarto/notify.d.ts

@@ -0,0 +1,16 @@
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+export type NotifyLevel = "info" | "warning" | "error";
+/** Whether `ctx` still belongs to the live session. See the module comment. */
+export declare function isCtxLive(ctx: ExtensionContext | ExtensionCommandContext): boolean;
+/**
+ * Format a notification for a stream. Exported so tests pin the shape a script
+ * would parse: one line, prefixed, level visible.
+ */
+export declare function formatStreamNotification(message: string, level: NotifyLevel): string;
+/**
+ * Notify through `ctx`: the TUI when there is one, stderr when there is not,
+ * nothing when the ctx is stale.
+ */
+export declare function notifyCtx(ctx: ExtensionContext | ExtensionCommandContext, message: string, level: NotifyLevel, stream?: {
+    write(chunk: string): unknown;
+}): void;

package/dist/extensions/codecarto/notify.js

@@ -0,0 +1,53 @@
+// User-facing notifications from the orchestrator side of the Pi extension.
+//
+// Two things go wrong with a bare `ctx.ui.notify(...)`, and this module is the
+// one place that handles both.
+//
+// A stale ctx throws. 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, not an error: the UI it would have
+// refreshed is gone with the session, so the message is dropped.
+//
+// A non-interactive session shows nothing. Under `pi -p`, `ctx.hasUI` is false
+// and `ctx.ui.notify` is a silent no-op. Commands whose only output is a notify
+// — /codecarto-status, /codecarto-usage, /codecarto-list-skills — then exit 0
+// having printed nothing, which is byte-for-byte what a silent refusal looks
+// like (#219). So when there is no UI, the message goes to stderr instead:
+// stderr rather than stdout because `--mode json` owns stdout for its event
+// stream and prose there would corrupt it.
+//
+// This is for the orchestrator's ctx only. Code that runs inside the phase
+// sub-agent (phase-compaction.ts) also sees `hasUI === false`, but there the
+// parent TUI may be on screen, and writing to stderr would put text into a live
+// terminal. That code keeps its own `if (ctx.hasUI)` guards.
+/** Whether `ctx` still belongs to the live session. See the module comment. */
+export function isCtxLive(ctx) {
+    try {
+        return typeof ctx.cwd === "string";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format a notification for a stream. Exported so tests pin the shape a script
+ * would parse: one line, prefixed, level visible.
+ */
+export function formatStreamNotification(message, level) {
+    return `[codecarto] ${level}: ${message}\n`;
+}
+/**
+ * Notify through `ctx`: the TUI when there is one, stderr when there is not,
+ * nothing when the ctx is stale.
+ */
+export function notifyCtx(ctx, message, level, stream = process.stderr) {
+    if (!isCtxLive(ctx))
+        return;
+    if (ctx.hasUI) {
+        ctx.ui.notify(message, level);
+        return;
+    }
+    stream.write(formatStreamNotification(message, level));
+}

package/package.json

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