codecartographer-pi 0.19.1 → 0.19.3

package/.codecarto/broadside/SKILL.md

@@ -90,6 +90,17 @@ Collect runs two cross-lens post-passes by default: **synthesis** (the
 executive report) and **triage** (the prioritized work order). Pass
 `include_synthesis: false` or `include_triage: false` on collect to skip one.
 
+Two caveats apply to any model you pick. The `models` action lists every id
+OpenRouter advertises a `:batch` variant for, and many of those variants do not
+exist — submitting one returns `does not have a :batch endpoint`, with nothing in
+the catalog to distinguish it beforehand. A rejected batch costs nothing, so
+probe a candidate on a single lens first. And reasoning competes with the answer for
+`max_tokens`: Broad-Side caps thinking at a quarter of each lens's output budget
+so three quarters remain for the JSON, which is the split the cost estimate
+already assumes. It caps rather than disables because some endpoints refuse to
+be switched off entirely. Override with `reasoning:` in `config.yaml` only
+alongside a raised output budget.
+
 Lenses do not all have to run on the same model. `lens_models` in `config.yaml`
 routes individual lenses to their own batch model — the usual reason being that
 a stronger model changes security and defect findings more than it changes an

package/.codecarto/broadside/config.yaml

@@ -46,9 +46,48 @@
 # and picking one for you would spend your money on our guess. Compare
 # candidates with the `models` action first.
 #
+# Two things to check before committing to a model, both learned the hard way:
+#
+#   1. The `models` action lists whatever OpenRouter advertises a `:batch`
+#      variant for, and a good number of those variants do not actually exist —
+#      submitting one comes back `Model '<id>' does not have a :batch endpoint.`
+#      Nothing in the catalog distinguishes them. Every Anthropic and OpenAI
+#      batch id tried so far is rejected this way; Google and DeepSeek work.
+#      A rejected batch costs nothing, so probe a candidate on one lens before
+#      relying on it.
+#   2. A reasoning-capable model spends its output budget thinking, and the
+#      thinking is billed at the full output rate. See `reasoning:` below.
+#
 # lens_models:
-#   security: anthropic/claude-opus-4.5:batch
-#   defect: anthropic/claude-opus-4.5:batch
+#   security: deepseek/deepseek-v4-pro-0813:batch
+#   defect: deepseek/deepseek-v4-pro-0813:batch
+
+# Reasoning control, sent on every lens request.
+#
+# By default Broad-Side caps thinking at a quarter of the lens's output budget,
+# leaving the other three quarters for the answer — which is exactly the split
+# the cost estimate already assumes.
+#
+# The cap exists because reasoning competes with the answer for `max_tokens`.
+# One measured run spent 5,758 of a 6,000-token budget thinking and left ~230
+# tokens for the JSON, which truncated mid-structure on 11 of 13 slices; those
+# tokens bill at the full output rate, so it paid for ~6,000 output tokens per
+# slice to receive ~230 usable ones. The shipped default model does the same
+# thing less consistently — reasoning from 0 to 5,757 tokens across 13 slices,
+# three of them cut off — so this is not something only exotic models do.
+#
+# It is a cap rather than an off switch on purpose. Some endpoints refuse to be
+# switched off: `google/gemini-3.8-flash:batch` rejects the entire batch with
+# "Reasoning is mandatory for this endpoint and cannot be disabled", which turns
+# a partial result into none at all. Capping works either way.
+#
+# Override only with a raised lens output budget, or the JSON truncates exactly
+# as above.
+#
+# reasoning:
+#   effort: low        # minimal | low | medium | high
+#   max_tokens: 2000   # or set the thinking budget directly
+#   enabled: false     # only where the provider allows it
 
 # Approximate run expense limit in USD (0 = no limit). Before submitting,
 # Broad-Side estimates the run cost from the collected file sizes and the

package/.codecarto/templates/phase-handoff.yaml

@@ -39,7 +39,8 @@ decisions: []
 #     evidence: <optional: where the pattern showed up>
 proposed_conventions: []
 closeout_summary: ""
-# Optional full closeout Markdown. YAML literal blocks are supported.
+# Optional full closeout Markdown. Block scalars are supported — literal (|, |-,
+# |+) to keep line breaks, folded (>, >-, >+) to join wrapped prose into one line.
 closeout_content: |-
   # Closeout — <phase-id>
 

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.1
+scaffold_version: 0.19.3

package/dist/core/broadside.d.ts

@@ -86,6 +86,46 @@ export type FileSlice = {
     /** Repo-relative paths of the files folded into this slice. */
     files: string[];
 };
+/**
+ * OpenRouter's unified `reasoning` control, as sent on a lens request.
+ *
+ * Left unsent, each model applies its own default — which is how a
+ * reasoning-capable model came to spend 5,758 of a 6,000-token output budget
+ * thinking, leaving ~230 tokens for JSON that then truncated mid-structure. The
+ * thinking is billed at the full *output* rate, so the run paid for roughly
+ * 6,000 output tokens per slice to receive 230 usable ones.
+ */
+export type BroadsideReasoning = {
+    enabled?: boolean;
+    effort?: "minimal" | "low" | "medium" | "high";
+    max_tokens?: number;
+};
+/**
+ * The share of a lens's output budget reasoning may spend.
+ *
+ * `estimateCost` already budgets output at 75% of `maxTokens`; capping thinking
+ * at the remaining quarter makes that assumption true by construction and
+ * guarantees the answer has room. A floor keeps the cap sane for a small lens.
+ */
+export declare const BROADSIDE_REASONING_BUDGET_FRACTION = 0.25;
+export declare const BROADSIDE_MIN_REASONING_TOKENS = 512;
+/**
+ * Cap reasoning for a lens request — deliberately a cap, not an off switch.
+ *
+ * Disabling outright is not portable: `google/gemini-3.8-flash:batch` refuses
+ * the whole batch with *"Reasoning is mandatory for this endpoint and cannot be
+ * disabled"*, turning a partial result into none at all. Capping works whether
+ * or not a provider allows reasoning to be switched off.
+ *
+ * The failure this prevents is the budget being spent thinking rather than
+ * answering. Measured on one run: 5,758 of a 6,000-token budget went to
+ * reasoning, leaving ~230 tokens for JSON that truncated mid-structure — and
+ * those tokens bill at the full output rate. The shipped default model does the
+ * same thing less consistently (reasoning tokens from 0 to 5,757 across 13
+ * slices, three of them cut off at `finish_reason: length`), so this is not a
+ * multi-model concern.
+ */
+export declare function defaultReasoningFor(maxTokens: number): BroadsideReasoning;
 export type BatchRequest = {
     custom_id: string;
     body: {
@@ -99,6 +139,7 @@ export type BatchRequest = {
             json_schema: JsonSchemaDef;
         };
         max_tokens: number;
+        reasoning?: BroadsideReasoning;
     };
 };
 export type BatchTerminalStatus = "completed" | "failed" | "expired" | "cancelled";
@@ -185,6 +226,8 @@ export type BroadsideConfig = {
      * trade-off is not the same for every lens.
      */
     lensModels: Partial<Record<BroadsideLensId, string>>;
+    /** Overrides every lens's reasoning setting when present. */
+    reasoning: BroadsideReasoning | null;
     /**
      * Repo defaults for the per-call run knobs. Each mirrors a tool parameter
      * of the same name; an explicit parameter always wins. They live here so a
@@ -304,6 +347,7 @@ type LensDefinition = {
     sliceBy: "none" | "directory" | "auto";
     maxChars: number;
     maxTokens: number;
+    reasoning?: BroadsideReasoning;
     skipTestFiles?: boolean;
     globsFor: (info: RepoInfo) => string[];
     systemPrompt: (info: RepoInfo) => string;
@@ -313,7 +357,7 @@ export declare function getLens(lensId: BroadsideLensId): LensDefinition;
 export declare function listLenses(): LensDefinition[];
 export declare function collectRepoInfo(targetDir: string): Promise<RepoInfo>;
 export declare function gatherSlices(targetDir: string, lens: LensDefinition, info: RepoInfo): Promise<FileSlice[]>;
-export declare function buildBatchRequest(lens: LensDefinition, info: RepoInfo, slice: FileSlice, index: number, sliceCount: number, model?: string, maxTokensOverride?: number): BatchRequest;
+export declare function buildBatchRequest(lens: LensDefinition, info: RepoInfo, slice: FileSlice, index: number, sliceCount: number, model?: string, maxTokensOverride?: number, reasoningOverride?: BroadsideReasoning): BatchRequest;
 /**
  * Pre-flight cost estimate for one lens.
  *

package/dist/core/broadside.js

@@ -74,6 +74,34 @@ export const BROADSIDE_LENS_IDS = [
 ];
 export const BROADSIDE_POLL_INTERVAL_MS = 15_000;
 export const BROADSIDE_DEFAULT_POLL_BUDGET_MS = 25 * 60 * 1000;
+/**
+ * The share of a lens's output budget reasoning may spend.
+ *
+ * `estimateCost` already budgets output at 75% of `maxTokens`; capping thinking
+ * at the remaining quarter makes that assumption true by construction and
+ * guarantees the answer has room. A floor keeps the cap sane for a small lens.
+ */
+export const BROADSIDE_REASONING_BUDGET_FRACTION = 0.25;
+export const BROADSIDE_MIN_REASONING_TOKENS = 512;
+/**
+ * Cap reasoning for a lens request — deliberately a cap, not an off switch.
+ *
+ * Disabling outright is not portable: `google/gemini-3.8-flash:batch` refuses
+ * the whole batch with *"Reasoning is mandatory for this endpoint and cannot be
+ * disabled"*, turning a partial result into none at all. Capping works whether
+ * or not a provider allows reasoning to be switched off.
+ *
+ * The failure this prevents is the budget being spent thinking rather than
+ * answering. Measured on one run: 5,758 of a 6,000-token budget went to
+ * reasoning, leaving ~230 tokens for JSON that truncated mid-structure — and
+ * those tokens bill at the full output rate. The shipped default model does the
+ * same thing less consistently (reasoning tokens from 0 to 5,757 across 13
+ * slices, three of them cut off at `finish_reason: length`), so this is not a
+ * multi-model concern.
+ */
+export function defaultReasoningFor(maxTokens) {
+    return { max_tokens: Math.max(BROADSIDE_MIN_REASONING_TOKENS, Math.floor(maxTokens * BROADSIDE_REASONING_BUDGET_FRACTION)) };
+}
 /** Thrown when a confirm hook declines a run. Nothing was submitted. */
 export class BroadsideCancelledError extends Error {
     constructor(message = "Broad-Side submission cancelled. Nothing was submitted.") {
@@ -1136,7 +1164,7 @@ async function sumFileSizes(targetDir, files) {
     return total;
 }
 // ---------- request building ----------
-export function buildBatchRequest(lens, info, slice, index, sliceCount, model = BROADSIDE_MODEL, maxTokensOverride) {
+export function buildBatchRequest(lens, info, slice, index, sliceCount, model = BROADSIDE_MODEL, maxTokensOverride, reasoningOverride) {
     const moduleTag = sanitizeId(slice.moduleName);
     const customId = sliceCount > 1 ? `${lens.id}-${moduleTag}-${index + 1}` : `${lens.id}-${moduleTag}`;
     return {
@@ -1149,6 +1177,9 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
             ],
             response_format: { type: "json_schema", json_schema: SCHEMAS[lens.schemaName] },
             max_tokens: maxTokensOverride ?? lens.maxTokens,
+            // Always sent, never inherited: an absent field means the model's
+            // own default, and that default is what truncated the JSON.
+            reasoning: reasoningOverride ?? lens.reasoning ?? defaultReasoningFor(maxTokensOverride ?? lens.maxTokens),
         },
     };
 }
@@ -1297,6 +1328,24 @@ export async function persistBroadsideRun(broadsideDir, run) {
             state.runs[index] = run;
     });
 }
+/** Read a `reasoning:` block from config.yaml, ignoring anything malformed. */
+function parseReasoningConfig(raw) {
+    if (raw === false)
+        return { enabled: false };
+    if (raw === true)
+        return { enabled: true };
+    if (!raw || typeof raw !== "object")
+        return null;
+    const value = raw;
+    const out = {};
+    if (typeof value.enabled === "boolean")
+        out.enabled = value.enabled;
+    if (value.effort === "minimal" || value.effort === "low" || value.effort === "medium" || value.effort === "high")
+        out.effort = value.effort;
+    if (typeof value.max_tokens === "number" && value.max_tokens > 0)
+        out.max_tokens = value.max_tokens;
+    return Object.keys(out).length > 0 ? out : null;
+}
 export async function loadBroadsideConfig(broadsideDir) {
     const configPath = join(broadsideDir, BROADSIDE_CONFIG_FILE);
     let raw = {};
@@ -1337,6 +1386,10 @@ export async function loadBroadsideConfig(broadsideDir) {
             ? { inputPerM: inputOverride, outputPerM: outputOverride }
             : null,
         lensModels,
+        // An escape hatch, not a knob to reach for: a model whose reasoning is
+        // worth paying for needs its lens maxTokens raised to cover both the
+        // thinking and the answer, or the JSON truncates exactly as before.
+        reasoning: parseReasoningConfig(raw.reasoning),
         incremental: flag("incremental", false),
         retryTruncated: flag("retry_truncated", true),
         includeSynthesis: flag("include_synthesis", true),
@@ -1797,7 +1850,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const { lens, maxTokens, lensModel, lensOutputCap } = priced;
         const lensId = lens.id;
         const slices = slicesByLens.get(lensId) ?? [];
-        const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens));
+        const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens, config.reasoning ?? undefined));
         for (const request of requests)
             requestsByCustomId[request.custom_id] = request;
         const entry = {

package/dist/core/yaml.js

@@ -105,6 +105,61 @@ export function parseYamlScalar(rawValue) {
     }
     return trimmed;
 }
+function parseBlockScalarHeader(rawValue) {
+    const match = /^([|>])([-+]?)$/.exec(rawValue);
+    if (!match)
+        return null;
+    return {
+        literal: match[1] === "|",
+        chomp: match[2] === "-" ? "strip" : match[2] === "+" ? "keep" : "clip",
+    };
+}
+/**
+ * Fold a block scalar's lines per YAML's folding rules: a single line break
+ * between two content lines becomes a space, and a run of k blank lines becomes
+ * k newlines. Lines indented deeper than the block's own content indent are
+ * "more indented" and keep their breaks literally, which is what lets a folded
+ * block hold an indented snippet without it being flattened onto one line.
+ */
+function foldBlockLines(blockLines) {
+    let result = "";
+    let pendingBreaks = 0;
+    let started = false;
+    let previousMoreIndented = false;
+    for (const line of blockLines) {
+        if (line.trim() === "") {
+            pendingBreaks++;
+            continue;
+        }
+        const moreIndented = /^[ \t]/.test(line);
+        if (!started) {
+            result = line;
+            started = true;
+            previousMoreIndented = moreIndented;
+            continue;
+        }
+        if (pendingBreaks > 0) {
+            result += "\n".repeat(pendingBreaks);
+            pendingBreaks = 0;
+        }
+        else if (moreIndented || previousMoreIndented) {
+            result += "\n";
+        }
+        else {
+            result += " ";
+        }
+        result += line;
+        previousMoreIndented = moreIndented;
+    }
+    return started ? result + "\n".repeat(pendingBreaks) : "";
+}
+function applyBlockScalar(blockLines, header) {
+    const content = header.literal ? blockLines.join("\n") : foldBlockLines(blockLines);
+    if (header.chomp === "keep")
+        return content;
+    const stripped = content.replace(/\n+$/, "");
+    return header.chomp === "strip" ? stripped : `${stripped}\n`;
+}
 export function parseSimpleYaml(raw) {
     const lines = raw.split(/\r?\n/);
     let index = 0;
@@ -164,7 +219,8 @@ export function parseSimpleYaml(raw) {
                 throw new Error(`Duplicate YAML key: ${key} near line: ${line.trim()}`);
             }
             seen.add(key);
-            if (rawValue === "|" || rawValue === "|-") {
+            const blockHeader = parseBlockScalarHeader(rawValue);
+            if (blockHeader) {
                 const blockLines = [];
                 let contentIndent = null;
                 while (index < lines.length) {
@@ -181,8 +237,7 @@ export function parseSimpleYaml(raw) {
                     blockLines.push(blockLine.slice(Math.min(contentIndent, blockIndent)));
                     index++;
                 }
-                const content = blockLines.join("\n").replace(/\n+$/, "");
-                assign(key, rawValue === "|" ? `${content}\n` : content);
+                assign(key, applyBlockScalar(blockLines, blockHeader));
                 continue;
             }
             if (rawValue !== "") {

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

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

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

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

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

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

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

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

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

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

package/dist/extensions/codecarto/guide-framing.d.ts

@@ -0,0 +1,11 @@
+/** Tool names in the guide that have no Pi slash command. */
+export declare const MCP_ONLY_TOOLS: readonly ["codecarto_library_list", "codecarto_library_reindex"];
+export declare const GUIDE_PREAMBLE: string;
+export declare const PI_SURFACE_ADDENDUM: string;
+/**
+ * Assemble the message /codecarto-guide queues. The guide document is embedded
+ * whole and unmodified between the framing and the addendum — `guide.test.mjs`
+ * pins that documents are served entire rather than summarized, and that holds
+ * on this surface too.
+ */
+export declare function buildPiGuideMessage(documentContent: string, otherTopics: readonly string[]): string;

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

@@ -0,0 +1,55 @@
+// Surface framing for the packaged agent guide when it is read into a Pi
+// session.
+//
+// Two problems this solves, both invisible on the MCP surface:
+//
+// 1. The guide arrives as a user message. /codecarto-guide queues the document
+//    through pi.sendUserMessage, so ~200 lines of imperative instructions land
+//    as if the user had typed them, with no task attached. A model handed
+//    instructions and no task either starts driving immediately or stalls
+//    asking what to do; both are wrong for what is a reference lookup.
+//
+// 2. The guide is written for the MCP surface. It tells the agent to call
+//    codecarto_* tools — but the Pi extension registers no tools at all, only
+//    slash commands the *user* invokes. A model that tries to follow it finds
+//    nothing to call and reasonably concludes the server is missing. The drive
+//    loop differs too: on Pi, /codecarto-next runs the phase as an isolated
+//    sub-agent and then auto-validates and auto-completes it, so the guide's
+//    hand-written execute → handoff → validate → complete loop does not
+//    describe a Pi session.
+//
+// The guide text itself stays untouched — agent-skill/ is the single source and
+// core/guide.ts serves it verbatim to every surface. Per-surface adaptation
+// belongs in the wrapper, which is here.
+/** Tool names in the guide that have no Pi slash command. */
+export const MCP_ONLY_TOOLS = ["codecarto_library_list", "codecarto_library_reindex"];
+export const GUIDE_PREAMBLE = [
+    "**CodeCartographer guide — reference material, not a task.**",
+    "",
+    "The user ran `/codecarto-guide`, which queues the guide below into this session so it is available when needed. Nothing is being asked of you yet.",
+    "",
+    "Do not start a workflow, do not begin a phase, and do not ask which repository or pipeline to use. Acknowledge in a sentence that you have read it, then wait. Answer from it when the user asks.",
+].join("\n");
+export const PI_SURFACE_ADDENDUM = [
+    "---",
+    "",
+    "## Reading this guide in a Pi session",
+    "",
+    "The guide above is written for the MCP surface, where an agent drives the workflow by calling `codecarto_*` tools. **This session is the Pi extension, which registers no tools.** There is nothing named `codecarto_*` for you to call, and their absence does not mean a server is missing or misconfigured.",
+    "",
+    `- **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.",
+].join("\n");
+/**
+ * Assemble the message /codecarto-guide queues. The guide document is embedded
+ * whole and unmodified between the framing and the addendum — `guide.test.mjs`
+ * pins that documents are served entire rather than summarized, and that holds
+ * on this surface too.
+ */
+export function buildPiGuideMessage(documentContent, otherTopics) {
+    const footer = otherTopics.length > 0
+        ? `\n\n---\nOther guide topics: ${otherTopics.join(", ")} (run /codecarto-guide <topic>).`
+        : "";
+    return `${GUIDE_PREAMBLE}\n\n---\n\n${documentContent}\n\n${PI_SURFACE_ADDENDUM}${footer}`;
+}

package/dist/extensions/codecarto/index.js

@@ -8,6 +8,7 @@ import { narrateDashboard } from "./dashboard-narrator.js";
 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 { 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";
@@ -785,7 +786,25 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
-            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx.cwd, validation);
+            // Completion refuses for reasons the framework words carefully — a
+            // missing phase handoff, a carry-forward without `derives_from`, a
+            // closure lacking runtime evidence. Those messages are the whole
+            // point of the refusal, and this was the one call in this file that
+            // let them escape as a rejection instead of showing them. The
+            // irony was sharp: /codecarto-next catches this same throw and tells
+            // the user to run /codecarto-complete manually, which then threw.
+            let completion;
+            try {
+                completion = await autoCompletePhase(ctx.cwd, validation);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lastFeedbackLines = [`Completion refused: ${message}`];
+                setUiState(ctx, currentState, lastFeedbackLines);
+                ctx.ui.notify(message, "error");
+                return;
+            }
+            const { updatedState, closeoutNotice, warnings } = completion;
             lastFeedbackLines = [
                 `Completed phase: ${validation.phaseId}`,
                 `Validation: ${validation.overall}`,
@@ -919,10 +938,10 @@ export default function codeCartographerExtension(pi) {
                 return;
             }
             const other = topics.filter((name) => name !== document.topic);
-            const footer = other.length > 0
-                ? `\n\n---\nOther guide topics: ${other.join(", ")} (run /codecarto-guide <topic>).`
-                : "";
-            const message = `${document.content}${footer}`;
+            // Framed, not bare: the guide is MCP-centric text arriving as a user
+            // message, so it needs both a "this is reference, not a task" header
+            // and a Pi-surface addendum. See guide-framing.ts.
+            const message = buildPiGuideMessage(document.content, other);
             if (ctx.isIdle()) {
                 pi.sendUserMessage(message);
             }

package/package.json

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