@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/output-result.d.ts

@@ -0,0 +1,15 @@
+/** The node's machine result: the latest completed terminal structured request's result row; undefined when none completed. */
+export declare function readOutputResult(nodeId: string): Promise<unknown>;
+import type { StructuredOutputRequest } from './structured-output.js';
+/** The node's pending structured request, read from its `structured_requests` row; null when none is pending. */
+export declare function readOutputRequest(nodeId: string): Promise<StructuredOutputRequest | null>;
+export interface SchemaReprompts {
+    count: number;
+    at: number;
+}
+/** The pending request's consecutive schema reprompts (stop guard); none recorded reads as 0. */
+export declare function readSchemaReprompts(nodeId: string): Promise<SchemaReprompts>;
+/** Record one reprompt only if the stored count is still `from`; false when another process counted first. */
+export declare function takeSchemaReprompt(nodeId: string, from: number, count: number, at: number): Promise<boolean>;
+/** A submission resets the count. */
+export declare function clearSchemaReprompts(nodeId: string): Promise<void>;

package/dist/core/runtime/output-result.js

@@ -0,0 +1,32 @@
+// The database-backed read of a node's machine result. Kept out of structured-output.ts, which CLI leaves import eagerly (V-1: the CLI never reaches the canvas database).
+import { openDb } from '../canvas/db.js';
+/** The node's machine result: the latest completed terminal structured request's result row; undefined when none completed. */
+export async function readOutputResult(nodeId) {
+    const row = await (await openDb()).prepareUncached(`SELECT result_json FROM structured_requests
+    WHERE node_id = ? AND submission = 'terminal' AND state = 'completed' AND result_json IS NOT NULL
+    ORDER BY settled_at DESC, seq DESC LIMIT 1`).get(nodeId);
+    return row === undefined ? undefined : JSON.parse(row.result_json);
+}
+/** The node's pending structured request, read from its `structured_requests` row; null when none is pending. */
+export async function readOutputRequest(nodeId) {
+    const row = await (await openDb()).prepareUncached(`SELECT request_id, submission, schema_json, request_message_id FROM structured_requests
+    WHERE node_id = ? AND state = 'pending'`).get(nodeId);
+    if (row === undefined)
+        return null;
+    return { request_id: row.request_id, mode: row.submission, schema: JSON.parse(row.schema_json), ...(row.request_message_id === null ? {} : { requestMessageId: row.request_message_id }) };
+}
+/** The pending request's consecutive schema reprompts (stop guard); none recorded reads as 0. */
+export async function readSchemaReprompts(nodeId) {
+    const row = await (await openDb()).prepareUncached("SELECT reprompt_count, reprompted_at FROM structured_requests WHERE node_id = ? AND state = 'pending'")
+        .get(nodeId);
+    return { count: Number(row?.reprompt_count ?? 0), at: Number(row?.reprompted_at ?? 0) };
+}
+/** Record one reprompt only if the stored count is still `from`; false when another process counted first. */
+export async function takeSchemaReprompt(nodeId, from, count, at) {
+    return Number((await (await openDb()).prepareUncached(`UPDATE structured_requests SET reprompt_count = ?, reprompted_at = ?
+    WHERE node_id = ? AND state = 'pending' AND reprompt_count = ?`).run(count, at, nodeId, from)).changes) === 1;
+}
+/** A submission resets the count. */
+export async function clearSchemaReprompts(nodeId) {
+    await (await openDb()).prepareUncached("UPDATE structured_requests SET reprompt_count = 0, reprompted_at = NULL WHERE node_id = ? AND state = 'pending'").run(nodeId);
+}

package/dist/core/runtime/output-schema-refs.d.ts

@@ -0,0 +1,3 @@
+/** The first `$ref` in `schema` that cannot resolve inside the schema itself, as a message
+ *  telling the caller what to change; `null` when every `$ref` resolves. */
+export declare function outputSchemaRefProblem(schema: Record<string, unknown>): string | null;

package/dist/core/runtime/output-schema-refs.js

@@ -0,0 +1,100 @@
+// `$ref` resolution check for a structured-output schema.
+//
+// A schema arrives as ONE JSON object, so a `$ref` can only resolve to something inside it: a
+// `#/…` pointer, a `#anchor`, or another document bundled under `$defs` that carries its own
+// `$id` (JSON Schema 2020-12 "compound document"). The validator treats any other `$ref`
+// as `false`, which rejects every valid result with "schema is false" — so the schema is
+// refused up front instead, naming the ref and saying how to bundle it. This walker does its
+// own resolution (rather than asking TypeBox) because TypeBox's pointer lookup is lenient:
+// it can resolve `other.json#/$defs/x` to an unrelated `#/$defs/x` elsewhere in the tree.
+const DEFAULT_BASE = 'https://json-schema.org/';
+/** Keywords whose value is data, not a subschema: a `$ref`-shaped object there is not a reference. */
+const DATA_KEYWORDS = new Set(['const', 'enum', 'default', 'examples']);
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseUrl(ref, base) {
+    try {
+        return new URL(ref, base);
+    }
+    catch {
+        return null;
+    }
+}
+function withoutHash(url) {
+    const copy = new URL(url.href);
+    copy.hash = '';
+    return copy.href;
+}
+function index(node, base, out) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            index(item, base, out);
+        return;
+    }
+    if (!isObject(node))
+        return;
+    let here = base;
+    if (typeof node['$id'] === 'string') {
+        const url = parseUrl(node['$id'], base);
+        if (url !== null && (url.hash === '' || url.hash === '#')) {
+            here = withoutHash(url);
+            if (!out.resources.has(here))
+                out.resources.set(here, node);
+        }
+    }
+    if (typeof node['$anchor'] === 'string')
+        out.anchors.set(`${here}#${node['$anchor']}`, node);
+    if (typeof node['$ref'] === 'string')
+        out.refs.push({ ref: node['$ref'], base: here });
+    for (const [key, child] of Object.entries(node)) {
+        if (!DATA_KEYWORDS.has(key))
+            index(child, here, out);
+    }
+}
+function pointerGet(root, pointer) {
+    let current = root;
+    for (const raw of pointer.split('/').slice(1)) {
+        let segment;
+        try {
+            segment = decodeURIComponent(raw).replaceAll('~1', '/').replaceAll('~0', '~');
+        }
+        catch {
+            return undefined;
+        }
+        if (Array.isArray(current))
+            current = current[Number(segment)];
+        else if (isObject(current) && Object.hasOwn(current, segment))
+            current = current[segment];
+        else
+            return undefined;
+    }
+    return current;
+}
+/** The first `$ref` in `schema` that cannot resolve inside the schema itself, as a message
+ *  telling the caller what to change; `null` when every `$ref` resolves. */
+export function outputSchemaRefProblem(schema) {
+    const rootId = typeof schema['$id'] === 'string' ? parseUrl(schema['$id'], DEFAULT_BASE) : null;
+    const rootBase = rootId === null ? DEFAULT_BASE : withoutHash(rootId);
+    const found = { resources: new Map([[rootBase, schema]]), anchors: new Map(), refs: [] };
+    index(schema, rootBase, found);
+    for (const { ref, base } of found.refs) {
+        const url = parseUrl(ref, base);
+        const fragment = url === null ? '' : decodeURIComponent(url.hash.replace(/^#/, ''));
+        const resource = url === null ? undefined : found.resources.get(withoutHash(url));
+        let resolved;
+        if (url === null || resource === undefined)
+            resolved = false;
+        else if (fragment === '')
+            resolved = true;
+        else if (fragment.startsWith('/'))
+            resolved = pointerGet(resource, fragment) !== undefined;
+        else
+            resolved = found.anchors.has(`${withoutHash(url)}#${fragment}`);
+        if (!resolved) {
+            const remote = !ref.startsWith('#');
+            return `$ref ${JSON.stringify(ref)} does not resolve inside the schema. The schema is a single JSON object, so a $ref can only point into itself (\`#/$defs/x\`, \`#anchor\`) or at another schema document bundled under \`$defs\` with its own \`$id\` (give that document an \`$id\` that the $ref's path resolves against, e.g. \`"$defs": { "common": { "$id": "common.schema.json", … } }\`).${remote ? ' Files are never fetched.' : ''}`;
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,34 @@
+export interface MissingPackage {
+    /** The raw `packages[]` entry as stored in settings.json. */
+    source: string;
+    /** Absolute path it resolved to (which does not exist). */
+    resolved: 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
+ * PURPOSE: `getAgentDir` lives in `@earendil-works/pi-coding-agent`, and
+ * importing that package pulls in the ENTIRE ~360ms pi engine module graph. The
+ * front door calls this on every bare-`crtr` boot BEFORE spawning the broker, so
+ * a static/dynamic pi import here adds ~316ms of serialized dead-time in the
+ * foreground before the broker (which loads pi itself) even starts. This mirrors
+ * pi's contract exactly: `$PI_CODING_AGENT_DIR` (tilde-expanded) else
+ * `~/.pi/agent`. Same precedent as `bearings.ts` (keep the pi engine out of the
+ * hot/foreground path). If pi ever rebrands its configDir/env, update here.
+ */
+export declare function piAgentDir(homeDir?: string): string;
+/**
+ * Return every local-path package in `<agentDir>/settings.json` whose resolved
+ * path is missing. Empty when settings is absent/unreadable or all paths exist.
+ * Mirrors pi's own resolution: `resolve(agentDir, expandTilde(source))`.
+ */
+export declare function findMissingPackagePaths(agentDir: string, homeDir?: string): MissingPackage[];
+/** A human-readable, actionable warning for a set of missing packages, or
+ *  `null` when nothing is missing. Names `crtr sys setup` as the fix. */
+export declare function missingPackageWarning(agentDir: string, homeDir?: string): string | null;

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

@@ -0,0 +1,100 @@
+// package-health: detect pi packages configured in `<agentDir>/settings.json`
+// whose LOCAL-PATH source no longer exists on disk.
+//
+// Why this exists: pi installs a local-path package (e.g. crouter's bundled
+// `pi-crtr-extensions`, which surfaces `~/.claude` commands/skills/plugins as
+// slash commands) by storing its path in settings.json RELATIVE to the settings
+// dir. Moving the crouter repo silently invalidates that relative path — and pi
+// DISCARDS a missing package with no error, so the extension just never loads
+// and its whole feature (here: every Claude command/marketplace command) simply
+// 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 { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { appSpace } from '../layout.js';
+import { join, resolve } from 'node:path';
+import { isRendererReady } from '../termrender/termrender.js';
+import { expandTilde } from '../fs-utils.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;
+    return 'crtr: the pinned termrender renderer is not provisioned — pages, reviews, and inline diagrams render as plaintext.\n' +
+        '  Fix: run `crtr sys setup` (requires `uv`: curl -LsSf https://astral.sh/uv/install.sh | sh).';
+}
+/**
+ * The pi agent config dir (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`) — a local
+ * reimplementation of pi's `getAgentDir()`. Reimplemented (not imported) ON
+ * PURPOSE: `getAgentDir` lives in `@earendil-works/pi-coding-agent`, and
+ * importing that package pulls in the ENTIRE ~360ms pi engine module graph. The
+ * front door calls this on every bare-`crtr` boot BEFORE spawning the broker, so
+ * a static/dynamic pi import here adds ~316ms of serialized dead-time in the
+ * foreground before the broker (which loads pi itself) even starts. This mirrors
+ * pi's contract exactly: `$PI_CODING_AGENT_DIR` (tilde-expanded) else
+ * `~/.pi/agent`. Same precedent as `bearings.ts` (keep the pi engine out of the
+ * hot/foreground path). If pi ever rebrands its configDir/env, update here.
+ */
+export function piAgentDir(homeDir = homedir()) {
+    const envDir = process.env['PI_CODING_AGENT_DIR'];
+    if (envDir !== undefined && envDir !== '')
+        return expandTilde(envDir, homeDir);
+    return join(homeDir === homedir() ? appSpace('terminal').home : homeDir, '.pi', 'agent');
+}
+/** A `packages[]` entry is a LOCAL PATH (not an npm ref) — the only kind that
+ *  can go stale on a repo move. `npm:...` and bare registry names resolve
+ *  through node/npm, not the filesystem, so they are out of scope here. */
+function isLocalPathSource(source) {
+    if (source.startsWith('npm:'))
+        return false;
+    return source.startsWith('.') || source.startsWith('/') || source.startsWith('~');
+}
+/**
+ * Return every local-path package in `<agentDir>/settings.json` whose resolved
+ * path is missing. Empty when settings is absent/unreadable or all paths exist.
+ * Mirrors pi's own resolution: `resolve(agentDir, expandTilde(source))`.
+ */
+export function findMissingPackagePaths(agentDir, homeDir = homedir()) {
+    let raw;
+    try {
+        raw = readFileSync(join(agentDir, 'settings.json'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let packages;
+    try {
+        packages = JSON.parse(raw).packages;
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(packages))
+        return [];
+    const missing = [];
+    for (const entry of packages) {
+        if (typeof entry !== 'string' || !isLocalPathSource(entry))
+            continue;
+        const resolved = resolve(agentDir, expandTilde(entry, homeDir));
+        if (!existsSync(resolved))
+            missing.push({ source: entry, resolved });
+    }
+    return missing;
+}
+/** A human-readable, actionable warning for a set of missing packages, or
+ *  `null` when nothing is missing. Names `crtr sys setup` as the fix. */
+export function missingPackageWarning(agentDir, homeDir = homedir()) {
+    const missing = findMissingPackagePaths(agentDir, homeDir);
+    if (missing.length === 0)
+        return null;
+    const lines = missing.map((m) => `  • ${m.source}\n      → ${m.resolved} (missing)`);
+    return (`crtr: ${missing.length} configured pi package path${missing.length === 1 ? '' : 's'} ` +
+        `no longer exist${missing.length === 1 ? 's' : ''} — pi silently skips these, so their ` +
+        `slash commands (e.g. ~/.claude commands & marketplace plugins) will not load.\n` +
+        lines.join('\n') +
+        `\n  Fix: re-run \`crtr sys setup\` (re-resolves package paths to this repo's current location).`);
+}

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

@@ -0,0 +1,21 @@
+import { type Mode, type Lifecycle } from '../canvas/index.js';
+/** The three-axis persona transition key. */
+export interface Persona {
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+}
+export interface PersonaDriftResult {
+    from: Persona;
+    to: Persona;
+    /** Fresh-context framing for `to`; its snapshots carry document context. */
+    guidance: string;
+}
+/** Build only the non-document framing for a fresh-context transition. */
+export declare function transitionGuidance(nodeId: string, from: Persona, to: Persona): Promise<string>;
+/** Compare the live persona with the last acknowledged context delivery.
+ * `guidance` contains only fresh-context framing; current snapshots supply its
+ * documents. An absent or pre-kind acknowledgment cannot fabricate drift. */
+export declare function personaDrift(nodeId: string): Promise<PersonaDriftResult | null>;
+/** Commit the persona state whose context delivery is complete. */
+export declare function commitPersonaAck(nodeId: string, to: Persona): Promise<void>;

package/dist/core/runtime/persona.js

@@ -0,0 +1,54 @@
+// Persona drift and the non-document framing carried by a fresh-revive kickoff.
+// The new context's system and bearings snapshots supply its memory baseline;
+// canvas-context-intro acknowledges the drift after both snapshots persist.
+import { getNode, updateNode } from '../canvas/index.js';
+import { readRoadmap } from './roadmap.js';
+import { orchestratorContextNote } from './bearings.js';
+// Base → orchestrator guidance
+/** Fresh-context framing for a base → orchestrator change. */
+async function orchestrationGuidance(nodeId, kind) {
+    const roadmap = await readRoadmap(nodeId) ?? '(no roadmap yet)';
+    const parts = [
+        `You are now a ${kind.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,
+        'Your job is to manage context and delegate — not to do the goal yourself.',
+    ];
+    parts.push('', 'Your roadmap is your document `roadmap`; it loads at every new session of yours. Author it now with `crtr doc edit roadmap`: state the goal and exit criteria, and set the preview to the goal’s first line, using your orchestration protocol. Current contents:', '', roadmap, '', orchestratorContextNote(), '', 'What promotion changes is how long your documents matter: you now persist across refresh cycles, so the documents you own (`crtr doc write`) carry what this goal needs between your refreshes, and a lesson that should outlive this node gets another owner (`--owner user|repo|profile`).', '', 'Then delegate each unit with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
+    return parts.join('\n');
+}
+// Orchestrator → base guidance
+/** orchestrator → base (demote): hands-on again, finish in-window. */
+function baseModeGuidance() {
+    return ('You are HANDS-ON again — base mode. Do the work yourself in THIS window and finish it here; ' +
+        'stop delegating by default. You no longer drive a roadmap, so `crtr node yield` is not your exit. ' +
+        'Spawn a child only for a cleanly separable unit, never as your first move.');
+}
+/** Build only the non-document framing for a fresh-context transition. */
+export async function transitionGuidance(nodeId, from, to) {
+    if (from.mode === to.mode)
+        return '';
+    if (to.mode === 'base')
+        return baseModeGuidance();
+    const node = await getNode(nodeId);
+    return await orchestrationGuidance(nodeId, node?.kind ?? 'general');
+}
+// Detector + ack commit.
+/** Compare the live persona with the last acknowledged context delivery.
+ * `guidance` contains only fresh-context framing; current snapshots supply its
+ * documents. An absent or pre-kind acknowledgment cannot fabricate drift. */
+export async function personaDrift(nodeId) {
+    const meta = await getNode(nodeId);
+    if (meta === null)
+        return null;
+    const to = { kind: meta.kind, mode: meta.mode, lifecycle: meta.lifecycle };
+    const ack = meta.persona_ack;
+    const from = ack === undefined
+        ? to
+        : { kind: ack.kind ?? meta.kind, mode: ack.mode, lifecycle: ack.lifecycle };
+    if (from.kind === to.kind && from.mode === to.mode && from.lifecycle === to.lifecycle)
+        return null;
+    return { from, to, guidance: await transitionGuidance(nodeId, from, to) };
+}
+/** Commit the persona state whose context delivery is complete. */
+export async function commitPersonaAck(nodeId, to) {
+    await updateNode(nodeId, { persona_ack: to });
+}

package/dist/core/runtime/pi-cli.d.ts

@@ -0,0 +1,8 @@
+export declare function resolveBundledPiPackageDir(): string;
+/** Environment for a bundled pi subprocess. pi resolves theme assets relative
+ *  to its package root; pnpm/npm mixed layouts can make its own module URL point
+ *  through `.pnpm` at a package copy without those JSON assets, so explicitly
+ *  pin the real bundled package directory (the same contract attach uses). */
+export declare function bundledPiSubprocessEnv(): NodeJS.ProcessEnv;
+export declare function resolveBundledPiCliPath(): string;
+export declare function bundledPiCommandForShell(quote: (value: string) => string): string;

package/dist/core/runtime/pi-cli.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function findPackageRootFromEntry(entryPath, expectedName) {
+    let dir = dirname(entryPath);
+    const root = parse(dir).root;
+    while (true) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (pkg.name === expectedName)
+                    return dir;
+            }
+            catch {
+                return null;
+            }
+        }
+        if (dir === root)
+            return null;
+        dir = dirname(dir);
+    }
+}
+export function resolveBundledPiPackageDir() {
+    const packageName = '@earendil-works/pi-coding-agent';
+    let entryPath;
+    try {
+        entryPath = fileURLToPath(import.meta.resolve(packageName));
+    }
+    catch (error) {
+        throw new Error(`crouter install is missing bundled ${packageName}; reinstall crouter. ${error.message}`);
+    }
+    const packageRoot = findPackageRootFromEntry(entryPath, packageName);
+    if (packageRoot === null) {
+        throw new Error(`could not locate bundled ${packageName} package root from ${entryPath}`);
+    }
+    return packageRoot;
+}
+/** Environment for a bundled pi subprocess. pi resolves theme assets relative
+ *  to its package root; pnpm/npm mixed layouts can make its own module URL point
+ *  through `.pnpm` at a package copy without those JSON assets, so explicitly
+ *  pin the real bundled package directory (the same contract attach uses). */
+export function bundledPiSubprocessEnv() {
+    return {
+        ...process.env,
+        PI_PACKAGE_DIR: resolveBundledPiPackageDir(),
+    };
+}
+export function resolveBundledPiCliPath() {
+    const packageRoot = resolveBundledPiPackageDir();
+    const pkgPath = join(packageRoot, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const bin = pkg.bin && typeof pkg.bin === 'object' ? pkg.bin.pi : undefined;
+    if (typeof bin !== 'string' || bin.trim() === '') {
+        throw new Error(`bundled @earendil-works/pi-coding-agent does not declare a pi binary in ${pkgPath}`);
+    }
+    const cliPath = join(packageRoot, bin);
+    if (!existsSync(cliPath)) {
+        throw new Error(`bundled pi binary is missing at ${cliPath}`);
+    }
+    return cliPath;
+}
+export function bundledPiCommandForShell(quote) {
+    return `${quote(process.execPath)} ${quote(resolveBundledPiCliPath())}`;
+}

package/dist/core/runtime/pi-vendored.d.ts

@@ -0,0 +1,28 @@
+/** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
+ *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
+ *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
+ *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
+ *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
+ *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
+ *  the sessions dir — same vendoring rationale as the slash-command list below.
+ *  `PI_CODING_AGENT_DIR` goes through the same tilde expansion pi's
+ *  `getAgentDir()` applies, or `~/custom-pi` yields a broken relative path. */
+export declare function piSessionsRoot(): string;
+/**
+ * pi's builtin slash commands — vendored verbatim from pi `core/slash-commands.js`
+ * `BUILTIN_SLASH_COMMANDS` (review C1). **21 entries at 0.78.1** (review n1 — NOT 23).
+ *
+ * Builtins are NOT engine-interpreted (`session.prompt('/model')` ships `/model`
+ * to the LLM as literal text), so the broker's `get_commands` op MERGES this list
+ * with the engine's registered commands/templates/skills, and the viewer
+ * autocomplete parses these locally. Both the broker and the viewer
+ * import this single copy.
+ *
+ * Upstream interpolates `${APP_NAME}` into the `quit` description; `APP_NAME`
+ * defaults to "pi" (overridable via pi config), so the vendored copy hardcodes
+ * "Quit pi".
+ */
+export declare const BUILTIN_SLASH_COMMANDS: ReadonlyArray<{
+    name: string;
+    description: string;
+}>;

package/dist/core/runtime/pi-vendored.js

@@ -0,0 +1,63 @@
+// pi-vendored.ts — symbols copied verbatim from pi that pi does NOT re-export.
+//
+// VENDORED, not imported, because pi's `exports` map is `.`-only (+`./hooks`):
+// a deep import like `@earendil-works/pi-coding-agent/dist/core/slash-commands`
+// fails with ERR_PACKAGE_PATH_NOT_EXPORTED, and the symbol is absent from the
+// package-root `index.d.ts` at BOTH 0.78.1 and 0.79.0 — so there is no pin at
+// which it becomes importable (review C1). The only safe access is to copy it.
+//
+// MAINTENANCE: re-sync on EVERY pi SDK bump. The source of truth is
+// `node_modules/@earendil-works/pi-coding-agent/dist/core/slash-commands.js`.
+// If the upstream list changes (entries added/removed/reworded), update the copy
+// below to match and adjust the count note.
+import { join } from 'node:path';
+import { piAgentDir } from './package-health.js';
+/** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
+ *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
+ *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
+ *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
+ *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
+ *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
+ *  the sessions dir — same vendoring rationale as the slash-command list below.
+ *  `PI_CODING_AGENT_DIR` goes through the same tilde expansion pi's
+ *  `getAgentDir()` applies, or `~/custom-pi` yields a broken relative path. */
+export function piSessionsRoot() {
+    return join(piAgentDir(), 'sessions');
+}
+/**
+ * pi's builtin slash commands — vendored verbatim from pi `core/slash-commands.js`
+ * `BUILTIN_SLASH_COMMANDS` (review C1). **21 entries at 0.78.1** (review n1 — NOT 23).
+ *
+ * Builtins are NOT engine-interpreted (`session.prompt('/model')` ships `/model`
+ * to the LLM as literal text), so the broker's `get_commands` op MERGES this list
+ * with the engine's registered commands/templates/skills, and the viewer
+ * autocomplete parses these locally. Both the broker and the viewer
+ * import this single copy.
+ *
+ * Upstream interpolates `${APP_NAME}` into the `quit` description; `APP_NAME`
+ * defaults to "pi" (overridable via pi config), so the vendored copy hardcodes
+ * "Quit pi".
+ */
+export const BUILTIN_SLASH_COMMANDS = [
+    { name: 'settings', description: 'Open settings menu' },
+    { name: 'model', description: 'Select model (opens selector UI)' },
+    { name: 'scoped-models', description: 'Enable/disable models for Ctrl+P cycling' },
+    { name: 'export', description: 'Export session (HTML default, or specify path: .html/.jsonl)' },
+    { name: 'import', description: 'Import and resume a session from a JSONL file' },
+    { name: 'share', description: 'Share session as a secret GitHub gist' },
+    { name: 'copy', description: 'Copy last agent message to clipboard' },
+    { name: 'name', description: 'Set session display name' },
+    { name: 'session', description: 'Show session info and stats' },
+    { name: 'changelog', description: 'Show changelog entries' },
+    { name: 'hotkeys', description: 'Show all keyboard shortcuts' },
+    { name: 'fork', description: 'Create a new fork from a previous user message' },
+    { name: 'clone', description: 'Duplicate the current session at the current position' },
+    { name: 'tree', description: 'Navigate session tree (switch branches)' },
+    { name: 'login', description: 'Configure provider authentication' },
+    { name: 'logout', description: 'Remove provider authentication' },
+    { name: 'new', description: 'Start a new session' },
+    { name: 'compact', description: 'Manually compact the session context' },
+    { name: 'resume', description: 'Resume a different session' },
+    { name: 'reload', description: 'Reload keybindings, extensions, skills, prompts, and themes' },
+    { name: 'quit', description: 'Quit pi' },
+];

package/dist/core/runtime/placement-tmux.d.ts

@@ -0,0 +1,32 @@
+export { paneExists, paneLocation, paneOfNode, paneCurrentPath, paneSize, paneRunning, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, renameWindow, displayPopup, displayPopupAsync, windowOfPane, respawnPaneSync, respawnPaneInBackground, respawnPaneInPlace, runShellInBackground, paneStartCommand, swapPanes, paneCurrentCommand, closeWindow, panePid, windowAlive, listLivePanes, VIEWER_STAMP_OPTION, stampViewerPaneAsync, liveViewerPanes, sendAttachControl, displayClientMessage, displayMessage, windowIndex, sessionExists, tmuxAvailable, tmuxInteractive, } from './tmux-driver.js';
+export { installTmuxBindings } from './tmux-bindings.js';
+export { BROKER_VIEW_SOCKET_WAIT_MS, waitForBrokerViewSocket } from './view-socket.js';
+/** Env for a `crtr surface attach` VIEWER pane (the focus split, the spawn viewer
+ *  window, AND recycle's re-attach respawn): propagate CRTR_HOME so the viewer
+ *  resolves the SAME canvas home — and thus the right view.sock — under a
+ *  non-default override; otherwise an empty env (the pane inherits the tmux
+ *  server env, like every other crtr chrome pane). One helper so the viewer-pane
+ *  sites can't drift. */
+export declare function viewerSplitEnv(): Record<string, string>;
+/** The opened viewer pane's tmux coordinates. */
+export interface ViewerPane {
+    pane: string;
+    session: string | null;
+    window: string | null;
+}
+/** Open a `crtr surface attach` VIEWER pane for `nodeId` — the PURE tmux half of
+ *  placement's openViewerWindow (no focus-row write). Wraps `ensureSession` +
+ *  `openNodeWindow`/`splitWindow`. The attach client connects to the node's
+ *  `view.sock` and renders/drives the live broker engine — it NEVER launches the
+ *  engine (the one-writer invariant; the caller ensures the broker is alive
+ *  first). Returns the opened pane's coordinates, or null if tmux refused.
+ *    - default → a fresh WINDOW in `session` (the --root spawn-viewer path).
+ *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
+ *      open-beside-the-caller path); `session` is then only a fallback. */
+export declare function openViewerPane(nodeId: string, session: string, opts?: {
+    name?: string;
+    cwd?: string;
+    besidePane?: string;
+    waitForBroker?: boolean;
+    initialWhip?: boolean;
+}): ViewerPane | null;