@north-light/crouter 0.3.235 → 0.3.237

package/dist/core/substrate/surface-match.js

@@ -323,69 +323,60 @@ export function matchesPreCommandEntry(entry, subject, command) {
     const stripped = stripHeredocs(command);
     return entry.match.some((g) => commandGlobMatches(g, stripped));
 }
-// Per-doc rung folds — a doc's delivery rung for one event occurrence is the
-// highest `at` over its matching entries of that event, `none` when none
-// match (entries OR together; `none` is the internal "does not deliver"
-// floor, never an authored rung).
-/** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
-export function readDeliveryRung(doc, subject, absReadFile, readFrontmatter) {
-    let r = 'none';
-    for (const e of doc.surfaces) {
-        if (!matchesReadEntry(e, doc, subject, absReadFile, readFrontmatter))
-            continue;
-        if (rungRank(e.at) > rungRank(r))
-            r = e.at;
+/** Does ONE entry of `event` fit this occurrence — constraints and the entry's
+ *  own gate together? */
+export function surfaceEntryParticipates(entry, doc, subject, event, payload) {
+    if (entry.on !== event)
+        return false;
+    switch (event) {
+        // Presence of the entry is the match; callers scope the corpus.
+        case 'boot':
+        case 'workspace-open':
+            return surfaceEntryGatePasses(entry, subject);
+        case 'read':
+            if (payload.absoluteFile === undefined || doc.path === undefined || doc.scope === undefined)
+                return false;
+            return matchesReadEntry(entry, { path: doc.path, scope: doc.scope }, subject, payload.absoluteFile, payload.readFrontmatter ?? {});
+        case 'memory-read':
+            if (payload.resolvedCanonicalName === undefined)
+                return false;
+            return matchesMemoryReadEntry(entry, payload.routingAnchor ?? '', subject, payload.resolvedCanonicalName);
+        case 'command':
+            return payload.command !== undefined && matchesCommandEntry(entry, subject, payload.command);
+        case 'pre-command':
+            return payload.command !== undefined && matchesPreCommandEntry(entry, subject, payload.command);
     }
-    return r;
 }
-/** The doc's workspace-open rung. Presence of an entry is the match; callers
- *  scope the corpus to project stores mounted by the subject's cwd/profile. */
-export function workspaceOpenRung(doc, subject) {
-    let r = 'none';
-    for (const e of doc.surfaces) {
-        if (e.on !== 'workspace-open' || !surfaceEntryGatePasses(e, subject))
+/** The entry that decides this doc's delivery for one event occurrence: the
+ *  highest-rung participating entry, or null when none participates. */
+export function matchingSurfaceEntry(doc, subject, event, payload) {
+    let best = null;
+    for (const entry of doc.surfaces) {
+        if (!surfaceEntryParticipates(entry, doc, subject, event, payload))
             continue;
-        if (rungRank(e.at) > rungRank(r))
-            r = e.at;
+        if (best === null || rungRank(entry.at) > rungRank(best.at))
+            best = entry;
     }
-    return r;
+    return best;
+}
+/** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
+export function readDeliveryRung(doc, subject, absReadFile, readFrontmatter) {
+    return matchingSurfaceEntry(doc, subject, 'read', { absoluteFile: absReadFile, readFrontmatter })?.at ?? 'none';
+}
+/** The doc's workspace-open rung. */
+export function workspaceOpenRung(doc, subject) {
+    return matchingSurfaceEntry(doc, subject, 'workspace-open', {})?.at ?? 'none';
 }
 /** The doc's delivery rung for a `crtr memory read` that resolved a doc known
- *  by its exact canonical `name` — no mount-stripped or other alias.
- *  `routingAnchor` comes from the doc's resolver descriptor — it is not
- *  derivable from the canonical name, which cannot say whether the doc fronts
- *  its own directory. */
+ *  by its exact canonical `name` — no mount-stripped or other alias. */
 export function memoryReadDeliveryRung(doc, routingAnchor, subject, name) {
-    let r = 'none';
-    for (const e of doc.surfaces) {
-        if (!matchesMemoryReadEntry(e, routingAnchor, subject, name))
-            continue;
-        if (rungRank(e.at) > rungRank(r))
-            r = e.at;
-    }
-    return r;
+    return matchingSurfaceEntry(doc, subject, 'memory-read', { routingAnchor, resolvedCanonicalName: name })?.at ?? 'none';
 }
 /** The doc's delivery rung for an executed command string. */
 export function commandDeliveryRung(doc, subject, command) {
-    let r = 'none';
-    for (const e of doc.surfaces) {
-        if (!matchesCommandEntry(e, subject, command))
-            continue;
-        if (rungRank(e.at) > rungRank(r))
-            r = e.at;
-    }
-    return r;
+    return matchingSurfaceEntry(doc, subject, 'command', { command })?.at ?? 'none';
 }
-/** The doc's delivery rung for a command about to run — the highest `at`
- *  over the doc's matching `pre-command` entries, folded the same way as every
- *  other event. */
+/** The doc's delivery rung for a command about to run. */
 export function preCommandDeliveryRung(doc, subject, command) {
-    let r = 'none';
-    for (const e of doc.surfaces) {
-        if (!matchesPreCommandEntry(e, subject, command))
-            continue;
-        if (rungRank(e.at) > rungRank(r))
-            r = e.at;
-    }
-    return r;
+    return matchingSurfaceEntry(doc, subject, 'pre-command', { command })?.at ?? 'none';
 }

package/dist/core/tui/page-host.d.ts

@@ -10,6 +10,12 @@ export interface TuiPageContext {
     terminal: ProcessTerminal;
     bindings: BindingResolution<BindingId>;
     rawUserConfig: ReturnType<typeof readRawScopeConfig>;
+    /**
+     * Hand the terminal to a child process ($EDITOR) and return the closure that
+     * takes it back with a full repaint. Callers must invoke the closure in a
+     * `finally` block. Same contract as the attach viewer's `SurfaceHost`.
+     */
+    suspendForChild(): () => void;
 }
 export interface TuiPageControl<Result> {
     /** Close the page with a result. */

package/dist/core/tui/page-host.js

@@ -2,8 +2,9 @@
 // `crtr sys settings`, the setup wizard, and `crtr pkg browse`.
 //
 // It owns exactly the concerns every page shares: theme, resolved keybindings,
-// the raw user config those pages edit, the ProcessTerminal/TUI pair, and a
-// restore path that survives an exception, a signal, and process exit. Anything
+// the raw user config those pages edit, the ProcessTerminal/TUI pair, the
+// release and reclaim of that terminal for a child process, and a restore path
+// that survives an exception, a signal, and process exit. Anything
 // a single page needs beyond that — pi's model runtime, a canvas client — the
 // page's own runner builds and closes over before calling in here.
 import { ProcessTerminal, TuiMainScreen, } from '@earendil-works/pi-tui';
@@ -40,8 +41,16 @@ export async function runTuiPage(createSurface, interceptCancel) {
             restore();
             resolve(result);
         };
+        const suspendForChild = () => {
+            tui.stop();
+            return () => {
+                tui.start();
+                tui.invalidate();
+                tui.requestRender(true);
+            };
+        };
         try {
-            surface = createSurface({ tui, terminal, bindings, rawUserConfig }, { submit: finish, cancel: () => finish(undefined) });
+            surface = createSurface({ tui, terminal, bindings, rawUserConfig, suspendForChild }, { submit: finish, cancel: () => finish(undefined) });
             tui.addChild(surface);
             tui.setFocus(surface);
             process.once("exit", restore);

package/dist/core/worktree.d.ts

@@ -31,6 +31,14 @@ export interface CloseManagedWorktreeResult {
     branch_delete_error?: string;
 }
 export declare function closeManagedWorktree(nodeId: string): CloseManagedWorktreeResult;
+export interface AbandonManagedWorktreeResult {
+    node_id: string;
+    branch: string;
+    tip_sha: string;
+    worktree_path: string;
+    branch_deleted: boolean;
+}
+export declare function abandonManagedWorktree(nodeId: string, by: string): AbandonManagedWorktreeResult;
 /** Recovery guidance for a vanished checkout whose refs do not prove that its
  * work is delivered. This deliberately never recommends `worktree close`:
  * that command cannot operate on the absent checkout. */

package/dist/core/worktree.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { gitSync } from './git.js';
 import { crtrHome } from './canvas/paths.js';
+import { isPidAlive } from './canvas/pid.js';
 import { getNode, updateNode } from './canvas/index.js';
 import { CONFIG_FILE, CRTR_DIR_NAME, STATE_FILE } from '../types.js';
 import { withExclusiveDirectoryLock } from './exclusive-lock.js';
@@ -357,6 +358,70 @@ export function closeManagedWorktree(nodeId) {
         return closeManagedWorktreeLocked(nodeId);
     return withRepositoryWorktreeLock(wt.repo_root, () => closeManagedWorktreeLocked(nodeId));
 }
+const ABANDON_AUTHOR_NAME = 'crtr-abandon';
+const ABANDON_AUTHOR_EMAIL = 'crtr-abandon@localhost';
+const ABANDON_SUBJECT = 'crtr-abandon';
+function persistAbandonedWorktreeState(nodeId, wt, tipSha, at, by) {
+    updateNode(nodeId, {
+        cwd: wt.repo_root,
+        managed_worktree: {
+            ...wt,
+            state: 'abandoned',
+            abandoned: { branch: wt.branch, tip_sha: tipSha, at, by },
+        },
+    });
+}
+function createAbandonMarker(wt, parentSha, nodeId, at) {
+    const treeSha = runGit(wt.repo_root, ['rev-parse', `${parentSha}^{tree}`], 'abandon_tree_failed', 'Inspect the branch manually, then retry.');
+    const markerSha = runGit(wt.repo_root, ['-c', `user.name=${ABANDON_AUTHOR_NAME}`, '-c', `user.email=${ABANDON_AUTHOR_EMAIL}`, 'commit-tree', treeSha, '-p', parentSha, '-m', ABANDON_SUBJECT, '-m', `Crtr-Abandon: ${nodeId} ${at}`], 'abandon_commit_failed', 'Inspect the branch manually, then retry.');
+    runGit(wt.repo_root, ['update-ref', `refs/heads/${wt.branch}`, markerSha, parentSha], 'abandon_marker_failed', 'The branch changed while abandon was starting; inspect the worktree, then retry.');
+    return markerSha;
+}
+function abandonManagedWorktreeLocked(nodeId, by) {
+    const node = getNode(nodeId);
+    if (node === null) {
+        throw new WorktreeError('unknown_node', `unknown node: ${nodeId}`, 'Pass a real node id.');
+    }
+    const wt = openManagedWorktreeForNode(nodeId);
+    if (wt === null) {
+        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to abandon for this node.');
+    }
+    if (node.status === 'active' || node.status === 'idle' || isPidAlive(node.pi_pid)) {
+        throw new WorktreeError('node_running', `node ${nodeId} is still running`, 'Stop the node before abandoning its managed worktree.');
+    }
+    if (!existsSync(wt.path)) {
+        throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${wt.path}`, missingWorktreeRecoveryHint(wt));
+    }
+    if (currentBranch(wt.path) !== wt.branch) {
+        throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch})`, `Check out ${wt.branch} in ${wt.path}, then rerun \`crtr node worktree abandon\`.`);
+    }
+    const at = new Date().toISOString();
+    const clean = proveCleanEmptyManagedWorktree(wt);
+    if (clean !== null && clean.branchSha === wt.base_sha) {
+        const markerSha = createAbandonMarker(wt, clean.branchSha, nodeId, at);
+        runGit(wt.repo_root, ['worktree', 'remove', wt.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
+        const deleted = bestEffortDeleteBranchWithContainmentProof(wt, markerSha, `refs/heads/${wt.base_ref}`, clean.baseSha);
+        if (deleted.branchDeleted) {
+            persistClosedWorktreeState(nodeId, wt, 'complete');
+            return { node_id: nodeId, branch: wt.branch, tip_sha: markerSha, worktree_path: wt.path, branch_deleted: true };
+        }
+        const tipSha = runGit(wt.repo_root, ['rev-parse', `refs/heads/${wt.branch}`], 'abandon_tip_failed', 'Inspect the branch manually, then retry.');
+        persistAbandonedWorktreeState(nodeId, wt, tipSha, at, by);
+        return { node_id: nodeId, branch: wt.branch, tip_sha: tipSha, worktree_path: wt.path, branch_deleted: false };
+    }
+    runGit(wt.path, ['add', '--all'], 'abandon_stage_failed', 'Inspect the worktree manually, then retry.');
+    runGit(wt.path, ['-c', `user.name=${ABANDON_AUTHOR_NAME}`, '-c', `user.email=${ABANDON_AUTHOR_EMAIL}`, 'commit', '--allow-empty', '-m', ABANDON_SUBJECT, '-m', `Crtr-Abandon: ${nodeId} ${at}`], 'abandon_commit_failed', 'Inspect the worktree manually, then retry.');
+    runGit(wt.repo_root, ['worktree', 'remove', wt.path], 'worktree_remove_failed', 'Inspect the worktree manually, then retry.');
+    const tipSha = runGit(wt.repo_root, ['rev-parse', `refs/heads/${wt.branch}`], 'abandon_tip_failed', 'Inspect the branch manually, then retry.');
+    persistAbandonedWorktreeState(nodeId, wt, tipSha, at, by);
+    return { node_id: nodeId, branch: wt.branch, tip_sha: tipSha, worktree_path: wt.path, branch_deleted: false };
+}
+export function abandonManagedWorktree(nodeId, by) {
+    const wt = openManagedWorktreeForNode(nodeId);
+    if (wt === null)
+        return abandonManagedWorktreeLocked(nodeId, by);
+    return withRepositoryWorktreeLock(wt.repo_root, () => abandonManagedWorktreeLocked(nodeId, by));
+}
 // Push-final auto-drop of a clean, zero-commit managed worktree
 /** Delete a source branch only while the ref that proved it already delivered
  *  is still at the exact inspected SHA. `containingRef` can be the recorded

package/dist/daemon/__tests__/reconciler-signature.test.js

@@ -9,7 +9,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { BrokerSupervisionReconciler } from '../reconcilers/broker-supervision.js';
-import { ControllerDeathReconciler, DormantInboxReconciler } from '../reconcilers/dormant-inbox.js';
+import { ControllerDeathReconciler } from '../reconcilers/controller-death.js';
+import { NodeLifecycleReconciler } from '../reconcilers/node-lifecycle/tick.js';
 import { CronLaneReconciler } from '../reconcilers/cron-lane.js';
 import { HumanDeliveryLaneReconciler } from '../reconcilers/human-delivery-lane.js';
 import { PendingReviewSubmitReconciler } from '../reconcilers/pending-review-submit.js';
@@ -18,7 +19,7 @@ import { StorageMaintenanceReconciler } from '../reconcilers/storage-maintenance
 const RECONCILERS = [
     ['BrokerSupervisionReconciler', BrokerSupervisionReconciler],
     ['ControllerDeathReconciler', ControllerDeathReconciler],
-    ['DormantInboxReconciler', DormantInboxReconciler],
+    ['NodeLifecycleReconciler', NodeLifecycleReconciler],
     ['CronLaneReconciler', CronLaneReconciler],
     ['HumanDeliveryLaneReconciler', HumanDeliveryLaneReconciler],
     ['PendingReviewSubmitReconciler', PendingReviewSubmitReconciler],

package/dist/daemon/__tests__/thaw-order.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/daemon/__tests__/thaw-order.test.js

@@ -0,0 +1,55 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/daemon/__tests__/thaw-order.test.ts
+//
+// Thaw ordering IS the freeze lane's allocation policy: the lane enacts
+// sequentially on the daemon's serial lane, so whichever candidate it reaches
+// first takes the free slot. `thawTier` + `compareThaw` are that whole policy,
+// and both are pure — this file pins them directly so a re-stalling node cannot
+// silently starve the mail queued behind it.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { compareThaw, thawTier } from '../reconcilers/node-lifecycle/freeze-lane.js';
+function row(over = {}) {
+    return {
+        node_id: over.node_id ?? 'N',
+        name: 'n',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        cwd: '/tmp',
+        host_kind: 'broker',
+        profile_id: null,
+        parent: null,
+        created: '2026-01-01T00:00:00.000Z',
+        intent: null,
+        waiting_for: null,
+        pi_pid: null,
+        pi_pid_identity: null,
+        window: null,
+        tmux_session: null,
+        pane: null,
+        ...over,
+    };
+}
+test('a node that spent a slot and settled nothing drops behind the mail it stalled', () => {
+    assert.equal(thawTier(row(), false), 1, 'a never-launched row has spent nothing');
+    assert.equal(thawTier(row({ launched_at: '2026-01-01T00:00:10.000Z', last_settled_at: '2026-01-01T00:00:20.000Z' }), false), 1, 'a launch that settled a turn earned its place at the front');
+    assert.equal(thawTier(row({ launched_at: '2026-01-01T00:00:10.000Z' }), false), 2, 're-stall demotion: a slot was spent and nothing was settled with it');
+    assert.equal(thawTier(row({ launched_at: '2026-01-01T00:00:20.000Z', last_settled_at: '2026-01-01T00:00:10.000Z' }), false), 2, 'a settlement from BEFORE the launch does not count for that launch');
+    assert.equal(thawTier(row(), true), 2, 'a row waiting on mail competes in tier 2 regardless of its history');
+});
+test('thaw order is tier first, then longest-frozen first, with the unfrozen last', () => {
+    const entry = (node_id, tier, frozen_at) => ({
+        row: row({ node_id, ...(frozen_at !== undefined ? { frozen_at } : {}) }),
+        enact: 'policy',
+        tier,
+    });
+    const entries = [
+        entry('never-frozen-stalled', 1),
+        entry('mail-old', 2, '2026-01-01T00:00:01.000Z'),
+        entry('stalled-new', 1, '2026-01-01T00:00:09.000Z'),
+        entry('stalled-old', 1, '2026-01-01T00:00:02.000Z'),
+    ];
+    entries.sort(compareThaw);
+    assert.deepEqual(entries.map((e) => e.row.node_id), ['stalled-old', 'stalled-new', 'never-frozen-stalled', 'mail-old'], 'tier 1 takes every free slot before tier 1 exhausts, oldest wait first; a row that has not waited sorts last in its tier');
+});

package/dist/daemon/api/__tests__/canvas-snapshot-fields.test.js

@@ -8,6 +8,8 @@ import { createNode, getNode } from '../../../core/canvas/canvas.js';
 import { contextDir, jobDir, viewSocketPath } from '../../../core/canvas/paths.js';
 import { recordFault } from '../../../core/runtime/fault.js';
 import { headlessBrokerHost } from '../../../core/runtime/host.js';
+import { resetFleetForTests } from '../../../core/runtime/fleet.js';
+import { bindTestFleet } from '../../../core/__tests__/helpers/fleet.js';
 import { handleCreate } from '../handlers/nodes.js';
 import { canvasRoutes } from '../handlers/canvas.js';
 let home = '';
@@ -18,6 +20,9 @@ let originalLaunch;
 before(() => {
     home = mkdtempSync('/tmp/crtr-snapshot-fields-');
     process.env['CRTR_HOME'] = home;
+    // Every launcher claims a slot from the ledger before it reaches the host, so
+    // a spawn in-process needs a bound fleet (D-2).
+    bindTestFleet();
     originalLaunch = headlessBrokerHost.launch;
     headlessBrokerHost.launch = (nodeId) => {
         const broker = createServer();
@@ -29,6 +34,7 @@ before(() => {
 });
 after(async () => {
     headlessBrokerHost.launch = originalLaunch;
+    resetFleetForTests();
     await Promise.all(brokers.map((broker) => new Promise((resolve) => {
         if (broker.listening)
             broker.close(() => resolve());

package/dist/daemon/api/__tests__/node-create-description.test.js

@@ -7,6 +7,8 @@ import { closeDb } from '../../../core/canvas/db.js';
 import { getNode } from '../../../core/canvas/canvas.js';
 import { nodeDir } from '../../../core/canvas/paths.js';
 import { headlessBrokerHost } from '../../../core/runtime/host.js';
+import { resetFleetForTests } from '../../../core/runtime/fleet.js';
+import { bindTestFleet } from '../../../core/__tests__/helpers/fleet.js';
 import { handleCreate, nodeRoutes } from '../handlers/nodes.js';
 import { brokerOperationRoutes } from '../handlers/broker-ops.js';
 let home = '';
@@ -18,6 +20,9 @@ before(() => {
     // macOS Unix-domain sockets have a short path limit; keep the canvas home short.
     home = mkdtempSync('/tmp/crtr-node-description-');
     process.env['CRTR_HOME'] = home;
+    // Every launcher claims a slot from the ledger before it reaches the host, so
+    // a spawn in-process needs a bound fleet (D-2).
+    bindTestFleet();
     originalLaunch = headlessBrokerHost.launch;
     headlessBrokerHost.launch = (nodeId) => {
         const broker = createServer();
@@ -28,6 +33,7 @@ before(() => {
 });
 after(async () => {
     headlessBrokerHost.launch = originalLaunch;
+    resetFleetForTests();
     await Promise.all(brokers.map((broker) => new Promise((resolve) => {
         if (broker.listening)
             broker.close(() => resolve());

package/dist/daemon/api/__tests__/profile-launch-gates.test.js

@@ -78,7 +78,7 @@ test('revive refuses a paused profile before launching a broker', () => {
         parent: null,
         profile_id: profile.profileId,
     });
-    assert.throws(() => reviveNode(nodeId, { resume: true }), (error) => {
+    assert.throws(() => reviveNode(nodeId, { resume: true, capacity: 'freeze' }), (error) => {
         assert.ok(error instanceof CrtrError);
         assert.equal(error.code, 'usage');
         assert.match(error.details?.['next'], new RegExp(`crtr profile resume ${profile.profileId}`));

package/dist/daemon/api/bridge.js

@@ -359,7 +359,11 @@ export async function handleAttachUpgrade(req, socket, head, nodeId) {
             // pass only `{ resume }`.
             let launchExited;
             try {
-                const result = reviveNode(nodeId, { resume: true });
+                // The bridge upgrade waits on this node's view socket, which only a
+                // live broker publishes: at the cap, refuse the upgrade with the real
+                // reason instead of freezing and then timing out on a socket that was
+                // never going to appear.
+                const result = reviveNode(nodeId, { resume: true, capacity: 'refuse' });
                 launchExited = result.launch?.exited;
             }
             catch (err) {

package/dist/daemon/api/handlers/attach.js

@@ -36,7 +36,11 @@ async function handleAttach(ctx) {
         // reviveNode is the ONLY sanctioned broker launcher; a double-revive of a
         // live node is an idempotent no-op (no `launch` handle) — `revived` reflects
         // whether a fresh engine actually started.
-        const result = reviveNode(id, { resume });
+        // An attach has a viewer waiting on a socket that only a live broker
+        // publishes, so there is nothing to wait for it with: refuse at the cap and
+        // let the caller see why, rather than freezing and returning a `revived`
+        // that never becomes true.
+        const result = reviveNode(id, { resume, capacity: 'refuse' });
         revived = result.launch !== undefined;
         resumed = result.resumed;
         // If we launched, let the broker publish its view socket so the local

package/dist/daemon/api/handlers/bash-jobs.js

@@ -77,7 +77,7 @@ async function handleStop(ctx) {
     const node = getNode(nodeId);
     if (node !== null && !isBrokerLive(node)) {
         try {
-            reviveNode(nodeId, { resume: true });
+            reviveNode(nodeId, { resume: true, capacity: 'freeze' });
         }
         catch { /* the notice remains durable */ }
     }

package/dist/daemon/api/handlers/messages.js

@@ -221,7 +221,9 @@ async function handleMessage(ctx) {
             appendSituationalContext(id, sidecar);
         if (req.reopen)
             commitReopen(id, expectedFinalReport);
-        const result = reviveNode(id, { resume: false });
+        // A fresh revive appends no inbox entry, so nothing survives a freeze for
+        // the daemon to act on later: at the cap the caller is told, not ignored.
+        const result = reviveNode(id, { resume: false, capacity: 'refuse' });
         const body = {
             node_id: id,
             delivered: false,
@@ -324,10 +326,15 @@ async function handleMessage(ctx) {
     // A wake-capable tier revives a dormant target so its inbox-watcher delivers
     // this; deferred never wakes — it rides the target's next natural cycle.
     let revived = false;
+    let frozen = false;
     if (tier !== 'deferred' && !paused && !isBrokerLive(meta)) {
         try {
-            const result = reviveNode(id, { resume: true });
+            // The entry is already durable, so a wake denied for capacity is only
+            // delayed: the row freezes and the tick relaunches it — at which point
+            // the inbox watcher delivers this entry as it always would.
+            const result = reviveNode(id, { resume: true, capacity: 'freeze' });
             revived = result.launch !== undefined;
+            frozen = result.outcome === 'frozen';
         }
         catch {
             /* best-effort wake — the entry is durably appended regardless */
@@ -337,6 +344,7 @@ async function handleMessage(ctx) {
         node_id: id,
         delivered: true,
         revived,
+        ...(frozen ? { not_revived_reason: 'capacity_frozen' } : {}),
         delivered_at: entry.ts,
         ...(req.delivery === 'interactive' ? { delivered_via: 'inbox' } : {}),
     };

package/dist/daemon/api/handlers/nodes.js

@@ -108,9 +108,6 @@ function parseCreateBody(body) {
         rootLifecycle !== 'terminal') {
         throw usage("root_lifecycle must be 'resident' or 'terminal'");
     }
-    if (rootLifecycle !== undefined && b['root'] !== true) {
-        throw usage('root_lifecycle is only valid with root: true');
-    }
     return b;
 }
 /** Build the immediate spawn recipe. */
@@ -490,6 +487,9 @@ function handleRevive(ctx) {
     const cron = !resume && body?.cron_id !== undefined ? getCron(body.cron_id) : null;
     const result = reviveNode(id, {
         resume,
+        // An explicit revive is a caller asking for this node NOW; at the cap it
+        // gets the refusal naming it rather than a silent nothing-happened.
+        capacity: 'refuse',
         ...(cron !== null ? { wakeReason: cronWakeOrigin(cron, 'schedule_revive') } : {}),
     });
     const status = (getNode(id)?.status ?? 'active');
@@ -603,7 +603,11 @@ function handleWait(ctx) {
 }
 function handleReviveAll() {
     const result = reviveAll();
-    const body = { revived: [...result.revived], failed: [...result.failed] };
+    const body = {
+        revived: [...result.revived],
+        failed: [...result.failed],
+        frozen: [...result.frozen],
+    };
     return { status: 200, body };
 }
 // PATCH /v1/nodes/{id}/config — model / situational-context (spec §6.2)

package/dist/daemon/api/handlers/worktree.js

@@ -12,13 +12,22 @@
 // all of that onto `CrtrError` for every route that can raise it — so the CLI
 // leaf can reconstruct the original agent-facing contract instead of collapsing
 // to a generic status code.
-import { closeManagedWorktree } from '../../../core/worktree.js';
+import { abandonManagedWorktree, closeManagedWorktree } from '../../../core/worktree.js';
+import { usage } from '../../../core/errors.js';
 function handleWorktreeClose(ctx) {
     const id = ctx.params['id'];
     // No requireMeta: closeManagedWorktree already throws the precise
     // `unknown_node` / `no_managed_worktree` WorktreeError for a bad id.
     return { status: 200, body: closeManagedWorktree(id) };
 }
+function handleWorktreeAbandon(ctx) {
+    const rawBy = ctx.body?.['by'];
+    const by = typeof rawBy === 'string' ? rawBy.trim() : '';
+    if (by === '')
+        throw usage('abandon requires a non-empty invoking identity', { received: ctx.body, next: 'Pass the invoking node id or human identity.' });
+    return { status: 200, body: abandonManagedWorktree(ctx.params['id'], by) };
+}
 export const worktreeRoutes = [
     { method: 'POST', pattern: '/v1/nodes/:id/worktree/close', handler: handleWorktreeClose },
+    { method: 'POST', pattern: '/v1/nodes/:id/worktree/abandon', handler: handleWorktreeAbandon },
 ];

package/dist/daemon/api/map.js

@@ -38,6 +38,8 @@ export function toNodeSummaryDTO(row) {
         created: row.created,
         intent: row.intent,
         waiting_for: row.waiting_for,
+        frozen_at: row.frozen_at ?? null,
+        terminal_reason: row.terminal_reason ?? null,
         pi_pid: row.pi_pid,
         pi_pid_identity: row.pi_pid_identity,
         window: row.window,
@@ -85,6 +87,8 @@ export function toNodeWorktreeDTO(w) {
         dto.cleanup = w.cleanup;
     if (w.closed !== undefined)
         dto.closed = w.closed;
+    if (w.abandoned !== undefined)
+        dto.abandoned = { ...w.abandoned };
     return dto;
 }
 /** Project the hydrated node view (`getNode` → `NodeMeta`) into a detail DTO.
@@ -106,6 +110,8 @@ export function toNodeDetailDTO(meta, edges) {
         created: meta.created,
         intent: (meta.intent ?? null),
         waiting_for: meta.waiting_for ?? null,
+        frozen_at: meta.frozen_at ?? null,
+        terminal_reason: meta.terminal_reason ?? null,
         pi_pid: meta.pi_pid ?? null,
         pi_pid_identity: meta.pi_pid_identity ?? null,
         window: meta.window ?? null,
@@ -154,6 +160,7 @@ export function toReviveResultDTO(nodeId, result, status) {
         revived: result.launch !== undefined,
         resumed: result.resumed,
         status,
+        outcome: result.outcome,
     };
 }
 /** Project a `closeNode` cascade result. Field names align 1:1. */

package/dist/daemon/companion-retire.js

@@ -29,7 +29,7 @@ export async function retireCompanion(nodeId, outcome) {
         catch { /* the canonical final is authoritative */ }
         return result;
     }
-    transition(nodeId, 'cancel');
+    transition(nodeId, 'cancel', { reason: 'retired' });
     if (node.status === 'active' || node.status === 'idle') {
         try {
             headlessBrokerHost.teardown(nodeId);

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

@@ -1,11 +1,6 @@
-import { type Cron } from '../../core/canvas/crons.js';
 export interface RunDueCronOptions {
     /** Registers settlement work for graceful-teardown draining. */
     register?: (work: Promise<void>) => void;
-    /** Node-launching runs need capacity; absent means all runs are admitted. */
-    hasBrokerCapacity?: () => boolean;
 }
-export declare function cronLaunchesNode(c: Cron): boolean;
 export declare function expireDueCrons(nowIso: string): void;
 export declare function applyOverlapPolicies(now: number, nowIso: string): void;
-export declare function emitCapacityDeferral(now: number, deferred: number): void;

package/dist/daemon/cron/passes.js

@@ -3,17 +3,9 @@ import { cronDaemonInstanceId, liveRunFor } from './live-runs.js';
 import { advanceCron, cancelCron, dueOverlapCrons, expiredIdleCrons, listCronRuns, recordCronRun, } from '../../core/canvas/crons.js';
 import { emitEvent } from '../../core/events/emit.js';
 import { nextSlotAfter } from '../../core/wake.js';
-import { parseSink } from '../cron-sink.js';
 /** Lead of a `cron_runs.delivered` string written by the overlap=skip pass.
  *  Matched (not just written) — see `latestRunIsSkip`. */
 const SKIP_MARKER = 'skipped (overlap=skip)';
-// A false negative is an ungated run; a false positive delays one poll at capacity.
-const NODE_LAUNCHING_COMMAND = /\bcrtr\b[^\n]*?\bnode\s+lifecycle\s+revive\b|\bcrtr\b[^\n]*?\bnode\s+new\b|\bcrtr\b[^\n]*?\bcanvas\s+revive\b|\bcrtr\b[^\n]*?\bnode\s+message\s+send\b[^\n]*?\s--fresh\b/;
-export function cronLaunchesNode(c) {
-    if (parseSink(c.sink)?.kind === 'spawn')
-        return true;
-    return NODE_LAUNCHING_COMMAND.test(c.command);
-}
 export function expireDueCrons(nowIso) {
     for (const c of expiredIdleCrons(nowIso)) {
         cancelCron(c.cron_id);
@@ -64,15 +56,3 @@ export function applyOverlapPolicies(now, nowIso) {
         }
     }
 }
-const CAPACITY_DEFER_LOG_THROTTLE_MS = 30_000;
-let lastCapacityDeferLogAt = Number.NEGATIVE_INFINITY;
-export function emitCapacityDeferral(now, deferred) {
-    if (now - lastCapacityDeferLogAt < CAPACITY_DEFER_LOG_THROTTLE_MS)
-        return;
-    lastCapacityDeferLogAt = now;
-    emitEvent({
-        level: 'warn',
-        event: 'cron.capacity.run_deferred',
-        fields: { deferred_runs: deferred },
-    });
-}

package/dist/daemon/cron/sinks.js

@@ -33,7 +33,7 @@ function deliverNodeSink(c, target, stdout) {
     // The durable append succeeds even if its best-effort wake fails.
     if (c.tier !== 'deferred' && !isBrokerLive(meta)) {
         try {
-            reviveNode(target, { resume: true });
+            reviveNode(target, { resume: true, capacity: 'freeze' });
         }
         catch {
             /* best-effort wake — the entry is durably appended regardless */