@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/canvas/render.js

@@ -12,12 +12,14 @@
 // Cycle guard: the subscription graph is declared acyclic (a node cannot
 // subscribe to its own ancestor), but we track visited ids defensively because
 // the db is mutable and bugs happen.
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode, listNodes, subscriptionsOf, view } from './canvas.js';
 import { fullName } from './labels.js';
 import { jobDir, contextDir } from './paths.js';
-import { countAsks } from './attention.js';
+import { countAsks, asksForNodes } from './attention.js';
+import { isPidAlive } from './pid.js';
+import { listFocuses } from './focuses.js';
 // ---------------------------------------------------------------------------
 // Glyphs
 // ---------------------------------------------------------------------------
@@ -181,54 +183,98 @@ function readGoalText(nodeId) {
         return undefined;
     }
 }
-/** EVERY user prompt across a node's pi session — the whole conversation, not just
- *  the spawn prompt. Streams the session jsonl off disk, prefiltering to user-role
- *  lines so the big assistant/toolResult lines are never JSON-parsed, extracts each
- *  user message's text, joins newline-separated, and caps total + per-message so a
- *  long session can't bloat the snapshot. Never throws; returns undefined when there
- *  is no session file yet (a node that was never revived). */
+/** The node's session-derived preview text in ONE file read (today's two reads,
+ *  folded): EVERY user prompt across the pi session (`prompts` — the whole
+ *  conversation, not just the spawn prompt) AND the LAST assistant message text
+ *  (`lastAssistant`). The single jsonl read is split once; a forward pass collects
+ *  user prompts (prefiltering to user-role lines so the big assistant/toolResult
+ *  lines are never JSON-parsed) and a backward pass finds the newest assistant
+ *  reply with text content (tool-only replies skipped). Both are capped per-message
+ *  + total so a long session can't bloat the snapshot. Never throws; returns an
+ *  empty object when there is no session file yet (a node that was never revived). */
 const CONVO_CAP = 8192;
 const CONVO_MSG_CAP = 2048;
-function readConversationPrompts(sessionFile) {
+function readSessionParts(sessionFile) {
     if (sessionFile === undefined || sessionFile === null || sessionFile === '')
-        return undefined;
+        return {};
+    let lines;
     try {
         if (!existsSync(sessionFile))
-            return undefined;
-        const raw = readFileSync(sessionFile, 'utf8');
-        const parts = [];
-        let total = 0;
-        for (const line of raw.split('\n')) {
-            // Cheap prefilter: skip every line that isn't a user-role message before the
-            // (relatively costly) JSON.parse. Pi writes compact JSON (no spaces), but
-            // tolerate the spaced form too.
-            if (line === '' || (line.indexOf('"role":"user"') === -1 && line.indexOf('"role": "user"') === -1))
-                continue;
-            let rec;
-            try {
-                rec = JSON.parse(line);
-            }
-            catch {
-                continue;
-            }
-            if (rec.type !== 'message' || rec.message?.role !== 'user')
-                continue;
-            const text = extractUserText(rec.message.content);
-            if (text === '')
-                continue;
-            const capped = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
-            parts.push(capped);
-            total += capped.length + 1;
-            if (total >= CONVO_CAP)
-                break;
+            return {};
+        lines = readFileSync(sessionFile, 'utf8').split('\n');
+    }
+    catch {
+        return {};
+    }
+    // Forward pass: every user prompt, joined + capped.
+    const parts = [];
+    let total = 0;
+    for (const line of lines) {
+        // Cheap prefilter: skip every line that isn't a user-role message before the
+        // (relatively costly) JSON.parse. Pi writes compact JSON (no spaces), but
+        // tolerate the spaced form too.
+        if (line === '' || (line.indexOf('"role":"user"') === -1 && line.indexOf('"role": "user"') === -1))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
         }
-        if (parts.length === 0)
-            return undefined;
+        catch {
+            continue;
+        }
+        if (rec.type !== 'message' || rec.message?.role !== 'user')
+            continue;
+        const text = extractUserText(rec.message.content);
+        if (text === '')
+            continue;
+        const capped = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
+        parts.push(capped);
+        total += capped.length + 1;
+        if (total >= CONVO_CAP)
+            break;
+    }
+    let prompts;
+    if (parts.length > 0) {
         const joined = parts.join('\n');
-        return joined.length > CONVO_CAP ? joined.slice(0, CONVO_CAP) : joined;
+        prompts = joined.length > CONVO_CAP ? joined.slice(0, CONVO_CAP) : joined;
+    }
+    // Backward pass: the newest assistant message carrying text.
+    let lastAssistant;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line === '' || (line.indexOf('"role":"assistant"') === -1 && line.indexOf('"role": "assistant"') === -1))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.type !== 'message' || rec.message?.role !== 'assistant')
+            continue;
+        const text = extractUserText(rec.message.content);
+        if (text === '')
+            continue;
+        lastAssistant = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
+        break;
+    }
+    return { prompts, lastAssistant };
+}
+/** Is the node GENUINELY mid-turn right now? The `busy` marker (touched on
+ *  agent_start, removed on agent_end) AND-ed with broker-pid liveness, so a stale
+ *  marker from a crashed pi reads false. This is the live "generating?" signal
+ *  — distinct from `status: 'active'`, which only means the engine never closed
+ *  (an active node is usually dormant between turns). Read directly off disk
+ *  (mirrors telemetry) to avoid inverting the canvas→runtime dependency. */
+function isStreaming(nodeId, piPid) {
+    if (!isPidAlive(piPid))
+        return false;
+    try {
+        return existsSync(join(jobDir(nodeId), 'busy'));
     }
     catch {
-        return undefined;
+        return false;
     }
 }
 /** Concatenate the `text` blocks of one pi user message's content. Content is
@@ -269,26 +315,114 @@ export function dashboardRows(rootId) {
             }];
     });
 }
-/** One row per node across the entire canvas. */
+/** "Most recent activity" sort key (epoch ms) read CHEAPLY: a `statSync` (no file
+ *  read, no parse) of the node's job/telemetry.json — rewritten on every turn_end at
+ *  a deterministic canvas-home path, so it tracks last-message recency without a meta
+ *  read. Falls back to `created`'s epoch when a node never ran a turn (no telemetry).
+ *  Never throws. */
+function sessionMtime(nodeId, created) {
+    try {
+        const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
+        if (st !== undefined)
+            return st.mtimeMs;
+    }
+    catch {
+        /* fall through to created */
+    }
+    const t = Date.parse(created);
+    return Number.isNaN(t) ? 0 : t;
+}
+/**
+ * CHEAP boot builder — one row per node across the entire canvas, with only the
+ * fields that need no per-node meta/telemetry/session read. Two db queries total:
+ * `listNodes()` + `listFocuses()` (the focus set replaces 1473 `getFocusByNode`
+ * calls). For each node:
+ *   - identity/status/kind/mode/cwd/created/lifecycle straight off the db row;
+ *   - `name` is the db HANDLE only (the informative label needs meta.description —
+ *     fold it in lazily via {@link enrichRow}/{@link enrichRows});
+ *   - `viewed` from the one focus-set;
+ *   - `streaming` only for LIVE nodes (active|idle — the only ones that can be
+ *     mid-turn); dormant rows are always false (skips an isPidAlive + statSync);
+ *   - `mtimeMs` via a cheap telemetry statSync (no read) for the attention sort;
+ *   - `ctx_tokens`/`asks` left 0 and `goal`/`prompts`/`lastAssistant` undefined —
+ *     all deferred to the lazy enrichment API below.
+ *
+ * This is the first-frame path: paint from it immediately, then enrich the visible
+ * viewport on demand. See {@link enrichRow}, {@link enrichRows}, {@link loadPreview}.
+ */
 export function dashboardRowsAll() {
-    return listNodes().flatMap((row) => {
-        const tel = readNodeTelemetry(row.node_id);
-        // listNodes() returns the db projection (no description); read the meta to
-        // get the full label. Falls back to the row name if the meta is gone.
-        const meta = getNode(row.node_id);
-        return [{
-                node_id: row.node_id,
-                name: meta !== null ? fullName(meta) : row.name,
-                status: row.status,
-                kind: row.kind,
-                mode: row.mode,
-                ctx_tokens: tel.tokens_in ?? 0,
-                asks: countAsks(row.node_id),
-                cwd: row.cwd,
-                created: row.created,
-                lifecycle: row.lifecycle,
-                goal: readGoalText(row.node_id),
-                prompts: readConversationPrompts(meta?.pi_session_file),
-            }];
+    const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
+    return listNodes().map((row) => {
+        const live = row.status === 'active' || row.status === 'idle';
+        return {
+            node_id: row.node_id,
+            name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
+            status: row.status,
+            kind: row.kind,
+            mode: row.mode,
+            ctx_tokens: 0, // lazy: enrichRow
+            asks: 0, // lazy: enrichRow / enrichRows
+            cwd: row.cwd,
+            created: row.created,
+            lifecycle: row.lifecycle,
+            mtimeMs: sessionMtime(row.node_id, row.created),
+            streaming: live ? isStreaming(row.node_id, row.pi_pid) : false,
+            viewed: focusedNodeIds.has(row.node_id),
+        };
     });
 }
+// ---------------------------------------------------------------------------
+// Lazy enrichment API — fold the expensive per-node reads into rows on demand,
+// for the VISIBLE viewport / top tiers only (never all 1473 up front). Each
+// function mutates the row in place (the browse tree holds the row reference, so
+// a later flush re-renders the upgraded data) and is idempotent via a guard flag
+// so progressive paint can call it for the viewport every keystroke for free.
+// ---------------------------------------------------------------------------
+/** Fold the cheap-boot row's deferred fields in for ONE row: the full label
+ *  (meta.description → fullName), ctx tokens (telemetry.json), and ⚑ asks. One
+ *  meta read + one telemetry read + one ask scan. Idempotent (no-op once enriched).
+ *  For a batch, prefer {@link enrichRows} — it scans each cwd's ask inbox once. */
+export function enrichRow(row) {
+    if (row.enriched === true)
+        return row;
+    const meta = getNode(row.node_id);
+    if (meta !== null)
+        row.name = fullName(meta);
+    row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
+    row.asks = countAsks(row.node_id);
+    row.enriched = true;
+    return row;
+}
+/** Batch {@link enrichRow}: enrich every not-yet-enriched row, scanning each
+ *  distinct cwd's ask inbox exactly ONCE (via `asksForNodes`) instead of per row.
+ *  Use this for a whole viewport / the full forest; mutates each row in place. */
+export function enrichRows(rows) {
+    const todo = rows.filter((r) => r.enriched !== true);
+    if (todo.length === 0)
+        return;
+    const asks = asksForNodes(todo.map((r) => r.node_id));
+    for (const row of todo) {
+        const meta = getNode(row.node_id);
+        if (meta !== null)
+            row.name = fullName(meta);
+        row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
+        row.asks = asks[row.node_id] ?? 0;
+        row.enriched = true;
+    }
+}
+/** Load the SELECTED row's preview text: the spawn `goal` (initial-prompt.md) plus
+ *  the whole-conversation `prompts` and the `lastAssistant` reply — the latter two
+ *  folded into ONE session-file read (see {@link readSessionParts}). Mutates the row
+ *  in place; idempotent. Call only for the cursor row (and lazily/in-background to
+ *  warm the prompt super-search corpus), never on the boot path. */
+export function loadPreview(row) {
+    if (row.previewLoaded === true)
+        return row;
+    row.goal = readGoalText(row.node_id);
+    const meta = getNode(row.node_id);
+    const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
+    row.prompts = prompts;
+    row.lastAssistant = lastAssistant;
+    row.previewLoaded = true;
+    return row;
+}

package/dist/core/canvas/types.d.ts

@@ -1,10 +1,15 @@
 import type { SpawnChildOpts } from '../runtime/spawn.js';
-/** What a node is doing right now. `active` means the engine process is live on
- *  its host — a tmux pane OR a headless broker (`host_kind`) — NOT that it holds
- *  a window or that anyone is watching it (attachment is a separate axis: the
- *  `focuses` table for tmux, the broker's viewer set for headless). UI shows
- *  active+idle; `done` is hidden but revivable; `canceled` is a user-closed node
- *  (also hidden, also revivable — not a fault); only `dead` is a fault. */
+/** What a node is doing right now. `active` means the engine process — a detached
+ *  headless broker — is live, NOT that it holds a window or that anyone is
+ *  watching it (attachment is a separate axis: the `focuses` table tracks each
+ *  node's one viewer pane, and the broker records its helloed-viewer count).
+ *  Crucially, `active` does NOT mean the node is GENERATING right now: a live
+ *  engine sits dormant between turns (waiting on a child, a human, or just left
+ *  open), so `active` ≠ busy — it only means the process was never closed. To tell
+ *  whether an active node is actually working, check its pi session-file mtime or
+ *  CPU, not its status. UI shows active+idle; `done` is hidden but revivable;
+ *  `canceled` is a user-closed node (also hidden, also revivable — not a fault);
+ *  only `dead` is a fault. */
 export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
 /** Does stopping finalize the node? terminal = worker (finalizes on push --final);
  *  resident = manager/orchestrator (stays dormant, woken by inbox). */
@@ -84,16 +89,6 @@ export interface NodeIdentity {
     fork_from?: string | null;
     /** New subscriptions this node opens default to passive when true. */
     passive_default?: boolean;
-    /** REVIVE-HOME — the tmux session a node is (re)opened into when it must
-     *  generate but is NOT focused (the durable revive target, distinct from the
-     *  live LOCATION held by the runtime `tmux_session`). Set once at birth
-     *  (managed child → the shared backstage `nodeSession()`; inline root → the
-     *  adopted caller session; independent `--root` → the caller session), and
-     *  rewritten only by demote-recycle. Durable identity (like `cwd`), never
-     *  touched by a focus swap — this is what keeps a background revive off the
-     *  user's session. Legacy metas omit it; readers default to
-     *  `tmux_session ?? nodeSession()` (see `homeSessionOf`). */
-    home_session?: string;
     /** The pi session id for `--session <id>` revival. */
     pi_session_id?: string | null;
     /** Absolute path to pi's session `.jsonl` file, captured at session_start via
@@ -126,13 +121,11 @@ export interface NodeRuntime {
      *  Optional on the hydrated view (a fresh construction omits it); the row
      *  column is always present, defaulting null. */
     intent?: ExitIntent;
-    /** OS pid of the live pi process, recorded on boot (stophook session_start).
-     *  The daemon's authoritative liveness signal: an inline root runs pi as a
-     *  child of a persistent login shell, so its tmux window outlives a dead pi —
-     *  window-existence alone can't detect the death, but a dead pid can. Cleared
-     *  to null by a window-backed relaunch (reviveNode) until the fresh pi
-     *  re-records it; left intact by an in-place respawn (reviveInPlace) so a
-     *  failed respawn surfaces as a dead pid. */
+    /** OS pid of the live broker process, recorded on boot (stophook session_start).
+     *  The daemon's authoritative liveness signal — every node is a detached broker,
+     *  so `isPidAlive(pi_pid)` is the sole liveness check. Cleared to null by
+     *  reviveNode until the fresh broker re-records it, so the relaunch gap reads as
+     *  a dead pid (guarded by the daemon's revive grace, not a double-spawn). */
     pi_pid?: number | null;
     /** Presence: the tmux session (its root's home) and window this node renders
      *  in while active. Cleared when the node goes done/dead and its window closes.

package/dist/core/config.js

@@ -118,10 +118,7 @@ function mergeConfig(partial) {
         ? Math.floor(rawMaxPanes)
         : defaults.max_panes_per_window;
     const canvasNav = mergeCanvasNav(partial.canvasNav);
-    // The merge drops unknown keys, so `headless` must be carried explicitly or it
-    // is lost on every read-modify-write of config.json.
-    const headless = typeof partial.headless === 'boolean' ? partial.headless : defaults.headless;
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, headless };
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav };
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);

package/dist/core/memory-resolver.js

@@ -1,4 +1,5 @@
 import { join, relative, sep } from 'node:path';
+import { readdirSync } from 'node:fs';
 import { pathExists, readText, walkFiles } from './fs-utils.js';
 import { parseFrontmatterGeneric } from './frontmatter.js';
 import { listInstalledPlugins, parseSkillQualifier } from './resolver.js';
@@ -33,19 +34,49 @@ export function listMemoryDocs(scope) {
     if (!dir || !pathExists(dir))
         return [];
     const docs = [];
-    for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
-        const name = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
-        if (!name)
+    // Walk: a dir containing SKILL.md is a single substrate bundle — emit ONE doc
+    // named by the dir's relative path, sourced from its SKILL.md, and STOP
+    // descending (deeper files are bundle assets, not docs). Every other dir
+    // yields its flat *.md files (topical subdirs / INDEX.md) as before.
+    const found = [];
+    const stack = [dir];
+    while (stack.length) {
+        const d = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
             continue;
+        }
+        const hasSkill = entries.some((e) => e.isFile() && e.name === 'SKILL.md');
+        if (hasSkill) {
+            const name = relative(dir, d).split(sep).join('/');
+            if (name)
+                found.push({ path: join(d, 'SKILL.md'), name });
+            continue; // stop descent — deeper dirs are assets
+        }
+        for (const e of entries) {
+            if (e.isDirectory())
+                stack.push(join(d, e.name));
+            else if (e.isFile() && e.name.endsWith('.md')) {
+                const file = join(d, e.name);
+                const name = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+                if (name)
+                    found.push({ path: file, name });
+            }
+        }
+    }
+    for (const { path, name } of found) {
         // COLLECTION layer: the strict frontmatter parser throws on invalid YAML.
         // Isolate one malformed doc with a clear scoped notice + skip, so a single
         // bad file can't brick `memory list`/`find` or the substrate boot render.
         try {
-            docs.push(loadMemoryDoc(name, scope, file));
+            docs.push(loadMemoryDoc(name, scope, path));
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-            warn(`invalid frontmatter in ${file}: ${msg}`);
+            warn(`invalid frontmatter in ${path}: ${msg}`);
         }
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
@@ -105,6 +136,13 @@ function findMemoryMatches(name, scope) {
                 matches.push(loadMemoryDoc(name, s, path));
                 continue;
             }
+            // Bundle marker is authoritative: a `<name>/SKILL.md` resolves the bare
+            // dir name to its bundle doc, and wins over INDEX.md if both exist.
+            const skillPath = join(dir, ...name.split('/'), 'SKILL.md');
+            if (pathExists(skillPath)) {
+                matches.push(loadMemoryDoc(name, s, skillPath));
+                continue;
+            }
             const indexPath = join(dir, ...name.split('/'), 'INDEX.md');
             if (pathExists(indexPath)) {
                 matches.push(loadMemoryDoc(name, s, indexPath));

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

@@ -56,6 +56,6 @@ export declare function buildWakeBearings(origin: WakeOrigin): string;
  *  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 `<references>` block carries the substrate reference docs
+ *  resumes from. The `<knowledge>` block carries the substrate knowledge docs
  *  + node-local docs. */
 export declare function buildContextBearings(nodeId: string): string;

package/dist/core/runtime/bearings.js

@@ -19,15 +19,15 @@
 // 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 `<references>` block
-// (substrate reference docs + node-local docs) rides into the context message.
+// sense once a node is a resident orchestrator). The `<knowledge>` block
+// (substrate knowledge docs + node-local docs) rides into the context message.
 //
 // 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 { cadenceDisplay } from '../wake.js';
-import { renderReferencesBlock } from '../substrate/index.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 ' +
@@ -145,7 +145,7 @@ export function buildWakeBearings(origin) {
  *  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 `<references>` block carries the substrate reference docs
+ *  resumes from. The `<knowledge>` block carries the substrate knowledge docs
  *  + node-local docs. */
 export function buildContextBearings(nodeId) {
     const identity = buildIdentityAssertion(nodeId);
@@ -155,11 +155,11 @@ export function buildContextBearings(nodeId) {
     // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
     if (node?.mode === 'orchestrator')
         parts.push(orchestratorContextNote(nodeId));
-    // The substrate references block: eligible `reference` docs at their
+    // The substrate knowledge block: eligible `knowledge` docs at their
     // system-prompt rung + node-local memory docs; dropped (returns '') when
     // nothing is eligible.
-    const references = renderReferencesBlock(nodeId);
-    if (references !== '')
-        parts.push(references);
+    const knowledge = renderKnowledgeBlock(nodeId);
+    if (knowledge !== '')
+        parts.push(knowledge);
     return `${identity}\n<crtr-context dir="${dir}">\n${parts.join('\n')}\n</crtr-context>`;
 }

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

@@ -0,0 +1,16 @@
+/** Machine-global host dir. Deliberately NOT under `CRTR_HOME` (tests override
+ *  that to an isolated temp): the branded binary is a per-machine artifact keyed
+ *  to the installed node, shared across every canvas home. */
+export declare function brandedHostDir(): string;
+export declare function brandedHostBin(): string;
+/** 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
+ *  surfaced, never silently masked by falling back to `node`. */
+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. */
+export declare function hostExecPath(): string;

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

@@ -0,0 +1,127 @@
+// branded-host.ts — a crouter-branded copy of the `node` binary, so the
+// long-lived engine processes (brokers + the crtrd daemon) show "crouter" in
+// macOS' TCC / Full Disk Access list instead of the generic "node".
+//
+// WHY a real copied binary (not a symlink, not process.title): macOS keys a
+// Full Disk Access entry on the Mach-O binary's *filename* — not argv[0], not
+// process.title, and symlinks resolve to their realpath. So the ONLY way to show
+// a branded name is to launch the engine from a real Mach-O file whose filename
+// is the brand. We copy the node launcher to `~/.crouter/host/crouter`.
+//
+// WHY self-contained (libnode beside it): a Homebrew node is a small (~70 KB)
+// launcher that dynamically loads `@rpath/libnode.<abi>.dylib` (~70 MB). node's
+// LC_RPATH includes `@loader_path`, so a copy of that dylib placed *beside* the
+// branded binary resolves with no DYLD_* env var (which SIP can strip) and no
+// dependency on the Cellar path surviving — even after a `brew uninstall` of the
+// old keg, the branded copy keeps running. A statically-linked node (nodejs.org)
+// has no separate libnode; we just copy the binary. The remaining absolute
+// `/opt/homebrew/opt/...` deps resolve by their baked-in absolute paths.
+//
+// SELF-HEAL: ensureBrandedHost() rebuilds the copy whenever the live node drifts
+// (a `brew upgrade node` moves realpath(execPath) to a new Cellar version) or the
+// copy is missing. The drift check is a cheap marker compare — no subprocess, no
+// copy — on the happy path.
+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 { CRTR_DIR_NAME } from '../../types.js';
+/** The filename the FDA / TCC entry is shown under. */
+const BRANDED_BIN_NAME = 'crouter';
+/** Machine-global host dir. Deliberately NOT under `CRTR_HOME` (tests override
+ *  that to an isolated temp): the branded binary is a per-machine artifact keyed
+ *  to the installed node, shared across every canvas home. */
+export function brandedHostDir() {
+    return join(homedir(), CRTR_DIR_NAME, 'host');
+}
+export function brandedHostBin() {
+    return join(brandedHostDir(), BRANDED_BIN_NAME);
+}
+function markerPath() {
+    return join(brandedHostDir(), '.source.json');
+}
+/** Locate the `libnode.<abi>.dylib` a Homebrew node loads via `@rpath`. node's
+ *  rpaths are `@loader_path` and `@loader_path/../lib`, so check the binary's own
+ *  dir first, then the sibling `lib/`. Returns the absolute path, or null for a
+ *  statically-linked node that has no separate libnode. */
+function findLibnode(nodeBin) {
+    const binDir = dirname(nodeBin);
+    for (const dir of [binDir, join(binDir, '..', 'lib')]) {
+        if (!existsSync(dir))
+            continue;
+        const hit = readdirSync(dir).find((f) => f.startsWith('libnode.') && f.endsWith('.dylib'));
+        if (hit !== undefined)
+            return join(dir, hit);
+    }
+    return null;
+}
+/** Copy `src` → `dst` via a unique temp + atomic rename, so concurrent rebuilds
+ *  (two brokers spawning at once) never observe a half-written file. */
+function atomicCopy(src, dst, mode) {
+    const tmp = `${dst}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    copyFileSync(src, tmp);
+    if (mode !== undefined)
+        chmodSync(tmp, mode);
+    renameSync(tmp, dst);
+}
+function readMarker() {
+    try {
+        return JSON.parse(readFileSync(markerPath(), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** 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
+ *  surfaced, never silently masked by falling back to `node`. */
+export function ensureBrandedHost() {
+    const dst = brandedHostBin();
+    const src = realpathSync(process.execPath);
+    // If THIS process is already running as the branded host (the daemon or a
+    // broker spawning a child), don't rebuild from ourselves — we can't see the
+    // real node from here, and the live process proves the copy works. Drift is
+    // healed by the next real-`node` CLI invocation.
+    if (existsSync(dst) && realpathSync(dst) === src)
+        return dst;
+    const marker = readMarker();
+    const libnodeSrc = findLibnode(src);
+    const libnodeName = libnodeSrc !== null ? libnodeSrc.split('/').pop() : null;
+    const fresh = existsSync(dst) &&
+        marker !== null &&
+        marker.source === src &&
+        marker.libnode === libnodeName &&
+        (libnodeName === null || existsSync(join(brandedHostDir(), libnodeName)));
+    if (fresh)
+        return dst;
+    // (Re)build. Clear a stale libnode of a different ABI so the dir stays clean.
+    mkdirSync(brandedHostDir(), { recursive: true });
+    if (marker?.libnode != null && marker.libnode !== libnodeName) {
+        try {
+            unlinkSync(join(brandedHostDir(), marker.libnode));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    if (libnodeSrc !== null && libnodeName !== null) {
+        atomicCopy(libnodeSrc, join(brandedHostDir(), libnodeName));
+    }
+    atomicCopy(src, dst, 0o755);
+    writeFileSync(markerPath(), JSON.stringify({ 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. */
+export function hostExecPath() {
+    if (process.env['CRTR_BRANDED_HOST'] === '0')
+        return process.execPath;
+    if (process.platform !== 'darwin')
+        return process.execPath;
+    if (import.meta.url.endsWith('.ts'))
+        return process.execPath;
+    return ensureBrandedHost();
+}