@north-light/api 0.3.580 → 0.3.587

package/dist/daemon/reconcilers/ledger-sandbox.d.ts

@@ -0,0 +1,54 @@
+import type { DetachedWorkLifecycle } from './broker-supervision.js';
+import { type LanePass } from './throttled-lane.js';
+export declare const LEDGER_SANDBOX_INTERVAL_MS = 60000;
+/** Executions billed per pass; the rest wait for the next pass. */
+export declare const LEDGER_SANDBOX_BUDGET = 200;
+interface Rates {
+    usdPerGbHour: number | null;
+    standbyMs: number;
+}
+export declare function sandboxRates(): Rates;
+/** The `[from, to]` chunks to bill: every whole hour, plus the remainder when the period is closed. The hours stay aligned to `from`
+ *  whatever the month; an hour or remainder that crosses a UTC month boundary is cut there into one chunk per month. */
+export declare function chunksOf(from: number, end: number, closed: boolean): Array<[number, number]>;
+/** When a chunk's seconds accrued, for the row's `at` (and so its month): its last millisecond, so a chunk ending at exactly 00:00Z
+ *  of a month belongs to the month before it. */
+export declare const chunkAccruedAt: (chunkEnd: number) => Date;
+/** The row id of the billed chunk of an execution that starts at `chunkStart`: the start time in whole seconds makes it
+ *  the same in every process and unique across the awake periods of one execution. */
+export declare const sandboxChargeId: (executionId: string, chunkStart: number) => string;
+/** An awake period that a wake ended: whose it was, where it began, when the broker went idle and how far it had been billed. */
+interface EndedPeriod {
+    execution_id: string;
+    awake_since: string;
+    idle_at: string;
+    charged_through: string | null;
+}
+export interface LedgerSandboxResult {
+    executions: number;
+    rows: number;
+    failed: number;
+}
+export declare class LedgerSandboxReconciler {
+    run(now: number, ctx: {
+        lifecycle: DetachedWorkLifecycle;
+    }): void;
+    /** One pass over the executions with awake time not yet billed. Exposed for tests. */
+    pass(now: number, lane?: LanePass): Promise<LedgerSandboxResult>;
+    /** Bills one execution; returns the rows it wrote. Payer and memory are read first; the rows and `charged_through` go in one
+     *  transaction that holds the execution row's lock, from which the period is recomputed. `settle` is the wake of a resident
+     *  broker: an idle period is closed at `min(now, idle_at + standby tail)` and billed whole, because the wake resets `awake_since`;
+     *  a period that is not idle is left to the lane. `ended` is a period a wake ended before its settle succeeded: it is billed from
+     *  the period saved with it, whatever the execution row says now, and its row is deleted in the same transaction. */
+    bill(executionId: string, now: number, usdPerGbHour: number, standbyMs: number, settle?: boolean, ended?: EndedPeriod): Promise<number>;
+}
+/** Whether any awake time that accrued in `month` (UTC) is not billed yet: an execution's current period, or an ended period a failed
+ *  settle saved, whose unbilled span `[max(awake_since, charged_through), end]` overlaps the month. `ledger-r2` moves no month while
+ *  this is true, because the month's allowance is summed from the live `charges` rows and a row written after the move would get it
+ *  again. With no sandbox rate the lane writes nothing, so nothing is unbilled. */
+export declare function sandboxUnbilledIn(month: string, now: number): Promise<boolean>;
+/** Before a wake resets `awake_since` (`recordExecutionAwake`): bills the idle period that is ending, which the lane would
+ *  otherwise lose. Never throws: a settle that fails must not block the wake, and the failure is logged. Settling the same
+ *  period twice charges once (`charged_through` and the deterministic row ids). */
+export declare function settleSandboxBeforeWake(executionId: string, now?: number): Promise<void>;
+export {};

package/dist/daemon/reconcilers/ledger-sandbox.js

@@ -0,0 +1,249 @@
+// The `ledger-sandbox` lane (design-fleet, Money: "Sandbox rows"): bills the awake time of each Blaxel execution.
+//
+// An awake period runs from `awake_since` to `now` while the broker is busy, to `idle_at + standby tail` once it is idle, and to
+// `exited_at + standby tail` once it exited. A wake of a resident broker resets `awake_since` and clears `idle_at`, so the frozen
+// time between two periods is never billed. `charged_through` is how far billing has reached.
+//
+// Each pass bills, per execution, one `sandbox:<execution id>:<chunk start, epoch seconds>` row for every whole hour past `charged_through`, and a final
+// row for the remainder once the period has ended. Rows and the new `charged_through` are written in one transaction holding
+// the execution row's lock, with `ON CONFLICT DO NOTHING` on the deterministic id, so a second lane process, a rerun after a
+// crash, or a pass that overlaps another bills nothing twice.
+import { openDb, withCanvasWrite } from '../../core/canvas/db.js';
+import { getNode } from '../../core/canvas/canvas.js';
+import { LEDGER_ENV, sandboxStandbyS, sandboxUsdPerGbHour, warnRateUnset } from '../../core/ledger/rates.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { operationIdContext } from '../../core/events/operation-id.js';
+import { billingAccountOf } from '../../core/ledger/account.js';
+import { writeInfraCharge } from '../../core/ledger/infra-allowance.js';
+import { resetAt } from '../../core/ledger/months.js';
+import { startCandidateOf } from '../../core/runtime/start-check.js';
+import { runThrottledLane } from './throttled-lane.js';
+export const LEDGER_SANDBOX_INTERVAL_MS = 60_000;
+const PASS_LEASE_MS = 5 * 60_000;
+const HOUR_MS = 3_600_000;
+/** Executions billed per pass; the rest wait for the next pass. */
+export const LEDGER_SANDBOX_BUDGET = 200;
+export function sandboxRates() {
+    return { usdPerGbHour: sandboxUsdPerGbHour(), standbyMs: sandboxStandbyS() * 1000 };
+}
+/** Where the current awake period ends, and whether it has ended. */
+function periodEnd(row, now, standbyMs) {
+    const closedAt = row.exited_at ?? row.idle_at;
+    if (closedAt === null)
+        return { end: now, closed: false };
+    const end = Date.parse(closedAt) + standbyMs;
+    return end <= now ? { end, closed: true } : { end: now, closed: false };
+}
+/** 00:00Z on the first day of the UTC month after the one containing `at`. */
+const monthEndAfter = (at) => { const d = new Date(at); return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1); };
+/** `[from, to]` cut at every UTC month boundary, so each piece lies in one month. */
+function withinMonths(from, to) {
+    const pieces = [];
+    for (let at = from; at < to;) {
+        const next = Math.min(to, monthEndAfter(at));
+        pieces.push([at, next]);
+        at = next;
+    }
+    return pieces;
+}
+/** The `[from, to]` chunks to bill: every whole hour, plus the remainder when the period is closed. The hours stay aligned to `from`
+ *  whatever the month; an hour or remainder that crosses a UTC month boundary is cut there into one chunk per month. */
+export function chunksOf(from, end, closed) {
+    const chunks = [];
+    let at = from;
+    while (end - at >= HOUR_MS) {
+        chunks.push(...withinMonths(at, at + HOUR_MS));
+        at += HOUR_MS;
+    }
+    if (closed && end > at)
+        chunks.push(...withinMonths(at, end));
+    return chunks;
+}
+/** When a chunk's seconds accrued, for the row's `at` (and so its month): its last millisecond, so a chunk ending at exactly 00:00Z
+ *  of a month belongs to the month before it. */
+export const chunkAccruedAt = (chunkEnd) => new Date(chunkEnd - 1);
+/** The row id of the billed chunk of an execution that starts at `chunkStart`: the start time in whole seconds makes it
+ *  the same in every process and unique across the awake periods of one execution. */
+export const sandboxChargeId = (executionId, chunkStart) => `sandbox:${executionId}:${Math.floor(chunkStart / 1000)}`;
+/** The `reconciler_leases` lane whose rows (key = execution id and period start, cursor = the period) are idle periods a wake ended
+ *  before they were billed; the lane bills each once and deletes the row. One row per ended period, so a second failed settle before
+ *  the lane recovers keeps the first. The lease columns are unused: `expires_at` is the epoch, so nothing claims it. */
+const UNSETTLED_LANE = 'ledger-sandbox-unsettled';
+const unsettledKey = (executionId, awakeSince) => `${executionId}@${Date.parse(awakeSince)}`;
+export class LedgerSandboxReconciler {
+    run(now, ctx) {
+        if (!ctx.lifecycle.acceptsDetachedWork())
+            return;
+        const pass = operationIdContext.fresh(() => runThrottledLane('ledger-sandbox', '', now, LEDGER_SANDBOX_INTERVAL_MS, PASS_LEASE_MS, async (lane) => { await this.pass(now, lane); }))
+            .then(() => undefined)
+            .catch((error) => { operationIdContext.fresh(() => emitEvent({ level: 'error', event: 'ledger.sandbox.failed', error })); });
+        ctx.lifecycle.registerDetached(pass);
+    }
+    /** One pass over the executions with awake time not yet billed. Exposed for tests. */
+    async pass(now, lane) {
+        const result = { executions: 0, rows: 0, failed: 0 };
+        const { usdPerGbHour, standbyMs } = sandboxRates();
+        if (usdPerGbHour === null) {
+            warnRateUnset('ledger-sandbox', LEDGER_ENV.sandboxUsdPerGbHour);
+            return result;
+        }
+        const db = await openDb();
+        const due = await db.prepare(`SELECT execution_id, node_id, awake_since, idle_at, exited_at, charged_through FROM executions
+      WHERE runner = 'blaxel' AND awake_since IS NOT NULL
+        AND (state <> 'exited' OR charged_through IS NULL OR charged_through::timestamptz < exited_at::timestamptz + make_interval(secs => ?::float8 / 1000))
+      ORDER BY execution_id LIMIT ?`).all(standbyMs, LEDGER_SANDBOX_BUDGET);
+        for (const row of due) {
+            if (lane && !await lane.holds())
+                break;
+            try {
+                const rows = await this.bill(row.execution_id, now, usdPerGbHour, standbyMs);
+                if (rows > 0)
+                    result.executions += 1;
+                result.rows += rows;
+            }
+            catch (error) {
+                result.failed += 1;
+                emitEvent({ level: 'warn', event: 'ledger.sandbox.execution_failed', error, fields: { execution_id: row.execution_id } });
+            }
+        }
+        const unsettled = await db.prepare('SELECT cursor FROM reconciler_leases WHERE lane = ? ORDER BY key LIMIT ?').all(UNSETTLED_LANE, LEDGER_SANDBOX_BUDGET);
+        for (const { cursor } of unsettled) {
+            const period = JSON.parse(cursor);
+            if (lane && !await lane.holds())
+                break;
+            try {
+                const rows = await this.bill(period.execution_id, now, usdPerGbHour, standbyMs, false, period);
+                if (rows > 0)
+                    result.executions += 1;
+                result.rows += rows;
+            }
+            catch (error) {
+                result.failed += 1;
+                emitEvent({ level: 'warn', event: 'ledger.sandbox.execution_failed', error, fields: { execution_id: period.execution_id } });
+            }
+        }
+        if (result.rows > 0 || result.failed > 0)
+            emitEvent({ level: 'info', event: 'ledger.sandbox.settled', outcome: 'succeeded', fields: { ...result } });
+        return result;
+    }
+    /** Bills one execution; returns the rows it wrote. Payer and memory are read first; the rows and `charged_through` go in one
+     *  transaction that holds the execution row's lock, from which the period is recomputed. `settle` is the wake of a resident
+     *  broker: an idle period is closed at `min(now, idle_at + standby tail)` and billed whole, because the wake resets `awake_since`;
+     *  a period that is not idle is left to the lane. `ended` is a period a wake ended before its settle succeeded: it is billed from
+     *  the period saved with it, whatever the execution row says now, and its row is deleted in the same transaction. */
+    async bill(executionId, now, usdPerGbHour, standbyMs, settle = false, ended) {
+        const db = await openDb();
+        const peek = await db.prepare('SELECT node_id FROM executions WHERE execution_id = ?').get(executionId);
+        if (peek === undefined)
+            return 0;
+        const meta = await getNode(peek.node_id);
+        if (meta === null)
+            throw new Error(`execution ${executionId} names node ${peek.node_id}, which has no row`);
+        const start = await startCandidateOf(meta);
+        if (start === null)
+            throw new Error(`node ${meta.node_id} has no person yet, so its sandbox hours have no payer`);
+        const memory = await db.prepare('SELECT e.memory_mb AS mb FROM profiles p JOIN environments e ON e.object = p.environment_id WHERE p.id = ?').get(meta.profile_id ?? null);
+        if (memory === undefined)
+            throw new Error(`node ${meta.node_id} has no environment, so its sandbox size is unknown`);
+        const memoryMb = Number(memory.mb);
+        const { account, billable } = await billingAccountOf(db, start.payer);
+        const runNode = meta.run_id ? await getNode(meta.run_id) : null;
+        const causedBy = runNode?.caused_by ?? meta.caused_by ?? null;
+        return await withCanvasWrite(async (tx) => {
+            const row = await tx.prepare(`SELECT execution_id, node_id, awake_since, idle_at, exited_at, charged_through FROM executions
+        WHERE execution_id = ? AND runner = 'blaxel' AND awake_since IS NOT NULL FOR UPDATE`).get(executionId);
+            if (ended === undefined && row === undefined)
+                return 0;
+            if (ended === undefined && settle && row.idle_at === null)
+                return 0;
+            let from;
+            let chunks;
+            if (ended !== undefined) {
+                from = Math.max(Date.parse(ended.awake_since), ended.charged_through === null ? 0 : Date.parse(ended.charged_through));
+                chunks = chunksOf(from, Date.parse(ended.idle_at) + standbyMs, true);
+            }
+            else {
+                const { end, closed } = settle ? { end: Math.min(now, Date.parse(row.idle_at) + standbyMs), closed: true } : periodEnd(row, now, standbyMs);
+                from = Math.max(Date.parse(row.awake_since), row.charged_through === null ? 0 : Date.parse(row.charged_through));
+                chunks = chunksOf(from, end, closed);
+            }
+            let written = 0;
+            for (const [chunkStart, chunkEnd] of chunks) {
+                const seconds = Math.round((chunkEnd - chunkStart) / 1000);
+                const gbHours = (memoryMb / 1024) * ((chunkEnd - chunkStart) / HOUR_MS);
+                const usd = gbHours * usdPerGbHour;
+                const result = await writeInfraCharge({ id: sandboxChargeId(executionId, chunkStart), at: chunkAccruedAt(chunkEnd), kind: 'sandbox', what: `${memoryMb} MB`,
+                    units: { gb_hours: gbHours, seconds, memory_mb: memoryMb }, usd, payer: start.payer, funding: 'bill', sub: start.sub, grantee: start.grantee,
+                    node: meta.node_id, run: meta.run_id ?? null, provider: 'blaxel', causedBy, account }, billable);
+                if (result.written)
+                    written += 1;
+            }
+            if (ended !== undefined) {
+                // The execution's own `charged_through` belongs to its current period; this period's row is done with.
+                await tx.prepare('DELETE FROM reconciler_leases WHERE lane = ? AND key = ?').run(UNSETTLED_LANE, unsettledKey(executionId, ended.awake_since));
+            }
+            else if (chunks.length > 0) {
+                await tx.prepare('UPDATE executions SET charged_through = ? WHERE execution_id = ?').run(new Date(chunks[chunks.length - 1][1]).toISOString(), executionId);
+            }
+            return written;
+        });
+    }
+}
+/** Whether any awake time that accrued in `month` (UTC) is not billed yet: an execution's current period, or an ended period a failed
+ *  settle saved, whose unbilled span `[max(awake_since, charged_through), end]` overlaps the month. `ledger-r2` moves no month while
+ *  this is true, because the month's allowance is summed from the live `charges` rows and a row written after the move would get it
+ *  again. With no sandbox rate the lane writes nothing, so nothing is unbilled. */
+export async function sandboxUnbilledIn(month, now) {
+    const { usdPerGbHour, standbyMs } = sandboxRates();
+    if (usdPerGbHour === null)
+        return false;
+    const db = await openDb();
+    const from = new Date(`${month}-01T00:00:00Z`).toISOString();
+    const to = resetAt(month);
+    const live = await db.prepare(`SELECT 1 AS found FROM executions e,
+      LATERAL (SELECT greatest(e.awake_since::timestamptz, COALESCE(e.charged_through::timestamptz, '-infinity'::timestamptz)) AS from_at,
+                      CASE WHEN COALESCE(e.exited_at, e.idle_at) IS NULL THEN ?::timestamptz
+                           ELSE least(COALESCE(e.exited_at, e.idle_at)::timestamptz + make_interval(secs => ?::float8 / 1000), ?::timestamptz) END AS end_at) p
+    WHERE e.runner = 'blaxel' AND e.awake_since IS NOT NULL AND p.from_at < p.end_at AND p.from_at < ?::timestamptz AND p.end_at > ?::timestamptz LIMIT 1`)
+        .get(new Date(now).toISOString(), standbyMs, new Date(now).toISOString(), to, from);
+    if (live !== undefined)
+        return true;
+    const saved = await db.prepare('SELECT cursor FROM reconciler_leases WHERE lane = ?').all(UNSETTLED_LANE);
+    return saved.some(({ cursor }) => {
+        const period = JSON.parse(cursor);
+        const start = Math.max(Date.parse(period.awake_since), period.charged_through === null ? 0 : Date.parse(period.charged_through));
+        const end = Date.parse(period.idle_at) + standbyMs;
+        return start < end && start < Date.parse(to) && end > Date.parse(from);
+    });
+}
+/** Before a wake resets `awake_since` (`recordExecutionAwake`): bills the idle period that is ending, which the lane would
+ *  otherwise lose. Never throws: a settle that fails must not block the wake, and the failure is logged. Settling the same
+ *  period twice charges once (`charged_through` and the deterministic row ids). */
+export async function settleSandboxBeforeWake(executionId, now = Date.now()) {
+    try {
+        const { usdPerGbHour, standbyMs } = sandboxRates();
+        if (usdPerGbHour === null)
+            return;
+        await new LedgerSandboxReconciler().bill(executionId, now, usdPerGbHour, standbyMs, true);
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'ledger.sandbox.settle_failed', error, fields: { execution_id: executionId } });
+        await keepUnsettled(executionId);
+    }
+}
+/** The wake that follows a failed settle resets the execution's period, so the idle period is saved as an `UNSETTLED_LANE` row for
+ *  the lane's next pass to bill (once: deterministic row ids, and the row is deleted in the billing transaction). Never throws. */
+async function keepUnsettled(executionId) {
+    try {
+        const db = await openDb();
+        const period = await db.prepare('SELECT execution_id, awake_since, idle_at, charged_through FROM executions WHERE execution_id = ? AND runner = \'blaxel\' AND awake_since IS NOT NULL AND idle_at IS NOT NULL')
+            .get(executionId);
+        if (period === undefined)
+            return;
+        await db.prepare('INSERT INTO reconciler_leases (lane, key, owner, expires_at, cursor) VALUES (?, ?, ?, ?, ?) ON CONFLICT (lane, key) DO NOTHING')
+            .run(UNSETTLED_LANE, unsettledKey(executionId, period.awake_since), 'settle', new Date(0).toISOString(), JSON.stringify(period));
+    }
+    catch (error) {
+        emitEvent({ level: 'error', event: 'ledger.sandbox.unsettled_lost', error, fields: { execution_id: executionId } });
+    }
+}

package/dist/daemon/reconcilers/live-obligation.d.ts

@@ -0,0 +1,77 @@
+import { type Lifecycle } from '../../core/canvas/index.js';
+import { type ViewerProbe } from '../../core/runtime/placement.js';
+import { type LifecycleEvent } from '../../core/runtime/lifecycle.js';
+import type { FleetRegistry } from '../../core/runtime/fleet.js';
+/** Durable work that requires a node to remain automatically wakeable. */
+export declare function hasLiveObligation(nodeId: string): Promise<boolean>;
+/** Whether anything would drive a turn if this node's engine came back right
+ *  now: durable work that must wake it, mail it has not seen, or a human
+ *  already looking at it. The negative is what makes re-launching a dead
+ *  node's engine pure cost — it would boot, load its context, sit at an idle
+ *  prompt, and wait out the park clock.
+ *
+ *  Deferred mail deliberately does not count: it rides the node's next natural
+ *  cycle rather than causing one. */
+export declare function hasPendingWake(nodeId: string): Promise<boolean>;
+/** The retention sweep's hold: a node with a launch claim, durable work that
+ *  must wake it, or a person looking at it is never pruned, whatever its age.
+ *  Unseen mail is deliberately not a hold: it never wakes a terminal node, and
+ *  children keep writing a finished manager's inbox, so it would retain most
+ *  finished history forever. The stale sweep checks unseen mail itself. */
+export declare function retentionHold(fleet: Pick<FleetRegistry, 'isClaimed'>): Promise<(nodeId: string) => Promise<boolean>>;
+/** Whether a person is looking at this node right now: a focused viewer pane,
+ *  or a broker client that declared itself attending. A client that hellos with
+ *  `attends: false` is a system observer and deliberately does not count, which
+ *  is how Northlight identifies itself — so an open product page is
+ *  invisible here, while crouter's own local and remote viewers are not. */
+export declare function hasHumanViewer(nodeId: string, viewer?: ViewerProbe): Promise<boolean>;
+/** What parking an unattended node actually amounts to — the one rule both the
+ *  live-broker park clock and the lifecycle tick apply.
+ *
+ *  `release` — something can still wake it, a person is watching it, or a
+ *              fatal provider fault prevents its engine from completing the
+ *              summary turn; parking is a pause.
+ *  `park`    — a resident with nothing left to wake it has completed its
+ *              conversation, and the row becomes prunable history. The live
+ *              clock asks it for a summary turn first; this verdict is what
+ *              that turn's settlement re-evaluates before enacting.
+ *  `cancel`  — a terminal node that never pushed a final was torn down before
+ *              finishing, which is what `canceled` records; it stays revivable
+ *              and becomes prunable. A live subscriber still awaiting its
+ *              report is an outstanding deliverable, so such a node keeps its
+ *              wakeable idle row instead of being written off.
+ *
+ *  Undelivered mail holds the row, with one carve-out: a deferred-only unseen
+ *  set does not hold a RESIDENT. Deferred mail never wakes a node on its own,
+ *  and parking a resident is reversible — a message sent to it revives it and
+ *  flushes the held mail on that cycle. A terminalized row takes no such
+ *  cycle, so unread mail of any tier keeps it from being written off: the
+ *  invariant is that content a sender already handed over is never dropped.
+ */
+export type ParkEvent = Extract<LifecycleEvent, 'release' | 'park' | 'cancel'>;
+export declare function parkEvent(nodeId: string, lifecycle: Lifecycle, viewer?: ViewerProbe): Promise<ParkEvent>;
+/** `parkEvent` plus whether a live subscriber awaiting the report is the ONLY thing holding a
+ *  terminal node's `release`: no viewer, no wake source, no unread mail, no fatal fault. Such a
+ *  node stopped unfinished with nothing that will wake it, and its subscriber knows nothing. */
+export declare function parkVerdict(nodeId: string, lifecycle: Lifecycle, viewer?: ViewerProbe): Promise<{
+    event: ParkEvent;
+    heldOnlyBySubscriber: boolean;
+}>;
+/** Apply an unattended decision and notify subscribers of automatic completion.
+ *  This is the DEGRADED enactment: no summary turn ran, so subscribers get the
+ *  doctrine notice instead of the node's own report. The live clock's good path
+ *  (broker settlement after a parking turn) enacts `park` directly and fans
+ *  nothing — the node's report is the notice.
+ *
+ *  The notice is DEFERRED: a node settling quietly at the end of its unattended
+ *  grace is not an event worth starting a manager's cycle for, so it rides the
+ *  manager's next natural cycle and arrives alongside whatever does.
+ *
+ *  Only `park` fans, and only a resident parks, so the notice speaks about a
+ *  resident throughout: its conversation ended without a final report, its state
+ *  lives in whatever report it did leave, and a message reopens it. */
+export declare function applyParkEvent(nodeId: string, event: ParkEvent): Promise<void>;
+/** Tell a terminal node's subscribers it went idle unfinished: it pushed no final, holds no wait
+ *  that will wake it, and only their subscription kept it from being canceled. The cause of the
+ *  stop is not known here, so the notice claims none. */
+export declare function noticeUnfinishedIdle(nodeId: string): Promise<void>;

package/dist/daemon/reconcilers/live-obligation.js

@@ -0,0 +1,114 @@
+import { getNode, hasActiveLiveSubscription, hasLiveSubscriber, hasPendingCronWake, } from '../../core/canvas/index.js';
+import { fullName } from '../../core/canvas/labels.js';
+import { hasLiveControllerWait, hasLiveObjectWait } from '../../core/canvas/waits.js';
+import { newestReportName } from '../../core/feed/reports.js';
+import { countTickets } from '../../core/canvas/attention.js';
+import { hasUnseenWakeMail } from '../../core/canvas/deliveries.js';
+import { readOutputRequest } from '../../core/runtime/output-result.js';
+import { focusOf } from '../../core/runtime/placement.js';
+import { hasAttachedBrokerViewers } from '../api/viewer-presence.js';
+import { publishNotice } from '../../core/runtime/close.js';
+import { readFault } from '../../core/canvas/recovery.js';
+import { transition } from '../../core/runtime/lifecycle.js';
+/** Durable work that requires a node to remain automatically wakeable. */
+export async function hasLiveObligation(nodeId) {
+    return await hasActiveLiveSubscription(nodeId)
+        || await hasLiveControllerWait(nodeId)
+        || await hasLiveObjectWait(nodeId)
+        || await hasPendingCronWake(nodeId)
+        || await countTickets(nodeId) > 0
+        || await readOutputRequest(nodeId) !== null;
+}
+/** Whether anything would drive a turn if this node's engine came back right
+ *  now: durable work that must wake it, mail it has not seen, or a human
+ *  already looking at it. The negative is what makes re-launching a dead
+ *  node's engine pure cost — it would boot, load its context, sit at an idle
+ *  prompt, and wait out the park clock.
+ *
+ *  Deferred mail deliberately does not count: it rides the node's next natural
+ *  cycle rather than causing one. */
+export async function hasPendingWake(nodeId) {
+    if (await hasLiveObligation(nodeId))
+        return true;
+    if (await hasUnseenWakeMail(nodeId))
+        return true;
+    return await hasHumanViewer(nodeId);
+}
+/** The retention sweep's hold: a node with a launch claim, durable work that
+ *  must wake it, or a person looking at it is never pruned, whatever its age.
+ *  Unseen mail is deliberately not a hold: it never wakes a terminal node, and
+ *  children keep writing a finished manager's inbox, so it would retain most
+ *  finished history forever. The stale sweep checks unseen mail itself. */
+export async function retentionHold(fleet) {
+    return async (nodeId) => await fleet.isClaimed(nodeId) || await hasLiveObligation(nodeId) || await hasHumanViewer(nodeId);
+}
+/** Whether a person is looking at this node right now: a focused viewer pane,
+ *  or a broker client that declared itself attending. A client that hellos with
+ *  `attends: false` is a system observer and deliberately does not count, which
+ *  is how Northlight identifies itself — so an open product page is
+ *  invisible here, while crouter's own local and remote viewers are not. */
+export async function hasHumanViewer(nodeId, viewer) {
+    return (viewer !== undefined ? viewer.live !== null : await focusOf(nodeId) !== null) || await hasAttachedBrokerViewers(nodeId);
+}
+export async function parkEvent(nodeId, lifecycle, viewer) {
+    return (await parkVerdict(nodeId, lifecycle, viewer)).event;
+}
+/** `parkEvent` plus whether a live subscriber awaiting the report is the ONLY thing holding a
+ *  terminal node's `release`: no viewer, no wake source, no unread mail, no fatal fault. Such a
+ *  node stopped unfinished with nothing that will wake it, and its subscriber knows nothing. */
+export async function parkVerdict(nodeId, lifecycle, viewer) {
+    const held = (event) => ({ event, heldOnlyBySubscriber: false });
+    // Attendance defeats unattended parking outright: the grace exists to settle
+    // a conversation nobody is in, and terminalizing a node somebody is watching
+    // is the one outcome the grace must never reach. The live clock resets its
+    // own timer on the same test, so this covers the paths that reach a verdict
+    // without it — the settlement re-check after a parking turn, and the tick's
+    // sweep over already-idle rows. The live clock discards its timer on that
+    // same reset, so parking resumes a full grace after the last viewer detaches.
+    if (await hasHumanViewer(nodeId, viewer))
+        return held('release');
+    if (await hasLiveObligation(nodeId))
+        return held('release');
+    const fault = await readFault(nodeId);
+    if (fault?.link === 'pi→provider' && fault.retry.disposition === 'fatal')
+        return held('release');
+    if (lifecycle === 'resident')
+        return held(await hasUnseenWakeMail(nodeId) ? 'release' : 'park');
+    if (await hasUnseenWakeMail(nodeId))
+        return held('release');
+    return await hasLiveSubscriber(nodeId) ? { event: 'release', heldOnlyBySubscriber: true } : held('cancel');
+}
+/** Apply an unattended decision and notify subscribers of automatic completion.
+ *  This is the DEGRADED enactment: no summary turn ran, so subscribers get the
+ *  doctrine notice instead of the node's own report. The live clock's good path
+ *  (broker settlement after a parking turn) enacts `park` directly and fans
+ *  nothing — the node's report is the notice.
+ *
+ *  The notice is DEFERRED: a node settling quietly at the end of its unattended
+ *  grace is not an event worth starting a manager's cycle for, so it rides the
+ *  manager's next natural cycle and arrives alongside whatever does.
+ *
+ *  Only `park` fans, and only a resident parks, so the notice speaks about a
+ *  resident throughout: its conversation ended without a final report, its state
+ *  lives in whatever report it did leave, and a message reopens it. */
+export async function applyParkEvent(nodeId, event) {
+    const node = event === 'cancel'
+        ? await transition(nodeId, event, { reason: 'stranded' })
+        : await transition(nodeId, event);
+    if (event !== 'park')
+        return;
+    const ref = await newestReportName(nodeId);
+    const pointer = ref === null
+        ? `It left no report behind; \`crtr node inspect show ${nodeId}\` shows where it stands.`
+        : `Its latest report is where it left things: \`crtr canvas read ${ref}\`.`;
+    await publishNotice(nodeId, 'notice.close', `Resident concluded — ${fullName(node)} (${nodeId}) had nothing left to wake it through its unattended grace, so its conversation was concluded. It submitted no final report. ${pointer} A message to it reopens it on a fresh cycle.`, { reason: 'child-auto-done', child: nodeId }, 'deferred');
+}
+/** Tell a terminal node's subscribers it went idle unfinished: it pushed no final, holds no wait
+ *  that will wake it, and only their subscription kept it from being canceled. The cause of the
+ *  stop is not known here, so the notice claims none. */
+export async function noticeUnfinishedIdle(nodeId) {
+    const node = await getNode(nodeId);
+    if (node === null)
+        return;
+    await publishNotice(nodeId, 'notice.crash', `Child went idle unfinished — ${fullName(node)} (${nodeId}) stopped without pushing a final report and has no wait that will wake it. Its engine was released; the cause is not recorded. \`crtr node inspect show ${nodeId}\` shows where it stands; a message to it revives it.`, { reason: 'child-idle-unfinished', child: nodeId }, 'urgent');
+}

package/dist/daemon/reconcilers/node-lifecycle/launch-failure.d.ts

@@ -0,0 +1 @@
+export declare function recordLaunchFailure(executionId: string, error: unknown): Promise<void>;

package/dist/daemon/reconcilers/node-lifecycle/launch-failure.js

@@ -0,0 +1,8 @@
+// launch-failure.ts — a launch that fails leaves its reason on the execution row, so `executions` says why without the daemon log.
+import { openDb } from '../../../core/canvas/db.js';
+import { exitDiagnosticJson } from '../../../core/canvas/recovery.js';
+export async function recordLaunchFailure(executionId, error) {
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    await (await openDb()).prepare('UPDATE executions SET exit_diagnostic_json = ? WHERE execution_id = ?')
+        .run(exitDiagnosticJson({ launch_failure: { message: message.slice(0, 2_000) } }), executionId);
+}

package/dist/daemon/reconcilers/node-lifecycle/node-person.d.ts

@@ -0,0 +1,9 @@
+import type { NodeRow } from '../../../core/canvas/types.js';
+/** A cloud-role node with no `sub` whose profile names no person: no one may be borrowed for it, so the lane leaves it untouched. */
+export declare class NodePersonUnresolvedError extends Error {
+    readonly code = "node_person_unresolved";
+    constructor(nodeId: string);
+}
+/** Run `fn` as `sub` with that person's settings loaded, as an API request does from its token. */
+export declare function asPerson<T>(sub: string, fn: () => Promise<T>): Promise<T>;
+export declare function asNodePerson<T>(row: Pick<NodeRow, 'node_id' | 'sub' | 'profile_id'>, fn: () => Promise<T>): Promise<T>;

package/dist/daemon/reconcilers/node-lifecycle/node-person.js

@@ -0,0 +1,40 @@
+// node-person.ts — a lane works on a node as the person the node belongs to.
+//
+// `POST /v1/nodes/:id/revive` runs inside `runAsPerson(<token sub>)` with that person's settings loaded. A reconcile process has no
+// request, so on a cloud role every person read (the profile's pause flag, rotation config, the settings snapshot for the launch recipe)
+// throws `PersonOutsideRequestError` or reads defaults. A lane therefore classifies and enacts each row inside the person the row names.
+import { openDb } from '../../../core/canvas/db.js';
+import { isCloudRole, runAsPerson } from '../../../core/canvas/person.js';
+import { loadPersonSettings } from '../../../core/scoped-state/person-rows.js';
+import { personHasSnapshot } from '../../../core/scoped-state/person-store.js';
+/** A cloud-role node with no `sub` whose profile names no person: no one may be borrowed for it, so the lane leaves it untouched. */
+export class NodePersonUnresolvedError extends Error {
+    code = 'node_person_unresolved';
+    constructor(nodeId) { super(`node ${nodeId} has no person: its row carries no sub and its profile names none`); this.name = 'NodePersonUnresolvedError'; }
+}
+/** The row's `sub`; on a cloud role a row without one takes the person that owns its profile (`profiles.person`) and keeps it from then on.
+ *  Null on a Mac for a row without one: the boot person is the install's one person. */
+async function personOf(row) {
+    if (row.sub != null && row.sub !== '')
+        return row.sub;
+    if (!isCloudRole())
+        return null;
+    const owner = row.profile_id == null ? undefined
+        : await (await openDb()).prepare('SELECT person FROM profiles WHERE id = ?').get(row.profile_id);
+    if (owner === undefined || owner.person === '')
+        throw new NodePersonUnresolvedError(row.node_id);
+    await (await openDb()).prepare("UPDATE nodes SET sub = ? WHERE node_id = ? AND (sub IS NULL OR sub = '')").run(owner.person, row.node_id);
+    return owner.person;
+}
+/** Run `fn` as `sub` with that person's settings loaded, as an API request does from its token. */
+export async function asPerson(sub, fn) {
+    return await runAsPerson(sub, async () => {
+        if (!personHasSnapshot())
+            await loadPersonSettings(sub);
+        return await fn();
+    });
+}
+export async function asNodePerson(row, fn) {
+    const sub = await personOf(row);
+    return sub === null ? await fn() : await asPerson(sub, fn);
+}

package/dist/daemon/reconcilers/node-lifecycle/remote-wake.d.ts

@@ -0,0 +1,32 @@
+import { type Execution } from '../../../core/canvas/executions.js';
+import type { NodeMeta } from '../../../core/canvas/index.js';
+import { type EnvironmentImage } from '../recipe-image.js';
+/** A `launching` execution running past this since `started_at` is stopped: the 30-minute recipe setup limit plus boot. */
+export declare const LAUNCH_DEADLINE_MS: number;
+/** A `launching` execution with no process is given this long before it is called lost, so the starter's own call is not raced. */
+export declare const LAUNCH_LOST_GRACE_MS = 120000;
+/** The release the control plane runs, which is the release a wake names. */
+export declare const acceptedRelease: () => string;
+/** The machine environment the node's profile points at when this process is a cloud role (the machine is another host, reached
+ *  through the remote machine runner), else null: a Mac's own crtrd runs its machine environment's nodes as processes. */
+export declare function remoteMachineEnvironmentOf(profileId: string | null): Promise<string | null>;
+/** Step 2: the `funding bill` check. A refusal writes `nodes.spend_refusal` and one refused `sandbox` row per node, limit and month,
+ *  then throws `402 cap_exhausted`; no execution row is written and no runner is called. A pass clears `spend_refusal`. */
+export declare function checkBilledWake(meta: NodeMeta): Promise<void>;
+/** A recipe environment with no built image: the wake is not started, the mail stays pending, and the image-built tick wakes it. */
+export declare class EnvironmentImagePending extends Error {
+    readonly environmentId: string;
+    readonly imageError: string | null;
+    constructor(environmentId: string, imageError: string | null);
+}
+/** D95: the image a new sandbox is created from. `pending` means the environment has a recipe and no image has built. */
+export declare function imageForWake(environmentId: string): Promise<EnvironmentImage>;
+/** Step 3: a `running` Blaxel execution is a resident broker, possibly frozen. On the accepted release it is woken and nothing else
+ *  is written. On another release it is asked to stop for the release first, so the thawed broker exits and the next claim starts
+ *  a new attempt on the accepted one. `lost` means no broker answered: the execution is ended and the caller starts a new attempt. */
+export declare function wakeResident(execution: Execution): Promise<'woken' | 'lost'>;
+/** A `running` remote execution is live while its runner reports the broker process running, frozen or not. When the runner
+ *  reports it gone (or ended non-zero), that exact execution is ended; a runner that cannot tell leaves it as it is. */
+export declare function endRemoteExecutionIfGone(execution: Execution): Promise<boolean>;
+/** The recovery table for a `launching` Blaxel execution found by a claim after its starter is gone. */
+export declare function recoverLaunching(nodeId: string, now: number): Promise<void>;