@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/nodes.js

@@ -0,0 +1,506 @@
+// Runtime node operations — the behavior layer above the canvas store.
+//
+// canvas/ is the pure data-access layer (nodes + edges). This is where the
+// design's *rules* live: how a node comes into being, the env contract its pi
+// process inherits, and the spawn-time wiring of the subscription spine.
+//
+// Two ways a node is born:
+//   • root  — a user-opened entry point (bare `crtr`).
+//             No parent; resident by default (it's a conversation you live in).
+//   • child — spawned by another node. Terminal until it must persist. On
+//             spawn the PARENT auto-subscribes (active) to the child, so it
+//             learns when the work finishes — this seeds the subscription
+//             graph to mirror the spawn structure. A `spawned_by` audit edge
+//             is also recorded.
+import { envHomeOverride, envRuntimeHomeOverride, INBOX_BETWEEN_TURNS_ENV, SCOPES_FILE_ENV, scopeAllowed } from '../../shared/env.js';
+import { isOwnMemoryScope, validateScopes } from '../scopes.js';
+import { activeGrant, terminalGrant } from '../grants/mirror.js';
+import { callerPerson, nodeTerminalGrant } from '../grants/terminal.js';
+import { grantSnapshotMissing } from '../../daemon/readiness.js';
+import { appendRunEvent } from '../runs/events.js';
+import { isCloudRole, personId } from '../canvas/person.js';
+import { InputError } from '../io.js';
+import { ApiError } from '../../api/errors.js';
+import { assertGranteeRunsHere } from './unsandboxed.js';
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { resolve, relative, isAbsolute, join, sep } from 'node:path';
+import { appSpace } from '../layout.js';
+import { scopesFilePath } from '../canvas/paths.js';
+import { createNode, assertRunNotDeleting, conversationOwner, getNode, getRow, } from '../canvas/index.js';
+import { ensureAppSpace } from '../spaces/space.js';
+import { LAUNCHER_SOCKET } from '../../launcher/spec.js';
+import { blaxelEnvironmentOf } from './blaxel-environment.js';
+import { resolveInstallId } from '../canvas/install-id.js';
+import { isAppRun } from '../canvas/app-run.js';
+import { contextDir } from '../canvas/paths.js';
+import { conversationIdFromPath } from '../conversation-store/index.js';
+import { usage } from '../errors.js';
+import { assertProfileAvailableForBirth } from '../profiles/deletion-reservation.js';
+import { loadExactProfileManifest } from '../profiles/manifest.js';
+import { admitNodeCreate } from '../command-hooks/lifecycle-create.js';
+import { getById, nodeObject, ownerForGrantee } from '../graph/objects.js';
+import { recordActedOn } from '../graph/edges.js';
+import { recordWatch, copyWatchesForFork } from '../graph/watches.js';
+import { publish } from '../graph/events.js';
+import { canvasDatabaseUrl } from '../canvas/db.js';
+import { someAsync } from '../async-array.js';
+import { admitIntoManagedCheckout } from '../worktree-mutation-async.js';
+// crtrd sets this once at boot (setInstallId) and it wins unconditionally —
+// a daemon process only ever serves one canvas home for its whole lifetime,
+// so no keying is needed there. Every OTHER in-process caller (tests,
+// in-process tooling — spawnNode is called directly by many existing test
+// files, several of which switch CRTR_HOME + closeDb() between cases) has no
+// such guarantee, so its lazy cache is keyed by database URL — the same
+// identity openDb() itself keys its handle cache by (db.ts's `handles` map) —
+// so a CRTR_HOME switch can never leak one canvas's install id onto another's
+// nodes.
+let daemonInstallId;
+const lazyInstallIdByHome = new Map();
+/** Explicitly set the resolved install id. crtrd calls this once at boot,
+ *  immediately after `resolveInstallId()` — see crtrd.ts — so a provisioning
+ *  mismatch fails the daemon loudly at STARTUP rather than lazily on first
+ *  spawn. Exported for the daemon only; every other caller gets it lazily via
+ *  `installId()` below. */
+export function setInstallId(id) {
+    daemonInstallId = id;
+}
+/** Lazily resolve and cache the canvas-install id, keyed by the currently
+ *  active canvas home so a process that switches `CRTR_HOME` (tests, in-
+ *  process tooling) never keeps stamping a stale home's install id onto a
+ *  different home's nodes. crtrd's boot-set value (`setInstallId`) always
+ *  wins when present — a daemon never switches homes mid-process. */
+async function installId() {
+    if (daemonInstallId !== undefined)
+        return daemonInstallId;
+    const home = await canvasDatabaseUrl();
+    const cached = lazyInstallIdByHome.get(home);
+    if (cached !== undefined)
+        return cached;
+    const resolved = await resolveInstallId();
+    lazyInstallIdByHome.set(home, resolved);
+    return resolved;
+}
+/** Raw time-sortable + random id shape — used for non-node opaque ids such as
+ *  focus ids (`f-…`) that are NOT canvas node identities and keep their
+ *  historical 2-segment shape (unstamped by the canvas-install id). */
+export function newJobId() {
+    return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+}
+/** Generate a NODE id: `<install>-<time36>-<rand4hex>` (3 segments) — the
+ *  canvas-install id stamped onto the historical job-id shape, so every
+ *  minted node id is a globally-unique NAME that also names the canvas that
+ *  minted it (see the unified-chat/addressing design's "ID scheme"). crtrd is
+ *  the sole node minter. */
+export async function newNodeId() {
+    return `${await installId()}-${newJobId()}`;
+}
+// The node id itself is an OPAQUE, caller-meaningless NAME (see the unified
+// chat/addressing design's "ID scheme") — never parsed for structure. This is
+// therefore a single non-structural, charset-safety predicate: lowercase
+// [a-z0-9-] only (so 'remote42' — zero hyphens — is exactly as valid as any
+// stamped 3-segment id) and a length cap. 128 is chosen to exactly match
+// paths.ts's `isSafeNodeId` filesystem-path-segment boundary (the sole other
+// place a node id's raw byte length is safety-checked) rather than picking an
+// independent number that could drift out of sync with it. Every id that
+// passes here is automatically also a safe fs path segment, a safe
+// `crtr/<id>` git branch suffix, and never contains '.', '..', '/', '\\', or a
+// null byte (the charset alone rules all of those out) — no sink needs a
+// leading/trailing/double-hyphen restriction on top, so none is imposed.
+const NODE_ID_MAX_LEN = 128;
+const NODE_ID_FORMAT = /^[a-z0-9-]+$/;
+/** Thrown when a caller-specified `--node-id` (or its API twin `node_id`)
+ *  already names a live node. Distinguishable from every other spawn failure
+ *  so a caller can treat it as "attach instead of create" per the unified
+ *  chat/addressing design's ensure semantics — never overwrite, never
+ *  double-spawn. Mapped to HTTP 409 in `src/daemon/api/map.ts`. */
+export class NodeIdConflictError extends Error {
+    nodeId;
+    constructor(nodeId) {
+        super(`node already exists: ${nodeId}`);
+        this.nodeId = nodeId;
+        this.name = 'NodeIdConflictError';
+    }
+}
+/** Format-validate a CALLER-SUPPLIED node id operand. Throws a usage error on
+ *  a bad shape; never touches the canvas. Shared by the early best-effort
+ *  preflight (`preflightNodeId`, run before any worktree is allocated) and the
+ *  authoritative check immediately before node creation (`validatedExplicitNodeId`
+ *  below) so the two can never disagree about what shape is valid. */
+function validateNodeIdFormat(nodeId) {
+    if (nodeId.length === 0 || nodeId.length > NODE_ID_MAX_LEN) {
+        throw usage(`invalid --node-id '${nodeId}': must be 1-${NODE_ID_MAX_LEN} characters`, {
+            next: `Pass an id-safe string (lowercase letters, digits, hyphens) of at most ${NODE_ID_MAX_LEN} characters.`,
+        });
+    }
+    if (!NODE_ID_FORMAT.test(nodeId)) {
+        throw usage(`invalid --node-id '${nodeId}': must contain only lowercase letters, digits, and hyphens (e.g. 'remote42', 'my-node-1')`, { next: 'Use only lowercase letters, digits, and hyphens.' });
+    }
+}
+/** Best-effort preflight for a caller-supplied `--node-id`, run BEFORE any
+ *  worktree is allocated for it (`spawnChild` in spawn.ts) — so a malformed or
+ *  already-taken id fails before there is anything to leak/clean up. Format
+ *  validation here is authoritative (an id that fails it can never become
+ *  valid); the duplicate check is advisory only — a concurrent create can
+ *  still win the race between this check and the synchronous check-then-
+ *  create below, which remains the SOLE authoritative decider. */
+export async function preflightNodeId(nodeId) {
+    validateNodeIdFormat(nodeId);
+    if (await getNode(nodeId) !== null)
+        throw new NodeIdConflictError(nodeId);
+}
+/** Validate + duplicate-check a CALLER-SUPPLIED node id operand before it
+ *  reaches the canvas. Internally-minted ids (newNodeId()-derived) already
+ *  satisfy the format unconditionally and are never a duplicate (they embed a
+ *  fresh timestamp+random suffix), so this is only ever exercised by an
+ *  explicit `opts.nodeId` from a real caller (`--node-id` / API `node_id`).
+ *  It runs inside the create critical section immediately before `createNode`,
+ *  so concurrent explicit-id births resolve to one winner and one
+ *  `NodeIdConflictError`. */
+async function validatedExplicitNodeId(nodeId) {
+    validateNodeIdFormat(nodeId);
+    if (await getNode(nodeId) !== null)
+        throw new NodeIdConflictError(nodeId);
+    return nodeId;
+}
+/** The root of a node's spine: walk the `parent` column up to `parent == null`.
+ *  Cycle-guarded (parents must not cycle, but never loop forever). Lives in the
+ *  node layer (not placement) so the env-builder and placement both reach it
+ *  without an import cycle — `CRTR_SUBTREE` is emitted as `rootOfSpine(nodeId)`
+ *  at every launch site. */
+export async function rootOfSpine(nodeId) {
+    let cur = nodeId;
+    const seen = new Set();
+    for (;;) {
+        if (seen.has(cur))
+            return cur;
+        seen.add(cur);
+        const row = await getRow(cur);
+        if (row === null || row.parent == null)
+            return cur;
+        cur = row.parent;
+    }
+}
+/** Read the current node's identity from the environment. A spawned pi process
+ *  runs with CRTR_NODE_ID set; its own `crtr` invocations spawn children under
+ *  it by reading CRTR_NODE_ID as the parent. */
+export function currentNodeContext() {
+    const env = process.env;
+    return {
+        nodeId: env['CRTR_NODE_ID'] ?? null,
+        kind: env['CRTR_KIND'] ?? null,
+        mode: env['CRTR_MODE'] ?? null,
+    };
+}
+/** Whether a node's broker admits inbox mail only between agent runs: an
+ *  app-started run and its descendants, never a person's terminal node. */
+export function inboxBetweenTurns(meta) {
+    return isAppRun(meta);
+}
+/** The env injected into a node's pi process. Self-gating extensions read
+ *  CRTR_KIND/CRTR_MODE to flip behavior on polymorph without a respawn; the
+ *  feed/inbox machinery reads CRTR_NODE_ID. */
+export function nodeEnv(meta) {
+    const env = {
+        CRTR_NODE_ID: meta.node_id,
+        CRTR_KIND: meta.kind,
+        CRTR_MODE: meta.mode,
+        CRTR_LIFECYCLE: meta.lifecycle,
+        CRTR_NODE_CWD: meta.cwd,
+        // The node's own context dir (canvas home), as an ABSOLUTE path. The engine
+        // runs with cwd = CRTR_NODE_CWD (the project), so a relative `context/`
+        // resolves into the REPO, not here — agents must address their files (scripts, data,
+        // logs) via this. Written work for others is a document (`crtr doc write`), not a file here.
+        CRTR_CONTEXT_DIR: contextDir(meta.node_id, meta.grantee),
+        // The broker's conversation writes stop retrying at the node's own deadline.
+        ...(meta.deadline_at ? { CRTR_NODE_DEADLINE_AT: meta.deadline_at } : {}),
+        CRTR_CYCLES: (meta.cycles ?? 0).toString(),
+        // The runtime→resolver seam: scope.ts/config.ts read this process-wide env
+        // var to pull in the node's profile and its multi-project pointer set. '' (never omitted) only for historical
+        // null-profile rows, matching every other CRTR_* scalar here.
+        CRTR_PROFILE_ID: meta.profile_id ?? '',
+        // The Claude subscription adapter re-injects pi's docs block as a hidden
+        // message whenever a turn's prompt mentions pi. canvas-prompt-scrub already
+        // removes that block from the system prompt, so re-injection would only put
+        // the adapter's own fallback copy back into the conversation. Never inject.
+        PI_CLAUDE_OAUTH_REINJECT_SCOPE: 'never',
+    };
+    if (meta.parent)
+        env['CRTR_PARENT_NODE_ID'] = meta.parent;
+    if (meta.run_id)
+        env['CRTR_RUN_ID'] = meta.run_id;
+    // Only an app-started run (`startRun`) and its descendants take inbox mail
+    // between agent runs, attributing each turn's input with `crtr-turn-input`.
+    // Terminal nodes carry a run_id too (for run events), but keep mid-turn
+    // steer/followUp delivery, so the gate is the owning app, not the run id.
+    if (inboxBetweenTurns(meta))
+        env[INBOX_BETWEEN_TURNS_ENV] = '1';
+    // The allow-list travels in a file in the node's run folder (written by
+    // `preflightBrokerLaunch`), never in env: a full first-party grant is tens of
+    // thousands of bytes, past the launcher packet (65,535) and Linux's per-string
+    // execve limit (128 KiB). Only the path crosses; `envScopes()` reads it back.
+    if (meta.scopes !== null && meta.scopes !== undefined)
+        env[SCOPES_FILE_ENV] = scopesFilePath(meta.node_id);
+    env['CRTR_GRANTEE'] = meta.grantee ?? 'app:terminal';
+    // Propagate an explicit canvas home so children share the same canvas.
+    const home = envHomeOverride();
+    if (home !== undefined && home !== '')
+        env['CRTR_HOME'] = home;
+    // Propagate an explicit runtime home so broker-side `crtr` invocations use
+    // the same installed generation despite an isolated HOME.
+    const runtimeHome = envRuntimeHomeOverride();
+    if (runtimeHome !== undefined && runtimeHome !== '')
+        env['CRTR_RUNTIME_HOME'] = runtimeHome;
+    // Propagate the subtree-root node id. The broker uses it to group a subtree;
+    // each launch site also emits the authoritative rootOfSpine(nodeId) over this
+    // passthrough.
+    const subtree = process.env['CRTR_SUBTREE'];
+    if (subtree !== undefined && subtree !== '')
+        env['CRTR_SUBTREE'] = subtree;
+    // Merge any launch-spec env last (it may override / extend).
+    return { ...env, ...(meta.launch?.env ?? {}) };
+}
+/** The node that owns the conversation a fork copies, or null when no node does. */
+export async function forkSourceNode(sourceFile) {
+    const conversation = conversationIdFromPath(sourceFile);
+    const owner = conversation === null ? null : await conversationOwner(conversation);
+    return owner === null ? null : await getNode(owner);
+}
+/** Create a node on the canvas and wire its spawn-time edges.
+ *
+ *  For a child (parent given): the parent auto-subscribes ACTIVE to the child
+ *  (so it's woken when the child finishes), and a spawned_by audit edge is
+ *  recorded. For a root (no parent): no edges, resident by default. */
+export async function spawnNode(opts) {
+    const nodeId = opts.nodeId !== undefined ? (validateNodeIdFormat(opts.nodeId), opts.nodeId) : await newNodeId();
+    const parent = opts.parent ?? null;
+    const isRoot = parent === null;
+    // Provenance is independent of the spine: a root has no parent but still
+    // records who spawned it. A child's spawner is its parent unless overridden.
+    const spawnedBy = opts.spawnedBy ?? parent;
+    const creator = opts.creator ?? null;
+    const mode = opts.mode ?? 'base';
+    // A user-opened root is resident (a conversation you live in); a spawned node
+    // is terminal until it must persist (promotion handles that later).
+    const lifecycle = opts.lifecycle ?? (isRoot ? 'resident' : 'terminal');
+    // The node belongs to the person who creates it: that person's own terminal grant, never another account's on the same runtime.
+    const creatorPerson = opts.run === undefined ? await callerPerson() : null;
+    let terminal = creatorPerson === null ? null : await terminalGrant(creatorPerson);
+    const meta = {
+        node_id: nodeId,
+        name: opts.name ?? opts.kind,
+        description: opts.description,
+        cycles: 0,
+        created: new Date().toISOString(),
+        cwd: opts.cwd,
+        // Broker is the only host: every node runs on the headless broker; a tmux
+        // pane is only an attach viewer.
+        host_kind: 'broker',
+        profile_id: opts.profile_id ?? null,
+        kind: opts.kind,
+        mode,
+        lifecycle,
+        // Birth snapshots already represent this persona, so no transition is pending.
+        persona_ack: { kind: opts.kind, mode, lifecycle },
+        status: 'active',
+        parent,
+        spawned_by: spawnedBy,
+        creator,
+        fork_from: opts.forkFrom,
+        fork_source_file: opts.forkSourceFile,
+        review_binding: opts.reviewBinding,
+        model_override: opts.modelOverride ?? null,
+        scopes: opts.scopes ?? null,
+        isolated: opts.isolated === true,
+        grantee: opts.run?.grantee ?? 'app:terminal',
+        sub: opts.run?.sub ?? terminal?.sub ?? null,
+        grant_id: opts.run?.grant_id ?? terminal?.id ?? null,
+        client_id: opts.run?.client_id ?? null,
+        metadata_json: isRoot ? opts.run?.metadata_json ?? null : null,
+        run_id: isRoot ? nodeId : opts.run?.run_id ?? null,
+        event_cursor: isRoot ? opts.run?.event_cursor ?? 1 : null,
+        usage_json: isRoot ? opts.run?.usage_json ?? JSON.stringify({ input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, cost_usd: 0 }) : null,
+        passive_default: opts.passiveDefault ?? false,
+        caused_by: opts.causedBy ?? null,
+        ...(opts.managedWorktree !== undefined ? { managed_worktree: opts.managedWorktree } : {}),
+        intent: null,
+        deadline_at: opts.deadlineAt ?? null,
+        pi_session_id: null,
+        pi_session_file: null,
+        launch: opts.launch,
+    };
+    // Validate BEFORE minting: a bad parent must leave no half-born orphan row or
+    // dirs behind, so the parent's existence is checked before createNode
+    // scaffolds anything on disk or in the db.
+    const requestedScopes = opts.scopes === undefined ? undefined : validateScopes(opts.scopes);
+    const parentMeta = parent === null ? null : await getNode(parent);
+    if (parent !== null && parentMeta === null) {
+        throw new Error(`cannot spawn under unknown parent node: ${parent}`);
+    }
+    if (parentMeta?.run_id && (await getNode(parentMeta.run_id))?.deleting_at)
+        throw new Error('run is deleting');
+    const creatorMeta = creator === null ? null : await getNode(creator);
+    if (creator !== null && creatorMeta === null) {
+        throw new Error(`cannot spawn from unknown creator node: ${creator}`);
+    }
+    if (creatorMeta?.run_id && (await getNode(creatorMeta.run_id))?.deleting_at)
+        throw new Error('run is deleting');
+    // The parent manages the spine, but is not necessarily the creator. A broker
+    // can place a child under another node; that placement cannot lend the child
+    // the parent's run, grant, or scopes. Fork/replacement sources still bound
+    // what their conversation may carry, independently of the creator.
+    const forkSourceMeta = opts.forkSourceFile == null ? null : await forkSourceNode(opts.forkSourceFile);
+    const replacedMeta = opts.replaces == null ? null : await getNode(opts.replaces);
+    const scopeSource = parentMeta ?? forkSourceMeta ?? replacedMeta ?? creatorMeta ?? (spawnedBy === null ? null : await getNode(spawnedBy));
+    // A run's isolation belongs to its persisted root, not to the caller's
+    // request. Resolve it independently of scope narrowing, including a root
+    // spawned by a node (which has no spine parent).
+    const isolationSources = [parentMeta, creatorMeta, forkSourceMeta, replacedMeta, spawnedBy === null ? null : await getNode(spawnedBy)];
+    const inheritedIsolation = (await someAsync(isolationSources, async (source) => source?.isolated === true ||
+        (source?.run_id != null && (await getNode(source.run_id))?.isolated === true)));
+    if (inheritedIsolation && opts.isolated === false) {
+        throw new ApiError(403, 'isolated_run', 'isolation cannot be turned off under an isolated run', { param: 'isolated' });
+    }
+    meta.isolated = inheritedIsolation || opts.isolated === true;
+    if (scopeSource !== null) {
+        const identitySource = creatorMeta ?? scopeSource;
+        if (creatorMeta && scopeSource.grantee && creatorMeta.grantee &&
+            creatorMeta.grantee !== scopeSource.grantee) {
+            throw new ApiError(403, 'other_app_run', 'cannot create under another app\'s node');
+        }
+        const sources = creatorMeta && creatorMeta !== scopeSource ? [scopeSource, creatorMeta] : [scopeSource];
+        // On the fleet Runtime a request person never takes another account's identity, grant or spend through a node it names as parent or creator.
+        if (isCloudRole() && creatorPerson !== null && sources.some((source) => source.sub && source.sub !== creatorPerson)) {
+            throw new ApiError(403, 'other_person_run', 'cannot create under another person\'s node');
+        }
+        const ceilings = [];
+        const grantCeilings = new Set();
+        for (const source of sources) {
+            if (source.scopes !== null && source.scopes !== undefined)
+                ceilings.push(source.scopes);
+            const grant = source.grantee === 'app:terminal' ? await nodeTerminalGrant(source) : source.grant_id ? await activeGrant(source.grant_id) : null;
+            if (grant) {
+                const resolved = [...grant.resolved];
+                grantCeilings.add(resolved);
+                ceilings.push(resolved);
+            }
+            else {
+                const none = [];
+                grantCeilings.add(none);
+                ceilings.push(none);
+            }
+        }
+        // The app's own documents are held by no grant string, only by the launched lists of the run's lineage (identity MEM-2): a grant
+        // ceiling does not apply to them, but every node list in the lineage still does, so a child never regains what a parent dropped.
+        const ownMemory = (scope) => isOwnMemoryScope(scope, identitySource.grantee ?? 'app:terminal');
+        const allowed = (held, scope) => (ownMemory(scope) && grantCeilings.has(held)) || scopeAllowed(held, scope);
+        if (requestedScopes !== undefined && !requestedScopes.every((scope) => ceilings.every((held) => allowed(held, scope)))) {
+            throw new InputError({ error: 'unknown_scope', message: 'child scopes must be covered by the creating node, its source and their current grants', received: requestedScopes, field: 'scopes', next: 'Request only scopes the creating node currently holds.' });
+        }
+        // A scope from any ceiling is usable only if every other ceiling covers it.
+        // This keeps omitted scopes narrowed too (including a broader parent and a
+        // narrower creator), while retaining the narrower side of hierarchical
+        // file/memory scopes whichever node supplied it.
+        meta.scopes = requestedScopes ?? (sources.every((source) => source.scopes == null) &&
+            sources.every((source) => source.grant_id === identitySource.grant_id && source.sub === identitySource.sub)
+            ? null : sources.length === 1 ? scopeSource.scopes ?? null
+            : [...new Set(ceilings.flat().filter((scope) => ceilings.every((held) => allowed(held, scope))))]);
+        if (meta.scopes?.includes('crtr:act') && !scopeAllowed(meta.scopes, 'crtr:llm'))
+            throw new InputError({ error: 'invalid_scope', message: 'crtr:act requires crtr:llm', received: meta.scopes, field: 'scopes', next: 'Include crtr:llm or omit crtr:act.' });
+        meta.grantee = identitySource.grantee;
+        // A child inherits its source's person, so that person's terminal grant (never the creator's) is the one it needs.
+        if (meta.grantee === 'app:terminal' && identitySource.sub)
+            terminal = await terminalGrant(identitySource.sub);
+        meta.sub = identitySource.sub ?? (meta.grantee === 'app:terminal' ? terminal?.sub : null) ?? null;
+        meta.grant_id = identitySource.grant_id ?? (meta.grantee === 'app:terminal' ? terminal?.id : null) ?? null;
+        meta.client_id = identitySource.client_id;
+        meta.run_id = isRoot ? nodeId : identitySource.run_id ?? null;
+    }
+    // An unsandboxed machine runs terminal agents only: this also covers a child inheriting an app grantee.
+    assertGranteeRunsHere(meta.grantee);
+    // A child inherits its app identity from its creator or parent. Only a node
+    // that actually belongs to app:terminal needs the terminal grant.
+    if (opts.run === undefined && meta.grantee === 'app:terminal' && terminal === null) {
+        // No snapshot yet is unknown authority, not a denial: the caller retries. After a snapshot the 403 is a real refusal.
+        if (await grantSnapshotMissing())
+            throw new ApiError(503, 'runtime_starting', 'the first grant snapshot from the directory has not committed');
+        throw new ApiError(403, 'scope_missing', 'terminal grant is not active');
+    }
+    if (meta.isolated) {
+        // Inherited isolation must be admitted before scaffolding the child. The
+        // broker host refuses a non-sandboxed launch too, but by then a row exists.
+        // A node in a Blaxel environment is confined by its own sandbox and needs no launcher.
+        if ((process.platform !== 'linux' || !existsSync(LAUNCHER_SOCKET)) && await blaxelEnvironmentOf(meta.profile_id ?? null) === null) {
+            throw new ApiError(400, 'isolated_unavailable', 'isolated nodes require the Linux root launcher');
+        }
+        if (opts.managedWorktree !== undefined)
+            throw new ApiError(400, 'invalid_request', 'isolated nodes cannot use a worktree', { param: 'worktree' });
+        const folder = join(appSpace(meta.grantee ?? 'app:terminal').nodes, nodeId);
+        const beneath = relative(folder, resolve(meta.cwd));
+        if (!isAbsolute(meta.cwd) || beneath === '..' || beneath.startsWith(`..${sep}`) || isAbsolute(beneath)) {
+            throw new ApiError(400, 'invalid_request', 'isolated node cwd must be inside its own folder', { param: 'cwd' });
+        }
+    }
+    if (meta.profile_id) {
+        const profileApp = loadExactProfileManifest(meta.profile_id).manifest.grantee ?? 'app:terminal';
+        if (profileApp !== meta.grantee) {
+            const permission = `crtr:memory:rw:${profileApp}:profile:${meta.profile_id}`;
+            const grant = meta.grantee === 'app:terminal' ? await nodeTerminalGrant(meta) : meta.grant_id ? await activeGrant(meta.grant_id) : null;
+            if (!grant || grant.grantee !== meta.grantee || !scopeAllowed(grant.resolved, permission) || !scopeAllowed(meta.scopes, permission)) {
+                throw new InputError({ error: 'scope_missing', message: `missing scope ${permission}`, received: meta.profile_id, field: 'profile', next: 'Select a profile covered by this run and its current grant.' });
+            }
+        }
+    }
+    assertProfileAvailableForBirth(meta.profile_id ?? null);
+    if (!meta.grantee)
+        throw new Error('node creation requires an app');
+    const releaseCreateGate = await admitNodeCreate({
+        kind: meta.kind,
+        mode: meta.mode,
+        cwd: meta.cwd,
+        profile: meta.profile_id ?? null,
+        root: isRoot,
+        parentId: parent,
+        requestingNodeId: creator,
+        lifecycle,
+        replaces: opts.replaces ?? null,
+    }, meta.grantee);
+    // The birth's graph writes, in the seeding transaction: the actor acted on the child, the
+    // parent watches it (`spawn`, in the tree), a fork copies its source's watches, and `created`
+    // is pushed. The actor is never pushed its own act, so a parent that created the child
+    // itself hears nothing.
+    const recordBirth = async (db, row) => {
+        const child = await nodeObject(db, row.node_id);
+        const actingNode = creator ?? parent ?? opts.actor ?? spawnedBy ?? null;
+        const actor = actingNode !== null && (await getById(db, actingNode))?.type === 'node'
+            ? await nodeObject(db, actingNode)
+            : await ownerForGrantee(db, opts.run === undefined ? personId() : row.grantee);
+        await recordActedOn(db, actor, child);
+        if (parent !== null && opts.subscribe !== false)
+            await recordWatch(db, await nodeObject(db, parent), child, 'spawn');
+        if (opts.forkSourceNode)
+            await copyWatchesForFork(db, await nodeObject(db, opts.forkSourceNode), child);
+        await publish(db, { event: 'created', object: child, actor, attrs: {
+                name: row.name, kind: row.kind, creator: creator ?? null,
+            } });
+    };
+    try {
+        if (opts.nodeId !== undefined)
+            await validatedExplicitNodeId(opts.nodeId);
+        await opts.beforeCreate?.();
+        if (process.platform !== 'linux' || existsSync(LAUNCHER_SOCKET))
+            await ensureAppSpace(meta.grantee ?? 'app:terminal');
+        await admitIntoManagedCheckout(meta.cwd, nodeId, () => createNode(meta, { outcomeDelivery: opts.outcomeDelivery, withinCreate: async (db, row) => {
+                if (row.run_id && row.run_id !== row.node_id)
+                    await assertRunNotDeleting(db, row.run_id);
+                if (isRoot && opts.run === undefined)
+                    await appendRunEvent(db, nodeId, nodeId, 'run.started', { scopes: row.scopes ?? null, payer: 'user', usage: JSON.parse(row.usage_json) });
+                await opts.withinCreate?.(db, row);
+                await recordBirth(db, row);
+            } }));
+    }
+    finally {
+        releaseCreateGate();
+    }
+    return meta;
+}

package/dist/core/runtime/outcome-document.d.ts

@@ -0,0 +1,58 @@
+import type { DeclinedResult, NodeMeta, NodeOutcomeDetailV1, NodeOutcomeKind, TerminalReason } from '../canvas/types.js';
+export interface NodeOutcomeDocumentV1 {
+    schema: 'crtr.node-outcome/v1';
+    outcomeId: string;
+    nodeId: string;
+    revision: number;
+    kind: NodeOutcomeKind;
+    reason: TerminalReason;
+    settledAt: string;
+    node: {
+        name: string;
+        description?: string;
+        kind: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+        status: 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+        terminalReason: TerminalReason | null;
+        cwd: string;
+        createdAt: string;
+        parent: string | null;
+        spawnedBy: string | null;
+    };
+    result?: {
+        /** The final report document's ref (`<nodeId>/reports/<name>`), read with `crtr canvas read`. */
+        finalReport: {
+            name: string;
+        };
+        structuredResult?: unknown;
+        structuredResultOmitted?: true;
+    };
+    failure?: {
+        message: string | null;
+        faultKind: NodeOutcomeDetailV1['fault_kind'] | null;
+        errorClass: NodeOutcomeDetailV1['error_class'] | null;
+        respawnFailures: number | null;
+        deadline: {
+            deadlineAt: string;
+            elapsedMs: number;
+        } | null;
+        /** Set only for reason `declined`: the reason, requester-classified code, and retryable claim. */
+        declined: DeclinedResult | null;
+    };
+}
+/** Freeze an action-independent document at outcome time. */
+export declare function composeNodeOutcomeDocument(args: {
+    node: NodeMeta;
+    outcome: {
+        kind: NodeOutcomeKind;
+        reason: TerminalReason;
+        at: string;
+        revision: number;
+        detailJson: string | null;
+    };
+    /** Required for a result before the final-report pointer has committed. */
+    finalReport?: string | null;
+    /** Lets the outcome transaction supply a parsed result without a second read. */
+    structuredResult?: unknown;
+}): Promise<NodeOutcomeDocumentV1>;

package/dist/core/runtime/outcome-document.js

@@ -0,0 +1,86 @@
+// The immutable outcome document handed to a registered delivery target.
+import { readOutputResult } from './output-result.js';
+const MAX_DOCUMENT_BYTES = 256 * 1024;
+async function structuredResult(nodeId) {
+    return await readOutputResult(nodeId);
+}
+function parseDetail(detailJson) {
+    if (detailJson === null)
+        return null;
+    try {
+        return JSON.parse(detailJson);
+    }
+    catch {
+        return null;
+    }
+}
+/** Preserve valid Unicode while bounding a display-only field by UTF-8 bytes. */
+function truncateDescription(value) {
+    const maxBytes = 1024;
+    if (Buffer.byteLength(value, 'utf8') <= maxBytes)
+        return value;
+    const ellipsis = '…';
+    let bytes = Buffer.byteLength(ellipsis, 'utf8');
+    let result = '';
+    for (const character of value) {
+        const next = Buffer.byteLength(character, 'utf8');
+        if (bytes + next > maxBytes)
+            break;
+        bytes += next;
+        result += character;
+    }
+    return `${result}${ellipsis}`;
+}
+/** Freeze an action-independent document at outcome time. */
+export async function composeNodeOutcomeDocument(args) {
+    const { node, outcome } = args;
+    const detail = parseDetail(outcome.detailJson);
+    const finalReport = args.finalReport ?? node.final_report ?? '';
+    const name = truncateDescription(node.name);
+    const description = node.description === undefined ? undefined : truncateDescription(node.description);
+    const result = outcome.kind === 'result'
+        ? args.structuredResult === undefined ? await structuredResult(node.node_id) : args.structuredResult
+        : undefined;
+    const document = {
+        schema: 'crtr.node-outcome/v1',
+        outcomeId: `${node.node_id}:${outcome.revision}`,
+        nodeId: node.node_id,
+        revision: outcome.revision,
+        kind: outcome.kind,
+        reason: outcome.reason,
+        settledAt: outcome.at,
+        node: {
+            name,
+            ...(description === undefined ? {} : { description }),
+            kind: node.kind,
+            mode: node.mode,
+            lifecycle: node.lifecycle,
+            status: node.status,
+            terminalReason: node.terminal_reason ?? null,
+            cwd: node.cwd,
+            createdAt: node.created,
+            parent: node.parent ?? null,
+            spawnedBy: node.spawned_by ?? null,
+        },
+        ...(outcome.kind === 'result' ? {
+            result: {
+                finalReport: { name: `${node.node_id}/${finalReport}` },
+                ...(result === undefined ? {} : { structuredResult: result }),
+            },
+        } : {
+            failure: {
+                message: detail?.message ?? null,
+                faultKind: detail?.fault_kind ?? null,
+                errorClass: detail?.error_class ?? null,
+                respawnFailures: detail?.respawn_failures ?? null,
+                deadline: detail?.deadline === undefined ? null : { deadlineAt: detail.deadline.deadline_at, elapsedMs: detail.deadline.elapsed_ms },
+                declined: detail?.declined ?? null,
+            },
+        }),
+    };
+    if (Buffer.byteLength(JSON.stringify(document), 'utf8') > MAX_DOCUMENT_BYTES && document.result?.structuredResult !== undefined) {
+        delete document.result.structuredResult;
+        document.result.structuredResultOmitted = true;
+    }
+    return document;
+}