@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,56 @@
+import { type Cron } from '../canvas/index.js';
+import type { DeliveredDoc, RenderContext } from '../substrate/delivery/render-event.js';
+import { buildProjectContextBlock, contextDirNote, orchestratorContextNote } from './bearings-render.js';
+/** The bearings custom type is shared with every attached renderer. */
+export { CONTEXT_INTRO_CUSTOM_TYPE } from '../../shared/generated-context.js';
+export { buildProjectContextBlock, contextDirNote, orchestratorContextNote };
+/** 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 declare function profileNote(nodeId: string): Promise<string>;
+/** 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 declare function buildGraphMap(nodeId: string): Promise<string>;
+/** Why a node was born or woken, as carried from the fired cron to the
+ *  injection seam. `ownerName` is the armer's resolved display name when it
+ *  still exists (a reaped cron's armer renders as a bare id, never crashes). */
+export interface WakeOrigin {
+    /** Which enactment the cron drove: a fresh node (`node_birth`) or a fresh
+     *  revive of an existing one (`schedule_revive`). */
+    kind: 'node_birth' | 'schedule_revive';
+    /** The armer node id (`crons.created_by`), or null if absent. */
+    ownerId: string | null;
+    /** The armer's display name, resolved if it still exists. */
+    ownerName?: string;
+    /** `crons.created` — when the cron was armed (ISO). */
+    armedAt: string;
+    /** `crons.recur` JSON when recurring, else null/undefined for a one-shot. */
+    recur?: string | null;
+}
+/** Build the provenance a fired cron carries to its injection seam, resolving
+ *  the armer's display name if that node still exists. */
+export declare function cronWakeOrigin(c: Cron, kind: WakeOrigin['kind']): Promise<WakeOrigin>;
+/** 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 declare function buildWakeBearings(origin: WakeOrigin): string;
+/** The bearings on the row-backed delivery engine: the knowledge catalog and
+ *  the workspace-open documents render against `ctx`'s ledger; `delivered`
+ *  lists what they delivered, for the caller to record. */
+export declare function buildContextBearings(nodeId: string, ctx: RenderContext): Promise<{
+    content: string;
+    delivered: DeliveredDoc[];
+}>;

package/dist/core/runtime/bearings.js

@@ -0,0 +1,199 @@
+// bearings.ts — session orientation shared by every delivery path.
+//
+// A conversation with no inherited crouter bearings receives the full baseline:
+// node identity and graph position, context-directory guidance, routed knowledge,
+// auto-loaded project docs, situational context, and the current environment.
+// A fork whose copied branch already carries that baseline receives only the
+// new node-scoped facts that supersede its source's identity — rendered by
+// buildForkBearingsFromState() in broker-extension-render.ts, the broker-side
+// mirror. The copied baseline remains useful reference without being repeated.
+//
+// persona.ts / broker-persona-guidance.ts deliver orchestratorContextNote() when a base node
+// becomes an orchestrator after birth.
+import { getNode, fullName, isSafeNodeId, subscriptionsOf, } from '../canvas/index.js';
+import { cadenceDisplay } from '../wake.js';
+import { renderKnowledge, renderWorkspaceOpen } from '../substrate/delivery/render-boot.js';
+import { situationalContextEnvelope } from './situational-context.js';
+import { statusRank } from '../canvas/node-order.js';
+import { buildProjectContextBlock, contextDirNote, orchestratorContextNote, profileNote as profileNoteShared, renderGraphMap, buildIdentityAssertion as buildIdentityAssertionShared, worktreeNote, } from './bearings-render.js';
+import { mapAsync } from '../async-array.js';
+/** The bearings custom type is shared with every attached renderer. */
+export { CONTEXT_INTRO_CUSTOM_TYPE } from '../../shared/generated-context.js';
+export { buildProjectContextBlock, contextDirNote, orchestratorContextNote };
+/** 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 async function profileNote(nodeId) {
+    const meta = await getNode(nodeId);
+    if (meta === null)
+        return '';
+    return profileNoteShared(meta.cwd, meta.profile_id);
+}
+// 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.
+/** Ancestry trunk from the root DOWN to (but excluding) `nodeId`, climbing the
+ *  spine `parent` edge. Cycle-guarded. Root first. */
+async function ancestorTrunk(nodeId) {
+    const trunk = [];
+    const seen = new Set([nodeId]);
+    let cur = (await getNode(nodeId))?.parent ?? null;
+    while (cur !== null && cur !== '' && !seen.has(cur)) {
+        seen.add(cur);
+        const m = await 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. */
+async function childNodes(nodeId) {
+    return (await mapAsync(await subscriptionsOf(nodeId), async (s) => await 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 async function buildGraphMap(nodeId) {
+    const meta = await getNode(nodeId);
+    if (meta === null)
+        return '';
+    const trunk = await ancestorTrunk(nodeId);
+    const children = await childNodes(nodeId);
+    return renderGraphMap(nodeId, meta.kind, meta.mode, trunk, children);
+}
+/** The identity assertion injected at session start. A fork names its source
+ *  while treating the copied first-person narrative as reference. */
+async function buildIdentityAssertion(nodeId) {
+    const meta = await getNode(nodeId);
+    const forkFrom = meta?.fork_from;
+    // A known node id carries its human label. Paths and session ids remain
+    // opaque provenance rather than being passed to the node-id lookup.
+    const src = forkFrom !== undefined && forkFrom !== null && forkFrom !== '' && isSafeNodeId(forkFrom) ? await getNode(forkFrom) : null;
+    const sourceLabel = src !== null ? `${forkFrom} ("${fullName(src)}")` : (forkFrom ?? '');
+    return buildIdentityAssertionShared(nodeId, meta?.kind ?? 'general', meta?.mode ?? 'base', forkFrom, sourceLabel);
+}
+/** 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 async function cronWakeOrigin(c, kind) {
+    const owner = c.created_by != null ? await 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>`;
+}
+function managedWorktreeNote(node) {
+    return worktreeNote(node?.managed_worktree);
+}
+/** The full boot intro, four 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 documents and
+ *      context directory` note. The across-cycles framing is added ONLY for an
+ *      orchestrator (by mode) — the one node whose documents a future cycle
+ *      resumes from.
+ *   2. `<memory kind="knowledge">` — the consultable boot catalog, a SIBLING of
+ *      the bearings (never nested under the context dir). Dropped when empty.
+ *   3. `<auto-loaded-context>` — documents whose `on: workspace-open` entry fires
+ *      for this node: any in its view (its repos, profile, app, the user, installed plugins)
+ *      whose entry's `if` conditions — cwd, repo, profile — hold. Dropped when empty.
+ *   4. `<project_context>` — the cwd/git environment snapshot. pi's own
+ *      AGENTS.md/CLAUDE.md injection stays suppressed (`noContextFiles` in
+ *      broker.ts); `crtr sys sync project-guidance` imports that guidance into
+ *      documents owned by the directory's repo (its `<repo>/index` is the workspace front door). */
+async function bearingsShell(nodeId, knowledge, workspaceContext) {
+    const node = await getNode(nodeId);
+    const bearings = ['<crtr-bearings>', await buildIdentityAssertion(nodeId)];
+    const map = await buildGraphMap(nodeId);
+    if (map !== '')
+        bearings.push('', '## Your place in the canvas', map);
+    bearings.push('', '## Your documents and context directory', contextDirNote(nodeId, node?.grantee));
+    // Profile purview — omitted entirely when there is no project purview (see profileNote).
+    const profileSection = await profileNote(nodeId);
+    if (profileSection !== '')
+        bearings.push('', profileSection);
+    const worktree = managedWorktreeNote(node);
+    if (worktree !== '')
+        bearings.push('', '## Your managed worktree', worktree);
+    // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
+    if (node?.mode === 'orchestrator')
+        bearings.push('', orchestratorContextNote());
+    bearings.push('</crtr-bearings>');
+    // Hidden applet/situation-origin ambient context (see situational-context.ts)
+    // — the stored `situational` card, placed in the bearings BODY, so it is a
+    // nested card inside the outer envelope. Never routed through the visible
+    // chat/digest path. '' when nothing was ever set.
+    const situational = await situationalContextEnvelope(nodeId) ?? '';
+    const projectCtx = node?.cwd !== undefined ? buildProjectContextBlock(node.cwd) : '';
+    return [bearings.join('\n'), knowledge, workspaceContext, situational, projectCtx]
+        .filter((s) => s !== '')
+        .join('\n');
+}
+/** The bearings on the row-backed delivery engine: the knowledge catalog and
+ *  the workspace-open documents render against `ctx`'s ledger; `delivered`
+ *  lists what they delivered, for the caller to record. */
+export async function buildContextBearings(nodeId, ctx) {
+    const knowledge = await renderKnowledge(ctx);
+    const workspace = await renderWorkspaceOpen(ctx);
+    return { content: await bearingsShell(nodeId, knowledge.content, workspace.content), delivered: [...knowledge.delivered, ...workspace.delivered] };
+}

package/dist/core/runtime/bin-contributions.d.ts

@@ -0,0 +1,44 @@
+import type { Scope } from '../../types.js';
+/** One resolved bare command: the name a node's bash sees, and the absolute
+ *  real path the shim links to. */
+export interface ResolvedBin {
+    name: string;
+    /** Absolute target validated inside the contributing root when this set resolved. */
+    target: string;
+    /** Human-readable contributor, e.g. `plugin "deploy-tools"` or
+     *  `config.json (/repo/.crouter)`. */
+    origin: string;
+    scope: Scope;
+}
+/** A declaration that did NOT become a bare command, with why. Surfaced by
+ *  `crtr sys doctor`; never thrown, so one bad entry can never stop a node
+ *  from launching. */
+export interface BinIssue {
+    name: string;
+    origin: string;
+    scope: Scope;
+    message: string;
+}
+export interface BinResolution {
+    /** Effective name → resolved bin, after layering. */
+    bins: Map<string, ResolvedBin>;
+    issues: BinIssue[];
+}
+/** The effective bare-command set for one node's cwd/profile, plus every
+ *  declaration that failed to become one.
+ *
+ *  Layers ascend in precedence (see `contributionLayers`). A name claimed by
+ *  two contributors in the SAME layer selects no winner: it is reported and
+ *  removed, so an ambiguous name resolves to nothing rather than to whichever
+ *  plugin sorted first. A higher layer may still claim that name explicitly —
+ *  that is an unambiguous choice, not a collision. */
+export declare function resolveBinContributions(targetCwd: string, targetProfileId: string | null): BinResolution;
+/** Materialize (idempotently) the shim directory for one effective set and
+ *  return its absolute path, or null when the set is empty. Built in a staging
+ *  dir and renamed into place, so a concurrent launch either sees no directory
+ *  or sees a complete one. */
+export declare function ensureBinShimDir(bins: Map<string, ResolvedBin>): string | null;
+/** The shim directory to prepend to a target node's PATH, or null when that
+ *  node's scopes declare no bare command. The one entry point the spawn-env
+ *  boundary calls. */
+export declare function binShimDirFor(targetCwd: string, targetProfileId: string | null): string | null;

package/dist/core/runtime/bin-contributions.js

@@ -0,0 +1,186 @@
+// Bare-binary contributions — the plain executables a node's bash can call by
+// name, with no `crtr` command leaf and no exec-command JSON protocol between
+// them and the agent.
+//
+// A plugin declares them in its manifest (`bin`), a user or project scope in
+// its own `config.json` (`bin`); both are a small name → root-relative-path
+// map. This module resolves those declarations across the same layering the
+// rest of the config uses (project stack > user, and within one root: that
+// root's own config > its enabled plugins), materializes one crouter-owned
+// shim directory of symlinks, and hands its path to the spawn-env boundary
+// (`spawn-env.ts`), which PREPENDS it to every broker child's PATH while
+// leaving the host PATH intact behind it.
+//
+// The shim directory exists so the declaration stays a per-name grant: crouter
+// links exactly the names that were declared, rather than putting a
+// contributor's whole `bin/` directory on the agent's PATH and admitting every
+// sibling file in it.
+//
+// These binaries are trusted local code running with the caller's authority —
+// the same authority the agent's bash tool already has. There is no sandbox,
+// no install hook, and no shell evaluation anywhere in this path. Containment
+// is checked while resolving the effective set; a contributor can change later
+// because it is trusted local code, not a sandboxed artifact.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { binDeclarationIssues, normalizeBin, readRawConfigAtRoot } from '../config.js';
+import { listInstalledPluginsInRoot } from '../installed-plugins.js';
+import { crtrHome } from '../canvas/paths.js';
+import { findProjectScopeRoots, scopeRoot } from '../scope.js';
+function contributorIssues(origin, scope, raw) {
+    return binDeclarationIssues(raw).map((issue) => ({ name: issue.name, origin, scope, message: issue.message }));
+}
+function pluginContributors(scope, root) {
+    return listInstalledPluginsInRoot(scope, root)
+        .filter((plugin) => plugin.enabled && plugin.manifest.bin !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((plugin) => {
+        const origin = `plugin "${plugin.name}"`;
+        return { origin, scope, root: plugin.root, bin: normalizeBin(plugin.manifest.bin), issues: contributorIssues(origin, scope, plugin.manifest.bin) };
+    });
+}
+/** A scope's own `config.json` contributions. Paths resolve against the scope's
+ *  AUTHORING root: the project directory for a project scope (so a repo writes
+ *  `tools/repoctl`, where its tools actually live, not `../tools/repoctl` out
+ *  of `.crouter/`), and `~/.crouter` itself for the user scope, which has no
+ *  enclosing project. */
+function configContributor(scope, scopeRootPath) {
+    const raw = readRawConfigAtRoot(scopeRootPath)?.bin;
+    if (raw === undefined)
+        return [];
+    const origin = `config.json (${scopeRootPath})`;
+    const bin = normalizeBin(raw);
+    const root = scope === 'project' ? dirname(scopeRootPath) : scopeRootPath;
+    return [{ origin, scope, root, bin, issues: contributorIssues(origin, scope, raw) }];
+}
+/** The contribution LAYERS in ascending precedence: a later layer's entry
+ *  replaces an earlier layer's same name. Within one root the root's own
+ *  `config.json` outranks its plugins (the rule `layerPluginKinds` follows for
+ *  `kinds`), and the project stack — nearest root last — outranks the user
+ *  scope entirely. Contributors WITHIN one layer never outrank each other:
+ *  two of them claiming one name is a collision, not a precedence question. */
+function contributionLayers(targetCwd, targetProfileId) {
+    const layers = [];
+    const userRoot = scopeRoot('user');
+    if (userRoot !== null) {
+        layers.push(pluginContributors('user', userRoot), configContributor('user', userRoot));
+    }
+    const projectRootsNearestFirst = findProjectScopeRoots(targetCwd, targetProfileId);
+    for (const root of [...projectRootsNearestFirst].reverse()) {
+        layers.push(pluginContributors('project', root), configContributor('project', root));
+    }
+    return layers.filter((layer) => layer.length > 0);
+}
+/** Resolve one declared path against its contributing root: it must stay
+ *  inside that root, be a regular file, and carry a POSIX exec bit when the
+ *  effective set is resolved. Returns the absolute real path, or the reason it
+ *  is not usable. */
+function resolveTarget(root, relative) {
+    let rootReal;
+    let target;
+    try {
+        rootReal = realpathSync(root);
+        target = realpathSync(resolve(root, relative));
+    }
+    catch {
+        return { reason: `target does not exist: ${join(root, relative)}` };
+    }
+    if (target !== rootReal && !target.startsWith(rootReal + sep)) {
+        return { reason: `target escapes its contributing root: ${relative}` };
+    }
+    const stat = statSync(target);
+    if (!stat.isFile())
+        return { reason: `target is not a regular file: ${target}` };
+    if ((stat.mode & 0o111) === 0)
+        return { reason: `target lacks the POSIX exec bit: ${target}` };
+    return { target };
+}
+/** The effective bare-command set for one node's cwd/profile, plus every
+ *  declaration that failed to become one.
+ *
+ *  Layers ascend in precedence (see `contributionLayers`). A name claimed by
+ *  two contributors in the SAME layer selects no winner: it is reported and
+ *  removed, so an ambiguous name resolves to nothing rather than to whichever
+ *  plugin sorted first. A higher layer may still claim that name explicitly —
+ *  that is an unambiguous choice, not a collision. */
+export function resolveBinContributions(targetCwd, targetProfileId) {
+    const bins = new Map();
+    const issues = [];
+    for (const layer of contributionLayers(targetCwd, targetProfileId)) {
+        const claims = new Map();
+        for (const contributor of layer) {
+            issues.push(...contributor.issues);
+            for (const name of Object.keys(contributor.bin)) {
+                const existing = claims.get(name);
+                if (existing === undefined)
+                    claims.set(name, [contributor]);
+                else
+                    existing.push(contributor);
+            }
+        }
+        for (const [name, claimants] of claims) {
+            if (claimants.length > 1) {
+                const origins = claimants.map((claimant) => claimant.origin).join(', ');
+                bins.delete(name);
+                for (const claimant of claimants) {
+                    issues.push({ name, origin: claimant.origin, scope: claimant.scope, message: `bare command "${name}" is claimed by ${origins} at the same precedence — no winner is selected and the name is not installed` });
+                }
+                continue;
+            }
+            const contributor = claimants[0];
+            const resolved = resolveTarget(contributor.root, contributor.bin[name]);
+            if ('reason' in resolved) {
+                issues.push({ name, origin: contributor.origin, scope: contributor.scope, message: resolved.reason });
+                continue;
+            }
+            bins.set(name, { name, target: resolved.target, origin: contributor.origin, scope: contributor.scope });
+        }
+    }
+    return { bins, issues };
+}
+/** Content address of one effective bare-command set — the shim directory's
+ *  name. Because the address covers every name and target, an existing
+ *  directory is already correct: nothing is ever rewritten in place, a changed
+ *  set simply materializes beside the old one, and two processes racing the
+ *  same set produce byte-identical trees. */
+function shimAddress(bins) {
+    const lines = [...bins.values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((bin) => `${bin.name}\u0000${bin.target}`)
+        .join('\n');
+    return createHash('sha256').update(lines).digest('hex').slice(0, 32);
+}
+/** Materialize (idempotently) the shim directory for one effective set and
+ *  return its absolute path, or null when the set is empty. Built in a staging
+ *  dir and renamed into place, so a concurrent launch either sees no directory
+ *  or sees a complete one. */
+export function ensureBinShimDir(bins) {
+    if (bins.size === 0)
+        return null;
+    const dir = join(crtrHome(), 'bin-shims', shimAddress(bins));
+    if (existsSync(dir))
+        return dir;
+    const staging = `${dir}.staging-${process.pid}-${Date.now().toString(36)}`;
+    mkdirSync(staging, { recursive: true });
+    try {
+        for (const bin of bins.values())
+            symlinkSync(bin.target, join(staging, bin.name));
+        renameSync(staging, dir);
+    }
+    catch (error) {
+        rmSync(staging, { recursive: true, force: true });
+        // Another launch materializing the same address won the rename — its tree
+        // is identical by construction, so the address is still correct.
+        if (existsSync(dir))
+            return dir;
+        throw error;
+    }
+    return dir;
+}
+/** The shim directory to prepend to a target node's PATH, or null when that
+ *  node's scopes declare no bare command. The one entry point the spawn-env
+ *  boundary calls. */
+export function binShimDirFor(targetCwd, targetProfileId) {
+    return ensureBinShimDir(resolveBinContributions(targetCwd, targetProfileId).bins);
+}

package/dist/core/runtime/blaxel-environment.d.ts

@@ -0,0 +1,2 @@
+/** The Blaxel environment the node's profile points at, or null when it runs on a machine. Reads rows only, so it is safe before any environment is registered. A leaf module: the launch and run-start paths import it without pulling in the ledger. */
+export declare function blaxelEnvironmentOf(profileId: string | null): Promise<string | null>;

package/dist/core/runtime/blaxel-environment.js

@@ -0,0 +1,8 @@
+import { openDb } from '../canvas/db.js';
+/** The Blaxel environment the node's profile points at, or null when it runs on a machine. Reads rows only, so it is safe before any environment is registered. A leaf module: the launch and run-start paths import it without pulling in the ledger. */
+export async function blaxelEnvironmentOf(profileId) {
+    if (profileId === null)
+        return null;
+    const row = await (await openDb()).prepare("SELECT e.object AS object FROM profiles p JOIN environments e ON e.object = p.environment_id WHERE p.id = ? AND e.kind = 'blaxel'").get(profileId);
+    return row?.object ?? null;
+}

package/dist/core/runtime/broker/bash-job-launch.d.ts

@@ -0,0 +1,12 @@
+import { type BashJobPaths } from '../../bash-jobs.js';
+/** True when the daemon's launcher starts jobs rather than this process: a Linux broker that shares the API host's
+ *  launcher. A sandbox broker (`CRTR_API_URL` set) runs on another machine, so it spawns its supervisor itself
+ *  and reports the job through `report`. */
+export declare function bashJobsUseLauncher(): boolean;
+/** Start the supervisor for a job whose `cmd.sh` and `job.log` are already written.
+ *  Resolves with the supervisor's process group and its launch-time identity, which
+ *  lets a later cancellation reject a stale pid; it is not a containment guarantee. */
+export declare function launchBashJobSupervisor(nodeId: string, paths: BashJobPaths, contextDir: string, cwd: string, env: NodeJS.ProcessEnv): Promise<{
+    pgid: number;
+    identity: string;
+}>;

package/dist/core/runtime/broker/bash-job-launch.js

@@ -0,0 +1,50 @@
+// Starts a prepared bash job's supervisor. The one fork between platforms lives
+// here: on Linux the daemon launches it through the sandboxed root launcher
+// (and persists the launcher identity itself); elsewhere this process spawns it
+// detached and persists the pgid and its identity. The valve and `node bash run`
+// both start jobs through this function.
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { BASH_JOB_SUPERVISOR_SCRIPT } from '../../bash-job-supervisor.js';
+import { readBashNiceness } from '../../bash-jobs.js';
+import { capturePidIdentities } from '../../canvas/pid.js';
+import { freshChildNodeExecPath } from '../branded-host.js';
+import { resolveAdmittedHostCommand } from '../spawn-env.js';
+import { brokerApiUrl, startBrokerBashJob } from './daemon-ops.js';
+/** True when the daemon's launcher starts jobs rather than this process: a Linux broker that shares the API host's
+ *  launcher. A sandbox broker (`CRTR_API_URL` set) runs on another machine, so it spawns its supervisor itself
+ *  and reports the job through `report`. */
+export function bashJobsUseLauncher() {
+    return process.platform === 'linux' && brokerApiUrl() === undefined;
+}
+/** Start the supervisor for a job whose `cmd.sh` and `job.log` are already written.
+ *  Resolves with the supervisor's process group and its launch-time identity, which
+ *  lets a later cancellation reject a stale pid; it is not a containment guarantee. */
+export async function launchBashJobSupervisor(nodeId, paths, contextDir, cwd, env) {
+    // A host broken since the last probe is caught before the supervisor starts,
+    // so the job's log collector never runs on a dead interpreter.
+    const nodeBin = await freshChildNodeExecPath();
+    if (bashJobsUseLauncher()) {
+        const { pid } = await startBrokerBashJob(nodeId, { job_id: paths.jobId, cwd, env });
+        return { pgid: pid, identity: `launcher:${pid}` };
+    }
+    const shellPath = resolveAdmittedHostCommand('bash', env, cwd);
+    const child = spawn(shellPath, ['-c', BASH_JOB_SUPERVISOR_SCRIPT, '--', paths.cmdSh, paths.jobLog, paths.jobExit, paths.jobRun, paths.jobDone, shellPath, String(readBashNiceness(contextDir)), nodeBin, paths.jobActivity], { cwd, detached: true, stdio: 'ignore', env });
+    const pgid = await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        if (child.pid !== undefined)
+            resolve(child.pid);
+    });
+    child.unref();
+    const identity = capturePidIdentities([pgid])?.get(pgid);
+    if (identity === undefined) {
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch { /* the just-started supervisor already exited */ }
+        throw new Error(`bash job ${paths.jobId} started without a process identity`);
+    }
+    writeFileSync(paths.jobPgid, String(pgid));
+    writeFileSync(paths.jobPgidIdentity, identity);
+    return { pgid, identity };
+}

package/dist/core/runtime/broker/model-adapter.d.ts

@@ -0,0 +1,27 @@
+import { type AssistantMessageEventStream, type Context, type Model, type ModelsSimpleStreamOptions } from '@earendil-works/pi-ai';
+import type { ModelRuntime } from '@earendil-works/pi-coding-agent';
+/** Pi uses availability and auth for its model controls; only the daemon can
+ * decide whether a route has credentials. Keep the broker's metadata selectable. */
+export declare function configureBrokerModelRuntime(runtime: ModelRuntime, intent?: string): void;
+export declare const LLM_BROKER_RETRY_WINDOW_S = 300;
+export declare const LLM_REFUSAL_DIAGNOSTIC = "crtr:llm-refusal";
+/** The retry deadline (epoch ms) a final daemon refusal carried on its
+ *  diagnostic, or undefined when the refusal named none. */
+export declare function refusalRetryAt(message: {
+    diagnostics?: ReadonlyArray<{
+        type: string;
+        details?: unknown;
+    }>;
+}): number | undefined;
+/** Messages the wire request carries. An errored or aborted assistant is an
+ *  incomplete turn that pi-ai's own serializers omit; this adapter bypasses
+ *  them, so drop it here. A request must also end on a non-assistant message
+ *  (Anthropic rejects assistant prefill with a 400), so trailing assistants go
+ *  too. */
+export declare function wireHistory(messages: Context['messages']): Context['messages'];
+export declare function requestBody(model: Model<any>, context: Context, options: ModelsSimpleStreamOptions, intentOverride?: string): Record<string, unknown>;
+/** The real response under a deferred-head framing (`daemon/api/deferred-head.ts`): the magic line, keep-alive
+ *  blank lines, one JSON head line, then the body unchanged. Any other response is returned as it is. */
+export declare function unwrapDeferredHead(response: Response): Promise<Response>;
+/** One pi stream, backed exclusively by the authenticated daemon llm route. `intent` replaces the node's own `CRTR_MODEL_INTENT` for one stream: a background one-shot of an app-paid node asks for `app/light`, not the node's rung. */
+export declare function streamBrokerModel(model: Model<any>, context: Context, options?: ModelsSimpleStreamOptions, intent?: string): AssistantMessageEventStream;