@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/runtime/bearings.js

@@ -1,15 +1,22 @@
-// bearings.ts — the boot-intro prose (the <crtr-identity> assertion + the
-// <crtr-context> framing), shared by the paths that deliver it so they can
-// never drift:
+// bearings.ts — the boot-intro prose (the <crtr-bearings> orientation block +
+// the <memory kind="knowledge"> catalog that rides beside it), shared by the
+// paths that deliver it so they can never drift:
 //
 //   • the context-intro pi-extension injects buildContextBearings() as the
-//     node's first session message in every brand-new chat. It opens with a
-//     <crtr-identity> block (buildIdentityAssertion) that names the node and,
+//     node's first session message in every brand-new chat. The <crtr-bearings>
+//     block opens with the identity assertion (buildIdentityAssertion) that
+//     names the node (id, kind, mode), then a `## Your place in the canvas`
+//     mini-map (ancestry trunk up + immediate children with statuses, via
+//     buildGraphMap) and a `## Your context directory` note; identity leads,
 //     ONLY for a fork, disowns the source's copied first-person narrative as
 //     inherited context — the fix for the `--fork-from` bug where a fork copies
 //     the source's whole conversation and then impersonates it. A non-fork
 //     node's bearings are its FIRST entry, so there is nothing earlier to
-//     disown; it gets only the declarative identity line;
+//     disown; it gets only the declarative identity line. The message also
+//     carries the <project_context> block (buildProjectContextBlock) — the
+//     AGENTS.md/CLAUDE.md project instructions, moved OUT of the system prompt
+//     (pi's copy is suppressed via noContextFiles in broker.ts) so they ride
+//     this user message instead;
 //   • promote.ts folds orchestratorContextNote() into the promotion guidance
 //     dump, so a node that becomes an orchestrator MID-LIFE gets the
 //     orchestrator framing it never received at spawn — it spawned as a base
@@ -19,21 +26,186 @@
 // one place other nodes on the canvas can read from, so it is for documents
 // worth a shared reference, NOT a task tracker, and NOT a "future memory-wiped
 // you" stash (a terminal worker has no future cycle — that framing only makes
-// sense once a node is a resident orchestrator). The `<knowledge>` block
-// (substrate knowledge docs + node-local docs) rides into the context message.
+// sense once a node is a resident orchestrator). The `<memory kind="knowledge">`
+// block (substrate knowledge docs + node-local docs) rides as a SIBLING of
+// <crtr-bearings> — never nested under the context dir, which would imply the
+// catalog belongs to that one directory rather than spanning all memory scopes.
 //
 // Orchestrator addendum (gated on orchestrator MODE): the dir ALSO survives
 // refresh cycles, so it is where a future cycle of the orchestrator resumes.
 // This across-cycles note is the ONE thing a terminal worker's bearings drop.
-import { contextDir, getNode, fullName } from '../canvas/index.js';
+import { contextDir, getNode, fullName, subscriptionsOf, } from '../canvas/index.js';
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
 import { cadenceDisplay } from '../wake.js';
 import { renderKnowledgeBlock } from '../substrate/index.js';
-/** Base framing — present for every node. No path baked in: the caller carries
- *  the dir in the `<crtr-context dir="…">` attribute. */
-export const BASE_CONTEXT_NOTE = 'This is your context directory — durable scratch space on disk, and the one place the other ' +
-    'nodes on the canvas can read from. Put documents here that you want to share by reference ' +
-    'instead of re-explaining them in a prompt: specs, designs, findings, notes worth pointing a ' +
-    'sibling, child, or parent at. It is a shared document store, not a task tracker.';
+// ---------------------------------------------------------------------------
+// Project context (<project_context>) — the AGENTS.md/CLAUDE.md files pi would
+// otherwise inject into its SYSTEM PROMPT, rendered here so they ride the
+// first-message bearings instead (pi's copy is suppressed via
+// resourceLoaderOptions.noContextFiles in broker.ts). We re-implement pi's
+// loadProjectContextFiles + getAgentDir (resource-loader.js / config.js) rather
+// than IMPORT pi: bearings.ts is statically imported by the thin daemon (crtrd,
+// for wakeOriginFrom), so a static @earendil-works import would pull the whole
+// pi engine into the supervisor. The discovery is a stable convention + pure fs.
+// ---------------------------------------------------------------------------
+/** pi's getAgentDir(): the global agent config dir holding a user-wide context
+ *  file. Honors PI_CODING_AGENT_DIR (tilde-expanded), else ~/.pi/agent (pi's
+ *  piConfig.configDir is ".pi"). */
+function piAgentDir() {
+    const env = process.env['PI_CODING_AGENT_DIR'];
+    if (env !== undefined && env !== '') {
+        return env.startsWith('~') ? join(homedir(), env.slice(1)) : env;
+    }
+    return join(homedir(), '.pi', 'agent');
+}
+/** Per-dir context-file candidates, in pi's precedence order (first match wins). */
+const CONTEXT_FILE_CANDIDATES = ['AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD'];
+function loadContextFileFromDir(dir) {
+    for (const name of CONTEXT_FILE_CANDIDATES) {
+        const p = join(dir, name);
+        if (existsSync(p)) {
+            try {
+                return { path: p, content: readFileSync(p, 'utf8') };
+            }
+            catch {
+                // Unreadable candidate — skip, mirroring pi (best-effort).
+            }
+        }
+    }
+    return null;
+}
+/** Mirror of pi's loadProjectContextFiles: the global agent-dir file first, then
+ *  every AGENTS.md/CLAUDE.md up the cwd's ancestry, ordered root→cwd (so the
+ *  most-specific project file reads last). Deduped by absolute path. */
+function loadProjectContextFiles(cwd) {
+    const files = [];
+    const seen = new Set();
+    const global = loadContextFileFromDir(piAgentDir());
+    if (global !== null) {
+        files.push(global);
+        seen.add(global.path);
+    }
+    const ancestors = [];
+    let dir = resolve(cwd);
+    const root = resolve('/');
+    for (;;) {
+        const f = loadContextFileFromDir(dir);
+        if (f !== null && !seen.has(f.path)) {
+            ancestors.unshift(f);
+            seen.add(f.path);
+        }
+        if (dir === root)
+            break;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    files.push(...ancestors);
+    return files;
+}
+function escapeAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function directoryListingLines(cwd) {
+    try {
+        const entries = readdirSync(cwd, { withFileTypes: true });
+        const sorted = entries.sort((a, b) => {
+            if (a.isDirectory() !== b.isDirectory())
+                return a.isDirectory() ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        const shown = sorted.slice(0, 50).map((entry) => `${entry.name}${entry.isDirectory() ? '/' : ''}`);
+        const hidden = sorted.length - shown.length;
+        return hidden > 0 ? [...shown, `[+${hidden} more]`] : shown;
+    }
+    catch {
+        return ['Directory listing: unavailable (cwd missing or unreadable).'];
+    }
+}
+function gitSnapshot(cwd) {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch {
+        return { lines: ['Git: not a git repository.'] };
+    }
+    const branch = runGit(cwd, 'git branch --show-current') || runGit(cwd, 'git rev-parse --abbrev-ref HEAD') || 'HEAD';
+    const sha = runGit(cwd, 'git rev-parse --short HEAD') || 'unknown';
+    const statusCount = runGit(cwd, 'git status --porcelain')
+        .split('\n')
+        .filter((line) => line !== '').length;
+    const worktreeLines = runGit(cwd, 'git worktree list --porcelain').split('\n');
+    const worktrees = parseWorktrees(worktreeLines);
+    const dirty = statusCount === 0 ? 'clean' : `${statusCount} uncommitted change${statusCount === 1 ? '' : 's'}`;
+    const summary = `Git: ${branch} @ ${sha}; ${dirty}; ${worktrees.length} worktree${worktrees.length === 1 ? '' : 's'}.`;
+    const worktreeSummary = worktrees.length === 0
+        ? 'Worktrees: none.'
+        : `Worktrees: ${worktrees.map((w) => `${w.path} (${w.branch})`).join(', ')}`;
+    return { lines: [summary, worktreeSummary] };
+}
+function runGit(cwd, command) {
+    try {
+        return execSync(command, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function parseWorktrees(lines) {
+    const worktrees = [];
+    let cur = {};
+    for (const line of lines) {
+        if (line.startsWith('worktree ')) {
+            if (cur.path !== undefined) {
+                worktrees.push({ path: cur.path, branch: cur.branch ?? 'detached HEAD' });
+            }
+            cur = { path: line.slice('worktree '.length) };
+        }
+        else if (line.startsWith('branch ')) {
+            cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+        }
+    }
+    if (cur.path !== undefined) {
+        worktrees.push({ path: cur.path, branch: cur.branch ?? 'detached HEAD' });
+    }
+    return worktrees;
+}
+/** The `<project_context>` block for the files discovered from `cwd`, plus the
+ *  cwd/git environment snapshot that now rides at the end of the wrapper.
+ *  Always emits the wrapper because the environment snapshot is always present
+ *  even when no project instructions exist. Exported for testing. */
+export function buildProjectContextBlock(cwd) {
+    const files = loadProjectContextFiles(cwd);
+    const envLines = directoryListingLines(cwd);
+    const git = gitSnapshot(cwd);
+    let out = '<project_context>\n\nProject-specific instructions and guidelines:\n\n';
+    for (const { path, content } of files) {
+        out += `<project_instructions path="${path}">\n${content}\n</project_instructions>\n\n`;
+    }
+    out += `<environment cwd="${escapeAttribute(cwd)}">\n`;
+    out += `Directory:\n${envLines.map((line) => `  ${line}`).join('\n')}\n`;
+    out += `${git.lines.map((line) => `${line}`).join('\n')}\n`;
+    out += '</environment>\n</project_context>';
+    return out;
+}
+/** The context-directory note — names the path INLINE (no XML attribute, so it
+ *  never scopes a sibling block) and frames the dir as durable, shared scratch.
+ *  Present for every node, rendered as the `## Your context directory`
+ *  subsection of <crtr-bearings>. */
+export function contextDirNote(nodeId) {
+    return (`Your context directory is \`${contextDir(nodeId)}\` (also in the env as \`$CRTR_CONTEXT_DIR\`) — ` +
+        'durable scratch space on disk, and the one place the other nodes on the canvas can read from. ' +
+        'Put documents here that you want to share by reference instead of re-explaining them in a ' +
+        'prompt: specs, designs, findings, notes worth pointing a sibling, child, or parent at. It is a ' +
+        'shared document store, not a task tracker. **Address it by absolute path** — write artifacts as ' +
+        '`$CRTR_CONTEXT_DIR/<name>.md` (or the full path above). Your working dir is the project, NOT ' +
+        'this directory, so a bare relative `context/...` lands in the repo, not here — and other nodes ' +
+        'can only read what is actually here. When you report a file, report its absolute path.');
+}
 /** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
  *  so its context dir is also where a future cycle of itself resumes the work.
  *  Used inside the bearings block AND in the promotion guidance dump, so a
@@ -43,52 +215,134 @@ export function orchestratorContextNote(nodeId) {
         `also where a future cycle of you resumes the work — keep the working notes and decisions a ` +
         `refreshed you would need there, alongside the docs you share with the nodes you spawn.`);
 }
+// ---------------------------------------------------------------------------
+// Graph mini-map — the node's place in the canvas, rendered into the identity
+// block so a node boots oriented: who is above it (its ancestry trunk, root
+// first) and who is directly below it (its immediate children + their statuses).
+// Not the full subtree — just the load-bearing spine up and one level down.
+// ---------------------------------------------------------------------------
+/** Live-first sibling ordering, so running children surface above finished ones. */
+function statusRank(status) {
+    switch (status) {
+        case 'active': return 0;
+        case 'idle': return 1;
+        case 'done': return 2;
+        case 'canceled': return 3;
+        case 'dead': return 4;
+        default: return 5;
+    }
+}
+/** One relative's line in the map: `<id> — <kind> · <status>`, plus the node's
+ *  task description when it carries one (orientation: what that relative is for). */
+function relativeLabel(meta) {
+    const desc = fullName(meta);
+    const descPart = desc !== '' && desc !== meta.kind && desc !== meta.name ? ` — ${desc}` : '';
+    return `${meta.node_id} (${meta.kind} · ${meta.status})${descPart}`;
+}
+/** Ancestry trunk from the root DOWN to (but excluding) `nodeId`, climbing the
+ *  spine `parent` edge. Cycle-guarded. Root first. */
+function ancestorTrunk(nodeId) {
+    const trunk = [];
+    const seen = new Set([nodeId]);
+    let cur = getNode(nodeId)?.parent ?? null;
+    while (cur !== null && cur !== '' && !seen.has(cur)) {
+        seen.add(cur);
+        const m = getNode(cur);
+        if (m === null)
+            break;
+        trunk.unshift(m);
+        cur = m.parent ?? null;
+    }
+    return trunk;
+}
+/** Most children listed in the mini-map before the rest collapse to `+N more`. */
+const MAX_CHILDREN_SHOWN = 5;
+/** The node's immediate children — the nodes it subscribes to (its reports) —
+ *  with human-ask control-plane nodes dropped, sorted live-first. */
+function childNodes(nodeId) {
+    return subscriptionsOf(nodeId)
+        .map((s) => getNode(s.node_id))
+        .filter((m) => m !== null && m.kind !== 'human')
+        .sort((a, b) => statusRank(a.status) - statusRank(b.status));
+}
+/** The graph mini-map: the ancestry trunk (root first), then this node marked
+ *  `● you`, then its immediate children. Returns '' for a lone root with no
+ *  children (nothing to map). Exported for testing. */
+export function buildGraphMap(nodeId) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return '';
+    const trunk = ancestorTrunk(nodeId);
+    const children = childNodes(nodeId);
+    if (trunk.length === 0 && children.length === 0)
+        return '';
+    const indent = (depth) => '  '.repeat(depth);
+    const lines = [
+        'Your place in the canvas graph (ancestry above you, your direct children below):',
+    ];
+    trunk.forEach((m, i) => {
+        lines.push(`${indent(i)}${i === 0 ? '' : '└ '}${relativeLabel(m)}`);
+    });
+    const selfDepth = trunk.length;
+    lines.push(`${indent(selfDepth)}${selfDepth === 0 ? '' : '└ '}● you: ${nodeId} (${meta.kind}, ${meta.mode})`);
+    // Cap the child list so a wide fan-out can't flood the boot context. Children
+    // are sorted live-first, so the shown slice favors active nodes; the rest
+    // collapse to a `+N more` tail (active-first ordering means anything elided is
+    // the most-finished work).
+    const shown = children.slice(0, MAX_CHILDREN_SHOWN);
+    const hidden = children.length - shown.length;
+    shown.forEach((m, i) => {
+        const last = i === shown.length - 1 && hidden === 0;
+        lines.push(`${indent(selfDepth + 1)}${last ? '└ ' : '├ '}${relativeLabel(m)}`);
+    });
+    if (hidden > 0) {
+        lines.push(`${indent(selfDepth + 1)}└ +${hidden} more`);
+    }
+    return lines.join('\n');
+}
 /** The IDENTITY assertion that opens every boot intro — the load-bearing fix
  *  for the `--fork-from` impersonation bug. A fork copies the SOURCE node's
  *  entire first-person conversation into its own session, so without an explicit
  *  re-assertion the forked agent reads that copied narrative as its own and
  *  impersonates the source (it kept "monitoring itself" as a phantom child).
- *  This block names the node unambiguously. ONLY when the node IS a fork does it
- *  additionally name the source AND disown the copied first-person narrative as
- *  inherited reference material — a non-fork node's bearings are its first session
- *  entry, so there is no earlier narrative to disown (emitting a disown line there
- *  is dead weight that reads as a contradiction with no referent). Always the FIRST
- *  thing the node reads. Exported for testing. */
+ *  These lines name the node unambiguously and lead the <crtr-bearings> block
+ *  (no wrapper of their own — identity is the first prose the model reads). ONLY
+ *  when the node IS a fork do they additionally name the source AND disown the
+ *  copied first-person narrative as inherited reference material — a non-fork
+ *  node's bearings are its first session entry, so there is no earlier narrative
+ *  to disown (emitting a disown line there is dead weight that reads as a
+ *  contradiction with no referent). Also prepended to a fork's kickoff prompt in
+ *  spawn.ts. Exported for testing. */
 export function buildIdentityAssertion(nodeId) {
     const meta = getNode(nodeId);
-    const name = meta?.name ?? nodeId;
     const kind = meta?.kind ?? 'general';
     const mode = meta?.mode ?? 'base';
-    const lines = [
-        '<crtr-identity>',
-        `You are node ${nodeId} — name "${name}", kind ${kind}, mode ${mode}.`,
-    ];
+    const lines = [`You are node ${nodeId} — kind ${kind}, mode ${mode}.`];
     const forkFrom = meta?.fork_from;
     if (forkFrom !== undefined && forkFrom !== null && forkFrom !== '') {
         // Name the source: a known node id gets its human label; a raw path/uuid
         // passes through as-is.
         const src = getNode(forkFrom);
         const sourceLabel = src !== null ? `${forkFrom} ("${fullName(src)}")` : forkFrom;
-        lines.push(`You are a FORK of ${sourceLabel}: at spawn pi COPIED that node's conversation into your ` +
+        lines.push('', `You are a FORK of ${sourceLabel}: at spawn pi COPIED that node's conversation into your ` +
             `session as a starting point. You are NOT ${sourceLabel}. Everything earlier in this ` +
             'conversation is THEIR first-person history — inherited reference material, not your own ' +
             'past. Do not speak or act as them, do not continue their task as if it were yours, and do ' +
             'not "monitor yourself" as though you were a child they spawned.');
     }
-    lines.push('</crtr-identity>');
     return lines.join('\n');
 }
-/** Build a WakeOrigin from a fired wakeup row, resolving the armer's display
+/** Build a WakeOrigin from a fired trigger row, resolving the armer's display
  *  name if the node still exists. The daemon calls this at fire time for the
  *  bare-revive and spawn-birth seams. */
-export function wakeOriginFrom(w) {
-    const owner = w.owner_id != null ? getNode(w.owner_id) : null;
+export function wakeOriginFrom(t) {
+    const owner = t.owner_id != null ? getNode(t.owner_id) : null;
     return {
-        kind: w.kind,
-        ownerId: w.owner_id ?? null,
+        kind: t.action_mode === 'node_birth' ? 'node_birth' : 'fresh_revive',
+        ownerId: t.owner_id ?? null,
         ownerName: owner !== null ? fullName(owner) : undefined,
-        armedAt: w.created,
-        recur: w.recur,
+        armedAt: t.created,
+        recur: t.recur,
     };
 }
 /** The armer rendered for prose, ROLE-explicit so a newborn never mistakes the
@@ -118,7 +372,7 @@ export function buildWakeBearings(origin) {
     const recurring = origin.recur !== null && origin.recur !== undefined && origin.recur !== '';
     const cadence = recurring ? cadenceDisplay(origin.recur) : null;
     let body;
-    if (origin.kind === 'spawn') {
+    if (origin.kind === 'node_birth') {
         const armer = armerPhrase(origin);
         body = recurring
             ? `You were BORN by a scheduled wake, not spawned on demand — a recurring spawn-cron armed by ` +
@@ -141,25 +395,32 @@ export function buildWakeBearings(origin) {
     }
     return `<crtr-wake>\n${body}\n</crtr-wake>`;
 }
-/** The full boot intro: the IDENTITY assertion (always first, so it overrides
- *  any copied-in persona) followed by the `<crtr-context>` bearings block. Base
- *  framing rides for EVERY node; the across-cycles context-dir note is added
- *  ONLY for an orchestrator (by mode) — the one node whose dir a future cycle
- *  resumes from. The `<knowledge>` block carries the substrate knowledge docs
- *  + node-local docs. */
+/** The full boot intro, three top-level sections:
+ *
+ *   1. `<crtr-bearings>` — the orienting facts about THIS node: the identity
+ *      assertion (always first, so it overrides any copied-in persona), then a
+ *      `## Your place in the canvas` graph map and a `## Your context directory`
+ *      note. The across-cycles context-dir framing is added ONLY for an
+ *      orchestrator (by mode) — the one node whose dir a future cycle resumes
+ *      from.
+ *   2. `<memory kind="knowledge">` — the consultable catalog, a SIBLING of the
+ *      bearings (never nested under the context dir). Dropped when empty.
+ *   3. `<project_context>` — the AGENTS.md/CLAUDE.md instructions + the cwd/git
+ *      environment snapshot, moved OUT of the system prompt (pi's copy is
+ *      suppressed via noContextFiles in broker.ts) so it rides this message. */
 export function buildContextBearings(nodeId) {
-    const identity = buildIdentityAssertion(nodeId);
-    const dir = contextDir(nodeId);
     const node = getNode(nodeId);
-    const parts = [BASE_CONTEXT_NOTE];
+    const bearings = ['<crtr-bearings>', buildIdentityAssertion(nodeId)];
+    const map = buildGraphMap(nodeId);
+    if (map !== '')
+        bearings.push('', '## Your place in the canvas', map);
+    bearings.push('', '## Your context directory', contextDirNote(nodeId));
     // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
     if (node?.mode === 'orchestrator')
-        parts.push(orchestratorContextNote(nodeId));
-    // The substrate knowledge block: eligible `knowledge` docs at their
-    // system-prompt rung + node-local memory docs; dropped (returns '') when
-    // nothing is eligible.
+        bearings.push('', orchestratorContextNote(nodeId));
+    bearings.push('</crtr-bearings>');
+    // The consultable catalog rides BESIDE the bearings, not inside them.
     const knowledge = renderKnowledgeBlock(nodeId);
-    if (knowledge !== '')
-        parts.push(knowledge);
-    return `${identity}\n<crtr-context dir="${dir}">\n${parts.join('\n')}\n</crtr-context>`;
+    const projectCtx = node?.cwd !== undefined ? buildProjectContextBlock(node.cwd) : '';
+    return [bearings.join('\n'), knowledge, projectCtx].filter((s) => s !== '').join('\n');
 }

package/dist/core/runtime/branded-host.d.ts

@@ -3,6 +3,8 @@
  *  to the installed node, shared across every canvas home. */
 export declare function brandedHostDir(): string;
 export declare function brandedHostBin(): string;
+export declare function signBrandedHostArtifacts(binPath: string, libnodePath: string | null, sign?: (path: string) => void): void;
+export declare function brandedHostWorks(binPath: string): boolean;
 /** Ensure the branded host binary exists and matches the live node; return its
  *  absolute path. Idempotent and self-healing. Throws on a genuine build failure
  *  (disk full / permissions) — branding is load-bearing for FDA, so a failure is
@@ -11,6 +13,6 @@ export declare function ensureBrandedHost(): string;
 /** The path the engine (broker / daemon) should be launched from. On macOS in a
  *  compiled (production) build this is the branded host; otherwise — non-darwin
  *  (TCC is macOS-only), source/tsx (dev + the test suite: never copy 70 MB into
- *  the real ~/.crouter), or an explicit `CRTR_BRANDED_HOST=0` opt-out — it is the
- *  live node. These are environment gates, not error fallbacks. */
+ *  the real ~/.crouter), an explicit `CRTR_BRANDED_HOST=0` opt-out, or a copied
+ *  host that macOS kills before it can execute JS — it is the live node. */
 export declare function hostExecPath(): string;

package/dist/core/runtime/branded-host.js

@@ -24,6 +24,7 @@
 import { copyFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, readdirSync, renameSync, realpathSync, unlinkSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { CRTR_DIR_NAME } from '../../types.js';
 /** The filename the FDA / TCC entry is shown under. */
 const BRANDED_BIN_NAME = 'crouter';
@@ -71,6 +72,61 @@ function readMarker() {
         return null;
     }
 }
+/** Sign a copied branded-host artifact with the Apple Development identity.
+ *  macOS keys FDA grants on the Mach-O cdhash, so ad-hoc signing loses grants
+ *  after each rebuild. Stable signing preserves them. Non-fatal — if signing
+ *  fails (no certificate, non-macOS, etc), return silently. */
+function signBrandedHost(binPath) {
+    if (process.platform !== 'darwin')
+        return;
+    try {
+        const res = spawnSync('codesign', [
+            '-s',
+            'Apple Development: Silas Rhyneer (8W9CF7WS32)',
+            '--deep',
+            '--force',
+            binPath,
+        ], { stdio: ['pipe', 'pipe', 'pipe'] });
+        if (res.status !== 0) {
+            const stderr = (res.stderr ?? '').toString().trim();
+            if (stderr && !stderr.includes('valid on disk')) {
+                console.debug(`[crouter] codesign failed (expected on some systems): ${stderr}`);
+            }
+        }
+    }
+    catch {
+        // codesign not found or other spawn error — non-fatal, continue.
+    }
+}
+export function signBrandedHostArtifacts(binPath, libnodePath, sign = signBrandedHost) {
+    if (libnodePath !== null)
+        sign(libnodePath);
+    sign(binPath);
+}
+let brandedHostWarningShown = false;
+export function brandedHostWorks(binPath) {
+    try {
+        const res = spawnSync(binPath, ['-e', ''], {
+            stdio: 'ignore',
+            timeout: 2_000,
+        });
+        return res.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function warnBrandedHostFallback(binPath) {
+    if (brandedHostWarningShown)
+        return;
+    brandedHostWarningShown = true;
+    try {
+        process.stderr.write(`[crouter] branded host ${binPath} failed its startup check; using ${process.execPath} for broker/daemon processes.\n`);
+    }
+    catch {
+        /* best effort */
+    }
+}
 /** Ensure the branded host binary exists and matches the live node; return its
  *  absolute path. Idempotent and self-healing. Throws on a genuine build failure
  *  (disk full / permissions) — branding is load-bearing for FDA, so a failure is
@@ -89,6 +145,7 @@ export function ensureBrandedHost() {
     const libnodeName = libnodeSrc !== null ? libnodeSrc.split('/').pop() : null;
     const fresh = existsSync(dst) &&
         marker !== null &&
+        marker.version === 2 &&
         marker.source === src &&
         marker.libnode === libnodeName &&
         (libnodeName === null || existsSync(join(brandedHostDir(), libnodeName)));
@@ -108,14 +165,15 @@ export function ensureBrandedHost() {
         atomicCopy(libnodeSrc, join(brandedHostDir(), libnodeName));
     }
     atomicCopy(src, dst, 0o755);
-    writeFileSync(markerPath(), JSON.stringify({ source: src, libnode: libnodeName }));
+    signBrandedHostArtifacts(dst, libnodeName !== null ? join(brandedHostDir(), libnodeName) : null);
+    writeFileSync(markerPath(), JSON.stringify({ version: 2, source: src, libnode: libnodeName }));
     return dst;
 }
 /** The path the engine (broker / daemon) should be launched from. On macOS in a
  *  compiled (production) build this is the branded host; otherwise — non-darwin
  *  (TCC is macOS-only), source/tsx (dev + the test suite: never copy 70 MB into
- *  the real ~/.crouter), or an explicit `CRTR_BRANDED_HOST=0` opt-out — it is the
- *  live node. These are environment gates, not error fallbacks. */
+ *  the real ~/.crouter), an explicit `CRTR_BRANDED_HOST=0` opt-out, or a copied
+ *  host that macOS kills before it can execute JS — it is the live node. */
 export function hostExecPath() {
     if (process.env['CRTR_BRANDED_HOST'] === '0')
         return process.execPath;
@@ -123,5 +181,9 @@ export function hostExecPath() {
         return process.execPath;
     if (import.meta.url.endsWith('.ts'))
         return process.execPath;
-    return ensureBrandedHost();
+    const host = ensureBrandedHost();
+    if (brandedHostWorks(host))
+        return host;
+    warnBrandedHostFallback(host);
+    return process.execPath;
 }

package/dist/core/runtime/broker-protocol.d.ts

@@ -128,6 +128,17 @@ export interface FollowUpFrame {
 export interface AbortFrame {
     type: 'abort';
 }
+/** Run a `!` bash command — controller only. Maps to `session.executeBash()`,
+ *  which runs the command, records a `bashExecution` message in context, and
+ *  starts NO agent turn (pi's interactive `!`/`!!` semantics). `command` is the
+ *  text AFTER the leading `!`/`!!`; `excludeFromContext` is the `!!` form (output
+ *  shown but withheld from the LLM). The broker streams the result back as
+ *  `bash_start`/`bash_output`/`bash_end` frames. */
+export interface BashFrame {
+    type: 'bash';
+    command: string;
+    excludeFromContext?: boolean;
+}
 /** Controller arbitration (§5.3). */
 export interface RequestControlFrame {
     type: 'request_control';
@@ -284,11 +295,15 @@ export interface ShareFrame {
     type: 'share';
 }
 /** Reload credentials + refresh model registry after a viewer-side auth change.
- *  Controller-only. Broker handler: services.authStorage.reload() + services.modelRegistry.refresh(). */
+ *  Open to any client — reload_auth is an idempotent local re-read that doesn't
+ *  steer the conversation, so the daemon's canvas-wide fan (one /login → every
+ *  live broker) can trigger it without claiming controller and demoting an
+ *  attached human. Broker handler: services.authStorage.reload() +
+ *  services.modelRegistry.refresh(). */
 export interface ReloadAuthFrame {
     type: 'reload_auth';
 }
-export type ClientToBroker = HelloFrame | PromptFrame | SteerFrame | FollowUpFrame | AbortFrame | RequestControlFrame | ReleaseControlFrame | ByeFrame | ShutdownFrame | SetModelFrame | CycleModelFrame | CycleThinkingFrame | SetThinkingLevelFrame | DequeueFrame | SetAutoRetryFrame | SetAutoCompactionFrame | CompactFrame | NewSessionFrame | SwitchSessionFrame | ForkFrame | SetSessionNameFrame | GetCommandsFrame | NavigateTreeFrame | ReloadFrame | ExportFrame | ListModelsFrame | ListSessionsFrame | GetTreeFrame | GetSettingsFrame | ListScopedModelsFrame | ExtensionUIResponseFrame | CloneFrame | ShareFrame | ReloadAuthFrame;
+export type ClientToBroker = HelloFrame | PromptFrame | SteerFrame | FollowUpFrame | AbortFrame | BashFrame | RequestControlFrame | ReleaseControlFrame | ByeFrame | ShutdownFrame | SetModelFrame | CycleModelFrame | CycleThinkingFrame | SetThinkingLevelFrame | DequeueFrame | SetAutoRetryFrame | SetAutoCompactionFrame | CompactFrame | NewSessionFrame | SwitchSessionFrame | ForkFrame | SetSessionNameFrame | GetCommandsFrame | NavigateTreeFrame | ReloadFrame | ExportFrame | ListModelsFrame | ListSessionsFrame | GetTreeFrame | GetSettingsFrame | ListScopedModelsFrame | ExtensionUIResponseFrame | CloneFrame | ShareFrame | ReloadAuthFrame;
 export interface WelcomeFrame {
     type: 'welcome';
     snapshot: BrokerSnapshot;
@@ -300,7 +315,7 @@ export interface WelcomeFrame {
     pending_dialog?: RpcExtensionUIRequest | null;
     /** The pi agent dir (`~/.pi/agent`) from the broker's process — so the viewer
      *  can construct an AuthStorage/ModelRegistry pointing at the SAME auth.json.
-     *  crtr attach is tmux-local only: broker + viewer share a filesystem. */
+     *  crtr surface attach is tmux-local only: broker + viewer share a filesystem. */
     agentDir?: string;
 }
 export interface ControlChangedFrame {
@@ -335,6 +350,26 @@ export interface AckFrame {
     ok: boolean;
     detail?: string;
 }
+/** A `!` run has begun — viewers create the bash component. */
+export interface BashStartFrame {
+    type: 'bash_start';
+    command: string;
+    excludeFromContext?: boolean;
+}
+/** A streamed chunk of combined stdout+stderr for the in-flight `!` run. */
+export interface BashOutputFrame {
+    type: 'bash_output';
+    chunk: string;
+}
+/** The `!` run finished — viewers mark the bash component complete. Mirrors
+ *  `BashResult` minus the (already-streamed) `output`. */
+export interface BashEndFrame {
+    type: 'bash_end';
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    fullOutputPath?: string;
+}
 /** `provider/id` model reference — the wire form of a current/selected model. */
 export interface WireModelRef {
     provider: string;
@@ -462,7 +497,7 @@ export type ExtensionUIRequestFrame = RpcExtensionUIRequest;
 /** Everything the broker can send. Live `AgentSessionEvent`s are relayed
  *  verbatim (the broker adds nothing); the broker's own control frames carry
  *  non-colliding `type` discriminants. */
-export type BrokerToClient = WelcomeFrame | ControlChangedFrame | ModelChangedFrame | ErrorFrame | AckFrame | BrokerDataFrame | DisplayStatusFrame | DisplayWidgetFrame | DisplayTitleFrame | ExtensionUIRequestFrame | AgentSessionEvent;
+export type BrokerToClient = WelcomeFrame | ControlChangedFrame | ModelChangedFrame | ErrorFrame | AckFrame | BrokerDataFrame | DisplayStatusFrame | DisplayWidgetFrame | DisplayTitleFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | AgentSessionEvent;
 /** Encode one frame as a single newline-terminated JSON line. */
 export declare function encodeFrame(frame: ClientToBroker | BrokerToClient): string;
 /** Byte bounds for a {@link FrameDecoder} (C5). */
@@ -517,7 +552,7 @@ export declare const BROKER_READ_CAPS: FrameDecoderCaps;
  *  arriving in ~64 KiB socket chunks costs O(frame) total instead of O(frame ×
  *  chunks). The old `buf += chunk; buf.indexOf('\n')` shape flattened + re-walked
  *  the whole carry per chunk: a 16 MiB welcome snapshot cost ~250 ms of
- *  event-loop stall in `crtr attach` (typing lag) and the same again in the
+ *  event-loop stall in `crtr surface attach` (typing lag) and the same again in the
  *  broker; this shape decodes it in ~13 ms.
  *
  *  A `StringDecoder` decodes incoming Buffer chunks: an incomplete trailing