@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/runner/index.js

@@ -0,0 +1,37 @@
+import { openDb } from '../../canvas/db.js';
+import { isCloudRole } from '../../canvas/person-state.js';
+import { processRunner } from './process.js';
+import { createMachineRunner } from './machine/runner.js';
+let blaxelRunner = null;
+const machineRunner = createMachineRunner();
+/** The Blaxel implementation is installed by the cloud runner module. */
+export function registerBlaxelRunner(runner) {
+    if (runner.kind !== 'blaxel')
+        throw new Error('expected a Blaxel runner');
+    blaxelRunner = runner;
+}
+/** A machine environment is this process's own host for a Mac's crtrd (process runner) and another machine for a cloud role (the remote machine runner, design-import I13). */
+export function runnerKindForEnvironment(kind) {
+    if (kind === 'blaxel')
+        return 'blaxel';
+    return isCloudRole() ? 'machine' : 'process';
+}
+export function runnerForEnvironment(kind) {
+    return runnerForExecution(runnerKindForEnvironment(kind));
+}
+export async function runnerForEnvironmentId(environmentId) {
+    const environment = await (await openDb()).prepare('SELECT kind FROM environments WHERE object = ?').get(environmentId);
+    if (!environment)
+        throw new Error(`environment ${environmentId} not found`);
+    return runnerForEnvironment(environment.kind);
+}
+/** The runner that holds an execution row, by the row's `runner` column. */
+export function runnerForExecution(runner) {
+    if (runner === 'process')
+        return processRunner;
+    if (runner === 'machine')
+        return machineRunner;
+    if (blaxelRunner === null)
+        throw new Error('Blaxel runner is not registered');
+    return blaxelRunner;
+}

package/dist/core/runtime/runner/machine/call.d.ts

@@ -0,0 +1,8 @@
+import { type MachineOp, type MachineOpTable } from './ops.js';
+/** Seconds a caller waits: `start` 60, every other op 15 (design). */
+export declare const MACHINE_CALL_TIMEOUT_S: Record<MachineOp, number>;
+export interface CallMachineOptions {
+    timeoutMs?: number;
+    rereadMs?: number;
+}
+export declare function callMachine<O extends MachineOp>(environmentId: string, op: O, args: MachineOpTable[O]['args'], options?: CallMachineOptions): Promise<MachineOpTable[O]['result']>;

package/dist/core/runtime/runner/machine/call.js

@@ -0,0 +1,67 @@
+// src/core/runtime/runner/machine/call.ts — `callMachine`, the control plane's one way to run an op on a machine (design-import I13).
+//
+// Writes a `machine_calls` row (`pending`) and waits for the API process holding the machine's link to answer it: the holder claims
+// the row, forwards it, writes `done`/`failed` and signals `machine_call:<call id>`. The wait re-reads the row every second
+// (the signal is only a hint). No live link row → MachineOfflineError, nothing written. A claimed call whose lease expires
+// unanswered → MachineLostError. A call nobody claimed within its timeout is failed here and reported offline.
+import { randomUUID } from 'node:crypto';
+import { openDb, withCanvasWrite } from '../../../canvas/db.js';
+import { MachineCallFailedError, MachineLostError, MachineOfflineError } from './ops.js';
+/** Seconds a caller waits: `start` 60, every other op 15 (design). */
+export const MACHINE_CALL_TIMEOUT_S = { start: 60, wake: 15, stop: 15, status: 15, delete: 15, viewer: 15, 'cron.run': 15, 'cron.cancel': 15 };
+const REREAD_MS = 1000;
+export async function callMachine(environmentId, op, args, options = {}) {
+    const callId = randomUUID();
+    const now = new Date().toISOString();
+    const queued = await withCanvasWrite(async (db) => {
+        const link = await db.prepare('SELECT 1 AS live FROM machine_links WHERE environment = ? AND lease_expires_at > ?').get(environmentId, now);
+        if (link === undefined)
+            return false;
+        await db.prepare('INSERT INTO machine_calls (call_id, environment, op, args_json, created_at) VALUES (?, ?, ?, ?, ?)').run(callId, environmentId, op, JSON.stringify(args), now);
+        await db.prepare('SELECT pg_notify(?, ?)').get('crtr_signal', `machine:${environmentId}`);
+        return true;
+    });
+    if (!queued)
+        throw new MachineOfflineError(environmentId, 'no live link');
+    const deadline = Date.now() + (options.timeoutMs ?? MACHINE_CALL_TIMEOUT_S[op] * 1000);
+    for (;;) {
+        const row = await (await openDb()).prepare('SELECT state, result_json, lease_expires_at, claimed_generation FROM machine_calls WHERE call_id = ?').get(callId);
+        if (row === undefined)
+            throw new MachineLostError(environmentId, callId);
+        if (row.state === 'done')
+            return (row.result_json === null ? null : JSON.parse(row.result_json));
+        if (row.state === 'failed') {
+            const failure = row.result_json === null ? {} : JSON.parse(row.result_json);
+            if (failure.code === 'machine_offline')
+                throw new MachineOfflineError(environmentId, failure.message, failure.sent === true);
+            if (failure.code === 'machine_lost')
+                throw new MachineLostError(environmentId, callId);
+            throw new MachineCallFailedError(environmentId, op, failure.message ?? 'unknown');
+        }
+        if (row.claimed_generation !== null && row.lease_expires_at !== null && row.lease_expires_at <= new Date().toISOString()) {
+            if (await failOpenCall(callId, 'lease expired') === undefined)
+                continue;
+            throw new MachineLostError(environmentId, callId);
+        }
+        if (Date.now() >= deadline) {
+            // Claimed and forwarded but unanswered: the machine may have run it. Never claimed: it ran nowhere. The row decides, not the earlier read:
+            // a holder may have claimed it since.
+            const claimed = await failOpenCall(callId, 'timed out');
+            if (claimed === undefined)
+                continue;
+            if (claimed === null)
+                throw new MachineOfflineError(environmentId, 'no holder claimed the call');
+            throw new MachineLostError(environmentId, callId);
+        }
+        await new Promise((resolve) => setTimeout(resolve, options.rereadMs ?? REREAD_MS));
+    }
+}
+/** Fail an open call as `machine_lost` when a holder claimed it, else `machine_offline` (never sent). Returns the claimed generation
+ *  the row had (null: never claimed), or undefined when the call was already settled, which the caller reads again. */
+async function failOpenCall(callId, message) {
+    const failed = await (await openDb()).prepare(`UPDATE machine_calls SET state = 'failed', finished_at = ?,
+      result_json = CASE WHEN claimed_generation IS NULL THEN ? ELSE ? END
+    WHERE call_id = ? AND state IN ('pending', 'sent') RETURNING claimed_generation`)
+        .get(new Date().toISOString(), JSON.stringify({ code: 'machine_offline', message, sent: false }), JSON.stringify({ code: 'machine_lost', message }), callId);
+    return failed === undefined ? undefined : failed.claimed_generation === null ? null : Number(failed.claimed_generation);
+}

package/dist/core/runtime/runner/machine/environment.d.ts

@@ -0,0 +1 @@
+export declare function machineEnvironmentOfProfile(profileId: string): Promise<string | null>;

package/dist/core/runtime/runner/machine/environment.js

@@ -0,0 +1,7 @@
+// src/core/runtime/runner/machine/environment.ts — the one profile → machine-environment join: the environment a profile points at when
+// its kind is `machine`, else null. Callers add their own conditions (cloud role, a node's or a cron's profile) before asking.
+import { openDb } from '../../../canvas/db.js';
+export async function machineEnvironmentOfProfile(profileId) {
+    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 = 'machine'").get(profileId);
+    return row?.object ?? null;
+}

package/dist/core/runtime/runner/machine/ops.d.ts

@@ -0,0 +1,127 @@
+import type { RunnerExecution, RunnerStartInput, RunnerStatus, RunnerStopOptions, RunnerStopResult, RunnerViewerAddress, RunnerWakeResult } from '../types.js';
+export declare const MACHINE_OPS: readonly ["start", "wake", "stop", "status", "delete", "viewer", "cron.run", "cron.cancel"];
+export type MachineOp = (typeof MACHINE_OPS)[number];
+/** A `start` call carries the whole start input and the node token the control plane minted: the Mac has no database, so it cannot mint one.
+ *  The token sits in `machine_calls.args_json` until the row is deleted a day after it finishes; the execution's token row holds its hash. */
+export type MachineStartArgs = RunnerStartInput & {
+    nodeToken: string;
+};
+export interface MachineStartResult {
+    pid: number | null;
+}
+export interface MachineWakeArgs {
+    execution: RunnerExecution;
+}
+export interface MachineStopArgs {
+    execution: RunnerExecution;
+    options: RunnerStopOptions;
+}
+export interface MachineStatusArgs {
+    execution: RunnerExecution;
+}
+export interface MachineDeleteArgs {
+    nodeId: string;
+}
+export interface MachineViewerArgs {
+    execution: RunnerExecution;
+}
+/** A cron fire on a machine. `runId` is the cron run id: it fences a second fire after a reconnect. */
+export interface MachineCronRunArgs {
+    runId: string;
+    cronId: string;
+    command: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The cron's app: the Mac decides whether the armed profile applies (only the terminal's crons run under their profile). */
+    grantee: string;
+    /** The cron's profile id; the Mac rebuilds its declared PATH entries from its own copy of the profile. */
+    profileId: string | null;
+    /** The anchor node's id and app when it is still on the canvas: the Mac sets `CRTR_CONTEXT_DIR` to that node's context dir. */
+    contextAnchor: {
+        node: string;
+        grantee: string;
+    } | null;
+    timeoutS: number;
+    /** The cron's lease expiry (ISO); the machine does not start a run whose lease has passed. */
+    leaseExpiresAt: string;
+}
+export interface MachineCronRunResult {
+    exitCode: number | null;
+    stdoutHead: string | null;
+    stderrHead: string | null;
+    durationMs: number;
+    /** SHA-256 of the whole stdout (not of the head): what `on-change` compares. */
+    stdoutSha256: string;
+    /** True when the machine did not start the command (its lease had passed): the sender may send the same run id again. */
+    notStarted?: true;
+}
+export interface MachineCronCancelArgs {
+    runId: string;
+}
+export interface MachineCronCancelResult {
+    canceled: boolean;
+}
+export interface MachineOpTable {
+    start: {
+        args: MachineStartArgs;
+        result: MachineStartResult;
+    };
+    wake: {
+        args: MachineWakeArgs;
+        result: RunnerWakeResult;
+    };
+    stop: {
+        args: MachineStopArgs;
+        result: Pick<RunnerStopResult, 'confirmed'> & {
+            error?: string;
+        };
+    };
+    status: {
+        args: MachineStatusArgs;
+        result: RunnerStatus;
+    };
+    delete: {
+        args: MachineDeleteArgs;
+        result: null;
+    };
+    viewer: {
+        args: MachineViewerArgs;
+        result: RunnerViewerAddress;
+    };
+    'cron.run': {
+        args: MachineCronRunArgs;
+        result: MachineCronRunResult;
+    };
+    'cron.cancel': {
+        args: MachineCronCancelArgs;
+        result: MachineCronCancelResult;
+    };
+}
+/** No live link row for the environment: the caller leaves its work pending and retries on its own backoff. */
+export declare class MachineOfflineError extends Error {
+    readonly environmentId: string;
+    readonly sent: boolean;
+    readonly code = "machine_offline";
+    /** True when the call was written to the link before it dropped: the machine may have run it. False: it ran nowhere. */
+    constructor(environmentId: string, detail?: string, sent?: boolean);
+}
+/** A forwarded `start` whose outcome is unknown (link dropped or call lost): the execution stays `launching`, the caller never aborts it
+ *  and never starts another. After the link returns `status` of that execution decides: running is adopted, gone is ended. */
+export declare class MachineLaunchUncertainError extends MachineOfflineError {
+    readonly uncertain = true;
+    constructor(environmentId: string, detail: string);
+}
+/** The holder claimed the call and never answered before its lease expired: the call may or may not have run. The caller runs `status` before a new `start`. */
+export declare class MachineLostError extends Error {
+    readonly environmentId: string;
+    readonly callId: string;
+    readonly code = "machine_lost";
+    constructor(environmentId: string, callId: string);
+}
+/** The machine executed the call and it failed (`result {ok: false, error}`). */
+export declare class MachineCallFailedError extends Error {
+    readonly environmentId: string;
+    readonly op: MachineOp;
+    readonly code = "machine_call_failed";
+    constructor(environmentId: string, op: MachineOp, message: string);
+}

package/dist/core/runtime/runner/machine/ops.js

@@ -0,0 +1,41 @@
+export const MACHINE_OPS = ['start', 'wake', 'stop', 'status', 'delete', 'viewer', 'cron.run', 'cron.cancel'];
+/** No live link row for the environment: the caller leaves its work pending and retries on its own backoff. */
+export class MachineOfflineError extends Error {
+    environmentId;
+    sent;
+    code = 'machine_offline';
+    /** True when the call was written to the link before it dropped: the machine may have run it. False: it ran nowhere. */
+    constructor(environmentId, detail, sent = false) {
+        super(`machine ${environmentId} is offline${detail ? `: ${detail}` : ''}`);
+        this.environmentId = environmentId;
+        this.sent = sent;
+    }
+}
+/** A forwarded `start` whose outcome is unknown (link dropped or call lost): the execution stays `launching`, the caller never aborts it
+ *  and never starts another. After the link returns `status` of that execution decides: running is adopted, gone is ended. */
+export class MachineLaunchUncertainError extends MachineOfflineError {
+    uncertain = true;
+    constructor(environmentId, detail) { super(environmentId, detail, true); }
+}
+/** The holder claimed the call and never answered before its lease expired: the call may or may not have run. The caller runs `status` before a new `start`. */
+export class MachineLostError extends Error {
+    environmentId;
+    callId;
+    code = 'machine_lost';
+    constructor(environmentId, callId) {
+        super(`call ${callId} to machine ${environmentId} was lost`);
+        this.environmentId = environmentId;
+        this.callId = callId;
+    }
+}
+/** The machine executed the call and it failed (`result {ok: false, error}`). */
+export class MachineCallFailedError extends Error {
+    environmentId;
+    op;
+    code = 'machine_call_failed';
+    constructor(environmentId, op, message) {
+        super(`${op} on machine ${environmentId} failed: ${message}`);
+        this.environmentId = environmentId;
+        this.op = op;
+    }
+}

package/dist/core/runtime/runner/machine/runner.d.ts

@@ -0,0 +1,12 @@
+import type { Runner, RunnerStartInput } from '../types.js';
+export interface MachineRunnerDeps {
+    /** The machine environment a node runs in. Default: the node's profile's `environment_id`, which must be kind `machine`. */
+    environmentOf?(nodeId: string): Promise<string>;
+    /** Mints the execution's node token (the execution must be `launching` and have none). Default: `mintNodeToken`. */
+    mintToken?(input: RunnerStartInput): Promise<string>;
+    /** Whether this execution already has a node token (a previous `start` minted it). Default: a `node_tokens` row for the execution. */
+    tokenMinted?(executionId: string): Promise<boolean>;
+}
+/** The machine environment of a node's profile, or null when the profile points at no machine environment. */
+export declare function machineEnvironmentOfNode(nodeId: string): Promise<string | null>;
+export declare function createMachineRunner(deps?: MachineRunnerDeps): Runner;

package/dist/core/runtime/runner/machine/runner.js

@@ -0,0 +1,90 @@
+// src/core/runtime/runner/machine/runner.ts — the remote machine runner (design-import I13): the third runner, for a node whose
+// profile's environment is kind `machine` and that machine is not this process's own host. Every method is one `callMachine`
+// to the Mac over its link; the Mac executes it with `machine/executor.ts`.
+//
+// The node token is minted HERE, in the control plane (the Mac has no database to mint it in) and travels in the `start` call.
+// `wake` and `stop` throw `machine_offline` untouched where the caller can wait; `stop` and `status` fold a failed call into
+// `confirmed: false` / `unknown` as the runner interface requires (the caller leaves everything as it is and retries).
+import { openDb } from '../../../canvas/db.js';
+import { mintExecutionToken } from '../../../canvas/node-tokens.js';
+import { callMachine } from './call.js';
+import { machineEnvironmentOfProfile } from './environment.js';
+import { MachineLaunchUncertainError, MachineLostError, MachineOfflineError } from './ops.js';
+/** The machine environment of a node's profile, or null when the profile points at no machine environment. */
+export async function machineEnvironmentOfNode(nodeId) {
+    const row = await (await openDb()).prepare('SELECT profile_id FROM nodes WHERE node_id = ?').get(nodeId);
+    return row?.profile_id == null ? null : await machineEnvironmentOfProfile(row.profile_id);
+}
+const defaultEnvironmentOf = async (nodeId) => {
+    const environment = await machineEnvironmentOfNode(nodeId);
+    if (environment === null)
+        throw new Error(`node ${nodeId} has no machine environment`);
+    return environment;
+};
+const defaultTokenMinted = async (executionId) => await (await openDb()).prepare('SELECT 1 AS x FROM node_tokens WHERE broker_process_id = ?').get(executionId) !== undefined;
+const asError = (error) => error instanceof Error ? error : new Error(String(error));
+export function createMachineRunner(deps = {}) {
+    const environmentOf = deps.environmentOf ?? defaultEnvironmentOf;
+    return {
+        kind: 'machine',
+        async start(input) {
+            const environment = await environmentOf(input.nodeId);
+            const tokenMinted = deps.tokenMinted ?? defaultTokenMinted;
+            const uncertain = (why) => new MachineLaunchUncertainError(environment, `the launch of execution ${input.executionId} is unconfirmed: ${why}`);
+            // `status` of THIS execution decides. A repeated start (a reconciler whose lease was taken, a start whose answer was lost) finds the
+            // broker of this execution and adopts it. A token is never minted twice for one execution (D75): one that exists means a start was
+            // already handed over, so what is left to learn is whether its broker exists.
+            const handedOver = await tokenMinted(input.executionId);
+            let status;
+            try {
+                status = await callMachine(environment, 'status', { execution: input });
+            }
+            catch (error) {
+                if (handedOver && (error instanceof MachineOfflineError || error instanceof MachineLostError))
+                    throw uncertain('the machine could not be asked');
+                throw error;
+            }
+            if (status.state === 'running')
+                return { pid: status.pid, exited: null };
+            if (handedOver)
+                throw uncertain('a start was handed over and no broker is running yet');
+            const nodeToken = await (deps.mintToken ?? ((i) => mintExecutionToken(i.executionId, i.nodeId)))(input);
+            try {
+                const result = await callMachine(environment, 'start', { ...input, nodeToken });
+                return { pid: result.pid, exited: null };
+            }
+            catch (error) {
+                // Sent and unanswered (the link dropped, or the lease ran out): the Mac may have spawned the broker. The execution stays launching.
+                if (error instanceof MachineLostError || (error instanceof MachineOfflineError && error.sent))
+                    throw uncertain(error.message);
+                throw error;
+            }
+        },
+        async wake(execution) {
+            return await callMachine(await environmentOf(execution.nodeId), 'wake', { execution });
+        },
+        async stop(execution, options) {
+            try {
+                const result = await callMachine(await environmentOf(execution.nodeId), 'stop', { execution, options });
+                return result.error === undefined ? { confirmed: result.confirmed } : { confirmed: result.confirmed, error: new Error(result.error) };
+            }
+            catch (error) {
+                return { confirmed: false, error: asError(error) };
+            }
+        },
+        async status(execution) {
+            try {
+                return await callMachine(await environmentOf(execution.nodeId), 'status', { execution });
+            }
+            catch (error) {
+                return { state: 'unknown', error: asError(error).message };
+            }
+        },
+        async delete(nodeId) {
+            await callMachine(await environmentOf(nodeId), 'delete', { nodeId });
+        },
+        async viewerAddress(execution) {
+            return { kind: 'machine', environmentId: await environmentOf(execution.nodeId), nodeId: execution.nodeId };
+        },
+    };
+}

package/dist/core/runtime/runner/process.d.ts

@@ -0,0 +1,11 @@
+import type { Runner, RunnerExit, RunnerStartInput } from './types.js';
+/** The local runner delegates process ownership to the existing detached broker host. */
+/** `start` narrows `exited` to non-null: the process runner always observes its child. */
+export declare const processRunner: Omit<Runner, 'start'> & {
+    start(input: RunnerStartInput): Promise<{
+        pid: number | null;
+        exited: Promise<RunnerExit>;
+    }>;
+} & {
+    kind: 'process';
+};

package/dist/core/runtime/runner/process.js

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { InputError } from '../../io.js';
+import { getNode } from '../../canvas/index.js';
+import { liveExecutionForNode } from '../../canvas/executions.js';
+import { nodeRunDir, viewSocketPath } from '../../canvas/paths.js';
+import { capturePidIdentities, identitiesMatch, isPidAlive } from '../../canvas/pid.js';
+import { writeFileBeneath } from '../../spaces/open-beneath.js';
+import { headlessBrokerHost } from '../host.js';
+async function pidFor(execution) {
+    const live = await liveExecutionForNode(execution.nodeId);
+    if (live?.executionId !== execution.executionId || live.pid === null || !isPidAlive(live.pid))
+        return null;
+    // A recycled pid is not the broker belonging to this execution.
+    const actual = capturePidIdentities([live.pid])?.get(live.pid);
+    return live.processIdentity && actual && identitiesMatch(actual, live.processIdentity) ? live.pid : null;
+}
+/** The local runner delegates process ownership to the existing detached broker host. */
+/** `start` narrows `exited` to non-null: the process runner always observes its child. */
+export const processRunner = {
+    kind: 'process',
+    async start(input) {
+        if (!existsSync(input.cwd)) {
+            throw new InputError({ error: 'cwd_missing', message: `${input.nodeId} cannot be revived — its recorded cwd no longer exists: ${input.cwd}`,
+                next: `Recreate ${input.cwd}, or repair it with \`crtr node config --cwd <path> --node ${input.nodeId}\`; then retry \`crtr node lifecycle revive ${input.nodeId}\`.` });
+        }
+        const runDir = nodeRunDir(input.nodeId);
+        mkdirSync(runDir, { recursive: true });
+        writeFileBeneath(runDir, join(runDir, 'broker-launch.json'), input.launchJson, { atomic: true });
+        const invocation = JSON.parse(input.launchJson);
+        const node = await getNode(input.nodeId);
+        if (!node)
+            throw new Error(`node ${input.nodeId} not found`);
+        const handle = await headlessBrokerHost.launch(input.nodeId, invocation, { cwd: input.cwd, name: node.name ?? input.nodeId, resuming: input.resuming, launchJson: input.launchJson });
+        return { pid: handle.pid, exited: handle.exited };
+    },
+    async wake(execution) {
+        const pid = await pidFor(execution);
+        if (pid === null)
+            return 'no_broker';
+        try {
+            process.kill(pid, 'SIGUSR1');
+            return 'signalled';
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                return 'no_broker';
+            throw error;
+        }
+    },
+    async stop(execution, options) {
+        // The host teardown reads nodes.pi_pid; refuse if it no longer names this execution.
+        const pid = await pidFor(execution);
+        if (pid === null)
+            return { confirmed: true };
+        const node = await getNode(execution.nodeId);
+        if (node?.pi_pid !== pid)
+            throw new Error(`node ${execution.nodeId} no longer points at execution ${execution.executionId}`);
+        return headlessBrokerHost.teardown(execution.nodeId, { excludePid: options.excludePid });
+    },
+    async status(execution) {
+        const pid = await pidFor(execution);
+        return pid !== null ? { state: 'running', pid } : { state: 'gone' };
+    },
+    async delete(nodeId) {
+        const { rm } = await import('node:fs/promises');
+        await rm(nodeRunDir(nodeId), { recursive: true, force: true });
+    },
+    async viewerAddress(execution) { return { kind: 'unix', path: viewSocketPath(execution.nodeId) }; },
+};

package/dist/core/runtime/runner/types.d.ts

@@ -0,0 +1,101 @@
+export type RunnerKind = 'process' | 'blaxel' | 'machine';
+/** The identity of one execution as the runner is asked about it. Rows already hold these. */
+export interface RunnerExecution {
+    executionId: string;
+    nodeId: string;
+    /** `executions.attempt`, the sandbox name suffix. */
+    attempt: number;
+    /** `executions.sandbox_name`, null for the process runner. */
+    sandboxName: string | null;
+}
+/** What `start` needs beyond the execution: the execution row's `launch_json` is the launch recipe. */
+export interface RunnerStartInput extends RunnerExecution {
+    /** The release the wake accepted (`executions.release`). */
+    release: string;
+    /** `executions.launch_json`: invocation argv and env, config snapshot, system prompt text, scopes. */
+    launchJson: string;
+    /** The working directory the broker starts in. */
+    cwd: string;
+    /** True when the broker resumes a saved session. */
+    resuming: boolean;
+}
+export interface RunnerStarted {
+    /** The broker's pid on a Mac; null where the runner cannot see one (Blaxel reports through `broker.started`). */
+    pid: number | null;
+    /** Resolves when the broker process ends, where the runner observes it (process runner); never for Blaxel. */
+    exited: Promise<RunnerExit> | null;
+}
+export interface RunnerExit {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    oomKilled?: boolean;
+}
+/** Process status of the named execution's broker. A frozen Blaxel broker reads `running`: the sandbox's own status is never the freeze signal. */
+export type RunnerStatus = {
+    state: 'running';
+    pid: number | null;
+}
+/** No process: the sandbox is absent, or present without the broker or start script. */
+ | {
+    state: 'gone';
+}
+/** The start script or broker ended non-zero; `reason` is the script's reason (`cwd_missing`, `extension_unavailable`, ...). */
+ | {
+    state: 'failed';
+    reason: string;
+    code: number | null;
+}
+/** The runner could not tell (a Blaxel API error). The caller leaves everything as it is and retries on the next claim. */
+ | {
+    state: 'unknown';
+    error: string;
+};
+export type RunnerWakeResult = 'signalled' | 'no_broker';
+export interface RunnerStopOptions {
+    /** Why: written to `executions.stop_reason` by the caller; carried here for the runner's diagnostics. */
+    reason: string;
+    /** A process whose tree is already known to the caller is excluded from the kill (the caller's own relay). */
+    excludePid?: number;
+}
+export interface RunnerStopResult {
+    /** False when the process could not be confirmed dead; the caller must not clean up what the broker owned. */
+    confirmed: boolean;
+    error?: Error;
+}
+/** Where a viewer connects. */
+export type RunnerViewerAddress = {
+    kind: 'unix';
+    path: string;
+} | {
+    kind: 'wss';
+    url: string;
+    headers: Record<string, string>;
+}
+/** The broker's `view.sock` is on a machine with no public address: the viewer opens a channel over that machine's link (design-import I13, `view.open`). */
+ | {
+    kind: 'machine';
+    environmentId: string;
+    nodeId: string;
+};
+export interface Runner {
+    readonly kind: RunnerKind;
+    /**
+     * Hand the execution to its environment and start the broker. The node token is minted INSIDE this call
+     * (`mintNodeToken` returns the raw token; the execution must be `launching` and have no token row) and
+     * handed over without being kept: fd 3 / unlinked file (process runner), process env (Blaxel). The process
+     * runner writes `broker-launch.json` from `launchJson` into the run dir and checks the cwd exists.
+     * Throws on refusal (cap, cwd missing, quota); the caller ends the execution `launch_failed`.
+     */
+    start(input: RunnerStartInput): Promise<RunnerStarted>;
+    /** Signal the execution's broker to look for mail again. `no_broker` when no process of that execution runs. Carries no token and starts nothing. */
+    wake(execution: RunnerExecution): Promise<RunnerWakeResult>;
+    /** Stop the execution's broker. Repeating it on a stopped execution confirms. */
+    stop(execution: RunnerExecution, options: RunnerStopOptions): Promise<RunnerStopResult>;
+    status(execution: RunnerExecution): Promise<RunnerStatus>;
+    /** Remove everything the runner holds for the node: the run dir (process) or the sandbox (Blaxel). */
+    delete(nodeId: string): Promise<void>;
+    /** Where a viewer reaches this execution's broker. */
+    viewerAddress(execution: RunnerExecution): Promise<RunnerViewerAddress>;
+}
+/** The runner for an environment kind: `machine` → process, `blaxel` → Blaxel. */
+export type RunnerForKind = (kind: 'machine' | 'blaxel') => Runner;

package/dist/core/runtime/runner/types.js

@@ -0,0 +1,16 @@
+// src/core/runtime/runner/types.ts — the runner interface (design-fleet, Components: Runner).
+//
+// A runner starts and stops a node's broker in its environment and is the only
+// component that knows where a broker runs. The environment a node's profile
+// points at chooses it: kind `machine` → the process runner (`process.ts`),
+// kind `blaxel` → the Blaxel runner (`runner/blaxel/`, C-A2).
+//
+// Boundaries: the runner does not decide when to wake (the node-lifecycle lane
+// does), holds no mail, and writes the `executions` row only through its runner
+// columns (`pid`, `process_identity`, `sandbox_name`, `heartbeat_at`). Every
+// method is safe to call twice: a reconciler whose lease was taken may repeat a
+// call, so a repeat must be harmless (design D76).
+//
+// The contract suite in `__tests__/runner-contract.ts` is what an implementation
+// must satisfy; the process runner and the Blaxel runner both run it.
+export {};

package/dist/core/runtime/session-branch.d.ts

@@ -0,0 +1,7 @@
+export interface HumanForkCoordinates {
+    sourceFile: string;
+    sourceSessionId: string;
+    leafId: string;
+}
+/** Fork the captured root-to-leaf branch without opening or mutating its live source. */
+export declare function materializeSessionBranch(coordinates: HumanForkCoordinates): Promise<string>;

package/dist/core/runtime/session-branch.js

@@ -0,0 +1,16 @@
+import { conversationIdFromPath, conversationStore } from '../conversation-store/index.js';
+/** Fork the captured root-to-leaf branch without opening or mutating its live source. */
+export async function materializeSessionBranch(coordinates) {
+    if (coordinates.sourceSessionId === '' || coordinates.leafId === '') {
+        throw new Error('session branch coordinates require source session and leaf ids');
+    }
+    const sourceId = conversationIdFromPath(coordinates.sourceFile);
+    if (sourceId === null || sourceId !== coordinates.sourceSessionId) {
+        throw new Error('source session id does not match captured coordinates');
+    }
+    const store = conversationStore();
+    if ((await store.header(sourceId)).header.id !== coordinates.sourceSessionId) {
+        throw new Error('source session id does not match captured coordinates');
+    }
+    return (await store.header(await store.fork(sourceId, undefined, coordinates.leafId))).path;
+}