@hicaru/pi-rlm 0.3.20 → 0.3.22

package/src/tool/repl-render.ts

@@ -1,14 +1,37 @@
-/** repl() tool TUI views — the single-line card and the expanded output view.
+/** repl() tool TUI views — call card (code payload), collapsed/expanded result views.
  * Sub-call trees are not rendered here; the live tree widget owns agent visualization. */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { CALL_PREVIEW_CHARS, previewText } from "../text/preview.ts";
 import type { ReplDetails } from "./repl-details.ts";
+import { highlightPython } from "../ui/python-highlight.ts";
 import { cardHeader, cardStatsLine, renderCollapsedCard } from "./subcall-render.ts";
 
 /** Chars of stdout/stderr shown in the expanded view. */
 const EXPANDED_STDOUT_CHARS = 2_000;
 const EXPANDED_STDERR_CHARS = 500;
+/** Lines of Python source shown on the collapsed card before the "+N more lines" cut. */
+const CODE_PREVIEW_LINES = 40;
+
+// ── Call card ──
+
+/**
+ * The tool-call row. The collapsed card's payload IS the source — expanding swaps it for the
+ * result view (context.expanded). While args still stream in (context.argsComplete false),
+ * keep the one-line preview: half-arrived code reads as garbage.
+ */
+export function replCallView(
+  args: { readonly code: string },
+  theme: Theme,
+  context?: { readonly expanded?: boolean; readonly argsComplete?: boolean },
+): Text {
+  const header = theme.fg("toolTitle", theme.bold("repl ")) + theme.fg("dim", previewText(args.code, CALL_PREVIEW_CHARS));
+  if (context?.expanded === true || context?.argsComplete === false) {
+    return new Text(header, 0, 0);
+  }
+  return new Text([header, "", renderReplCode(args.code, theme)].join("\n"), 0, 0);
+}
 
 // ── Collapsed view ──
 
@@ -18,7 +41,20 @@ function replStats(details: ReplDetails, theme: Theme): string {
 }
 
 export function renderReplCollapsed(details: ReplDetails, theme: Theme): Text {
-  return renderCollapsedCard("REPL", details.status, replStats(details, theme), theme);
+  // Collapsed shows the CODE (replCallView); expanding reveals the result — say so.
+  return renderCollapsedCard("REPL", details.status, replStats(details, theme), theme, "to show result");
+}
+
+/**
+ * The collapsed card's payload — the cell's Python source, capped. Full source lives in the
+ * session args; expanding swaps this block for the result view (see replCallView). Sliced
+ * BEFORE highlighting so a triple-quoted string cut by the cap can only fall back to plain.
+ */
+export function renderReplCode(code: string, theme: Theme): string {
+  const lines = code.split("\n");
+  const shown = highlightPython(lines.slice(0, CODE_PREVIEW_LINES).join("\n"), theme);
+  const rest = lines.length - CODE_PREVIEW_LINES;
+  return rest > 0 ? `${shown}\n${theme.fg("muted", `… +${String(rest)} more lines`)}` : shown;
 }
 
 // ── Expanded view ──

package/src/tool/repl-tool.ts

@@ -23,6 +23,7 @@ import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { buildAddContextHandler, type AddContextHandlerBundle } from "../bridge/add-context.ts";
 import { contextPrefixesIn } from "../context/namespace.ts";
 import type { SubcallGates } from "../util/concurrency.ts";
+import { raceAbort } from "../util/abort.ts";
 import { LimitGuard, limitsFromConfig } from "../core/limits.ts";
 import type { RlmConfig, RlmInput, RlmResult } from "../core/types.ts";
 import { SandboxManager } from "../sandbox/sandbox-manager.ts";
@@ -40,7 +41,7 @@ import { createEngine } from "../core/engine.ts";
 import type { RunState } from "../core/run-state.ts";
 import { modelRef } from "../config/settings.ts";
 import { spinnerFrame } from "../ui/theme.ts";
-import { CALL_PREVIEW_CHARS, previewText } from "../text/preview.ts";
+import { previewText } from "../text/preview.ts";
 import { errorMessage } from "../util/errors.ts";
 import {
   groundLeafPrompt,
@@ -49,7 +50,7 @@ import {
 } from "../config/skillstate.ts";
 import { createProgressNotifier, validateToolParams } from "./tool-utils.ts";
 import { buildReplResultText, collectReplWarnings } from "./repl-result.ts";
-import { renderReplCollapsed, renderReplExpanded } from "./repl-render.ts";
+import { renderReplCollapsed, renderReplExpanded, replCallView } from "./repl-render.ts";
 import { attachTracer, trace, traceEnabled } from "../util/trace.ts";
 
 /** Last non-empty line of a Python traceback — the `TypeError: …` line, not the frames. */
@@ -129,7 +130,12 @@ interface ReplToolDeps {
   readonly getSkillBlock?: (task: string) => string | undefined;
   /** Session tree panel index; omitted → runs don't appear in the widget. */
   readonly runRegistry?: RunRegistry;
-  readonly signal?: AbortSignal;
+  /**
+   * Live abort signal accessor — read per child engine / sub-call / exec, NOT captured at
+   * registration. /rlm-stop aborts and ROTATES the session controller, so a stale signal
+   * must never outlive the call that started it.
+   */
+  readonly getSignal?: () => AbortSignal | undefined;
   readonly onUsage?: (usage: Usage, role: "sub") => void;
   readonly ensureContext?: () => Promise<void>;
   /** Register a reset hook for sandbox death/dispose (e.g. add_context prefix cache). */
@@ -142,7 +148,9 @@ interface ReplToolDeps {
 }
 
 export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplToolParams, ReplDetails> {
-  const { sandboxManager, llmModel, registry, getConfig, signal, onUsage, background } = deps;
+  const { sandboxManager, llmModel, registry, getConfig, onUsage, background } = deps;
+  // Read per use, never captured: see ReplToolDeps.getSignal.
+  const currentSignal = (): AbortSignal | undefined => deps.getSignal?.();
   const bridgeState = new NativeBridgeState(background);
   // v5: one session-wide blackboard for the native repl() path — the same claim/coalesce/
   // demote logic the engine gets per run, shared by every turn and every child it spawns.
@@ -177,7 +185,7 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
       llmModel: getLlmModel(),
       registry,
       config: getConfig(),
-      signal,
+      signal: currentSignal(),
       gates: currentGates(),
       // Same emitter the parent subcall node lives on — see SubcallHandlerDeps.runChild.
       emitter: inv.emitter,
@@ -202,7 +210,9 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
     getLlmModel,
     getModel,
     getConfig,
-    signal,
+    get signal() {
+      return currentSignal();
+    },
     onUsage,
     runChild,
     // The session sandbox's context is the child's world. Read lazily so an add_context from an
@@ -224,7 +234,9 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         // committed for an append that did not happen.
         getContext: () => sandboxManager.contextPayload,
         parentId: undefined,
-        signal,
+        get signal() {
+          return currentSignal();
+        },
         // Keep the manager's replay copy in step with the worker's live `context`, and with it
         // whatever a child spawned after this load will inherit.
         onLoaded: (payload) => { sandboxManager.appendContext(payload); },
@@ -368,12 +380,19 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         // spawns claim against an empty stack, so an originator can never echo against
         // itself. Duplicates are caught by the ledger's claim store (exact/near
         // coalescing + rlmBudget demotion), never by silent suppression.
-        const result: ReplResult = await sandboxManager.execWithSetup(params.code, () => {
-          // Wire per-invocation mutable state only after the serialized exec slot
-          // is active. Swapping earlier would let queued repl() calls overwrite
-          // emitter/limits for the currently running REPL execution.
-          bridgeState.swap({ emitter, parentId: undefined, depth: 0, limits });
-        }, execSignal);
+        // The cell races pi's per-call signal (esc) against /rlm-stop's session signal.
+        const cellAbort = raceAbort(execSignal, currentSignal());
+        let result: ReplResult;
+        try {
+          result = await sandboxManager.execWithSetup(params.code, () => {
+            // Wire per-invocation mutable state only after the serialized exec slot
+            // is active. Swapping earlier would let queued repl() calls overwrite
+            // emitter/limits for the currently running REPL execution.
+            bridgeState.swap({ emitter, parentId: undefined, depth: 0, limits });
+          }, cellAbort.signal);
+        } finally {
+          cellAbort.dispose();
+        }
         const elapsed = Date.now() - start;
         capturedStdout = result.stdout;
         capturedStderr = result.stderr;
@@ -470,11 +489,8 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
       }
     },
 
-    renderCall(args, theme) {
-      return new Text(
-        theme.fg("toolTitle", theme.bold("repl ")) + theme.fg("dim", previewText(args.code, CALL_PREVIEW_CHARS)),
-        0, 0,
-      );
+    renderCall(args, theme, context) {
+      return replCallView(args, theme, context);
     },
 
     renderResult(result, { expanded }, theme) {

package/src/tool/subcall-render.ts

@@ -64,21 +64,24 @@ export function cardHeader(
  * Deliberately `keyText` + the injected theme rather than pi's `keyHint`: `keyHint` colours via
  * pi's module-global theme, which throws when that global is uninitialized — the same jiti
  * hazard `ui/theme-adapter.ts` exists to avoid. `keyText` only reads the keybinding registry.
+ * Shared by tool cards AND the [rlm.stage] transcript cards (ui/stage-cards.ts).
  */
-function expandHint(theme: Theme): string {
+export function expandHint(theme: Theme, action = "to expand"): string {
   // Empty outside a live pi session (the app installs the real binding registry at startup) —
   // the phrase stays the same, only the key prefix drops out.
   const key = keyText("app.tools.expand");
-  return theme.fg("muted", key ? `${key} to expand` : "to expand");
+  return theme.fg("muted", key ? `${key} ${action}` : action);
 }
 
-/** The collapsed card: header line, then the expand hint once settled. */
+/** The collapsed card: header line, then the expand hint once settled. `action` labels what
+ * expanding reveals — the repl card says "to show result" (collapsed shows the code instead). */
 export function renderCollapsedCard(
   title: string,
   status: SubcallStatus | "aborted" | "done",
   stats: string,
   theme: Theme,
+  action = "to expand",
 ): Text {
-  const hint = status === "running" ? "" : `\n${expandHint(theme)}`;
+  const hint = status === "running" ? "" : `\n${expandHint(theme, action)}`;
   return new Text(`${cardHeader(title, status, stats, theme)}${hint}`, 0, 0);
 }

package/src/ui/config-panel.ts

@@ -67,9 +67,9 @@ export async function showConfigPanel(ctx: ExtensionContext, config: RlmConfig):
       "Seed the working directory into context on the first repl() call (otherwise starts empty)."),
     // R5: the window calibrations are rlm.json-only knobs — shown read-only with live values.
     item("__sigma_window__", "Root Σ window (calibration)",
-      `keepTurns=${config.rootContextKeepTurns} · elide=${config.rootContextElideChars} · snapshot=${config.rootContextSnapshot ? "on" : "off"}`,
+      `keepTurns=${config.rootContextKeepTurns} · elide=${config.rootContextElideChars} · snapshot=${config.rootContextSnapshot ? "on" : "off"} · archive=${config.rootArchiveMaxChars > 0 ? `${Math.round(config.rootArchiveMaxChars / 1000)}k` : "off"}`,
       ["rlm.json"],
-      "Query-time window calibrations, rlm.json only: rootContextKeepTurns (1 = strict: Σ + current turn; 2 = default), rootContextElideChars, rootContextSnapshot. " +
+      "Query-time window calibrations, rlm.json only: rootContextKeepTurns (4 = default), rootContextElideChars, rootContextSnapshot, rootArchiveMaxChars (0 = archive off; elided turns are otherwise unrecoverable). " +
         "Session resume/fork: the tracker is reborn lazily and Σ re-grows from live observations — the first call after a resume has an empty Σ by design."),
     item("__save__", "Save & close", "↵", ["↵"], "Save these settings and close (Esc also saves)."),
   ];

package/src/ui/intro.ts

@@ -14,7 +14,7 @@ const RLM_GUIDE = `# RLM mode
 - \`/rlm-llm\` — pin the LLM model for llm_query / llm_batch / map_files
 - \`/rlm-rlm\` — pin the model for rlm_query / rlm_batch child engines (default: session model)
 - \`/rlm-config\` — run limits and engine settings
-- \`/rlm-stop\` — cancel the current run but stay in RLM mode (use /rlm or Ctrl+Shift+R to leave)
+- \`/rlm-stop\` — abort all in-flight RLM work: RLM runs, native repl cells and background tasks (use /rlm or Ctrl+Shift+R to leave RLM mode)
 
 ## Live tree
 

package/src/ui/python-highlight.ts

@@ -0,0 +1,49 @@
+/**
+ * python-highlight — minimal Python syntax coloring for the repl card's code payload.
+ *
+ * Deliberately NOT pi's highlightCode(): that closes over the module-global theme,
+ * which is unreliable inside a jiti-loaded plugin (see ui/theme-adapter.ts). The
+ * grammar here is a small, honest subset — comments, strings (triple-quoted and
+ * prefixed), keywords, numbers, decorators — enough to read a cell at a glance.
+ * Colors come from the theme pi hands each render pass.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Master pattern; alternation order is priority — a `#` comment consumes to end-of-line
+ * before strings can match, leftmost match wins everywhere else. Group indices:
+ * 1 comment, 2 triple-quoted string, 3 single-line string (optional prefix), 4 decorator,
+ * 5 number, 6 keyword. Module-level snapshot: a regex is immutable state, not session state.
+ */
+const TOKEN_RE = new RegExp(
+  [
+    "(#[^\\n]*)",                                                                                       // 1
+    '("""[\\s\\S]*?"""|\'\'\'[\\s\\S]*?\'\'\')',                                                        // 2
+    '([fFrRbBuU]{0,2}"(?:\\\\.|[^"\\\\\\n])*"|[fFrRbBuU]{0,2}\'(?:\\\\.|[^\'\\\\\\n])*\')',             // 3
+    "(@[A-Za-z_][\\w.]*)",                                                                              // 4
+    "\\b(\\d[\\d_]*(?:\\.\\d+)?(?:[eE][+-]?\\d+)?j?)\\b",                                               // 5
+    "\\b(False|None|True|and|as|assert|async|await|break|class|continue|def|del|elif|else|except|" +
+      "finally|for|from|global|if|import|in|is|lambda|nonlocal|not|or|pass|raise|return|try|while|with|yield)\\b", // 6
+  ].join("|"),
+  "g",
+);
+
+/** The whole code colored in one pass; spans never overlap, text content is preserved byte-for-byte. */
+export function highlightPython(code: string, theme: Theme): string {
+  const out: string[] = [];
+  let last = 0;
+  for (const m of code.matchAll(TOKEN_RE)) {
+    const at = m.index ?? 0;
+    if (at > last) out.push(code.slice(last, at));
+    const [raw = "", comment, triple, str, decorator, num, keyword] = m;
+    if (comment !== undefined) out.push(theme.fg("muted", comment));
+    else if (triple !== undefined || str !== undefined) out.push(theme.fg("mdCode", raw));
+    else if (decorator !== undefined) out.push(theme.fg("mdHeading", decorator));
+    else if (num !== undefined) out.push(theme.fg("warning", num));
+    else out.push(theme.fg("accent", keyword));
+    last = at + raw.length;
+  }
+  if (last < code.length) out.push(code.slice(last));
+  return out.join("");
+}

package/src/ui/stage-cards.ts

@@ -0,0 +1,192 @@
+/**
+ * stage-cards — [rlm.stage] transcript cards for orchestrator stage transitions.
+ *
+ * Same visual language as zebra-catch's finding cards: a `**◆ …**` header with
+ * status + stats, a body paragraph, `− tag (source)` bullets — sent via
+ * `pi.sendMessage({ customType, display: true })` so pi draws the labeled box.
+ * The renderer honors `options.expanded`, which pi's CustomMessageComponent
+ * re-invokes on the user's ctrl+o (app.tools.expand) — collapsed shows the
+ * header + expand hint, expanded shows the full card. Digest bodies embed the
+ * root-digest text VERBATIM (glossary wording — never re-worded here).
+ *
+ * Pure builders + one renderer; emission points live in the rlmExtension
+ * closure (src/index.ts) — no session state at module load.
+ */
+
+import { Box, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { MessageRenderer, Theme } from "@earendil-works/pi-coding-agent";
+import type { SkillNoteInput } from "../config/skillstate.ts";
+import { previewText } from "../text/preview.ts";
+import { expandHint } from "../tool/subcall-render.ts";
+import { formatTokens } from "./theme.ts";
+import { markdownTheme } from "./theme-adapter.ts";
+
+/** The transcript tag pi renders for these cards — `[rlm.stage]`. */
+export const STAGE_CUSTOM_TYPE = "rlm.stage";
+
+/** Distill bullets shown before the "+N more" ellipsis. */
+const DISTILL_BULLET_CAP = 8;
+/** Note text cap inside a distill bullet — the full note lives in skill.state itself. */
+const DISTILL_TEXT_CHARS = 100;
+
+/** One orchestrator stage transition. Discriminated — the renderer never guesses. */
+export type StageCardDetails =
+  | {
+      readonly kind: "digest";
+      /** 1-based compaction index (rootDigests counter at emit time). */
+      readonly index: number;
+      readonly turnsFolded: number;
+      /** Host-consumed token estimate for the displaced span (V1 soak probe). */
+      readonly tokensBefore: number;
+      /** Our own estimate over the same span — divergence here is the probe's signal. */
+      readonly tokensBeforeRecomputed: number;
+      /** The root-digest summary text, embedded verbatim when expanded. */
+      readonly summary: string;
+    }
+  | {
+      readonly kind: "degrade";
+      readonly reason: string;
+      readonly idleTurns: number;
+      readonly idleMax: number;
+    }
+  | {
+      readonly kind: "recover";
+      readonly fencesAccepted: number;
+      readonly fencesTotal: number;
+    }
+  | {
+      readonly kind: "distill";
+      /** The notes this session contributed (pre-id/hits inputs, as handed to SkillStore.merge). */
+      readonly merged: readonly SkillNoteInput[];
+      readonly total: number;
+      readonly byTag: Readonly<Record<string, number>>;
+    };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Runtime guard for details replayed from old/corrupt session files — fail-soft, never throws. */
+export function isStageCardDetails(value: unknown): value is StageCardDetails {
+  if (!isRecord(value)) return false;
+  switch (value.kind) {
+    case "digest":
+      return (
+        typeof value.index === "number" &&
+        typeof value.turnsFolded === "number" &&
+        typeof value.tokensBefore === "number" &&
+        typeof value.tokensBeforeRecomputed === "number" &&
+        typeof value.summary === "string"
+      );
+    case "degrade":
+      return (
+        typeof value.reason === "string" &&
+        typeof value.idleTurns === "number" &&
+        typeof value.idleMax === "number"
+      );
+    case "recover":
+      return typeof value.fencesAccepted === "number" && typeof value.fencesTotal === "number";
+    case "distill": {
+      if (typeof value.total !== "number" || !Array.isArray(value.merged) || !isRecord(value.byTag)) return false;
+      if (!Object.values(value.byTag).every((v) => typeof v === "number")) return false;
+      return value.merged.every((note) => isRecord(note) && typeof note.text === "string");
+    }
+    default:
+      return false;
+  }
+}
+
+/** "gotcha 4 · recipe 3" — tags with a nonzero count, insertion order. */
+function byTagPart(byTag: Readonly<Record<string, number>>): string {
+  const parts: string[] = [];
+  for (const [tag, count] of Object.entries(byTag)) {
+    if (count > 0) parts.push(`${tag} ${String(count)}`);
+  }
+  return parts.length === 0 ? "" : ` (${parts.join(" · ")})`;
+}
+
+/** The `**◆ …**` headline — the only thing visible while collapsed. */
+export function stageCardHeaderLine(details: StageCardDetails): string {
+  switch (details.kind) {
+    case "digest":
+      return (
+        `**◆ digest #${String(details.index)}** folded ${String(details.turnsFolded)} turns · ` +
+        `${formatTokens(details.tokensBefore)} tok (recomputed ${formatTokens(details.tokensBeforeRecomputed)})`
+      );
+    case "degrade":
+      return (
+        `**⚠ Σ degraded** idle ${String(details.idleTurns)}/${String(details.idleMax)} fence-eligible turns · ` +
+        previewText(details.reason, 80)
+      );
+    case "recover":
+      return `**◆ Σ recovered** fences accepted ${String(details.fencesAccepted)}/${String(details.fencesTotal)}`;
+    case "distill":
+      return (
+        `**◆ skill.state** +${String(details.merged.length)} notes distilled · ` +
+        `${String(details.total)} total${byTagPart(details.byTag)}`
+      );
+  }
+}
+
+/** Body under the header — blank for recover (the headline says it all). */
+function stageCardBody(details: StageCardDetails): string {
+  switch (details.kind) {
+    case "digest":
+      return details.summary;
+    case "degrade":
+      return "− splices paused; tool outcomes still feed Σ (observe floor)";
+    case "distill": {
+      const shown = details.merged.slice(0, DISTILL_BULLET_CAP);
+      const lines = new Array<string>(shown.length);
+      for (let i = 0; i < shown.length; i++) {
+        const note = shown[i];
+        if (note === undefined) continue;
+        lines[i] = `− ${note.tags?.[0] ?? "note"}: ${previewText(note.text, DISTILL_TEXT_CHARS)}`;
+      }
+      const rest = details.merged.length - shown.length;
+      return rest > 0 ? [...lines, `− +${String(rest)} more`].join("\n") : lines.join("\n");
+    }
+    case "recover":
+      return "";
+  }
+}
+
+/** Full card content — what sendMessage stores and what expanded rendering shows. */
+export function stageCardMarkdown(details: StageCardDetails): string {
+  const body = stageCardBody(details);
+  return body === "" ? stageCardHeaderLine(details) : `${stageCardHeaderLine(details)}\n\n${body}`;
+}
+
+/** Markdown block styled through the injected theme's adapter. */
+function themedMarkdown(text: string, theme: Theme): Markdown {
+  return new Markdown(text, 0, 0, markdownTheme(theme), {
+    color: (t) => theme.fg("customMessageText", t),
+  });
+}
+
+/**
+ * The [rlm.stage] message renderer — mirrors pi's default custom-message box
+ * (labeled Box + Markdown) but honors `expanded`: collapsed shows just the
+ * headline + expand hint, expanded the full card. Returns undefined on
+ * stale/corrupt details so pi falls back to default rendering (fail-soft,
+ * host contract).
+ */
+export const renderStageCard: MessageRenderer = (message, options, theme) => {
+  try {
+    if (!isStageCardDetails(message.details)) return undefined;
+    const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
+    box.addChild(new Text(theme.fg("customMessageLabel", theme.bold(`[${STAGE_CUSTOM_TYPE}]`)), 0, 0));
+    box.addChild(new Spacer(1));
+    box.addChild(themedMarkdown(
+      options.expanded ? stageCardMarkdown(message.details) : stageCardHeaderLine(message.details),
+      theme,
+    ));
+    if (!options.expanded) {
+      box.addChild(new Spacer(1));
+      box.addChild(new Text(expandHint(theme), 0, 0));
+    }
+    return box;
+  } catch {
+    return undefined; // default rendering shows the stored markdown instead
+  }
+};

package/src/ui/theme-adapter.ts

@@ -5,19 +5,87 @@
  * loaded through jiti, which gives them a separate module cache, so that global can be
  * `undefined` inside a plugin — pi documents this footgun on `DynamicBorder`. Every renderer
  * pi calls hands us a live `Theme`, so we build the adapter from that instead of the global.
+ *
+ * Fork hosts (oh-my-pi) remap `@earendil-works/pi-tui` to their own bundled copy, whose
+ * `Markdown` requires a nested `symbols` record on the theme (`theme.symbols.table/hrChar/
+ * quoteBorder/colorSwatch`) in addition to the upstream render functions. Their `Theme.md`
+ * getter is NOT a MarkdownTheme — it is a flat symbol-string partial
+ * (`{ quoteBorder, hrChar, bullet, colorSwatch }`), so returning it raw amputates the render
+ * functions and the host crashes (`this.#r.heading is not a function`). Hence the merge
+ * below: base functions from the injected theme, function-valued host overrides on top,
+ * and the flat strings folded into a complete `symbols` record with safe defaults.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { MarkdownTheme } from "@earendil-works/pi-tui";
 
+/** The `symbols` record fork hosts read off a MarkdownTheme (upstream has no such key). */
+interface MarkdownThemeSymbols {
+  readonly colorSwatch: string;
+  readonly hrChar: string;
+  readonly quoteBorder: string;
+  readonly bullet?: string;
+  readonly table: Readonly<Record<string, string>>;
+}
+
+/** Safe defaults covering every symbol a fork's `Markdown` dereferences (omp: table/hrChar/quoteBorder/colorSwatch). */
+const FALLBACK_SYMBOLS: MarkdownThemeSymbols = Object.freeze({
+  colorSwatch: "●",
+  hrChar: "─",
+  quoteBorder: "▌",
+  table: Object.freeze({
+    horizontal: "─",
+    vertical: "│",
+    topLeft: "┌",
+    topRight: "┐",
+    bottomLeft: "└",
+    bottomRight: "┘",
+    teeUp: "┴",
+    teeDown: "┬",
+    teeLeft: "├",
+    teeRight: "┤",
+    cross: "┼",
+  }),
+});
+
+type MarkdownThemeWithSymbols = MarkdownTheme & { symbols?: MarkdownThemeSymbols };
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null;
+const asNonEmptyString = (v: unknown): string | undefined =>
+  typeof v === "string" && v.length > 0 ? v : undefined;
+
+/**
+ * Fold the host's symbol surface into one complete `symbols` record. Forks expose the same
+ * chars in two shapes — nested (`theme.md.symbols.colorSwatch`) or flat
+ * (`theme.md.colorSwatch`) — and the host's values win over our safe defaults. `host.md`
+ * flat strings are also NOT spread over the base: `quoteBorder`/`hrChar` exist on the base
+ * as FUNCTIONS, so a naive spread would corrupt them.
+ */
+function hostSymbols(md: Record<string, unknown>): MarkdownThemeSymbols {
+  const nested = isRecord(md.symbols) ? md.symbols : {};
+  const fallback = FALLBACK_SYMBOLS as unknown as Record<string, unknown>;
+  const fallbackString = (k: string): string => (typeof fallback[k] === "string" ? fallback[k] : "");
+  const pick = (k: string): string => asNonEmptyString(nested[k]) ?? asNonEmptyString(md[k]) ?? fallbackString(k);
+  const hostTable = isRecord(nested.table) ? nested.table : {};
+  const table: Record<string, string> = { ...FALLBACK_SYMBOLS.table };
+  for (const k of Object.keys(table)) {
+    const v = asNonEmptyString(hostTable[k]);
+    if (v !== undefined) table[k] = v;
+  }
+  const bullet = asNonEmptyString(nested.bullet) ?? asNonEmptyString(md.bullet);
+  return Object.freeze({ colorSwatch: pick("colorSwatch"), hrChar: pick("hrChar"), quoteBorder: pick("quoteBorder"), bullet, table: Object.freeze(table) });
+}
+
 /**
  * A `MarkdownTheme` derived from the theme pi passed to this render pass.
  *
- * `highlightCode` is deliberately omitted: pi's implementation also reads the module global,
- * and it is optional on `MarkdownTheme` — code blocks render uncoloured rather than crashing.
+ * `highlightCode`/`resolveMermaidAscii` come through only if the host itself provides them
+ * as functions on `theme.md` — pi's own global-based implementation reads the broken
+ * module global and is deliberately never reconstructed here.
  */
 export function markdownTheme(theme: Theme): MarkdownTheme {
-  return {
+  const base: MarkdownTheme = {
     heading: (text) => theme.fg("mdHeading", text),
     link: (text) => theme.fg("mdLink", text),
     linkUrl: (text) => theme.fg("mdLinkUrl", text),
@@ -33,4 +101,18 @@ export function markdownTheme(theme: Theme): MarkdownTheme {
     underline: (text) => theme.underline(text),
     strikethrough: (text) => theme.strikethrough(text),
   };
+  const md: unknown = (theme as Theme & { md?: unknown }).md;
+  if (!isRecord(md)) {
+    const bare: MarkdownThemeWithSymbols = { ...base, symbols: hostSymbols({}) };
+    return bare;
+  }
+  // Function-valued host fields override the base (a real host MarkdownTheme wins);
+  // flat symbol strings stay out of the function surface and fold into `symbols`.
+  const hostFns: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(md)) {
+    if (typeof v === "function") hostFns[k] = v;
+  }
+  const merged = { ...base, ...hostFns } as MarkdownTheme & { symbols?: MarkdownThemeSymbols };
+  merged.symbols = hostSymbols(md);
+  return merged;
 }