@north-light/crouter 0.3.236 → 0.3.238

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

@@ -0,0 +1,140 @@
+// tick.ts — the node-lifecycle tick: one pass over durable rows that decides,
+// for every node, whether it should be executing and what is owed if it is not.
+//
+// Durable row state is the input, and the fleet handle is liveness (design
+// D-1/D-4). The pass is two-phase on purpose: phase one classifies every row and
+// enacts everything that costs no slot, phase two hands the surviving candidates
+// to the freeze lane, which orders them by tier and spends the free slots in
+// that order. Splitting the phases is what makes the tier order mean anything —
+// a single interleaved pass would give slots out in row-creation order.
+import { clearFrozen, clearRecordedPid, getNode, } from '../../../core/canvas/index.js';
+import { isSafeNodeId } from '../../../core/canvas/paths.js';
+import { recordedPidLiveness } from '../../../core/canvas/pid.js';
+import { emitEvent } from '../../../core/events/emit.js';
+import { operationIdContext } from '../../../core/events/operation-id.js';
+import { hasUnseenWakeMail } from '../../../core/feed/inbox.js';
+import { hasCleanAbort, isBusy } from '../../../core/runtime/busy.js';
+import { isProfilePaused } from '../../../core/profiles/manifest.js';
+import { classifyDeadNode } from '../../fleet.js';
+import { applyParkEvent, hasPendingWake, parkEvent } from '../live-obligation.js';
+import { FreezeLaneReconciler } from './freeze-lane.js';
+import { isInBackoff } from './respawn-policy.js';
+import { handleTerminatingRow } from './terminating.js';
+function isTerminal(row) {
+    return row.status === 'done' || row.status === 'canceled' || row.status === 'dead';
+}
+/** Whether this row should have a live engine right now. An active row always
+ *  should — that status IS the claim that it is executing. An idle row was
+ *  deliberately released and holds no engine on purpose: only mail it has not
+ *  seen brings one back, because a live obligation keeps a node WAKEABLE rather
+ *  than awake, and relaunching on one would re-release it every tick. */
+export function wantsExecution(row) {
+    if (row.status === 'active')
+        return true;
+    if (row.status !== 'idle')
+        return false;
+    return hasUnseenWakeMail(row.node_id);
+}
+export class NodeLifecycleReconciler {
+    freezeLane = new FreezeLaneReconciler();
+    async run(now, ctx) {
+        const candidates = [];
+        for (const row of ctx.rows) {
+            await operationIdContext.fresh(async () => {
+                try {
+                    await this.classifyRow(now, row, ctx, candidates);
+                }
+                catch (err) {
+                    const id = row.node_id;
+                    emitEvent({
+                        level: 'error',
+                        event: 'node.lifecycle.classify_failed',
+                        ...(isSafeNodeId(id) ? { node_id: id } : { fields: { affected_node_id: id } }),
+                        error: err,
+                    });
+                }
+            });
+        }
+        return this.freezeLane.run(now, { fleet: ctx.fleet, candidates });
+    }
+    async classifyRow(now, row, ctx, candidates) {
+        const id = row.node_id;
+        // 1. A fleet handle IS execution. Whatever froze this row is over.
+        if (ctx.fleet.has(id)) {
+            this.thawMark(row);
+            return;
+        }
+        // 2. A terminal row still holding a process is Terminating, and P4's.
+        if (isTerminal(row)) {
+            handleTerminatingRow(row);
+            return;
+        }
+        // A paused profile launches nothing, and its stuck-delivery episode is over
+        // rather than merely stalled — the pause is not a delivery failure.
+        if (isProfilePaused(row.profile_id)) {
+            this.freezeLane.endEpisode(id);
+            return;
+        }
+        // 3. Nothing is owed: drop the freeze mark, and settle a parked row whose
+        //    conversation has nothing left to wake it.
+        if (!wantsExecution(row)) {
+            this.thawMark(row);
+            this.settleParked(row);
+            return;
+        }
+        // 4. Backoff owns this row's next launch; it holds no slot.
+        if (isInBackoff(row, now))
+            return;
+        // An idle row that wants execution is a stuck delivery, and the freeze lane
+        // owns its episode rules.
+        if (row.status === 'idle') {
+            candidates.push({ row, enact: 'idle-release' });
+            return;
+        }
+        // 5. An active row with no recorded pid has no broker to rule on, so the
+        //    dead-row table — which answers "this node's engine died, what now?" —
+        //    has no jurisdiction. Only the freeze mark distinguishes the two ways a
+        //    row gets here: a launcher that reached the ledger and was turned away
+        //    (the mark, and the launch it is still owed), versus a birth still on
+        //    its way to the launch seam, which owns its own launch and must be left
+        //    alone rather than raced or written off as a boot failure.
+        if (row.pi_pid == null) {
+            if (row.frozen_at != null)
+                candidates.push({ row, enact: 'thaw' });
+            return;
+        }
+        // 6. A recorded pid: prove it is not alive before writing it off. An
+        //    indeterminate probe leaves the row for the next tick — the failure
+        //    mode is delay, never a wrong kill.
+        if (recordedPidLiveness(row.pi_pid, row.pi_pid_identity) !== 'dead')
+            return;
+        clearRecordedPid(id);
+        // 7. The invariant-5 policy table, on the same inputs an exit event gives
+        //    it. 8. A verdict that needs no broker is enacted right here, because it
+        //    costs no slot; a respawn becomes a candidate for the freeze lane.
+        const action = classifyDeadNode(getNode(id), isBusy(id) || hasCleanAbort(id), hasPendingWake(id));
+        if (action === 'respawn-fresh' || action === 'respawn-cycle' || action === 'respawn-resume') {
+            candidates.push({ row, enact: 'policy' });
+            return;
+        }
+        await ctx.fleet.applyDeadRowPolicy(id);
+        this.thawMark(row);
+    }
+    thawMark(row) {
+        if (row.frozen_at == null)
+            return;
+        clearFrozen(row.node_id);
+    }
+    /** An idle row with no wake-worthy inbox entry still needs the lifecycle
+     *  settlement the live park clock applies: once nothing live remains, this is
+     *  history rather than a permanently protected idle row. The row is already
+     *  parked, so only a terminalizing verdict is worth writing. */
+    settleParked(row) {
+        if (row.status !== 'idle')
+            return;
+        this.freezeLane.endEpisode(row.node_id);
+        const event = parkEvent(row.node_id, row.lifecycle);
+        if (event !== 'release')
+            applyParkEvent(row.node_id, event);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.236",
+  "version": "0.3.238",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.236",
+  "version": "0.3.238",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.236",
+      "version": "0.3.238",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/dist/commands/sys/prompt-review.d.ts

@@ -1 +0,0 @@
-export declare const promptReviewLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/sysprompt.d.ts

@@ -1 +0,0 @@
-export declare const sysSyspromptLeaf: import("../../core/command.js").LeafDef;

package/dist/core/__tests__/cron-broker-capacity.test.js

@@ -1,119 +0,0 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/cron-broker-capacity.test.ts
-//
-// Broker-capacity admission for the daemon's due-cron pass (design D-7, the
-// fleet-safety invariant the retired clock pass carried): a due run that would
-// LAUNCH OR REVIVE a node is admitted only while the fleet is under its
-// automatic-revive cap. An unadmitted run is DEFERRED, never consumed — no
-// record, no recurrence advance, no one-shot deletion, no escalation — so it
-// stays due for the next poll. A cron that merely runs a shell command consumes
-// no broker capacity and is never gated.
-import { after, afterEach, before, test } from 'node:test';
-import assert from 'node:assert/strict';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { setTimeout as delay } from 'node:timers/promises';
-import { closeDb } from '../canvas/db.js';
-import { armCron, cancelCron, getCron, listCronRuns } from '../canvas/crons.js';
-import { cronLaunchesNode, executeCron, markSelfCanceledCronRun, runDueCrons } from '../../daemon/cron-run.js';
-let home;
-let realHome;
-function arm(overrides) {
-    armCron({
-        name: overrides.cron_id,
-        created_by: null,
-        fire_at: new Date(Date.now() - 1_000).toISOString(),
-        recur: null,
-        tz: null,
-        expires_at: null,
-        anchor_node: null,
-        cancel_on_wake: false,
-        cwd: home,
-        env_json: null,
-        profile: null,
-        scope: 'profile',
-        run_timeout_s: 30,
-        overlap: 'skip',
-        on_output: 'silent',
-        sink: '{}',
-        tier: 'normal',
-        ...overrides,
-    });
-}
-before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-cron-broker-capacity-'));
-    realHome = process.env['CRTR_HOME'];
-    process.env['CRTR_HOME'] = home;
-});
-afterEach(() => {
-    closeDb();
-});
-after(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-    if (realHome === undefined)
-        delete process.env['CRTR_HOME'];
-    else
-        process.env['CRTR_HOME'] = realHome;
-});
-test('a capacity-deferred one-shot revive cron stays due, unconsumed and unrun', async () => {
-    arm({ cron_id: 'revive-at-capacity', command: "crtr node lifecycle revive 'target-node' --fresh" });
-    const settlements = runDueCrons(Date.now(), { hasBrokerCapacity: () => false });
-    await Promise.all(settlements);
-    assert.equal(settlements.length, 0, 'no run was started');
-    const row = getCron('revive-at-capacity');
-    assert.notEqual(row, null, 'the one-shot was not consumed');
-    assert.equal(row.state, 'active', 'deferral is not a failure — the row is not paused');
-    assert.equal(row.run_state, 'idle', 'no lease was taken');
-    assert.equal(listCronRuns('revive-at-capacity').length, 0, 'nothing was recorded');
-});
-test('a capacity-deferred recurring spawn cron keeps its past-due fire_at', async () => {
-    const fireAt = new Date(Date.now() - 1_000).toISOString();
-    arm({
-        cron_id: 'spawn-at-capacity',
-        command: 'crtr node new --kind general --root',
-        fire_at: fireAt,
-        recur: JSON.stringify({ every: 'hour' }),
-    });
-    await Promise.all(runDueCrons(Date.now(), { hasBrokerCapacity: () => false }));
-    // Deferring must never advance the recurrence past its window: the slot is
-    // still owed, so the row is retried on the next poll.
-    assert.equal(getCron('spawn-at-capacity').fire_at, fireAt);
-    assert.equal(listCronRuns('spawn-at-capacity').length, 0);
-});
-test('a plain shell cron runs at zero capacity — only launches are gated', async () => {
-    arm({ cron_id: 'plain-shell', command: 'exit 0' });
-    const settlements = runDueCrons(Date.now(), { hasBrokerCapacity: () => false });
-    assert.equal(settlements.length, 1, 'the run was admitted');
-    await Promise.all(settlements);
-    assert.equal(getCron('plain-shell'), null, 'the one-shot settled and was consumed');
-});
-test('an on-change cron that cancels itself still delivers its final output', async () => {
-    const runIdPath = join(home, 'self-cancel-run-id');
-    arm({
-        cron_id: 'self-cancel-delivery',
-        command: `printf '%s' "$CRTR_RUN_ID" > '${runIdPath}'; echo settled; sleep 0.1`,
-        recur: JSON.stringify({ every: '1h' }),
-        on_output: 'on-change',
-        sink: JSON.stringify({ human: true }),
-    });
-    const run = executeCron(getCron('self-cancel-delivery'), { outOfBand: false });
-    for (let i = 0; i < 50 && !existsSync(runIdPath); i++)
-        await delay(10);
-    assert.ok(existsSync(runIdPath), 'the live run exposed its id to its self-cancel command');
-    assert.equal(markSelfCanceledCronRun('self-cancel-delivery', readFileSync(runIdPath, 'utf8')), true);
-    assert.equal(cancelCron('self-cancel-delivery', { preserveRunningProcess: true }), true);
-    const record = await run;
-    assert.equal(record?.delivered, 'delivered: human send --inbox');
-});
-test('cronLaunchesNode classifies by command verb and armed sink', () => {
-    const of = (command, sink = '{}') => cronLaunchesNode({ command, sink });
-    assert.equal(of("crtr node lifecycle revive 'n' --fresh"), true);
-    assert.equal(of('crtr node new --kind general --root'), true);
-    assert.equal(of('crtr canvas revive --all'), true);
-    assert.equal(of("crtr node message send --to 'n' --tier urgent --fresh"), true);
-    assert.equal(of('echo hi', JSON.stringify({ spawn: 'general' })), true);
-    assert.equal(of("crtr node message send --to 'n' --tier urgent"), false);
-    assert.equal(of('npm test'), false);
-    assert.equal(of('echo hi', JSON.stringify({ node: 'n' })), false);
-});

package/dist/daemon/reconcilers/dormant-inbox.d.ts

@@ -1,18 +0,0 @@
-import { type NodeRow } from '../../core/canvas/index.js';
-import type { FleetRegistry } from '../../core/runtime/fleet.js';
-export interface ControllerDeathContext {
-    rows: readonly NodeRow[];
-}
-export interface DormantInboxContext extends ControllerDeathContext {
-    fleet: FleetRegistry;
-    /** P3.4's capacity authority, bound to the thresholds returned by the live
-     * supervision pass for this same tick. */
-    hasBrokerCapacity(): boolean;
-}
-export declare class ControllerDeathReconciler {
-    run(now: number, ctx: ControllerDeathContext): void;
-}
-export declare class DormantInboxReconciler {
-    private readonly relaunchState;
-    run(now: number, ctx: DormantInboxContext): void;
-}

package/dist/daemon/reconcilers/dormant-inbox.js

@@ -1,157 +0,0 @@
-import { getNode, getRow, subscribersOf, } from '../../core/canvas/index.js';
-import { fullName } from '../../core/canvas/labels.js';
-import { isSafeNodeId } from '../../core/canvas/paths.js';
-import { emitEvent } from '../../core/events/emit.js';
-import { operationIdContext } from '../../core/events/operation-id.js';
-import { appendControllerDeathNotice, readCursor, readInboxSince, } from '../../core/feed/inbox.js';
-import { fanDoctrineWake } from '../../core/runtime/close.js';
-import { transition } from '../../core/runtime/lifecycle.js';
-import { reviveNode } from '../../core/runtime/revive.js';
-import { isProfilePaused } from '../../core/profiles/manifest.js';
-import { applyParkEvent, parkEvent } from './live-obligation.js';
-// Idle-release/inbox retry cap (2026-07-10 diagnosis, round 2): the SAME
-// livelock shape as the stranded-relaunch case, but on the separate pass that
-// resumes a dormant idle-released node when its inbox gains an unseen entry.
-// The counter is keyed on inbox-cursor progress, not row-state residency or pid
-// liveness: a transiently-live broker does not prove that delivery completed.
-const IDLE_RELEASE_RELAUNCH_MAX_ATTEMPTS = 6;
-const IDLE_RELEASE_RELAUNCH_MAX_BACKOFF_MS = 10 * 60_000;
-const IDLE_RELEASE_RELAUNCH_BASE_MS = 20_000;
-export class ControllerDeathReconciler {
-    run(now, ctx) {
-        void now; // no time-gating here — the death check is already-controller-status-driven; the param is kept for six-way call-site uniformity, matching every other reconciler's run(now, ctx) shape.
-        // Settle every wait whose controller has ended, independent of the waiter's
-        // current status. Active and focused terminal nodes own a live inbox
-        // watcher; idle-released nodes are revived by the following reconciler.
-        for (const row of ctx.rows) {
-            const current = getRow(row.node_id);
-            const controllerId = current?.waiting_for;
-            if (controllerId === null || controllerId === undefined)
-                continue;
-            // Read-gate before the write boundary: only a dead controller warrants a
-            // notice. appendControllerDeathNotice re-checks liveness inside its
-            // transaction, so this gate cannot misfire.
-            const controller = getRow(controllerId);
-            if (controller !== null && (controller.status === 'active' || controller.status === 'idle'))
-                continue;
-            operationIdContext.fresh(() => {
-                appendControllerDeathNotice(row.node_id, controllerId);
-            });
-        }
-    }
-}
-export class DormantInboxReconciler {
-    relaunchState = new Map();
-    run(now, ctx) {
-        // Re-read each row because live supervision may have mutated it earlier in
-        // this tick. A fleet entry is the live engine; no pid probe participates.
-        for (const row of ctx.rows) {
-            const id = row.node_id;
-            let current;
-            try {
-                current = getRow(id);
-                if (current === null) {
-                    this.relaunchState.delete(id);
-                    continue;
-                }
-                // Do not clear state on status flaps or transient liveness. Only cursor
-                // progress, no wake-worthy work, row deletion, or exhaustion ends the
-                // stuck-delivery episode.
-                if (current.status !== 'idle' || current.intent !== 'idle-release')
-                    continue;
-                if (ctx.fleet.has(id))
-                    continue;
-                if (isProfilePaused(current.profile_id)) {
-                    this.relaunchState.delete(id);
-                    continue;
-                }
-            }
-            catch (err) {
-                operationIdContext.fresh(() => {
-                    emitEvent({
-                        level: 'error',
-                        event: 'inbox.poll.failed',
-                        ...(isSafeNodeId(id) ? { node_id: id } : { fields: { affected_node_id: id } }),
-                        error: err,
-                    });
-                });
-                continue;
-            }
-            operationIdContext.fresh(() => {
-                try {
-                    const cursorNow = readCursor(id);
-                    const entries = readInboxSince(id, cursorNow);
-                    // Deferred entries ride the next natural cycle. A deferred-only unseen
-                    // set neither revives the node nor starts a stuck-relaunch episode.
-                    if (!entries.some((entry) => entry.tier !== 'deferred')) {
-                        this.relaunchState.delete(id);
-                        const meta = getNode(id);
-                        // An idle row with no wake-worthy inbox entry still needs the same
-                        // lifecycle settlement the live park clock applies: once nothing
-                        // live remains, this is history rather than a permanently protected
-                        // idle row. The row is already parked, so only a terminalizing
-                        // verdict is worth writing. Unclaimed warm-pool spares never reach
-                        // here — `listNodes` hides them from `ctx.rows`.
-                        if (meta !== null) {
-                            const event = parkEvent(id, meta.lifecycle);
-                            if (event !== 'release')
-                                applyParkEvent(id, event);
-                        }
-                        return;
-                    }
-                    const prior = this.relaunchState.get(id);
-                    const cursorChanged = prior === undefined || prior.cursor !== cursorNow;
-                    const attempts = cursorChanged ? 0 : prior.attempts;
-                    if (attempts >= IDLE_RELEASE_RELAUNCH_MAX_ATTEMPTS) {
-                        this.relaunchState.delete(id);
-                        const meta = getNode(id);
-                        emitEvent({
-                            level: 'warn',
-                            event: 'broker.idle_release.exhausted',
-                            ...(isSafeNodeId(id) ? { node_id: id } : {}),
-                            fields: {
-                                ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
-                                attempts,
-                                max_attempts: IDLE_RELEASE_RELAUNCH_MAX_ATTEMPTS,
-                            },
-                        });
-                        transition(id, 'crash');
-                        if (meta !== null) {
-                            fanDoctrineWake(id, subscribersOf(id), `Child crashed — ${fullName(meta)} (${id}) failed to relaunch after ${attempts} attempts while trying to ` +
-                                `deliver a pending inbox message (no delivery progress across any attempt), and is now dead. It stays ` +
-                                `dead until you revive it — \`crtr node lifecycle revive ${id}\`.`, { reason: 'child-crashed', child: id });
-                        }
-                        return;
-                    }
-                    const lastAttempt = cursorChanged ? undefined : prior?.lastAttempt;
-                    const backoff = Math.min(IDLE_RELEASE_RELAUNCH_BASE_MS * 2 ** attempts, IDLE_RELEASE_RELAUNCH_MAX_BACKOFF_MS);
-                    if (lastAttempt !== undefined && now - lastAttempt < backoff)
-                        return;
-                    if (!ctx.hasBrokerCapacity())
-                        return;
-                    this.relaunchState.set(id, { cursor: cursorNow, attempts: attempts + 1, lastAttempt: now });
-                    emitEvent({
-                        level: 'info',
-                        event: 'broker.revive.idle_release',
-                        ...(isSafeNodeId(id) ? { node_id: id } : {}),
-                        attempt: attempts + 1,
-                        fields: {
-                            ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
-                            attempts: attempts + 1,
-                            max_attempts: IDLE_RELEASE_RELAUNCH_MAX_ATTEMPTS,
-                        },
-                    });
-                    reviveNode(id, { resume: true });
-                }
-                catch (err) {
-                    emitEvent({
-                        level: 'error',
-                        event: 'inbox.poll.failed',
-                        ...(isSafeNodeId(id) ? { node_id: id } : { fields: { affected_node_id: id } }),
-                        error: err,
-                    });
-                }
-            });
-        }
-    }
-}