@north-light/crouter 0.3.154

package/dist/core/runtime/bearings.js

@@ -0,0 +1,429 @@
+// 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. 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. The message also
+//     carries the <project_context> block (buildProjectContextBlock), which is
+//     now only the <environment> snapshot: a host/runtime line (platform,
+//     hostname, node, tmux-or-not), the cwd dir listing, and git status.
+//     Project guidance rides the
+//     document substrate instead: migrated CLAUDE.md/AGENTS.md docs live in the
+//     source dir's own `.crouter/memory/AGENTS.md` and surface through the
+//     <memory kind="knowledge"> block below (renderKnowledgeBlock) via the
+//     profile-widened boot render — no parallel project-context loader lives
+//     here anymore (see `crtr memory read taste/document-substrate`);
+//   • 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
+//     worker, and the bearings already in its history carry only the base note.
+//
+// Base framing (every node): the context dir is durable, shared scratch — the
+// 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 `<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, isSafeNodeId, subscriptionsOf, } from '../canvas/index.js';
+import { execSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { hostname } from 'node:os';
+import { cadenceDisplay } from '../wake.js';
+import { renderKnowledgeBlock } from '../substrate/index.js';
+import { loadProfileManifest } from '../profiles/manifest.js';
+import { situationalContextBlock } from './situational-context.js';
+function escapeAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+/** A one-line snapshot of the host/runtime the node's engine is executing in —
+ *  platform, hostname, node version, and whether a tmux server is reachable.
+ *  The engine is headless, so this reflects the broker/daemon environment the
+ *  node's own bash tools inherit — NOT a viewer pane.
+ *
+ *  The tmux bit deliberately reports SERVER REACHABILITY, not "am I inside a
+ *  tmux pane" — the latter is a constant `no` for every node and so tells the
+ *  agent nothing: a broker is detached and paneless, and DELETES $TMUX /
+ *  $TMUX_PANE from its env on boot (broker.ts) so its children never act on the
+ *  launching parent's pane. The actionable question is whether this process's
+ *  bash tools can drive tmux at all, and `tmux list-sessions` exits 0 iff a
+ *  server is running. The label says `tmux server` so it cannot be misread as
+ *  pane residency. */
+function runtimeLine() {
+    const tmuxServer = spawnSync('tmux', ['list-sessions'], { encoding: 'utf8', stdio: 'ignore' }).status === 0;
+    const parts = [
+        `${process.platform} ${process.arch}`,
+        hostname(),
+        `node ${process.version}`,
+        `tmux server: ${tmuxServer ? 'reachable' : 'none'}`,
+    ];
+    return `Host: ${parts.join(' · ')}`;
+}
+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 — the `<environment>` snapshot only: a
+ *  host/runtime line (platform, hostname, node version, tmux-or-not — the
+ *  headless engine's own process env, which its bash tools inherit), the cwd
+ *  dir listing, and git status/worktrees. Project guidance lives in the
+ *  document substrate, so this wrapper stays environment-only. It always emits
+ *  because the environment snapshot is always present. Exported for testing. */
+/** The `customType` stamped on a node's injected bearings message. Lives here,
+ *  beside the builder, because BOTH delivery paths need it: the context-intro
+ *  pi-extension (session_start, the cold path) and the warm-pool claim's live
+ *  delivery. It is also the idempotency discriminator a later revive matches. */
+export const CONTEXT_INTRO_CUSTOM_TYPE = 'crtr-context';
+export function buildProjectContextBlock(cwd) {
+    const envLines = directoryListingLines(cwd);
+    const git = gitSnapshot(cwd);
+    let out = '<project_context>\n\n';
+    out += `<environment cwd="${escapeAttribute(cwd)}">\n`;
+    out += `${runtimeLine()}\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.');
+}
+/** The profile-purview note — rendered ONLY when `profile_id` resolves to a
+ *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd
+ *  replacement: the node's cwd is still its one working dir (bash/edits run
+ *  there), the profile just widens what it may ALSO read/act on. Omitted
+ *  entirely for a profile with no project purview (including the stable root
+ *  profile) or a deleted/unreadable manifest — never throws (mirrors
+ *  `assembleNodeSubject`'s profile resolution). This absolute-path disclosure
+ *  is intentional (spec-approved): the agent must know its full purview, not a
+ *  redacted count. */
+export function profileNote(nodeId) {
+    const meta = getNode(nodeId);
+    const profileId = meta?.profile_id;
+    if (profileId === undefined || profileId === null || profileId === '')
+        return '';
+    let entry;
+    try {
+        entry = loadProfileManifest(profileId);
+    }
+    catch {
+        return '';
+    }
+    const projects = entry.manifest.projects;
+    if (projects.length === 0)
+        return '';
+    return (`Your working dir is \`${meta.cwd}\`. Your profile **${entry.manifest.name}** also has purview ` +
+        `over: ${projects.join(', ')}.`);
+}
+/** 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
+ *  promoted node gets the same note a born-orchestrator gets. */
+export function orchestratorContextNote(nodeId) {
+    return (`Because you persist across refresh cycles, your context directory (${contextDir(nodeId)}) is ` +
+        `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');
+}
+/** Render the identity assertion for a known or not-yet-persisted node. A fork
+ *  copies the source's first-person conversation, so its kickoff names the new
+ *  identity and treats the inherited narrative as reference material. */
+export function buildIdentityAssertionFor(meta) {
+    const lines = [`You are node ${meta.node_id} — kind ${meta.kind}, mode ${meta.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
+        // (e.g. a human-work provenance file) passes through as-is — getNode()
+        // requires a safe node-id segment and throws on an arbitrary path, so only
+        // call it when forkFrom actually looks like a node id.
+        const src = isSafeNodeId(forkFrom) ? getNode(forkFrom) : null;
+        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 ` +
+            `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. You inherit none of the ' +
+            'source node’s graph edges and are not responsible for monitoring or managing its children.');
+    }
+    return lines.join('\n');
+}
+/** The identity assertion injected at session start for an already-persisted
+ *  node. Exported for tests and spawn-time fork kickoff construction. */
+export function buildIdentityAssertion(nodeId) {
+    const meta = getNode(nodeId);
+    return buildIdentityAssertionFor({
+        node_id: nodeId,
+        kind: meta?.kind ?? 'general',
+        mode: meta?.mode ?? 'base',
+        fork_from: meta?.fork_from,
+    });
+}
+/** The armer rendered for prose, ROLE-explicit so a newborn never mistakes the
+ *  id for its own: `node <id> ("<name>")` when the name resolved, `node <id>
+ *  (now gone)` when the armer was reaped, `an unknown node` only if the owner id
+ *  is somehow absent (owner_id is NOT NULL on every real row — defensive). */
+function armerPhrase(origin) {
+    if (origin.ownerId === null || origin.ownerId === '')
+        return 'an unknown node';
+    if (origin.ownerName !== undefined)
+        return `node ${origin.ownerId} ("${origin.ownerName}")`;
+    return `node ${origin.ownerId} (now gone)`;
+}
+/** Build the provenance a fired cron carries to its injection seam, resolving
+ *  the armer's display name if that node still exists. */
+export function cronWakeOrigin(c, kind) {
+    const owner = c.created_by != null ? getNode(c.created_by) : null;
+    return {
+        kind,
+        ownerId: c.created_by,
+        ...(owner !== null ? { ownerName: fullName(owner) } : {}),
+        armedAt: c.created,
+        recur: c.recur,
+    };
+}
+/** Render the cron provenance block. The BIRTH variant names the ARMER
+ *  explicitly ("armed by node X") so a newborn never reads that id as its own;
+ *  the REVIVE variant drops armer attribution — a cron can revive a node it did
+ *  not create, and who armed it is not decision-relevant to a timed re-check —
+ *  and instead reframes the generic "you were revived" into "a clock woke you".
+ *  A recurrence surfaces its cadence either way, so the agent knows it is one
+ *  run of a standing job. No timestamp is rendered: "now"/the cadence already
+ *  carry the signal, and a raw ISO instant is noise an agent cannot cheaply turn
+ *  into an elapsed delta. */
+export function buildWakeBearings(origin) {
+    const recurring = origin.recur !== null && origin.recur !== undefined && origin.recur !== '';
+    const cadence = recurring ? cadenceDisplay(origin.recur) : null;
+    if (origin.kind === 'schedule_revive') {
+        const reviveBody = recurring
+            ? `A SCHEDULE woke you, not a message — a recurring cron firing ${cadence} revived you fresh. ` +
+                `Nothing new happened on the canvas and nobody is waiting on a reply: the clock came round. ` +
+                `Re-read your bearings below, do this cycle's pass of the standing job, and stop.`
+            : `A SCHEDULE woke you, not a message — a one-shot cron armed to fire now revived you fresh. ` +
+                `Nothing new happened on the canvas and nobody is waiting on a reply: the time you were waiting ` +
+                `for arrived. Re-read your bearings below and continue from there.`;
+        return `<crtr-wake>\n${reviveBody}\n</crtr-wake>`;
+    }
+    const armer = armerPhrase(origin);
+    const body = recurring
+        ? `You were BORN by a scheduled wake, not spawned on demand — a recurring spawn-cron armed by ` +
+            `${armer}, firing ${cadence}. The runtime re-births a fresh node like you on this cadence whether ` +
+            `or not earlier runs survived: you are one run of a standing job, not a one-off, and you inherit ` +
+            `nothing from prior runs but this task. Your task follows.`
+        : `You were BORN by a scheduled wake, not spawned on demand — a one-shot deferred birth armed by ` +
+            `${armer} to fire now. You are its only run, not a recurring job. Your task follows.`;
+    return `<crtr-wake>\n${body}\n</crtr-wake>`;
+}
+/** 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 cwd/git environment snapshot. pi's own
+ *      AGENTS.md/CLAUDE.md system-prompt injection stays suppressed
+ *      (noContextFiles in broker.ts); project guidance instead rides the
+ *      `<memory kind="knowledge">` block above via the document substrate
+ *      (`crtr sys sync project-guidance` migrates each CLAUDE.md/AGENTS.md into
+ *      that dir's own `.crouter/memory/AGENTS.md`). */
+export function buildContextBearings(nodeId) {
+    const node = getNode(nodeId);
+    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));
+    // Profile purview — omitted entirely when there is no project purview (see profileNote).
+    const profileSection = profileNote(nodeId);
+    if (profileSection !== '')
+        bearings.push('', profileSection);
+    const wt = node?.managed_worktree;
+    if (wt?.state === 'open') {
+        bearings.push('', '## Your managed worktree', `Branch: \`${wt.branch}\`\nWorktree: \`${wt.path}\`\nBase: \`${wt.base_ref}\` @ \`${wt.base_sha}\`\nCommit work here. Land it with \`crtr node worktree close\` before finishing. Auto-drop applies only when the worktree is clean (no uncommitted changes) and nothing remains to land (zero commits ahead of the base, or its commits are already contained in the base); unlanded commits (commits not already contained in the base) or uncommitted changes require an explicit close/landing decision.`);
+    }
+    // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
+    if (node?.mode === 'orchestrator')
+        bearings.push('', orchestratorContextNote(nodeId));
+    bearings.push('</crtr-bearings>');
+    // The consultable catalog rides BESIDE the bearings, not inside them.
+    const knowledge = renderKnowledgeBlock(nodeId);
+    // Hidden applet/situation-origin ambient context (see situational-context.ts)
+    // — a SIBLING block, never nested under <crtr-bearings>, and never routed
+    // through the visible chat/digest path. '' when nothing was ever set.
+    const situational = situationalContextBlock(nodeId);
+    const projectCtx = node?.cwd !== undefined ? buildProjectContextBlock(node.cwd) : '';
+    return [bearings.join('\n'), knowledge, situational, projectCtx].filter((s) => s !== '').join('\n');
+}

package/dist/core/runtime/boot-root.d.ts

@@ -0,0 +1,24 @@
+export interface BootRootOpts {
+    cwd: string;
+    kind?: string;
+    name?: string;
+    /** Optional starter prompt (bare `crtr` requires none). */
+    prompt?: string;
+    /** Explicit `--profile <id-or-name>` on the front-door invocation, validated
+     *  through `loadProfileManifest`. Omit to run the MRU/create-or-root-profile
+     *  startup selector for `cwd` (see `selectProfileForCwd`) — a root has no
+     *  spawner to inherit from, so this is the front door's only source of profile
+     *  identity. */
+    profile?: string | null;
+    /** `crtr --pick-profile`: force the startup profile chooser to open even when
+     *  a per-cwd default is pinned, so the user can re-pin or unpin it. Without
+     *  this a pinned default auto-picks silently (that is what "default" means). */
+    pickProfile?: boolean;
+}
+/** Boot the front-door root: create the resident root through crtrd (broker
+ *  launched + view socket ready server-side), register THIS terminal's pane as
+ *  its foreground viewer, then exec `crtr surface attach` inline so this terminal
+ *  becomes a writable viewer. Does not return — it process.exit()s
+ *  when the inline attach exits (detach leaves the resident broker running, to
+ *  be reconnected later). */
+export declare function bootRoot(opts: BootRootOpts): Promise<never>;

package/dist/core/runtime/boot-root.js

@@ -0,0 +1,102 @@
+// boot-root.ts — the user-opened front door (bare `crtr`), canvas-free.
+//
+// bootRoot creates the resident root through crtrd (`createNode({root:true})`,
+// which the daemon serves at readiness 'await' — node birth, broker launch, and
+// view-socket readiness ALL happen server-side), then execs `crtr surface
+// attach` inline so THIS terminal becomes the broker's writable viewer.
+//
+// crtrd is the sole owner of canvas state (see crtrd-sole-state-owner), so this
+// module opens NO canvas.db: node creation and the viewer-focus row both route
+// through the /v1 API client. The only work that stays client-side is what
+// genuinely belongs to the user's terminal — the interactive startup profile
+// pick, the tmux-binding reconcile, and the inline attach exec. This is why the
+// front-door boot path (cli.js → front-door.js → here) reaches zero canvas code.
+import { spawn } from 'node:child_process';
+import { inTmux, currentTmux, viewerSplitEnv } from './placement-tmux.js';
+import { selectProfileForCwd } from '../profiles/select.js';
+import { cliClient } from '../../commands/api-client.js';
+import { mark } from '../timing.js';
+/** Boot the front-door root: create the resident root through crtrd (broker
+ *  launched + view socket ready server-side), register THIS terminal's pane as
+ *  its foreground viewer, then exec `crtr surface attach` inline so this terminal
+ *  becomes a writable viewer. Does not return — it process.exit()s
+ *  when the inline attach exits (detach leaves the resident broker running, to
+ *  be reconnected later). */
+export async function bootRoot(opts) {
+    // crtr is tmux-only: the front door execs `crtr surface attach` inline in THIS
+    // pane to become the root's writable viewer, so there must be a tmux pane to
+    // anchor on. Outside tmux there is no viewer surface — throw with a friendly
+    // message rather than boot a root nobody can see.
+    if (!inTmux()) {
+        throw new Error('crtr must be started from inside a tmux session — start tmux first (e.g. `tmux new -s work`), then run `crtr` there.');
+    }
+    const kind = opts.kind ?? 'general';
+    // The front door's only source of profile identity — a root has no spawner to
+    // inherit from. Runs BEFORE the create call: explicit --profile > MRU profile
+    // covering cwd > a synchronous create-or-root-profile prompt (the stable root
+    // profile, headless). INTERACTIVE, so it must stay client-side; the resolved
+    // id is handed to crtrd so the server never re-runs the picker.
+    mark('boot_root.start');
+    const profileId = await selectProfileForCwd(opts.cwd, opts.profile, opts.pickProfile ?? false);
+    mark('boot_root.profile_resolved');
+    // Create the resident root through crtrd. `root:true` makes the daemon spawn
+    // it at readiness 'await' — the node row is born (base mode, resident
+    // lifecycle, spawned_by null), its detached broker engine is launched, and its
+    // view socket is bound before this returns. The starter prompt is persisted as
+    // the goal server-side (empty ⇒ no kickoff turn). No boot spinner: the attach
+    // viewer paints the crouton banner the instant the engine attaches (~1s),
+    // which is the real "we're up" signal.
+    const detail = await cliClient().createNode({
+        kind,
+        mode: 'base',
+        prompt: opts.prompt,
+        profile: profileId,
+        cwd: opts.cwd,
+        name: opts.name ?? kind,
+        root: true,
+        // The front door is exactly the wait a warm spare exists to remove: a bare
+        // resident root with no kickoff. A miss costs nothing (cold spawn) and
+        // mints the spare that serves the next one.
+        prefer_warm: true,
+    });
+    const nodeId = detail.node_id;
+    mark('boot_root.node_created', { node: nodeId });
+    // The crouter-owned tmux bindings (including the inbox-toggle key folded into
+    // the same manifest sweep) are NOT reconciled here: that sweep is ~20
+    // sequential `spawnSync tmux` calls (measured ~150ms) and the attach viewer
+    // this boot is about to spawn already runs it a tick after its first paint
+    // (`refreshAttachBindingSnapshot` in viewer.ts). Doing it here only delays
+    // that viewer.
+    // This terminal becomes the root's attach VIEWER in the user's CURRENT session,
+    // so its window stays where the user already is. The node row carries NO
+    // presence — a broker node's pane/window/tmux_session stay NULL; the viewer
+    // pane lives in the focuses table. Register the FOREGROUND front-door pane as
+    // this node's focus (canvas write, routed through crtrd) so focus/nav can find
+    // it. Best-effort — attach works regardless.
+    const here = currentTmux();
+    if (here !== null) {
+        try {
+            await cliClient().registerFocus({ node_id: nodeId, pane: here.pane, session: here.session, window: here.window });
+        }
+        catch { /* best-effort */ }
+    }
+    // Broker is the only host: the root runs as a detached broker engine (already
+    // launched above), and THIS terminal execs `crtr surface attach` inline to
+    // become its writable viewer. The attach's own ensureAttach is an idempotent
+    // no-op on the already-live broker. CRTR_ATTACH_WAIT_MS tells the viewer to
+    // poll view.sock until it accepts instead of failing fast on a not-yet-bound
+    // socket. CRTR_ATTACH_BORROWED_PANE tells the viewer that its pane is the
+    // user's OWN pre-existing shell pane (not one crtr split open): on a
+    // detach-reap of an empty root it must delete the node WITHOUT kill-pane, else
+    // a plain ctrl+c closes the user's whole tmux pane.
+    const attachEnv = { ...process.env, ...viewerSplitEnv(), CRTR_ATTACH_WAIT_MS: '30000' };
+    if (here !== null)
+        attachEnv['CRTR_ATTACH_BORROWED_PANE'] = here.pane;
+    mark('boot_root.viewer_spawn');
+    const attachChild = spawn('crtr', ['surface', 'attach', 'to', nodeId], { stdio: 'inherit', env: attachEnv });
+    const code = await new Promise((res) => {
+        attachChild.once('exit', (exitCode) => res(exitCode ?? 0));
+        attachChild.once('error', () => res(1));
+    });
+    process.exit(code);
+}

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

@@ -0,0 +1,25 @@
+/** 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;
+/** macOS keys FDA grants on the Mach-O cdhash. A real developer identity
+ *  keeps that hash stable across branded-host rebuilds; ad-hoc signing is the
+ *  portable default for machines without a local signing certificate. */
+export declare function codesignIdentitiesForBrandedHost(opts?: {
+    configured?: string | null;
+    discovered?: string | null;
+}): string[];
+export declare function signBrandedHostArtifacts(binPath: string, libnodePath: string | null, sign?: (path: string) => void): void;
+export declare function brandedHostWorks(binPath: string, timeoutMs?: number): 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
+ *  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 validated branded host; otherwise —
+ * non-darwin (TCC is macOS-only), source/tsx (dev + the test suite: never copy
+ * 70 MB into the real ~/.crouter), or the explicit `CRTR_BRANDED_HOST=0`
+ * opt-out — it is the live node. */
+export declare function hostExecPath(): string;