@north-light/crouter 0.3.169 → 0.3.171

package/dist/core/runtime/naming.d.ts

@@ -5,6 +5,13 @@ export declare function sanitizeSessionName(raw: string): string;
 /** Local fallback: derive a name straight from the prompt (no pi call). Drops
  *  stop-words, takes the first few content words. */
 export declare function slugFromPrompt(prompt: string): string;
+/** The namer's model: the `light` rung of the DEFAULT provider's ladder, with
+ *  any thinking suffix stripped (we pass `--thinking off` explicitly — naming is
+ *  a trivial classification that never needs a reasoning budget). Reading the
+ *  ladder rather than pinning a concrete model id keeps naming working for a
+ *  user who never configured Anthropic: an OpenAI default provider resolves to
+ *  its own light rung. `CRTR_NAME_MODEL` still overrides. */
+export declare function lightModel(overrideEnv?: string): string;
 /** A generated session name: the kebab-case handle plus the Nerd Font glyph the
  *  namer chose for it. `icon` is '' when the model returned nothing usable —
  *  every surface renders the name alone in that case. */

package/dist/core/runtime/naming.js

@@ -119,13 +119,16 @@ export function slugFromPrompt(prompt) {
  *  ladder rather than pinning a concrete model id keeps naming working for a
  *  user who never configured Anthropic: an OpenAI default provider resolves to
  *  its own light rung. `CRTR_NAME_MODEL` still overrides. */
-function nameModel() {
-    const override = process.env['CRTR_NAME_MODEL'];
+export function lightModel(overrideEnv) {
+    const override = overrideEnv === undefined ? undefined : process.env[overrideEnv];
     if (override !== undefined && override.trim() !== '')
         return override.trim();
     const ladders = modelLadders();
     return stripThinkingSuffix(ladders[defaultProvider(ladders)].light);
 }
+function nameModel() {
+    return lightModel('CRTR_NAME_MODEL');
+}
 /** The pi argv for a headless TEXT request (issue titles). Stripped down (no
  *  tools, session, context files, extensions, skills, templates, themes) so
  *  it's fast and side-effect free. */

package/dist/core/runtime/node-read.js

@@ -8,6 +8,7 @@
 // and were imported into the handlers from there; Stage B-3 relocated them here
 // so the CLI leaves' import graph reaches no canvas state store (spec §1/§10).
 import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { readJsonIfExists } from '../fs-utils.js';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { InputError } from '../io.js';
@@ -17,6 +18,7 @@ import { SessionManager } from './broker-sdk.js';
 import { piAgentDir } from './package-health.js';
 import { BUILTIN_SLASH_COMMANDS } from './pi-vendored.js';
 import { cycleAwareMessages } from './session-cycles.js';
+import { normalizeToolGroupSummaryRecord } from '../../shared/tool-groups.js';
 import { ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';
 import { PoolCredentialStore } from '../pool-credential-store.js';
 /** A session `.jsonl` records only `{ provider, modelId }` — pi never persists a
@@ -131,6 +133,15 @@ function readIfPresent(path) {
         return null;
     }
 }
+function readToolGroupSummaries(nodeId) {
+    try {
+        const raw = readJsonIfExists(join(jobDir(nodeId), 'tool-summaries.json'));
+        return normalizeToolGroupSummaryRecord(raw);
+    }
+    catch {
+        return {};
+    }
+}
 /** Reconstruct a persisted session without launching its broker. Backs the
  * machine-readable snapshot endpoint and the human transcript render. */
 export async function readNodeSnapshot(nodeId) {
@@ -175,6 +186,10 @@ export async function readNodeSnapshot(nodeId) {
             // process state (last setStatus/setWidget/setTitle) and is not persisted,
             // so an offline read has none.
             display: { statuses: {}, widgets: {}, title: undefined },
+            // Sidecar summaries survive broker exit so a dormant transcript receives
+            // the same completed-group data as a live welcome snapshot. Malformed or
+            // absent sidecars are deliberately ignored: tool calls remain visible.
+            toolGroupSummaries: readToolGroupSummaries(nodeId),
         };
         return {
             nodeId,

package/dist/core/runtime/package-health.d.ts

@@ -4,27 +4,12 @@ export interface MissingPackage {
     /** Absolute path it resolved to (which does not exist). */
     resolved: string;
 }
-export interface GlobalHumanloopHealth {
-    bundledVersion: string | null;
-    globalVersion: string | null;
-    current: boolean;
-}
-/** Read the installed library's version rather than coupling this check to the
- * dependency range in crouter's package.json. The bundled copy is the floor
- * required by crouter's generated `hl inbox toggle` binding. */
-export declare function bundledHumanloopVersion(): string | null;
-/** Read the PATH-visible `hl` package directly. Spawning `npm ls -g` here
- * makes every front-door boot pay for npm's global dependency-tree scan; a
- * linked development install can make that scan take many seconds. The real
- * executable points into the package for both ordinary and npm-linked installs,
- * so walking upward to its package.json is authoritative for the CLI crtr will
- * actually invoke. */
-export declare function globalHumanloopVersion(): string | null;
-export declare function globalHumanloopHealth(): GlobalHumanloopHealth;
-/** A non-fatal action-oriented diagnostic for a missing, unreadable, or stale
- * global `hl` executable. */
-export declare function globalHumanloopWarning(): string | null;
-export declare function globalHumanloopInstallCommand(): string;
+/** A non-fatal, action-oriented diagnostic for an unprovisioned managed
+ * renderer — the one remaining out-of-tree dependency. Deliberately calls
+ * `isRendererReady()`, NOT `ensureRenderer()`: this runs on the front-door boot
+ * path and at crtrd startup, where a `uv pip install` (up to 180s) must never
+ * happen. Readiness is a handful of fs stats, no subprocess. */
+export declare function rendererWarning(): string | null;
 /**
  * The pi agent config dir (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`) — a local
  * reimplementation of pi's `getAgentDir()`. Reimplemented (not imported) ON

package/dist/core/runtime/package-health.js

@@ -10,131 +10,20 @@
 // vanishes with no diagnostic. This turns that silent failure into a loud,
 // actionable warning. The fix it points at is `crtr sys setup`, which re-resolves
 // package paths to the repo's current location.
-import { accessSync, constants, existsSync, readFileSync, realpathSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { delimiter, dirname, join, resolve } from 'node:path';
-const GLOBAL_HUMANLOOP_INSTALL_COMMAND = 'npm i -g @crouton-kit/humanloop@latest';
-/** Read the installed library's version rather than coupling this check to the
- * dependency range in crouter's package.json. The bundled copy is the floor
- * required by crouter's generated `hl inbox toggle` binding. */
-export function bundledHumanloopVersion() {
-    try {
-        // package.json is deliberately not an exported subpath. Resolve the public
-        // ESM entry, then walk from dist/index.js to the package root.
-        const entryPath = fileURLToPath(import.meta.resolve('@crouton-kit/humanloop'));
-        const packageJsonPath = join(dirname(entryPath), '..', 'package.json');
-        const value = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-        return typeof value.version === 'string'
-            ? value.version
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** Compare ordinary npm semvers without loading a semver dependency on the
- * foreground/daemon startup path. Unparseable versions deliberately fail the
- * health check: setup can repair them and boot only warns. */
-function compareVersions(left, right) {
-    const parse = (version) => {
-        const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
-        if (match === null)
-            return null;
-        return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4]?.split('.') ?? [] };
-    };
-    const a = parse(left);
-    const b = parse(right);
-    if (a === null || b === null)
+import { join, resolve } from 'node:path';
+import { isRendererReady } from '../termrender/termrender.js';
+/** A non-fatal, action-oriented diagnostic for an unprovisioned managed
+ * renderer — the one remaining out-of-tree dependency. Deliberately calls
+ * `isRendererReady()`, NOT `ensureRenderer()`: this runs on the front-door boot
+ * path and at crtrd startup, where a `uv pip install` (up to 180s) must never
+ * happen. Readiness is a handful of fs stats, no subprocess. */
+export function rendererWarning() {
+    if (isRendererReady())
         return null;
-    for (let index = 0; index < a.core.length; index++) {
-        const difference = a.core[index] - b.core[index];
-        if (difference !== 0)
-            return difference;
-    }
-    if (a.prerelease.length === 0 || b.prerelease.length === 0) {
-        return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
-    }
-    for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index++) {
-        const aPart = a.prerelease[index];
-        const bPart = b.prerelease[index];
-        if (aPart === undefined || bPart === undefined)
-            return aPart === bPart ? 0 : aPart === undefined ? -1 : 1;
-        if (aPart === bPart)
-            continue;
-        const aNumber = /^\d+$/.test(aPart);
-        const bNumber = /^\d+$/.test(bPart);
-        if (aNumber && bNumber)
-            return Number(aPart) - Number(bPart);
-        if (aNumber !== bNumber)
-            return aNumber ? -1 : 1;
-        return aPart < bPart ? -1 : 1;
-    }
-    return 0;
-}
-/** Read the PATH-visible `hl` package directly. Spawning `npm ls -g` here
- * makes every front-door boot pay for npm's global dependency-tree scan; a
- * linked development install can make that scan take many seconds. The real
- * executable points into the package for both ordinary and npm-linked installs,
- * so walking upward to its package.json is authoritative for the CLI crtr will
- * actually invoke. */
-export function globalHumanloopVersion() {
-    const executable = (process.env['PATH'] ?? '')
-        .split(delimiter)
-        .filter(Boolean)
-        .map((entry) => join(entry, 'hl'))
-        .find((candidate) => {
-        try {
-            accessSync(candidate, constants.X_OK);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    });
-    if (executable === undefined)
-        return null;
-    try {
-        let cursor = dirname(realpathSync(executable));
-        for (;;) {
-            const packageJsonPath = join(cursor, 'package.json');
-            if (existsSync(packageJsonPath)) {
-                const value = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-                const manifest = value;
-                if (manifest.name === '@crouton-kit/humanloop')
-                    return typeof manifest.version === 'string' ? manifest.version : null;
-            }
-            const parent = dirname(cursor);
-            if (parent === cursor)
-                return null;
-            cursor = parent;
-        }
-    }
-    catch {
-        return null;
-    }
-}
-export function globalHumanloopHealth() {
-    const bundledVersion = bundledHumanloopVersion();
-    const globalVersion = globalHumanloopVersion();
-    const comparison = bundledVersion !== null && globalVersion !== null
-        ? compareVersions(globalVersion, bundledVersion)
-        : null;
-    return { bundledVersion, globalVersion, current: comparison !== null && comparison >= 0 };
-}
-/** A non-fatal action-oriented diagnostic for a missing, unreadable, or stale
- * global `hl` executable. */
-export function globalHumanloopWarning() {
-    const { bundledVersion, globalVersion, current } = globalHumanloopHealth();
-    if (current)
-        return null;
-    const floor = bundledVersion ?? 'the bundled version';
-    const found = globalVersion === null ? 'missing or unprobeable' : globalVersion;
-    return `crtr: global \`hl\` CLI is ${found}; crouter requires at least bundled humanloop ${floor} for its inbox toggle.\n` +
-        `  Fix: run \`${GLOBAL_HUMANLOOP_INSTALL_COMMAND}\`.`;
-}
-export function globalHumanloopInstallCommand() {
-    return GLOBAL_HUMANLOOP_INSTALL_COMMAND;
+    return 'crtr: the pinned termrender renderer is not provisioned — decks, reviews, and inline diagrams render as plaintext.\n' +
+        '  Fix: run `crtr sys setup` (requires `uv`: curl -LsSf https://astral.sh/uv/install.sh | sh).';
 }
 /** Expand a leading `~` against `homeDir` (pi's own convention). */
 function expandTilde(pathValue, homeDir) {

package/dist/core/runtime/stop-guard.d.ts

@@ -1,3 +1,4 @@
+export { STALL_REPROMPT } from '../../shared/generated-context.js';
 export interface StopSignals {
     /** Did the node call `push --final` (finish) this turn? */
     pushedFinal: boolean;
@@ -12,7 +13,6 @@ export type StopAction = {
     reason: 'stalled';
     message: string;
 };
-export declare const STALL_REPROMPT: string;
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
  *  signals — the stophook supplies the signals and enacts the action. */
 export declare function evaluateStop(nodeId: string, signals: StopSignals): StopAction;

package/dist/core/runtime/stop-guard.js

@@ -18,9 +18,9 @@
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
 import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCancelOnWakeCron, getNode } from '../canvas/index.js';
+import { formatStructuredOutputReprompt, STALL_REPROMPT } from '../../shared/generated-context.js';
 import { hasPendingStructuredOutput, readOutputRequest } from './structured-output.js';
-export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
-    "Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human ask` if you are blocked or need the user.";
+export { STALL_REPROMPT } from '../../shared/generated-context.js';
 function structuredOutputReprompt(nodeId) {
     let schema = '{}';
     try {
@@ -31,7 +31,7 @@ function structuredOutputReprompt(nodeId) {
     catch {
         /* keep a deterministic reprompt even if the schema file was corrupted */
     }
-    return `You must call the \`submit\` tool with a result matching the required schema before you can stop. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n\`\`\`json\n${schema}\n\`\`\``;
+    return formatStructuredOutputReprompt(schema);
 }
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
  *  signals — the stophook supplies the signals and enacts the action. */

package/dist/core/runtime/tool-group-summary.d.ts

@@ -0,0 +1,19 @@
+import { type ToolGroupSummary } from '../../shared/tool-groups.js';
+export type ToolGroupPiece = {
+    type: 'tool';
+    name: string;
+    args: unknown;
+} | {
+    type: 'result';
+    name: string;
+    result: unknown;
+    isError: boolean;
+} | {
+    type: 'text';
+    text: string;
+};
+/** Serialize only the causal material around one group, with fixed per-piece
+ * and total budgets so a verbose tool result cannot dominate the light-model call. */
+export declare function serializeToolGroup(previousBoundaryProse: string, pieces: readonly ToolGroupPiece[]): string;
+/** Generate a structured summary object, or null on every failure. */
+export declare function headlessToolGroupSummary(segment: string): Promise<ToolGroupSummary | null>;

package/dist/core/runtime/tool-group-summary.js

@@ -0,0 +1,117 @@
+// Broker-side, best-effort tool-group summarization. The only successful output
+// path is the constrained submit_summary tool; failures deliberately yield no
+// substitute object so callers leave the normal folded calls visible.
+import { execFile } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SUMMARY_TOOL_PATH } from './canvas-extensions.js';
+import { lightModel } from './naming.js';
+import { bundledPiSubprocessEnv, resolveBundledPiCliPath } from './pi-cli.js';
+import { normalizeToolGroupSummary } from '../../shared/tool-groups.js';
+const BOUNDARY_CAP = 600;
+const TOOL_ARGS_CAP = 300;
+const RESULT_CAP = 400;
+const TEXT_CAP = 1_000;
+const SEGMENT_CAP = 10_000;
+const SUMMARY_TIMEOUT_MS = 45_000;
+function capped(value, cap) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized.length <= cap ? normalized : `${normalized.slice(0, Math.max(0, cap - 1)).trimEnd()}…`;
+}
+function printable(value, cap) {
+    try {
+        return capped(typeof value === 'string' ? value : JSON.stringify(value), cap);
+    }
+    catch {
+        return capped(String(value), cap);
+    }
+}
+/** Serialize only the causal material around one group, with fixed per-piece
+ * and total budgets so a verbose tool result cannot dominate the light-model call. */
+export function serializeToolGroup(previousBoundaryProse, pieces) {
+    const lines = [`Previous visible message: ${capped(previousBoundaryProse, BOUNDARY_CAP) || '(none)'}`, 'Between-message activity:'];
+    for (const piece of pieces) {
+        if (piece.type === 'tool')
+            lines.push(`- tool ${piece.name}(${printable(piece.args, TOOL_ARGS_CAP)})`);
+        else if (piece.type === 'result')
+            lines.push(`- ${piece.isError ? 'error' : 'result'} ${piece.name}: ${printable(piece.result, RESULT_CAP)}`);
+        else
+            lines.push(`- context: ${capped(piece.text, TEXT_CAP)}`);
+    }
+    return capped(lines.join('\n'), SEGMENT_CAP);
+}
+// Tool mechanics, identifiers, and inbox bookkeeping produce a machine log rather
+// than the glanceable human recap this surface needs, so the prompt asks only for
+// very short outcomes while the structured fields retain the underlying stats.
+const SUMMARY_SYSTEM_PROMPT = 'Create a structured recap of this coding-agent tool activity. ' +
+    'Prefer 1–3 bullets and use at most 5 only for distinct meaningful outcomes. ' +
+    'Each bullet must be an extremely readable plain-English outcome of 3–10 words, without markdown markers. ' +
+    'Describe what changed or was accomplished, not the tools, commands, or investigation steps; for code work, say what capability was added to a one- or two-phrase plain-English part of the system, such as "Added scheduling controls to the worker service." ' +
+    'Never include IDs, hashes, paths, filenames, command names, tool names, raw values, or report text. ' +
+    'Omit inbox receipt, delivery, and queueing; node-response and report bookkeeping; help lookups; status checks; and summary-generation activity. ' +
+    'A node response may support a substantive outcome, but its arrival or resummarization is never itself an outcome. ' +
+    'If no meaningful outcome remains after those omissions, submit the single bullet "No meaningful changes." ' +
+    'Count nodes created and distinct files created, modified, or deleted only when evidenced by the supplied tool arguments or results; otherwise use zero, even when the corresponding mechanics are omitted from bullets. ' +
+    'Do not invent success when a result shows failure. ' +
+    'Call submit_summary exactly once with bullets, nodesSpawned, and filesEdited, then stop.';
+function summaryArgs(segment) {
+    return [
+        '-p',
+        '--no-session',
+        '--no-context-files',
+        '--no-extensions',
+        '--no-skills',
+        '--no-prompt-templates',
+        '--no-themes',
+        '-e', SUMMARY_TOOL_PATH,
+        '--tools', 'submit_summary',
+        '--mode', 'text',
+        '--thinking', 'off',
+        '--model', lightModel(),
+        '--system-prompt', SUMMARY_SYSTEM_PROMPT,
+        `<tool-group>\n${segment}\n</tool-group>\n\nSummarize the activity above.`,
+    ];
+}
+/** Generate a structured summary object, or null on every failure. */
+export function headlessToolGroupSummary(segment) {
+    return new Promise((resolve) => {
+        let dir = null;
+        try {
+            dir = mkdtempSync(join(tmpdir(), 'crtr-tool-summary-'));
+            const resultFile = join(dir, 'summary.json');
+            const done = (value) => {
+                if (dir !== null) {
+                    try {
+                        rmSync(dir, { recursive: true, force: true });
+                    }
+                    catch { /* temp cleanup */ }
+                }
+                resolve(value);
+            };
+            const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...summaryArgs(segment)], {
+                encoding: 'utf8',
+                timeout: SUMMARY_TIMEOUT_MS,
+                env: { ...bundledPiSubprocessEnv(), CRTR_SUMMARY_RESULT_FILE: resultFile },
+            }, () => {
+                try {
+                    const parsed = JSON.parse(readFileSync(resultFile, 'utf8'));
+                    done(normalizeToolGroupSummary(parsed));
+                }
+                catch {
+                    done(null);
+                }
+            });
+            child.stdin?.end();
+        }
+        catch {
+            if (dir !== null) {
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                catch { /* temp cleanup */ }
+            }
+            resolve(null);
+        }
+    });
+}

package/dist/core/termrender/code-doc.d.ts

@@ -0,0 +1,12 @@
+import { type RenderedDoc } from './termrender.js';
+export declare function isMarkdownFile(file: string): boolean;
+/** Fence info string for a source file — `text` when the extension is unknown,
+ *  which every highlighter degrades to plain text on. */
+export declare function fenceLanguageFor(file: string): string;
+/** Wrap source text as a fenced block. The fence is grown past the longest
+ *  backtick run in the content, so a file that itself contains ``` can't close
+ *  its own block. */
+export declare function codeFenceDocument(content: string, language: string): string;
+/** Render a source file as a syntax-highlighted code panel whose spans are
+ *  source lines — the code-file counterpart of `renderReviewDoc`. */
+export declare function codeRenderedDoc(content: string, language: string, width: number): RenderedDoc;

package/dist/core/termrender/code-doc.js

@@ -0,0 +1,91 @@
+import { extname } from 'node:path';
+import { renderMarkdownWithMap } from './termrender.js';
+// ── Source files as review documents ─────────────────────────────────────────
+//
+// A review ticket may point at a .ts/.py/.sql source file, not just a .md
+// artifact. Every surface still wants ONE rendering story, so a source file is
+// presented as a single fenced code block: termrender (Pygments) and the
+// browser (highlight.js) then syntax-highlight it for free, and the fence's
+// language comes from the file extension.
+//
+// The one cost is a line shift: the fence's opening line makes source line N
+// land on line N+1 of the wrapped document. `codeRenderedDoc` folds that back
+// out so every span/anchor the surfaces expose is a real SOURCE line number.
+/** Extension → fence info string. Names are the ones Pygments (termrender) and
+ *  highlight.js (browser) both accept, so one map serves every surface. */
+const FENCE_BY_EXT = {
+    '.ts': 'typescript', '.mts': 'typescript', '.cts': 'typescript', '.tsx': 'tsx',
+    '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript', '.jsx': 'jsx',
+    '.py': 'python', '.rb': 'ruby', '.go': 'go', '.rs': 'rust', '.java': 'java',
+    '.c': 'c', '.h': 'c', '.cc': 'cpp', '.cpp': 'cpp', '.hpp': 'cpp', '.cs': 'csharp',
+    '.swift': 'swift', '.kt': 'kotlin', '.php': 'php', '.lua': 'lua', '.pl': 'perl',
+    '.sh': 'bash', '.bash': 'bash', '.zsh': 'bash', '.fish': 'fish',
+    '.sql': 'sql', '.json': 'json', '.jsonc': 'json', '.yaml': 'yaml', '.yml': 'yaml',
+    '.toml': 'toml', '.ini': 'ini', '.xml': 'xml', '.html': 'html', '.htm': 'html',
+    '.css': 'css', '.scss': 'scss', '.less': 'less', '.vim': 'vim', '.el': 'lisp',
+    '.ex': 'elixir', '.exs': 'elixir', '.erl': 'erlang', '.hs': 'haskell',
+    '.scala': 'scala', '.dart': 'dart', '.r': 'r', '.jl': 'julia', '.zig': 'zig',
+    '.tf': 'terraform', '.proto': 'protobuf', '.graphql': 'graphql', '.gql': 'graphql',
+    '.dockerfile': 'dockerfile', '.diff': 'diff', '.patch': 'diff', '.csv': 'text',
+    '.txt': 'text', '.log': 'text', '.env': 'bash', '.mk': 'makefile',
+};
+/** Markdown extensions render as a DOCUMENT (headings, tables, Mermaid); every
+ *  other text file renders as code. */
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdown', '.mkd']);
+export function isMarkdownFile(file) {
+    return MARKDOWN_EXTENSIONS.has(extname(file).toLowerCase());
+}
+/** Fence info string for a source file — `text` when the extension is unknown,
+ *  which every highlighter degrades to plain text on. */
+export function fenceLanguageFor(file) {
+    const ext = extname(file).toLowerCase();
+    if (ext === '') {
+        // Extensionless but conventionally-named files still have obvious types.
+        const base = file.slice(file.lastIndexOf('/') + 1).toLowerCase();
+        if (base === 'dockerfile')
+            return 'dockerfile';
+        if (base === 'makefile')
+            return 'makefile';
+        return 'text';
+    }
+    return FENCE_BY_EXT[ext] ?? 'text';
+}
+/** Wrap source text as a fenced block. The fence is grown past the longest
+ *  backtick run in the content, so a file that itself contains ``` can't close
+ *  its own block. */
+export function codeFenceDocument(content, language) {
+    let longest = 0;
+    for (const run of content.matchAll(/`+/g))
+        longest = Math.max(longest, run[0].length);
+    const fence = '`'.repeat(Math.max(3, longest + 1));
+    const body = content.endsWith('\n') ? content.slice(0, -1) : content;
+    return `${fence}${language}\n${body}\n${fence}\n`;
+}
+/** Shift a rendered wrapped-document map back onto SOURCE line numbers: the
+ *  opening fence occupies line 1, so document line N is source line N-1.
+ *
+ *  Rows that touch a fence line are the panel's border/title chrome, not
+ *  source: they lose BOTH their span and their block row so nothing anchors to
+ *  them — otherwise the top border would be a step in j/k that selects the
+ *  whole file. */
+function foldFenceOffset(doc, sourceLineCount) {
+    const closingFenceLine = sourceLineCount + 2;
+    const clamp = (line) => Math.max(1, Math.min(line - 1, sourceLineCount));
+    const chrome = doc.spans.map((span) => span !== null && (span[0] <= 1 || span[1] >= closingFenceLine));
+    return {
+        lines: doc.lines,
+        rows: doc.rows.map((row, index) => (chrome[index] === true ? null : row)),
+        spans: doc.spans.map((span, index) => {
+            if (span === null || chrome[index] === true)
+                return null;
+            return [clamp(span[0]), clamp(span[1])];
+        }),
+        blocks: doc.blocks.map((block) => ({ type: block.type, start: clamp(block.start), end: clamp(block.end) })),
+    };
+}
+/** Render a source file as a syntax-highlighted code panel whose spans are
+ *  source lines — the code-file counterpart of `renderReviewDoc`. */
+export function codeRenderedDoc(content, language, width) {
+    const sourceLineCount = content.split('\n').length;
+    return foldFenceOffset(renderMarkdownWithMap(codeFenceDocument(content, language), width), sourceLineCount);
+}

package/dist/core/termrender/display.d.ts

@@ -0,0 +1,12 @@
+/** Options for `display()` — the live-watch tmux pane surface. The pane always
+ *  watches the file and live-updates on edits; there is no non-watched mode. */
+export interface DisplayOpts {
+    /** `'auto'` (default) splits until the pane budget, then opens a new window. */
+    window?: 'auto' | 'split' | 'new';
+    /** Pane budget per window before `'auto'` opens a new window. Default 3. */
+    maxPanes?: number;
+}
+export declare function countPanesInCurrentWindow(): number;
+export declare function display(path: string, opts?: DisplayOpts): {
+    paneId?: string;
+};

package/dist/core/termrender/display.js

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process';
+import { displayInPane } from './termrender.js';
+export function countPanesInCurrentWindow() {
+    // -t '' targets the current window of the current session.
+    const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return 0;
+    return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
+}
+export function display(path, opts) {
+    const window = (opts?.window === 'split' || opts?.window === 'new') ? opts.window : 'auto';
+    const maxPanes = (opts?.maxPanes !== undefined && opts.maxPanes > 0) ? opts.maxPanes : 3;
+    const newWindow = window === 'new' ||
+        (window === 'auto' && countPanesInCurrentWindow() >= maxPanes);
+    // The pane always watches the file — displayed docs are live by definition.
+    return displayInPane(path, { newWindow });
+}

package/dist/core/termrender/termrender.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Memoized, self-healing. Guarantees at most one authoritative renderer
+ * lifecycle per process: trust a valid stamp outright (zero subprocess spawns),
+ * else run ONE provision/verify/publish transition under the exclusive lock.
+ * There is no permanent legacy-verifier fallback — the spawn-based verify
+ * (`binaryOk` + `installedVersion`) is a step INSIDE that single transition,
+ * always followed by publishing the stamp, never a lasting alternate path.
+ *
+ * Single degradation path: `uv` absent → one stderr remediation line + plaintext.
+ * win32 → plaintext (no renderer).
+ *
+ * Invoked at postinstall AND lazily on the first render/check/display call,
+ * so `npm ci --ignore-scripts` consumers still self-heal on first use.
+ */
+export declare function ensureRenderer(): void;
+/** Cheap predicate — true when the pinned managed binary is verified ready. Does not install or spawn. */
+export declare function isRendererReady(): boolean;
+/** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
+export declare function renderMarkdown(md: string, width: number): string[];
+export interface RenderedDoc {
+    /** Rendered ANSI rows — byte-identical to the plain `doc render` output. */
+    lines: string[];
+    /** Per-row index into `blocks`; null for the blank separator rows between blocks. */
+    rows: (number | null)[];
+    /** Per-row finest 1-indexed inclusive source-line range the renderer knows
+     *  (a bullet, a table row, a code line…); null for separator rows and rows
+     *  of unmapped blocks. Same length as `lines`. */
+    spans: ([number, number] | null)[];
+    /** Per top-level block: its termrender block type plus 1-indexed inclusive
+     *  source-line bounds. Never empty. */
+    blocks: {
+        type: string;
+        start: number;
+        end: number;
+    }[];
+}
+/** Render markdown with a row→source-line map via the pinned binary
+ *  (`doc render --line-map`); plaintext paragraph-block fallback. */
+export declare function renderMarkdownWithMap(md: string, width: number): RenderedDoc;
+/**
+ * The shared block-aware mapped render: prose blocks keep the readability cap
+ * (`proseWidth`), while diagram blocks are re-rendered at the pane's full
+ * `paneWidth` and spliced back in by block index. Both surfaces (terminal
+ * review and the ask deck) go through this, so "which blocks may be wide" is
+ * decided once, from the renderer's own block types, never by heuristics on
+ * the emitted rows.
+ *
+ * Row order, block list and source spans are the narrow render's; only the
+ * rows OF a wide block are replaced, so anchoring stays source-based and
+ * unchanged.
+ */
+export declare function renderMarkdownBlockAware(md: string, proseWidth: number, paneWidth: number): RenderedDoc;
+/** Block-aware render as plain rows, for surfaces that do not anchor. */
+export declare function renderMarkdownBlockAwareLines(md: string, proseWidth: number, paneWidth: number): string[];
+/** Validate markdown via `termrender doc check`. */
+export declare function checkMarkdown(md: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DisplayInPaneOpts {
+    /** Open in a new tmux window instead of splitting the current one. */
+    newWindow?: boolean;
+}
+/**
+ * Spawn termrender into a live tmux pane. The pane-budget policy (whether to
+ * split vs open a new window) is decided by the caller (`src/surfaces/
+ * display.ts`); this is the thin managed-binary spawn it delegates to.
+ */
+export declare function displayInPane(path: string, opts?: DisplayInPaneOpts): {
+    paneId?: string;
+};