@north-light/api 0.3.579 → 0.3.587

package/dist/daemon/machine-link/holder.js

@@ -0,0 +1,272 @@
+// src/daemon/machine-link/holder.ts — the API process that holds a Mac's link (design-import I13).
+//
+// On upgrade it takes the environment's `machine_links` row with the next `generation` (the previous holder's row is replaced and its
+// next renewal sees it lost), renews the lease every 15 s (45 s lease) with `environments.last_seen_at`, claims `pending` `machine_calls`
+// rows on the `machine:<environment>` signal (and on listen start and a 1 s sweep), forwards each as a `call` frame, writes the `result`
+// and signals `machine_call:<id>`. A link that drops fails the calls it had sent `machine_offline` and deletes its row only where the
+// generation is still its own. A revoked or rotated-away credential closes the link at the next renewal.
+import { EventEmitter } from 'node:events';
+import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { WebSocket, WebSocketServer } from 'ws';
+import { openDb } from '../../core/canvas/db.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { brokerSignalBus } from '../broker-signals/bus.js';
+import { verifyMachineCredential } from './credential.js';
+import { CLOSE_REVOKED, CLOSE_SUPERSEDED, LINK_MAX_PAYLOAD_BYTES, parseFrame } from './frames.js';
+export const LINK_LEASE_MS = 45_000;
+export const LINK_RENEW_MS = 15_000;
+export const LINK_PING_MS = 30_000;
+const CLAIM_SWEEP_MS = 1000;
+const CLAIM_BATCH = 10;
+const wss = new WebSocketServer({ noServer: true, maxPayload: LINK_MAX_PAYLOAD_BYTES });
+const links = new Map();
+/** Prefix of the address an API process writes when nothing tells it where other API processes can reach it; the viewer forward refuses it. */
+export const UNROUTABLE_PREFIX = 'unroutable:';
+let boundApiAddress;
+/** The TCP listener's bound `host:port`, used as this process's address when `CRTR_API_ADDRESS` is not set. */
+export const setApiAddress = (address) => { boundApiAddress = address; };
+/** The address other API processes find this one at, written to `machine_links.api_address`: `CRTR_API_ADDRESS`, else the listener's bound address, else an unroutable marker. */
+export const apiAddress = () => process.env['CRTR_API_ADDRESS'] ?? boundApiAddress ?? `${UNROUTABLE_PREFIX}${hostname()}:${process.pid}`;
+const lease = () => new Date(Date.now() + LINK_LEASE_MS).toISOString();
+export class HeldLink extends EventEmitter {
+    environmentId;
+    generation;
+    ws;
+    token;
+    timers = [];
+    unsubscribe;
+    claiming = false;
+    closed = false;
+    alive = true;
+    channels = new Map();
+    constructor(environmentId, generation, ws, token) {
+        super();
+        this.environmentId = environmentId;
+        this.generation = generation;
+        this.ws = ws;
+        this.token = token;
+    }
+    start() {
+        const { ws } = this;
+        ws.on('message', (data) => { this.onMessage(data).catch((error) => this.fault('daemon.machine_link.frame_failed', error)); });
+        ws.on('pong', () => { this.alive = true; });
+        ws.on('close', () => { this.teardown().catch((error) => this.fault('daemon.machine_link.teardown_failed', error)); });
+        ws.on('error', () => { });
+        this.timers.push(setInterval(() => { this.renew().catch((error) => this.fault('daemon.machine_link.renew_failed', error)); }, LINK_RENEW_MS));
+        this.timers.push(setInterval(() => {
+            if (!this.alive) {
+                ws.terminate();
+                return;
+            }
+            this.alive = false;
+            try {
+                ws.ping();
+            }
+            catch { /* close follows */ }
+        }, LINK_PING_MS));
+        this.timers.push(setInterval(() => { this.claim().catch((error) => this.fault('daemon.machine_link.claim_failed', error)); }, CLAIM_SWEEP_MS));
+        void brokerSignalBus.subscribe((id) => {
+            if (id === this.environmentId)
+                this.claim().catch((error) => this.fault('daemon.machine_link.claim_failed', error));
+        }, { kinds: ['machine'], onListenStart: () => { this.claim().catch((error) => this.fault('daemon.machine_link.claim_failed', error)); } })
+            .then((off) => { if (this.closed)
+            off();
+        else
+            this.unsubscribe = off; });
+    }
+    fault(event, error) { emitEvent({ level: 'error', event, fields: { environment: this.environmentId }, error }); }
+    send(frame) {
+        if (this.ws.readyState !== WebSocket.OPEN)
+            return false;
+        this.ws.send(JSON.stringify(frame));
+        return true;
+    }
+    /** Renew the row, my sent calls' leases and `last_seen_at`; a lost generation or a revoked credential closes the link. */
+    async renew() {
+        if (this.closed)
+            return;
+        const db = await openDb();
+        const until = lease();
+        const renewed = await db.prepare('UPDATE machine_links SET lease_expires_at = ? WHERE environment = ? AND generation = ?').run(until, this.environmentId, this.generation);
+        if (renewed.changes === 0) {
+            this.ws.close(CLOSE_SUPERSEDED, 'superseded');
+            return;
+        }
+        await db.prepare("UPDATE machine_calls SET lease_expires_at = ? WHERE environment = ? AND state = 'sent' AND claimed_generation = ?").run(until, this.environmentId, this.generation);
+        await db.prepare('UPDATE environments SET last_seen_at = ? WHERE object = ?').run(new Date().toISOString(), this.environmentId);
+        if (!await this.credentialValid())
+            this.ws.close(CLOSE_REVOKED, 'revoked');
+    }
+    /** The credential this link authenticated with is still the environment's current one: rotation or revocation evicts the link. */
+    async credentialValid() { return await verifyMachineCredential(this.environmentId, this.token); }
+    /** Claim this environment's pending calls (fenced by this link's generation) and forward them. */
+    async claim() {
+        if (this.closed || this.claiming)
+            return;
+        this.claiming = true;
+        try {
+            for (;;) {
+                const rows = await (await openDb()).prepare(`UPDATE machine_calls SET state = 'sent', claimed_generation = ?, lease_expires_at = ?
+          WHERE call_id IN (SELECT call_id FROM machine_calls WHERE environment = ? AND state = 'pending'
+            AND EXISTS (SELECT 1 FROM machine_links WHERE environment = ? AND generation = ?)
+            ORDER BY created_at FOR UPDATE SKIP LOCKED LIMIT ${CLAIM_BATCH})
+          RETURNING call_id, op, args_json`).all(this.generation, lease(), this.environmentId, this.environmentId, this.generation);
+                // The claim fenced on this generation, but another holder may have taken the link since: a superseded holder sends nothing and
+                // gives its claims back, so the call reaches the machine once, through the current link.
+                const current = !this.closed && await this.isCurrentGeneration();
+                for (const row of rows) {
+                    if (!current)
+                        await this.release(row.call_id);
+                    else if (!this.send({ type: 'call', call_id: row.call_id, op: row.op, args: JSON.parse(row.args_json) }))
+                        await this.failCall(row.call_id, 'machine_offline', 'link closed before the call was sent', false);
+                }
+                if (rows.length < CLAIM_BATCH)
+                    return;
+            }
+        }
+        finally {
+            this.claiming = false;
+        }
+    }
+    /** `sent` is whether the call was written to the link: a call that was sent may have run, one that was not ran nowhere. */
+    async failCall(callId, code, message, sent) {
+        await this.settle(callId, 'failed', { code, message, sent }, false);
+    }
+    /** This link's generation is still the one in the environment's `machine_links` row. */
+    async isCurrentGeneration() {
+        return await (await openDb()).prepare('SELECT 1 AS live FROM machine_links WHERE environment = ? AND generation = ?').get(this.environmentId, this.generation) !== undefined;
+    }
+    /** Give a claimed, unsent call back to `pending`. */
+    async release(callId) {
+        await (await openDb()).prepare("UPDATE machine_calls SET state = 'pending', claimed_generation = NULL, lease_expires_at = NULL WHERE call_id = ? AND state = 'sent' AND claimed_generation = ?").run(callId, this.generation);
+    }
+    /** Settle a call this link holds; a call another holder owns or one already settled is left as it is. A result settles only
+     *  while this link is the current generation (`requireCurrent`); a failure for a dropped link settles whatever the row now says. */
+    async settle(callId, state, result, requireCurrent) {
+        await withNotify(callId, state, result, this.environmentId, this.generation, requireCurrent);
+    }
+    async onMessage(data) {
+        const frame = parseFrame(data);
+        if (frame === null)
+            return;
+        switch (frame.type) {
+            case 'result':
+                if (frame.ok)
+                    await this.settle(frame.call_id, 'done', frame.value ?? null, true);
+                else
+                    await this.settle(frame.call_id, 'failed', { code: 'machine_call_failed', message: frame.error }, true);
+                return;
+            case 'view.ready':
+                this.channels.get(frame.channel)?.emit('connect');
+                return;
+            case 'view.data':
+                this.channels.get(frame.channel)?.emit('data', Buffer.from(frame.bytes, 'base64'));
+                return;
+            case 'view.close':
+                this.channels.get(frame.channel)?.finish(frame.error);
+                return;
+            default: return;
+        }
+    }
+    async teardown() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const timer of this.timers)
+            clearInterval(timer);
+        this.unsubscribe?.();
+        if (links.get(this.environmentId) === this)
+            links.delete(this.environmentId);
+        for (const channel of [...this.channels.values()])
+            channel.finish('machine link closed');
+        const db = await openDb();
+        // The calls this link sent and never got a result for may or may not have run: the caller reads `machine_offline`.
+        const dropped = await db.prepare("SELECT call_id FROM machine_calls WHERE environment = ? AND state = 'sent' AND claimed_generation = ?").all(this.environmentId, this.generation);
+        for (const { call_id } of dropped)
+            await this.failCall(call_id, 'machine_offline', 'link dropped before the result', true);
+        await db.prepare('DELETE FROM machine_links WHERE environment = ? AND generation = ?').run(this.environmentId, this.generation);
+    }
+}
+async function withNotify(callId, state, result, environmentId, generation, requireCurrent) {
+    const db = await openDb();
+    const settled = await db.prepare(`UPDATE machine_calls SET state = ?, result_json = ?, finished_at = ?
+    WHERE call_id = ? AND environment = ? AND claimed_generation = ? AND state = 'sent'
+    ${requireCurrent ? 'AND EXISTS (SELECT 1 FROM machine_links WHERE environment = ? AND generation = ?)' : ''}`)
+        .run(state, JSON.stringify(result), new Date().toISOString(), callId, environmentId, generation, ...(requireCurrent ? [environmentId, generation] : []));
+    if (settled.changes > 0)
+        await db.prepare('SELECT pg_notify(?, ?)').get('crtr_signal', `machine_call:${callId}`);
+}
+/** A viewer channel to one node's view.sock on the Mac, as the relay's broker-side link. */
+export class MachineViewLink extends EventEmitter {
+    link;
+    ended = false;
+    failed = false;
+    channel = randomUUID();
+    constructor(link, nodeId) {
+        super();
+        this.link = link;
+        link.channels.set(this.channel, this);
+        if (!link.send({ type: 'view.open', channel: this.channel, node: nodeId }))
+            queueMicrotask(() => this.finish('machine link closed'));
+    }
+    get destroyed() { return this.ended; }
+    write(line) {
+        return !this.ended && this.link.send({ type: 'view.data', channel: this.channel, bytes: Buffer.from(line).toString('base64') });
+    }
+    destroy() {
+        if (!this.ended) {
+            this.link.send({ type: 'view.close', channel: this.channel });
+            this.finish(undefined);
+        }
+        return this;
+    }
+    /** The channel is over: `error` names a failure (the relay records a fault), none is a clean end. */
+    finish(error) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.link.channels.delete(this.channel);
+        if (error !== undefined && !this.failed) {
+            this.failed = true;
+            this.emit('error', Object.assign(new Error(error), { code: 'ECONNRESET' }));
+        }
+        this.emit('close', this.failed);
+    }
+}
+/** The link this process holds for `environmentId`, or null (no link, or another API process holds it). */
+export const heldLinkOf = (environmentId) => links.get(environmentId) ?? null;
+const MACHINE_LINK_PATH = /^\/v1\/machines\/([A-Za-z0-9_-]+)\/link$/;
+/** The environment id of a machine-link upgrade path, or null for any other path. */
+export function machineLinkEnvironment(req) {
+    const match = MACHINE_LINK_PATH.exec(new URL(req.url ?? '/', 'http://runtime.local').pathname);
+    return match === null ? null : match[1];
+}
+/** Authenticate the machine credential and take over the environment's link. Returns a refusal for the caller to write, or null once upgraded. */
+export async function handleMachineLinkUpgrade(req, socket, head, environmentId) {
+    const header = req.headers['authorization'];
+    const token = /^Bearer (\S+)$/.exec(Array.isArray(header) ? header[0] ?? '' : header ?? '')?.[1];
+    if (token === undefined || !await verifyMachineCredential(environmentId, token))
+        return { status: 401, text: 'Unauthorized', code: 'unauthorized', message: 'machine credential refused' };
+    const now = new Date().toISOString();
+    const db = await openDb();
+    const row = await db.prepare(`INSERT INTO machine_links (environment, generation, api_address, connected_at, lease_expires_at) VALUES (?, 1, ?, ?, ?)
+    ON CONFLICT (environment) DO UPDATE SET generation = machine_links.generation + 1, api_address = EXCLUDED.api_address, connected_at = EXCLUDED.connected_at, lease_expires_at = EXCLUDED.lease_expires_at
+    RETURNING generation`).get(environmentId, apiAddress(), now, lease());
+    await db.prepare('UPDATE environments SET last_seen_at = ? WHERE object = ?').run(now, environmentId);
+    const generation = Number(row.generation);
+    if (socket.destroyed) {
+        await db.prepare('DELETE FROM machine_links WHERE environment = ? AND generation = ?').run(environmentId, generation);
+        return null;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+        const link = new HeldLink(environmentId, generation, ws, token);
+        // A second link from the same machine to this process replaces the first: the first's row is gone, so it closes at its next renewal; close it now.
+        const previous = links.get(environmentId);
+        links.set(environmentId, link);
+        previous?.ws.close(CLOSE_SUPERSEDED, 'superseded');
+        link.start();
+        void link.claim().catch((error) => emitEvent({ level: 'error', event: 'daemon.machine_link.claim_failed', fields: { environment: environmentId }, error }));
+    });
+    return null;
+}

package/dist/daemon/machine-link/move-notify.d.ts

@@ -0,0 +1,4 @@
+import { type MoveRecord } from './config.js';
+/** Tell the node that asked for the move that it finished, through the control plane with the person's bearer (`POST /v1/nodes/:id/messages`): the node
+ *  now lives in the account, so the message is stored there as mail and wakes it once the machine link is up. Then the record says `notified`. */
+export declare function notifyMoveFinished(move: MoveRecord): Promise<MoveRecord>;

package/dist/daemon/machine-link/move-notify.js

@@ -0,0 +1,15 @@
+// src/daemon/machine-link/move-notify.ts — telling the node that asked for a move to Northlight that it finished (design-crtr-northlight-signin component 4).
+import { CrtrClient } from '../../api/index.js';
+import { northlightFetch } from '../../core/directory/person-credential.js';
+import { writeMoveRecord } from './config.js';
+/** Tell the node that asked for the move that it finished, through the control plane with the person's bearer (`POST /v1/nodes/:id/messages`): the node
+ *  now lives in the account, so the message is stored there as mail and wakes it once the machine link is up. Then the record says `notified`. */
+export async function notifyMoveFinished(move) {
+    if (move.notified || move.notify === null)
+        return move;
+    await new CrtrClient({ baseUrl: move.apiUrl, fetch: northlightFetch(move.directoryUrl, move.apiUrl) }).sendMessage(move.notify, { from: null,
+        body: `The move to Northlight finished; crtr on this computer now runs with the account ${move.account.display}. Retry the command that needed the account and carry on.` });
+    const notified = { ...move, notified: true };
+    writeMoveRecord(notified);
+    return notified;
+}

package/dist/daemon/manage.d.ts

@@ -1,4 +1,5 @@
 import { type HealthDTO, type StartupPhaseDTO } from '../api/index.js';
+import type { DumpResult } from '../core/import/export/dump.js';
 /** Env keys that must NEVER reach the daemon process. Restarting crtrd is
  *  overwhelmingly done from inside an agent node's own bash tool (`crtr sys
  *  daemon stop && start`), which inherits that node's FULL env — its identity
@@ -46,10 +47,25 @@ export interface DaemonExportSqliteResult {
     ms: number;
     userVersion: number;
 }
-/** Run the selected generation's `crtrd-cli export-sqlite` and wait for it. The export loads canvas database code, which
- *  a CLI process may not, so it runs in the daemon entry the way the daemon itself is launched. Throws with the child's
- *  stderr when it fails. */
+export interface DaemonExportSqliteResult {
+    path: string;
+    rows: number;
+    ms: number;
+    userVersion: number;
+}
+/** Run the selected generation's `crtrd-cli export-sqlite` and wait for it. */
 export declare function runDaemonExportSqlite(): Promise<DaemonExportSqliteResult>;
+/** Run the selected generation's `crtrd-cli import-dump`: the row files of the running canvas into `out`/rows. */
+export declare function runDaemonImportDump(out: string, kind: 'machine' | 'hosted'): Promise<DumpResult>;
+/** Run `crtrd-cli import-dump <out> bodies`: every `bodies` row into `out`/rows/bodies (the pre-pause dump; the later `runDaemonImportDump` adds the rows written since). */
+export declare function runDaemonBodiesDump(out: string): Promise<{
+    parts: string[];
+    count: number;
+}>;
+/** Run `crtrd-cli import-dump <out> install-id`: this install's id, read from the running canvas. */
+export declare function runDaemonInstallId(): Promise<{
+    installId: string;
+}>;
 export interface SpawnDaemonOptions {
     /** The phase that proves a daemon launched by this call is available. */
     targetPhase?: 'ready' | 'prepared';

package/dist/daemon/manage.js

@@ -195,12 +195,11 @@ export async function execDaemon() {
     const launchArgs = await resolveDaemonLaunch();
     return execve(executable, [executable, ...launchArgs, '--canvas-home', crtrHome()], sanitizedDaemonEnv());
 }
-/** Run the selected generation's `crtrd-cli export-sqlite` and wait for it. The export loads canvas database code, which
- *  a CLI process may not, so it runs in the daemon entry the way the daemon itself is launched. Throws with the child's
- *  stderr when it fails. */
-export async function runDaemonExportSqlite() {
+/** Run one of the selected generation's `crtrd-cli` entries that load canvas database code (a CLI process may not) and read
+ *  its one JSON result line. Throws with the child's stderr when it fails. */
+async function runDaemonEntry(args) {
     const launchArgs = await resolveDaemonLaunch();
-    const child = spawn(hostExecPath(), [...launchArgs, 'export-sqlite'], { stdio: ['ignore', 'pipe', 'pipe'], env: sanitizedDaemonEnv() });
+    const child = spawn(hostExecPath(), [...launchArgs, ...args], { stdio: ['ignore', 'pipe', 'pipe'], env: sanitizedDaemonEnv() });
     let stdout = '';
     let stderr = '';
     child.stdout.setEncoding('utf8').on('data', (chunk) => { stdout += chunk; });
@@ -210,10 +209,26 @@ export async function runDaemonExportSqlite() {
         child.once('close', (exitCode) => resolve(exitCode));
     });
     if (code !== 0)
-        throw new Error(stderr.trim() || `the export process exited with code ${code}`);
+        throw new Error(stderr.trim() || `the ${args[0]} process exited with code ${code}`);
     const line = stdout.trim().split('\n').at(-1) ?? '';
     return JSON.parse(line);
 }
+/** Run the selected generation's `crtrd-cli export-sqlite` and wait for it. */
+export function runDaemonExportSqlite() {
+    return runDaemonEntry(['export-sqlite']);
+}
+/** Run the selected generation's `crtrd-cli import-dump`: the row files of the running canvas into `out`/rows. */
+export function runDaemonImportDump(out, kind) {
+    return runDaemonEntry(['import-dump', out, kind]);
+}
+/** Run `crtrd-cli import-dump <out> bodies`: every `bodies` row into `out`/rows/bodies (the pre-pause dump; the later `runDaemonImportDump` adds the rows written since). */
+export function runDaemonBodiesDump(out) {
+    return runDaemonEntry(['import-dump', out, 'bodies']);
+}
+/** Run `crtrd-cli import-dump <out> install-id`: this install's id, read from the running canvas. */
+export function runDaemonInstallId() {
+    return runDaemonEntry(['import-dump', '', 'install-id']);
+}
 /** How long a handover successor waits for a running join: a registration call (30 s) plus the join's own stop and start. */
 const JOIN_WAIT_WINDOW_MS = 3 * 60_000;
 // Shutdown stays short even though startup may include corpus migration.

package/dist/daemon/park-activity.d.ts

@@ -0,0 +1,10 @@
+import type { NodeMeta } from '../core/canvas/types.js';
+import type { ViewerProbe } from '../core/runtime/placement.js';
+import type { PendingPark } from './park-pending.js';
+/** A main-session write after parking was armed is durable evidence of live
+ * input even when the turn has since settled and the viewer detached. */
+export declare function mainSessionActivitySince(sessionFile: string | null | undefined, startedAt: number): Promise<boolean>;
+/** One verdict shared by normal completion and grace expiry. A broker records
+ * accepted live input against the process-local marker before it drives Pi, so
+ * the verdict cannot race a viewer, live delivery, or durable wake. */
+export declare function shouldParkAfterSummary(nodeId: string, node: Pick<NodeMeta, 'lifecycle' | 'pi_session_file'>, pending: PendingPark, viewer?: ViewerProbe): Promise<boolean>;

package/dist/daemon/park-activity.js

@@ -0,0 +1,33 @@
+import { conversationIdFromPath, conversationStore, ConversationNotFoundError } from '../core/conversation-store/index.js';
+import { emitEvent } from '../core/events/emit.js';
+import { hasWakeMailSince } from '../core/canvas/deliveries.js';
+import { readLiveTurn } from '../core/canvas/recovery.js';
+import { parkEvent } from './reconcilers/live-obligation.js';
+/** A main-session write after parking was armed is durable evidence of live
+ * input even when the turn has since settled and the viewer detached. */
+export async function mainSessionActivitySince(sessionFile, startedAt) {
+    if (sessionFile === null || sessionFile === undefined)
+        return false;
+    const id = conversationIdFromPath(sessionFile);
+    if (id === null)
+        return false;
+    try {
+        return (await conversationStore().header(id)).mtime >= startedAt;
+    }
+    catch (error) {
+        if (error instanceof ConversationNotFoundError)
+            return false;
+        emitEvent({ level: 'warn', event: 'broker.park.session_activity_scan_failed', error });
+        return true;
+    }
+}
+/** One verdict shared by normal completion and grace expiry. A broker records
+ * accepted live input against the process-local marker before it drives Pi, so
+ * the verdict cannot race a viewer, live delivery, or durable wake. */
+export async function shouldParkAfterSummary(nodeId, node, pending, viewer) {
+    return !pending.activity
+        && (await readLiveTurn(nodeId))?.busy !== true
+        && !await mainSessionActivitySince(node.pi_session_file, pending.startedAt)
+        && !await hasWakeMailSince(nodeId, pending.startedAt)
+        && await parkEvent(nodeId, node.lifecycle, viewer) === 'park';
+}

package/dist/daemon/park-pending.d.ts

@@ -0,0 +1,25 @@
+import { type CanvasDb } from '../core/canvas/db.js';
+export type PendingPark = {
+    startedAt: number;
+    activity: boolean;
+};
+/** Arm a pending park for `nodeId`. The caller delivers the parking prompt. */
+export declare function beginPendingPark(nodeId: string, now: number): Promise<void>;
+/** Record main-engine input accepted while the isolated turn is in flight. False when no park is armed. */
+export declare function recordPendingParkActivity(nodeId: string): Promise<boolean>;
+export declare function isPendingPark(nodeId: string): Promise<boolean>;
+/** When the pending park was armed (epoch ms), or undefined when none is armed. */
+export declare function pendingParkStartedAt(nodeId: string): Promise<number | undefined>;
+/** Clear-and-report the pending marker with one conditional update. Exactly one caller, in any process, gets the prior values back. */
+export declare function consumePendingPark(nodeId: string): Promise<PendingPark | undefined>;
+/** Every node with a parking turn in flight — the supervision sweep drops the ones whose broker has left the fleet. */
+export declare function pendingParkIds(): Promise<string[]>;
+/** The same clear inside the caller's transaction, for the execution leaving `running`. */
+export declare function clearPendingParkIn(db: CanvasDb, nodeId: string): Promise<void>;
+export type SupervisionMark = 'unattended_since' | 'stall_noticed_at' | 'wedge_noticed_at';
+/** The mark's time (epoch ms), or undefined when unset. */
+export declare function readSupervisionMark(nodeId: string, mark: SupervisionMark): Promise<number | undefined>;
+/** Set the mark to `at` (epoch ms). */
+export declare function writeSupervisionMark(nodeId: string, mark: SupervisionMark, at: number): Promise<void>;
+/** Clear the mark; a tick that finds it already clear takes no write. */
+export declare function clearSupervisionMark(nodeId: string, mark: SupervisionMark): Promise<void>;

package/dist/daemon/park-pending.js

@@ -0,0 +1,76 @@
+// park-pending.ts — the in-flight parking turn, as two columns of the node row.
+//
+// When the unattended clock expires on a live resident, the daemon does not
+// terminalize it: it asks the still-live engine for one summary turn and hands
+// the terminal decision to broker settlement. `nodes.park_requested_at` and
+// `nodes.park_activity` are the record that a node's next settlement means
+// "park". Any API process or reconcile process reads and consumes them, so a
+// park-complete that lands on another process than the one that armed it still
+// finds the marker (design D35, "Pending park").
+//
+//   arm      supervision sets `park_requested_at = now, park_activity = false`
+//   activity accepted live input sets `park_activity = true` only where armed
+//   consume  grace expiry, prompt failure and park-complete each clear the
+//            marker with ONE conditional update returning the prior values;
+//            only the caller that gets a row back evaluates the verdict and enacts
+//   clear    the execution leaving `running` clears the marker in the same
+//            transaction (`clearPendingParkIn`)
+//
+// The same node-row home holds the three supervision clocks (`unattended_since`,
+// `stall_noticed_at`, `wedge_noticed_at`): one live execution per node, so no
+// incarnation key, and the execution leaving `running` clears them too.
+import { openDb, withCanvasWrite } from '../core/canvas/db.js';
+/** Arm a pending park for `nodeId`. The caller delivers the parking prompt. */
+export async function beginPendingPark(nodeId, now) {
+    await withCanvasWrite(async (db) => {
+        await db.prepare('UPDATE nodes SET park_requested_at = ?, park_activity = 0 WHERE node_id = ?').run(new Date(now).toISOString(), nodeId);
+    });
+}
+/** Record main-engine input accepted while the isolated turn is in flight. False when no park is armed. */
+export async function recordPendingParkActivity(nodeId) {
+    return await withCanvasWrite(async (db) => Number((await db.prepare('UPDATE nodes SET park_activity = 1 WHERE node_id = ? AND park_requested_at IS NOT NULL').run(nodeId)).changes) > 0);
+}
+export async function isPendingPark(nodeId) {
+    return (await pendingParkStartedAt(nodeId)) !== undefined;
+}
+/** When the pending park was armed (epoch ms), or undefined when none is armed. */
+export async function pendingParkStartedAt(nodeId) {
+    const row = await (await openDb()).prepare('SELECT park_requested_at FROM nodes WHERE node_id = ?').get(nodeId);
+    return row?.park_requested_at ? Date.parse(row.park_requested_at) : undefined;
+}
+/** Clear-and-report the pending marker with one conditional update. Exactly one caller, in any process, gets the prior values back. */
+export async function consumePendingPark(nodeId) {
+    return await withCanvasWrite(async (db) => {
+        const prior = await db.prepare(`WITH prior AS (SELECT park_requested_at, park_activity FROM nodes WHERE node_id = ? AND park_requested_at IS NOT NULL FOR UPDATE)
+      UPDATE nodes n SET park_requested_at = NULL, park_activity = 0 FROM prior WHERE n.node_id = ?
+      RETURNING prior.park_requested_at AS park_requested_at, prior.park_activity AS park_activity`).get(nodeId, nodeId);
+        return prior === undefined ? undefined : { startedAt: Date.parse(prior.park_requested_at), activity: Number(prior.park_activity) === 1 };
+    });
+}
+/** Every node with a parking turn in flight — the supervision sweep drops the ones whose broker has left the fleet. */
+export async function pendingParkIds() {
+    return (await (await openDb()).prepare('SELECT node_id FROM nodes WHERE park_requested_at IS NOT NULL').all()).map((row) => row.node_id);
+}
+/** The same clear inside the caller's transaction, for the execution leaving `running`. */
+export async function clearPendingParkIn(db, nodeId) {
+    await db.prepare('UPDATE nodes SET park_requested_at = NULL, park_activity = 0, unattended_since = NULL, stall_noticed_at = NULL, wedge_noticed_at = NULL WHERE node_id = ?').run(nodeId);
+}
+/** The mark's time (epoch ms), or undefined when unset. */
+export async function readSupervisionMark(nodeId, mark) {
+    const row = await (await openDb()).prepare(`SELECT ${mark} AS at FROM nodes WHERE node_id = ?`).get(nodeId);
+    return row?.at ? Date.parse(row.at) : undefined;
+}
+/** Set the mark to `at` (epoch ms). */
+export async function writeSupervisionMark(nodeId, mark, at) {
+    await withCanvasWrite(async (db) => {
+        await db.prepare(`UPDATE nodes SET ${mark} = ? WHERE node_id = ?`).run(new Date(at).toISOString(), nodeId);
+    });
+}
+/** Clear the mark; a tick that finds it already clear takes no write. */
+export async function clearSupervisionMark(nodeId, mark) {
+    if (await readSupervisionMark(nodeId, mark) === undefined)
+        return;
+    await withCanvasWrite(async (db) => {
+        await db.prepare(`UPDATE nodes SET ${mark} = NULL WHERE node_id = ?`).run(nodeId);
+    });
+}

package/dist/daemon/postgres/binary.d.ts

@@ -0,0 +1,17 @@
+export interface PostgresBinaries {
+    /** Directory holding `bin/`, `lib/` and `share/`. */
+    root: string;
+    initdb: string;
+    postgres: string;
+    pgCtl: string;
+}
+/** The jar artifact suffix for this host. Linux picks the musl build on Alpine-style hosts. */
+export declare function hostJarSuffix(): string;
+/** `$XDG_CACHE_HOME/crouter/postgres/<version>/`, the same shared cache as the termrender pin. */
+export declare function postgresCacheDir(version?: string): string;
+/**
+ * Resolve the Postgres binaries: `CRTR_POSTGRES_HOME` names a pre-unpacked tree (the CI image bakes one); otherwise
+ * the pinned jar is downloaded from Maven Central, sha256-verified, unpacked and slimmed into the version-keyed shared
+ * cache, once, under a lock. A later call finds the ready stamp and does no work.
+ */
+export declare function ensurePostgresBinaries(log?: (message: string) => void): Promise<PostgresBinaries>;