@north-light/api 0.3.580 → 0.3.587

package/dist/daemon/api/viewer-presence.js

@@ -0,0 +1,100 @@
+// Viewer presence as `viewer_attachments` rows (design-fleet, Presence; D34).
+//
+// Only the daemon's authenticated attach relay (`bridge.ts`) writes these rows:
+// nothing a broker writes is trusted. One row per viewer connection. A
+// connection is "attending" from its hello and "presented" once the relay has
+// forwarded it the broker's welcome, i.e. once it holds the conversation it
+// shows. Liveness and supervision count unexpired attending rows; the
+// dashboard's read marker counts unexpired presented ones.
+//
+// A row lives 90 s and the relay refreshes it every 30 s while the viewer's
+// socket is open, so a crashed API process's rows lapse on their own. A clean
+// viewer close deletes the row; a broker-side close extends it to 60 s ahead so
+// the viewer's redial keeps the node attended. Expired rows are deleted by
+// storage maintenance. No process keeps a presence cache: every reader reads
+// the rows, so a reconciler or another API process sees the same answer.
+import { randomUUID } from 'node:crypto';
+import { openDb } from '../../core/canvas/db.js';
+export const VIEWER_ROW_TTL_MS = 90_000;
+export const VIEWER_ROW_REFRESH_MS = 30_000;
+/** How long a viewer stays attending after its broker connection ended, for its redial to land. */
+export const VIEWER_REDIAL_HOLD_MS = 60_000;
+/** This process's id on the rows it writes. */
+export const API_PROCESS_ID = randomUUID();
+/** This process's open connections: the registry the 30 s refresh runs from (Process-local state: connections this process holds). */
+const held = new WeakMap();
+const at = (offsetMs = 0) => new Date(Date.now() + offsetMs).toISOString();
+/** Whether an unexpired attending row exists for the node. */
+export async function hasAttachedBrokerViewers(nodeId) {
+    const row = await (await openDb()).prepare('SELECT 1 AS present FROM viewer_attachments WHERE node_id = ? AND attends = 1 AND expires_at > ? LIMIT 1')
+        .get(nodeId, at());
+    return row !== undefined;
+}
+/** Whether an unexpired attending row has been shown the conversation (the relay forwarded the broker's welcome). */
+export async function hasPresentedViewer(nodeId) {
+    const row = await (await openDb()).prepare('SELECT 1 AS present FROM viewer_attachments WHERE node_id = ? AND attends = 1 AND presented_at IS NOT NULL AND expires_at > ? LIMIT 1')
+        .get(nodeId, at());
+    return row !== undefined;
+}
+/** The row id of an attached connection, for diagnostics and tests. */
+export function viewerConnectionId(connection) {
+    return held.get(connection)?.connectionId;
+}
+/** Insert the attending row for `connection` and keep it fresh until {@link detachViewer} or {@link holdViewerForRedial}. Repeating it is a no-op. */
+export async function attachViewer(nodeId, connection) {
+    if (held.has(connection))
+        return;
+    const connectionId = randomUUID();
+    const refresh = setInterval(() => {
+        void refreshViewer(connectionId).catch(() => { });
+    }, VIEWER_ROW_REFRESH_MS);
+    refresh.unref();
+    const insert = (async () => {
+        const now = at();
+        await (await openDb()).prepare(`INSERT INTO viewer_attachments (connection_id, node_id, api_process_id, attends, presented_at, opened_at, expires_at)
+      VALUES (?, ?, ?, 1, NULL, ?, ?)`).run(connectionId, nodeId, API_PROCESS_ID, now, at(VIEWER_ROW_TTL_MS));
+    })();
+    held.set(connection, { connectionId, refresh, inserted: insert.then(() => true, () => false) });
+    try {
+        await insert;
+    }
+    catch (error) {
+        if (held.get(connection)?.connectionId === connectionId)
+            release(connection);
+        throw error;
+    }
+}
+async function refreshViewer(connectionId) {
+    await (await openDb()).prepare('UPDATE viewer_attachments SET expires_at = ? WHERE connection_id = ?').run(at(VIEWER_ROW_TTL_MS), connectionId);
+}
+/** Mark an attending connection as shown the conversation. Returns true the first time only. */
+export async function presentViewer(_nodeId, connection) {
+    const own = held.get(connection);
+    if (own === undefined || !await own.inserted)
+        return false;
+    const result = await (await openDb()).prepare('UPDATE viewer_attachments SET presented_at = ? WHERE connection_id = ? AND presented_at IS NULL')
+        .run(at(), own.connectionId);
+    return result.changes === 1;
+}
+/** A clean viewer close: delete the row. */
+export async function detachViewer(_nodeId, connection) {
+    const own = release(connection);
+    if (own === undefined || !await own.inserted)
+        return;
+    await (await openDb()).prepare('DELETE FROM viewer_attachments WHERE connection_id = ?').run(own.connectionId);
+}
+/** The broker connection ended under an open viewer: stop refreshing and keep the row 60 s for the viewer's redial. */
+export async function holdViewerForRedial(_nodeId, connection) {
+    const own = release(connection);
+    if (own === undefined || !await own.inserted)
+        return;
+    await (await openDb()).prepare('UPDATE viewer_attachments SET expires_at = ? WHERE connection_id = ?').run(at(VIEWER_REDIAL_HOLD_MS), own.connectionId);
+}
+function release(connection) {
+    const own = held.get(connection);
+    if (own === undefined)
+        return undefined;
+    clearInterval(own.refresh);
+    held.delete(connection);
+    return own;
+}

package/dist/daemon/broker-signals/bus.d.ts

@@ -10,9 +10,10 @@ export declare function cachedBrokerNodeFields(node: BrokerExtensionNodeDTO): Br
 /** What a `crtr_signal` notification names. `mail` and `node` carry a node id; the others name the row that changed
  *  (D39): a grant id, run or node id, structured request, queue, limit, or environment object. `fault_retry` carries a node id: the
  *  fault-retry backstop publishes it in the commit that claims the nudge, and the API process holding that node's stream turns it
- *  into a `fault-retry` line. The writers fire them (the
+ *  into a `fault-retry` line. `machine` carries a machine environment object id (a call is pending for the API process holding its link);
+ *  `machine_call` carries a call id (the caller waiting on it re-reads the row). The writers fire them (the
  *  schema's triggers, or the unit that owns the writer); the bus only delivers. */
-export declare const BROKER_SIGNAL_KINDS: readonly ["mail", "node", "grant", "run_event", "report", "structured_request", "queue", "spend_limits", "environment_image", "fault_retry", "settings"];
+export declare const BROKER_SIGNAL_KINDS: readonly ["mail", "node", "grant", "run_event", "report", "structured_request", "queue", "spend_limits", "environment_image", "fault_retry", "settings", "machine", "machine_call"];
 export type BrokerSignalKind = (typeof BROKER_SIGNAL_KINDS)[number];
 export type BrokerSignalSubscriber = (id: string, kind: BrokerSignalKind) => void;
 export interface BrokerSignalSubscription {

package/dist/daemon/broker-signals/bus.js

@@ -22,9 +22,10 @@ export function cachedBrokerNodeFields(node) {
 /** What a `crtr_signal` notification names. `mail` and `node` carry a node id; the others name the row that changed
  *  (D39): a grant id, run or node id, structured request, queue, limit, or environment object. `fault_retry` carries a node id: the
  *  fault-retry backstop publishes it in the commit that claims the nudge, and the API process holding that node's stream turns it
- *  into a `fault-retry` line. The writers fire them (the
+ *  into a `fault-retry` line. `machine` carries a machine environment object id (a call is pending for the API process holding its link);
+ *  `machine_call` carries a call id (the caller waiting on it re-reads the row). The writers fire them (the
  *  schema's triggers, or the unit that owns the writer); the bus only delivers. */
-export const BROKER_SIGNAL_KINDS = ['mail', 'node', 'grant', 'run_event', 'report', 'structured_request', 'queue', 'spend_limits', 'environment_image', 'fault_retry', 'settings'];
+export const BROKER_SIGNAL_KINDS = ['mail', 'node', 'grant', 'run_event', 'report', 'structured_request', 'queue', 'spend_limits', 'environment_image', 'fault_retry', 'settings', 'machine', 'machine_call'];
 const KNOWN_KINDS = new Set(BROKER_SIGNAL_KINDS);
 /** Hints, not delivery state: a rolled-back write may mark an id. The consumer always re-reads durable state. Pending
  * marks are bounded by distinct (kind, id) pairs and delivered once per flush. */

package/dist/daemon/companion-retire.d.ts

@@ -0,0 +1,4 @@
+/** Retire a companion only through the terminal transition legal for its current status.
+ *  A review companion may have forks working single comments beside it; they hold
+ *  the same review binding and go terminal with the review that owns them. */
+export declare function retireCompanion(nodeId: string, outcome: 'approved' | 'canceled'): Promise<'retired' | 'already' | 'missing'>;

package/dist/daemon/companion-retire.js

@@ -0,0 +1,44 @@
+// Companion retirement — the one lifecycle exit shared by human-review and
+// page-feedback companions. Lives outside review/finish.ts so human/finish.ts
+// can retire a feedback companion without importing the review finisher (which
+// itself imports human/finish.ts).
+import { childrenOf, getNode } from '../core/canvas/canvas.js';
+import { FinalizationError, pushFinal } from '../core/feed/feed.js';
+import { transition } from '../core/runtime/lifecycle.js';
+import { requestBrokerTeardown } from '../core/runtime/host.js';
+/** Retire a companion only through the terminal transition legal for its current status.
+ *  A review companion may have forks working single comments beside it; they hold
+ *  the same review binding and go terminal with the review that owns them. */
+export async function retireCompanion(nodeId, outcome) {
+    const node = await getNode(nodeId);
+    if (node === null)
+        return 'missing';
+    const reviewId = node.review_binding?.review_id;
+    if (reviewId !== undefined) {
+        for (const childId of await childrenOf(nodeId)) {
+            if ((await getNode(childId))?.review_binding?.review_id !== reviewId)
+                continue;
+            await retireCompanion(childId, outcome);
+        }
+    }
+    if (node.status === 'canceled' || (outcome === 'canceled' && node.status === 'done'))
+        return 'already';
+    if (outcome === 'approved' && (node.status === 'active' || node.status === 'idle' || node.status === 'done')) {
+        let result = 'retired';
+        try {
+            await pushFinal(nodeId, 'The companion conversation is complete.');
+        }
+        catch (error) {
+            if (!(error instanceof FinalizationError) || error.code !== 'already_finalized')
+                throw error;
+            result = 'already';
+        }
+        void requestBrokerTeardown(nodeId);
+        return result;
+    }
+    await transition(nodeId, 'cancel', { reason: 'retired' });
+    if (node.status === 'active' || node.status === 'idle') {
+        void requestBrokerTeardown(nodeId);
+    }
+    return 'retired';
+}

package/dist/daemon/control.d.ts

@@ -0,0 +1,40 @@
+import type { DaemonAdmitDTO, StartupPhaseDTO } from '../api/dto/health.js';
+/** What crtrd exposes to handlers that act on the daemon process itself. */
+export interface DaemonControl {
+    /** This daemon's epoch id. */
+    epoch: string;
+    /** Schedule the handover: this daemon answers now, then after a bounded
+     *  grace tears its fleet down, releases its claim, spawns a successor on the
+     *  currently selected runtime generation, and exits.
+     *
+     *  Returns the grace it will wait. Idempotent — a second request while one is
+     *  already scheduled returns the same grace and schedules nothing new, so an
+     *  agent that retries cannot stack handovers. */
+    requestHandover(): {
+        graceMs: number;
+    };
+    /** Register daemon-owned post-response work for shutdown draining. */
+    registerDetached(work: Promise<void>): void;
+    /** Null only after normal startup completed. */
+    startupBlock(): {
+        phase: Exclude<StartupPhaseDTO, 'ready'>;
+        message: string;
+        blockerPaths: readonly string[];
+    } | null;
+    /** Admit normal work after the daemon has prepared its storage. */
+    admitStartup(): Promise<DaemonAdmitDTO>;
+    /** Plan or run the canvas import and resume normal startup when it completes. */
+    repairMigrations(req: {
+        dryRun: boolean;
+    }): Promise<{
+        result: import('../migrations/activation.js').CanvasImportResult;
+        resumed: boolean;
+        resumeError?: string;
+    }>;
+}
+/** Bind this process's control surface. Called once, by `runDaemon`. */
+export declare function bindDaemonControl(control: DaemonControl): void;
+/** Release the binding (cleanup, and test isolation). */
+export declare function clearDaemonControl(): void;
+/** The bound control surface, or null when this process is not a live daemon. */
+export declare function boundDaemonControl(): DaemonControl | null;

package/dist/daemon/control.js

@@ -0,0 +1,22 @@
+// The daemon's self-control seam — how an API handler reaches the ONE live
+// `runDaemon` closure that owns this process's epoch, fleet, and claim.
+//
+// Handlers are module-level route tables built before (and independently of)
+// `runDaemon`, so they cannot close over its internals. `bindDaemonControl` is
+// the same pattern `bindFleet` uses for the fleet registry: crtrd binds exactly
+// one control surface at startup, and a handler calls it through
+// `boundDaemonControl()`. Unbound (a test harness, or an API server hosted
+// outside crtrd) reads as null so the handler answers 503 rather than throwing.
+let bound = null;
+/** Bind this process's control surface. Called once, by `runDaemon`. */
+export function bindDaemonControl(control) {
+    bound = control;
+}
+/** Release the binding (cleanup, and test isolation). */
+export function clearDaemonControl() {
+    bound = null;
+}
+/** The bound control surface, or null when this process is not a live daemon. */
+export function boundDaemonControl() {
+    return bound;
+}

package/dist/daemon/cron/authority.d.ts

@@ -0,0 +1,38 @@
+import { ApiError } from '../../api/index.js';
+import type { Cron } from '../../core/canvas/crons.js';
+import { type ProspectiveLaunch } from '../../core/model-auth/readiness.js';
+export interface CronPrincipal {
+    grantee: string;
+    sub: string;
+    grant_id: string | null;
+    /** Null = the grant's whole current set (person-armed terminal crons and exec executions; the grant is the ceiling). */
+    scopes: readonly string[] | null;
+    /** An exec execution, or a cron armed from one: a node birth first checks model sign-in. Absent on births saved before it existed. */
+    from_exec?: boolean;
+}
+export type CronRefusalReason = 'unsandboxed_machine' | 'grant_missing' | 'grant_revoked' | 'scope_narrowed' | 'scope_missing' | 'limit_reached' | 'model_sign_in_required';
+export type CronAuthority = 
+/** `effectiveScopes` is the grant's current resolved set. A stored scope list is a second ceiling the caller still applies (as `router.ts` does for a broker). */
+{
+    allowed: true;
+    effectiveScopes: readonly string[];
+} | {
+    allowed: false;
+    reason: CronRefusalReason;
+    message: string;
+    url?: string;
+};
+/** The directory page where the person signs in to an AI subscription for this runtime; null without an issuer. */
+export declare function modelSignInUrl(): string | null;
+/** The API refusal for a refused birth or arm. */
+export declare function cronRefusalError(refusal: Extract<CronAuthority, {
+    allowed: false;
+}>): ApiError;
+/** May this principal fire now? The grant row must exist, be active and unexpired for this
+ *  grantee and sub; every stored scope must still be covered by it; `crtr:schedule` must be
+ *  in the effective set. A null `grant_id` is `grant_missing`. */
+export declare function checkCronFire(p: CronPrincipal): Promise<CronAuthority>;
+/** May this principal start a node? The fire check plus `crtr:act`; for an exec principal (or a cron armed from an exec)
+ *  also model sign-in for the provider `launch` would use (a root launch of the default kind when omitted). */
+export declare function checkCronBirth(p: CronPrincipal, launch?: ProspectiveLaunch): Promise<CronAuthority>;
+export declare function cronPrincipalOf(c: Cron): CronPrincipal;

package/dist/daemon/cron/authority.js

@@ -0,0 +1,90 @@
+// src/daemon/cron/authority.ts — the cron authority check: the one function that
+// answers "may this principal act now, and with what scope set" for an app cron.
+//
+// A cron is the app acting for a user under that user's grant. Its authority is
+// the grant — app (`grantee`), user (`sub`) and the scopes it was bounded to —
+// read from the synced grants mirror at every fire, call and birth. The creator
+// node is provenance only and is never consulted. The check takes a PRINCIPAL,
+// never a cron row, so the action lane can check a principal whose row was consumed.
+import { covers } from '@north-light/identity';
+import { ApiError } from '../../api/index.js';
+import { directoryIssuer } from '../../core/directory/issuer.js';
+import { activeRecord, grantRecord } from '../../core/grants/mirror.js';
+import { modelAuthReadiness } from '../../core/model-auth/readiness.js';
+import { isUnsandboxedMachine } from '../../core/runtime/unsandboxed.js';
+import { isOwnMemoryScope, scopeAllowed } from '../../core/scopes.js';
+function refuse(reason, message, url) {
+    return { allowed: false, reason, message, ...(url === undefined ? {} : { url }) };
+}
+/** The directory page where the person signs in to an AI subscription for this runtime; null without an issuer. */
+export function modelSignInUrl() {
+    const issuer = directoryIssuer();
+    return issuer === null ? null : `${issuer}/account/ai-subscription`;
+}
+/** The API refusal for a refused birth or arm. */
+export function cronRefusalError(refusal) {
+    if (refusal.reason === 'model_sign_in_required') {
+        return new ApiError(409, 'model_sign_in_required', refusal.message, refusal.url === undefined ? undefined : { url: refusal.url });
+    }
+    if (refusal.reason === 'scope_missing')
+        return new ApiError(403, 'scope_missing', refusal.message);
+    return new ApiError(401, 'grant_revoked', refusal.message);
+}
+/** May this principal fire now? The grant row must exist, be active and unexpired for this
+ *  grantee and sub; every stored scope must still be covered by it; `crtr:schedule` must be
+ *  in the effective set. A null `grant_id` is `grant_missing`. */
+export async function checkCronFire(p) {
+    // An unsandboxed machine runs only terminal crons, whatever an old grant mirror still holds.
+    if (p.grantee !== 'app:terminal' && isUnsandboxedMachine()) {
+        return refuse('unsandboxed_machine', `This computer runs only your own terminal agents; ${p.grantee} runs on your hosted machine.`);
+    }
+    let resolved;
+    if (p.grant_id === null) {
+        return refuse('grant_missing', `cron has no grant for ${p.grantee}; re-arm it from a node of that app`);
+    }
+    else {
+        const row = await grantRecord(p.grant_id);
+        if (row === null)
+            return refuse('grant_missing', `grant ${p.grant_id} is not in this runtime's grant mirror`);
+        if (row.status !== 'active')
+            return refuse('grant_revoked', `grant ${p.grant_id} is ${row.status}`);
+        if (row.expires_at !== null && Date.parse(row.expires_at) <= Date.now())
+            return refuse('grant_revoked', `grant ${p.grant_id} expired at ${row.expires_at}`);
+        if (row.grantee !== p.grantee || row.sub !== p.sub)
+            return refuse('grant_revoked', `grant ${p.grant_id} no longer belongs to ${p.grantee} for ${p.sub}`);
+        const active = activeRecord(row);
+        if (active === null)
+            return refuse('grant_revoked', `grant ${p.grant_id} cannot be read`);
+        resolved = active.resolved;
+    }
+    if (p.scopes !== null) {
+        const lost = p.scopes.find((scope) => !isOwnMemoryScope(scope, p.grantee) && !resolved.some((held) => covers(held, scope)));
+        if (lost !== undefined)
+            return refuse('scope_narrowed', `scope ${lost} is no longer covered by the grant`);
+    }
+    if (!scopeAllowed(resolved, 'crtr:schedule') || !scopeAllowed(p.scopes, 'crtr:schedule')) {
+        return refuse('scope_missing', 'the cron no longer holds crtr:schedule');
+    }
+    return { allowed: true, effectiveScopes: resolved };
+}
+/** May this principal start a node? The fire check plus `crtr:act`; for an exec principal (or a cron armed from an exec)
+ *  also model sign-in for the provider `launch` would use (a root launch of the default kind when omitted). */
+export async function checkCronBirth(p, launch = {}) {
+    const fire = await checkCronFire(p);
+    if (!fire.allowed)
+        return fire;
+    if (!scopeAllowed(fire.effectiveScopes, 'crtr:act') || !scopeAllowed(p.scopes, 'crtr:act')) {
+        return refuse('scope_missing', 'the cron no longer holds crtr:act');
+    }
+    if (p.from_exec === true) {
+        const readiness = await modelAuthReadiness(launch);
+        if (readiness.credential !== 'ready') {
+            const url = modelSignInUrl() ?? undefined;
+            return refuse('model_sign_in_required', `Starting an agent needs a signed-in AI subscription for ${readiness.provider}; sign in${url === undefined ? ' on your Northlight account' : ` at ${url}`}, then try again.`, url);
+        }
+    }
+    return fire;
+}
+export function cronPrincipalOf(c) {
+    return { grantee: c.grantee, sub: c.sub, grant_id: c.grant_id, scopes: c.scopes, from_exec: c.armed_from_exec };
+}

package/dist/daemon/cron/live-runs.d.ts

@@ -0,0 +1,54 @@
+import type { CronRefusalReason } from './authority.js';
+export declare const cronDaemonInstanceId: `${string}-${string}-${string}-${string}-${string}`;
+export declare const CRON_OWNER_HEARTBEAT_TTL_MS = 15000;
+/** Call before naming this process the owner of a cron run lease. Keeps the heartbeat alive from then on; the heartbeat stops
+ *  itself if a beat fails, and the next call restarts it. */
+export declare function ensureCronOwnerLease(): Promise<void>;
+/** Whether `owner` (another process's instance id) has a live heartbeat. */
+export declare function cronOwnerAlive(owner: string): Promise<boolean>;
+export interface LiveRun {
+    runId: string;
+    replaced: boolean;
+    selfCanceled: boolean;
+    kill(): void;
+}
+export declare function liveRunFor(cronId: string): LiveRun | undefined;
+export declare function registerLiveRun(cronId: string, run: LiveRun): void;
+export declare function clearLiveRun(cronId: string, runId: string): void;
+export declare function markSelfCanceledCronRun(cronId: string, runId: string): boolean;
+/** `cron`: one fire of a cron row (`cronId` names it). `exec`: one `POST /v1/exec` call, with no cron row. */
+export type CronExecutionKind = {
+    kind: 'cron';
+    cronId: string;
+} | {
+    kind: 'exec';
+    cronId: null;
+};
+/** One cron execution's identity while it runs: the stored cron principal keyed by execution id.
+ *  Its socket answers as this principal; the grant sweep and the router read it. A principal is
+ *  never read off the cron row after the fire, so two executions of one run keep separate scopes. */
+export type CronExecution = CronExecutionKind & {
+    executionId: string;
+    /** An exec, or a fire of a cron armed from one: every node it starts checks model sign-in first. */
+    fromExec: boolean;
+    grantee: string;
+    sub: string;
+    grantId: string | null;
+    scopes: string[] | null;
+    originRunId: string | null;
+    isolated: boolean;
+    anchor: string | null;
+    /** The app's OS uid: the only peer the execution socket serves on Linux. */
+    uid: number;
+    /** Rebuilt from a row and a live sandbox after a daemon restart: no executor promise owns its close. */
+    rebuilt: boolean;
+    /** Set by the grant sweep when it stopped this execution; the executor settles the run `refused` with it. */
+    refusal: {
+        reason: CronRefusalReason;
+        message: string;
+    } | null;
+};
+export declare function registerCronExecution(execution: CronExecution): void;
+export declare function cronExecutionFor(executionId: string): CronExecution | undefined;
+export declare function dropCronExecution(executionId: string): void;
+export declare function cronExecutions(): CronExecution[];

package/dist/daemon/cron/live-runs.js

@@ -0,0 +1,66 @@
+import { randomUUID } from 'node:crypto';
+import { claimReconcilerLease, renewReconcilerLease } from '../../core/canvas/reconciler-leases.js';
+import { openDb } from '../../core/canvas/db.js';
+export const cronDaemonInstanceId = randomUUID();
+/** A process that owns cron run leases keeps this heartbeat: a `reconciler_leases` row keyed by its instance id. Another process
+ *  recovers a run it does not own only once that owner's heartbeat has lapsed, so a live peer still building a run's context
+ *  (no pid recorded yet) is never taken for a crashed one. */
+const CRON_OWNER_LANE = 'cron-owner';
+export const CRON_OWNER_HEARTBEAT_TTL_MS = 15_000;
+const CRON_OWNER_HEARTBEAT_EVERY_MS = 5_000;
+let heartbeat;
+let lastBeatAt = 0;
+async function beat() {
+    if (await renewReconcilerLease(CRON_OWNER_LANE, cronDaemonInstanceId, cronDaemonInstanceId, CRON_OWNER_HEARTBEAT_TTL_MS)) {
+        lastBeatAt = Date.now();
+        return;
+    }
+    // Absent (first beat) or lapsed (this process stalled): take it again under the same owner.
+    await claimReconcilerLease(CRON_OWNER_LANE, cronDaemonInstanceId, cronDaemonInstanceId, CRON_OWNER_HEARTBEAT_TTL_MS);
+    lastBeatAt = Date.now();
+}
+/** Call before naming this process the owner of a cron run lease. Keeps the heartbeat alive from then on; the heartbeat stops
+ *  itself if a beat fails, and the next call restarts it. */
+export async function ensureCronOwnerLease() {
+    if (heartbeat !== undefined && Date.now() - lastBeatAt < CRON_OWNER_HEARTBEAT_EVERY_MS)
+        return;
+    await beat();
+    if (heartbeat !== undefined)
+        return;
+    heartbeat = setInterval(() => {
+        beat().catch(() => { clearInterval(heartbeat); heartbeat = undefined; });
+    }, CRON_OWNER_HEARTBEAT_EVERY_MS);
+    heartbeat.unref();
+}
+/** Whether `owner` (another process's instance id) has a live heartbeat. */
+export async function cronOwnerAlive(owner) {
+    const row = await (await openDb()).prepare('SELECT 1 AS alive FROM reconciler_leases WHERE lane = ? AND key = ? AND expires_at > ?')
+        .get(CRON_OWNER_LANE, owner, new Date().toISOString());
+    return row !== undefined;
+}
+const liveRuns = new Map();
+export function liveRunFor(cronId) {
+    return liveRuns.get(cronId);
+}
+export function registerLiveRun(cronId, run) {
+    liveRuns.set(cronId, run);
+}
+// An earlier close handler must not evict a later run.
+export function clearLiveRun(cronId, runId) {
+    const live = liveRuns.get(cronId);
+    if (live !== undefined && live.runId === runId)
+        liveRuns.delete(cronId);
+}
+// Only that exact process may finish after its row is removed.
+export function markSelfCanceledCronRun(cronId, runId) {
+    const live = liveRuns.get(cronId);
+    if (live === undefined || live.runId !== runId)
+        return false;
+    live.selfCanceled = true;
+    return true;
+}
+const executions = new Map();
+export function registerCronExecution(execution) { executions.set(execution.executionId, execution); }
+export function cronExecutionFor(executionId) { return executions.get(executionId); }
+export function dropCronExecution(executionId) { executions.delete(executionId); }
+export function cronExecutions() { return [...executions.values()]; }

package/dist/daemon/cron/run-socket.d.ts

@@ -0,0 +1,30 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import type { CronPrincipalClass } from '../api/router.js';
+import { type CronExecution } from './live-runs.js';
+/** Installed by the API server: runs one request through the router as `principal`. */
+export type CronRequestHandler = (req: IncomingMessage, res: ServerResponse, principal: CronPrincipalClass) => void;
+export declare function setCronRequestHandler(handler: CronRequestHandler | null): void;
+type PeerUid = (req: IncomingMessage) => number | null;
+/** Test seam: the peer uid of a request (null = unchecked). */
+export declare function __setCronPeerUidForTest(fn: PeerUid | undefined): void;
+export declare function cronSocketPath(executionId: string): string;
+export declare function cronPrincipalClassOf(e: CronExecution): CronPrincipalClass;
+/** Register the execution and open its socket. The folder is created daemon-owned, group daemon, mode 0770 — the state
+ *  the root launcher's `SourceValidator.pin` accepts and re-owns to the app uid for a launch whose node id is
+ *  `cron-<execution_id>` (`launcher/validate.ts`); `cron-launch.json` carries the config snapshot a sandboxed
+ *  `crtr` installs (the shape of `broker-launch.json`'s). */
+export declare function openCronExecution(execution: CronExecution, cwd: string, profileId: string | null): Promise<void>;
+/** Close the listener, delete the execution folder, drop the registry entry. Idempotent. */
+export declare function closeCronExecution(executionId: string): void;
+/** Resolves once a restart rebuild finished; the grant sweep waits on it so it never stops a live execution it has not yet re-registered. */
+export declare function cronExecutionsReady(): Promise<void>;
+/** After a daemon restart the listener died with the daemon but the folder and the sandbox survived. Rebuild the registry from
+ *  `running` rows whose recorded execution id still has a live `cron-<id>` sandbox and re-listen on the same path; delete
+ *  `nodes/cron-*` folders with no live sandbox. A self-canceled execution (row deleted) cannot be rebuilt: it stays without
+ *  an API path and the grant sweep stops it. */
+export declare function rebuildCronExecutions(list?: () => Promise<Array<{
+    nodeId: string;
+}>>): Promise<void>;
+/** Close rebuilt executions whose row no longer records them (their lease settled elsewhere). Own executions close in the executor. */
+export declare function reapRebuiltCronExecutions(): Promise<void>;
+export {};