@north-light/crouter 0.3.249 → 0.3.250

package/dist/core/runtime/placement.js

@@ -23,9 +23,10 @@
 //     model-over-driver. Raw driver access is confined to placement, its pure
 //     tmux half, the bindings owner, and tmux chrome.
 import { envNodeId } from '../../shared/env.js';
-import { getNode, fullName, deleteNode, listNodes, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, } from '../canvas/index.js';
+import { getNode, fullName, deleteNode, listNodes, subscribersOf, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, } from '../canvas/index.js';
 import { nodeHasAssistantMessage, isStreaming } from '../canvas/render-source.js';
 import { headlessBrokerHost } from './host.js';
+import { fanDoctrineWake } from './close.js';
 import { paneExists, paneLocation, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, respawnPaneSync, windowOfPane, renameWindow, } from './tmux-driver.js';
 // The PURE tmux + broker-socket half now lives in placement-tmux.ts. placement
 // composes the viewer OPENER over openViewerPane (tmux) + registerViewerFocus
@@ -351,12 +352,12 @@ export function reapIfEmpty(nodeId, keepPane) {
 }
 /** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
  *  behind `crtr canvas prune --empty`, for the husks that accumulated before
- *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), nodes
- *  mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a running
- *  engine is the daemon's domain and may have output not yet persisted, so bulk
- *  GC never kills one (the per-action {@link reapIfEmpty} does, since the user
- *  explicitly closed/detached that node). `dryRun` reports candidates without
- *  deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
+ *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), dead rows,
+ *  nodes mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a
+ *  running engine is the daemon's domain and may have output not yet persisted,
+ *  so bulk GC never kills one (the per-action {@link reapIfEmpty} does, since
+ *  the user explicitly closed/detached that node). `dryRun` reports candidates
+ *  without deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
 export function reapEmptyNodes(opts = {}) {
     const dryRun = opts.dryRun ?? false;
     const selfId = envNodeId() ?? '';
@@ -364,9 +365,15 @@ export function reapEmptyNodes(opts = {}) {
     for (const row of listNodes()) {
         const id = row.node_id;
         const meta = getNode(id);
-        if (id === selfId || isPidAlive(row.pi_pid) || meta?.managed_worktree?.state === 'open' || !isEmptyNode(id))
+        if (id === selfId
+            || row.status === 'dead'
+            || isPidAlive(row.pi_pid)
+            || meta?.managed_worktree?.state === 'open'
+            || !isEmptyNode(id))
             continue;
+        const subscribers = subscribersOf(id);
         if (!dryRun) {
+            fanDoctrineWake(id, subscribers, `Child closed — ${meta?.name ?? id} (${id}) was closed from the canvas and is no longer running.`, { reason: 'child-closed', child: id });
             headlessBrokerHost.teardown(id);
             tearDownNode(id);
             if (!deleteNode(id).deleted)

package/dist/core/runtime/reset.js

@@ -22,7 +22,7 @@
 // Best-effort throughout: a tmux/fs failure on one node never aborts the reap.
 import { getNode, updateNode, fullName, closeFocusRow, view, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
-import { headlessBrokerHost } from './host.js';
+import { headlessBrokerHost, requestBrokerTeardown } from './host.js';
 import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPane, renameWindow, } from './placement.js';
 import { viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
@@ -51,7 +51,7 @@ export function reapDescendants(rootId) {
             // viewer pane + registry row (attach auto-reconnects, so the viewer must be
             // closed here or it lingers ~30s in a misleading "reconnecting…" state).
             transition(id, 'cancel', { reason: 'closed' });
-            headlessBrokerHost.teardown(id);
+            requestBrokerTeardown(id);
             tearDownNode(id);
             reaped.push(id);
         }

package/dist/core/runtime/revive.js

@@ -22,9 +22,9 @@
 // and there is goal/roadmap ground state to re-enter on.
 //
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
-import { findNodeBySessionFile, getNode, updateNode, clearPid, recordPid, setFrozen, clearFrozen, fullName, subscribersOf, } from '../canvas/index.js';
+import { findNodeBySessionFile, getNode, updateNode, clearPid, recordLaunch, recordPid, setFrozen, clearFrozen, fullName, subscribersOf, } from '../canvas/index.js';
 import { emitEvent } from '../events/emit.js';
 import { cancelCronsOnWake } from '../canvas/crons.js';
 import { isParked, transition } from './lifecycle.js';
@@ -41,6 +41,7 @@ import { clearContextExposureState, initializeForkContextExposure, } from '../su
 import { rootOfSpine } from './nodes.js';
 import { isReviewCompanionBound } from '../review/companion.js';
 import { assertProfileActive } from '../profiles/manifest.js';
+import { isPidAlive } from '../canvas/pid.js';
 // resumeArgs — which session source a revive resumes from
 /** Pick the `--session` source for a revive. Both resume=true (a true resume)
  *  and resume=false (a refresh-yield) resume by the absolute session-file path
@@ -64,6 +65,40 @@ export function resumeArgs(meta, resume) {
         return {};
     return resume ? { resumeSessionPath: path } : { resumeSessionPath: path, newCycle: true };
 }
+/** Return false only when a valid Pi session header positively names a cwd that
+ * has gone away. Missing/corrupt headers remain the engine's concern: old
+ * fixtures and partial transcripts do not prove a cwd mismatch. */
+function sessionCwdExists(sessionFile) {
+    try {
+        for (const line of readFileSync(sessionFile, 'utf8').split('\n')) {
+            if (line.trim() === '')
+                continue;
+            const entry = JSON.parse(line);
+            if (entry.type !== 'session')
+                continue;
+            return typeof entry.cwd !== 'string' || existsSync(entry.cwd);
+        }
+    }
+    catch {
+        // The broker/engine owns malformed-transcript diagnostics; it is not proof
+        // that the stored cwd is absent.
+    }
+    return true;
+}
+/** The session-file preflight has two ordered vetoes. A live owner wins before
+ * inspecting its transcript, so this node can never adopt or clear another
+ * broker's file. Only an unowned/dead-owner file then reaches the cwd check. */
+function resumableSessionArgs(nodeId, meta, resume) {
+    const path = meta.pi_session_file;
+    if (path == null || path === '' || !existsSync(path))
+        return {};
+    const owner = findNodeBySessionFile(path);
+    if (owner !== null && owner.node_id !== nodeId && isPidAlive(owner.pi_pid))
+        return {};
+    if (!sessionCwdExists(path))
+        return {};
+    return resumeArgs(meta, resume);
+}
 // Return type
 /** A relaunch that has NO transcript to resume or branch from, and no durable
  *  work state on disk (no roadmap, no yield note), is not a revive at all — the
@@ -262,7 +297,7 @@ function launchRevive(nodeId, meta, opts) {
     const refreshPending = meta.intent === 'refresh' || meta.cycle_pending === true;
     const parkedReentry = isParked(meta) && hasFreshGroundState(nodeId) && hasUnseenWakeMail(nodeId);
     const effectiveResume = refreshPending || parkedReentry ? false : opts.resume;
-    const resume = forkBirthPending ? {} : resumeArgs(meta, effectiveResume);
+    const resume = forkBirthPending ? {} : resumableSessionArgs(nodeId, meta, effectiveResume);
     // hasSessionPath: there is a real `.jsonl` to hand pi via `--session`, whether
     // as a true resume OR a cycling refresh-yield (resumeArgs sets `newCycle` in
     // the latter case). cycling and resuming are mutually exclusive; `resuming`
@@ -354,7 +389,7 @@ function launchRevive(nodeId, meta, opts) {
     // this marker advertised. Snapshot the boot-fault attempt in the SAME
     // breath (see beginBootFaultAttempt): its own verification, not this call's
     // unchecked result, is what scopes a later diagnostic read to this attempt.
-    clearFault(nodeId);
+    clearFault(nodeId, { preserveProviderRetryEpisode: true });
     const bootFault = beginBootFaultAttempt(nodeId);
     // A cron armed --cancel-on-wake belongs to the dormancy being left, so a WAKE
     // of its anchor deletes it — an inbox delivery, an attach, an explicit
@@ -394,6 +429,7 @@ function launchRevive(nodeId, meta, opts) {
         clearPid(nodeId);
         throw new Error(`[broker] refusing to revive ${nodeId}: ${error.message}`);
     }
+    recordLaunch(nodeId, new Date().toISOString());
     // Record the real broker pid. The pid is METADATA now (design D-13) — the
     // liveness authority is the fleet entry registered synchronously inside
     // `launch` above — but session_start re-records it after extension bind,

package/dist/core/runtime/spawn.d.ts

@@ -11,6 +11,9 @@ export interface SpawnChildOpts {
     prompt: string;
     /** Override the parent (defaults to the calling node from env). */
     parent?: string;
+    /** Actor that created this node. Unlike parent (manager) and spawned_by
+     *  (provenance), it controls the parent's birth announcement. */
+    creator?: string | null;
     /** Spawn an INDEPENDENT root instead of a managed child: parent=null, no
      *  subscription back to the spawner, spawned_by=spawner. Resident and brought
      *  forefront by default — see `rootLifecycle` for the unattended variant. */

package/dist/core/runtime/spawn.js

@@ -275,6 +275,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             // records spawned_by=spawner when a node (not a human shell) spawned it.
             // A child's parent IS its manager.
             parent: root ? null : spawner,
+            creator: opts.creator,
             spawnedBy: root ? (spawner ?? undefined) : undefined,
             profile_id: profileId,
             forkFrom: opts.forkFrom,

package/dist/core/runtime/warm-pool.d.ts

@@ -24,6 +24,10 @@ export interface WarmRequest {
     model: string | null;
     situationalContext: string | null;
     name: string | null;
+    /** Node that asked for this create, or null for an external process. Claim-time
+     *  identity like `name` — a spare is minted creator-less and adopts the
+     *  claimant's, so provenance survives the warm path. */
+    creator: string | null;
 }
 /** Claim a spare for `request`, reshaped onto its persona — or null when the
  *  pool cannot serve it. The caller falls back to a cold spawn; a claim never

package/dist/core/runtime/warm-pool.js

@@ -128,6 +128,7 @@ export async function claimWarmNode(request) {
         kind: request.kind,
         mode: request.mode,
         name: request.name ?? request.kind,
+        creator: request.creator,
         // The recipe a later revive replays — skip it and the node silently comes
         // back as the spare's persona.
         launch: recipe.launch,
@@ -354,6 +355,7 @@ export function prewarmRecentRecipes() {
                 model: null,
                 situationalContext: null,
                 name: null,
+                creator: null,
             }).then(mint).catch((err) => console.error(`[warm-pool] prewarm failed for ${candidate.cwd}: ${err.message}`));
         }
         catch (err) {

package/dist/core/worktree.d.ts

@@ -57,9 +57,10 @@ interface CleanEmptyProof {
  *  be a git-ancestor of (or equal to) the CURRENT tip of its recorded base
  *  branch — i.e. landing it would be a pure no-op. Any ambiguity (missing
  *  path, mid-rebase, wrong branch, an unresolvable base, or a real ancestry
- *  divergence) returns null: this function only ever proves a no-op land
- *  when a live git check establishes it, never on a heuristic guess, so real
- *  unlanded work always falls through to the explicit-close guard. The locked
+ *  divergence) returns null. A missing base is the one exception: equality
+ *  between the live HEAD and recorded creation SHA proves no work was added.
+ *  This function only ever proves a no-op land from live Git state, never on
+ *  a heuristic guess, so real unlanded work always falls through to the explicit-close guard. The locked
  *  path re-checks this predicate before recording deferred cleanup; production
  *  code must always go through `autoDropCleanManagedWorktree`. */
 export declare function proveCleanEmptyManagedWorktree(wt: ManagedWorktree): CleanEmptyProof | null;

package/dist/core/worktree.js

@@ -51,9 +51,17 @@ function resolveLandableBase(repoRoot, baseRef) {
     // syntax, which could turn a SHA or a `^{commit}` suffix into a non-landable
     // base even though no local branch by that exact name exists.
     const exists = gitSync(['show-ref', '--verify', '--quiet', ref], repoRoot);
-    if (exists.status !== 0) {
+    // `show-ref --verify --quiet` reserves exit 1 for an absent ref. gitSync
+    // preserves that numeric status for compatibility, but marks spawn failures,
+    // timeouts, and signal exits so they cannot masquerade as an absent branch.
+    if (exists.status === 1 && exists.executionFailed !== true) {
         throw new WorktreeError('missing_base_branch', `managed worktree base '${baseRef}' does not name an existing local branch`, 'The base must be a local branch that landing can fast-forward — freshen your local branch from origin first (rebase-not-merge), then base on it.');
     }
+    if (exists.status !== 0) {
+        const stderr = exists.stderr.trim() || '<empty>';
+        const execution = exists.processError === undefined ? '' : `\nprocess error: ${exists.processError}`;
+        throw new WorktreeError('base_branch_inspection_failed', `could not inspect local base branch '${baseRef}' (git show-ref exited with status ${exists.status})`, 'Inspect the repository and its Git metadata, then retry.', `status: ${exists.status}\nstderr: ${stderr}${execution}`);
+    }
     return runGit(repoRoot, ['rev-parse', '--verify', ref], 'base_branch_resolve_failed', 'Inspect the local base branch, then retry.');
 }
 /** Path of the worktree where a local branch is currently checked out, or null
@@ -238,16 +246,23 @@ export function isRebaseInProgress(cwd) {
     return existsSync(gitPath(cwd, 'rebase-merge')) || existsSync(gitPath(cwd, 'rebase-apply'));
 }
 /** The ONE authoritative closed-worktree state transition, shared by both
- *  closing paths (explicit `closeManagedWorktreeLocked` land, and the clean
- *  `autoDropCleanManagedWorktreeLocked` push-final drop): persist
- *  `managed_worktree.state: 'closed'`, name its cleanup state, and repoint the
- *  node's launch `cwd` to the durable base checkout atomically in the same
- *  `updateNode` write. A live node keeps its checkout intact for explicit
- *  post-exit cleanup: `git worktree remove` recursively deletes the caller's
- *  cwd and cannot safely run against it. Both closing paths MUST go through this helper instead of
- *  hand-rolling the `updateNode` call, so neither can drift out of sync. */
+ * closing paths (explicit `closeManagedWorktreeLocked` land, and the clean
+ * `autoDropCleanManagedWorktreeLocked` push-final drop): persist
+ * `managed_worktree.state: 'closed'`, name its cleanup state, and repoint the
+ * node's launch `cwd` to the durable base checkout. The caller broker stays
+ * alive and is Pi's sole transcript writer, so its session header cannot be
+ * safely rewritten here; clear the session coordinates and let the later
+ * revive launch fresh instead. Both closing paths MUST go through this helper
+ * instead of hand-rolling the `updateNode` call, so neither can drift out of
+ * sync. */
 function persistClosedWorktreeState(nodeId, wt, cleanup = 'pending') {
-    updateNode(nodeId, { cwd: wt.repo_root, managed_worktree: { ...wt, state: 'closed', cleanup, closed: new Date().toISOString() } });
+    const node = getNode(nodeId);
+    const sessionInvalidated = node?.pi_session_id != null || node?.pi_session_file != null;
+    updateNode(nodeId, {
+        cwd: wt.repo_root,
+        ...(sessionInvalidated ? { pi_session_id: null, pi_session_file: null } : {}),
+        managed_worktree: { ...wt, state: 'closed', cleanup, closed: new Date().toISOString() },
+    });
 }
 function deferredCleanupResult(wt) {
     const remove = `git -C ${shellQuote(wt.repo_root)} worktree remove ${shellQuote(wt.path)}`;
@@ -301,7 +316,29 @@ function closeManagedWorktreeLocked(nodeId) {
         const found = branch === 'HEAD' ? 'detached HEAD' : branch;
         throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}, found ${found})`, `Check out ${wt.branch} in ${wt.path} before closing, or ask the user with \`crtr human send\` if you are unsure why it changed, then rerun \`crtr node worktree close\`.`);
     }
-    const baseSha = resolveLandableBase(wt.repo_root, wt.base_ref);
+    let baseSha;
+    try {
+        // `repo_root` is the checkout that created this child, and it can vanish
+        // when that parent finishes first. The live managed checkout still names
+        // the shared repository and is the authority for every close operation.
+        baseSha = resolveLandableBase(wt.path, wt.base_ref);
+    }
+    catch (error) {
+        // A deleted parent base cannot receive a fast-forward. A clean child at
+        // its recorded creation SHA has nothing to land, however, so conclude its
+        // deferred cleanup without guessing where work should go.
+        const head = runGit(wt.path, ['rev-parse', 'HEAD'], 'landed_sha_failed', 'Inspect the worktree checkout manually, then rerun `crtr node worktree close`.');
+        if (!(error instanceof WorktreeError) || error.code !== 'missing_base_branch' || head !== wt.base_sha)
+            throw error;
+        persistClosedWorktreeState(nodeId, wt, 'pending');
+        return {
+            node_id: nodeId,
+            branch: wt.branch,
+            worktree_path: wt.path,
+            landed_sha: wt.base_sha,
+            ...deferredCleanupResult(wt),
+        };
+    }
     const rebase = gitSync(['rebase', baseSha], wt.path);
     if (rebase.status !== 0) {
         const detail = (rebase.stderr.trim() || rebase.stdout.trim()).trim();
@@ -312,11 +349,11 @@ function closeManagedWorktreeLocked(nodeId) {
     // captured baseSha — landing is purely local, nothing is ever pushed to
     // origin. Both landing paths require the base to still be exactly at that
     // captured tip, so neither can overwrite a concurrent base change.
-    const fastForward = gitSync(['merge-base', '--is-ancestor', baseSha, landedSha], wt.repo_root);
+    const fastForward = gitSync(['merge-base', '--is-ancestor', baseSha, landedSha], wt.path);
     if (fastForward.status !== 0) {
         throw new WorktreeError('land_base_failed', `rebased worktree is not a fast-forward of local base branch '${wt.base_ref}'`, 'Ask the user with `crtr human send` how to land this managed worktree.', (fastForward.stderr.trim() || fastForward.stdout.trim()).trim());
     }
-    const baseCheckout = checkoutPathForBranch(wt.repo_root, wt.base_ref);
+    const baseCheckout = checkoutPathForBranch(wt.path, wt.base_ref);
     if (baseCheckout !== null) {
         const checkoutHead = gitSync(['rev-parse', 'HEAD'], baseCheckout);
         const actualHead = checkoutHead.stdout.trim();
@@ -329,7 +366,7 @@ function closeManagedWorktreeLocked(nodeId) {
     }
     const land = baseCheckout !== null
         ? gitSync(['merge', '--ff-only', landedSha], baseCheckout)
-        : gitSync(['update-ref', `refs/heads/${wt.base_ref}`, landedSha, baseSha], wt.repo_root);
+        : gitSync(['update-ref', `refs/heads/${wt.base_ref}`, landedSha, baseSha], wt.path);
     if (land.status !== 0) {
         const detail = (land.stderr.trim() || land.stdout.trim()).trim();
         throw new WorktreeError('land_base_failed', `could not fast-forward local base branch '${wt.base_ref}' to this worktree`, baseCheckout !== null
@@ -356,7 +393,10 @@ export function closeManagedWorktree(nodeId) {
     // repository to lock; every state-mutating close path runs under the lock.
     if (wt === null)
         return closeManagedWorktreeLocked(nodeId);
-    return withRepositoryWorktreeLock(wt.repo_root, () => closeManagedWorktreeLocked(nodeId));
+    // An absent checkout has no live Git directory; its separate recovery proof
+    // still relies on the recorded repository path. Every live close locks from
+    // the child checkout instead of the parent that created it.
+    return withRepositoryWorktreeLock(existsSync(wt.path) ? wt.path : wt.repo_root, () => closeManagedWorktreeLocked(nodeId));
 }
 const ABANDON_AUTHOR_NAME = 'crtr-abandon';
 const ABANDON_AUTHOR_EMAIL = 'crtr-abandon@localhost';
@@ -519,9 +559,10 @@ export function missingWorktreeRecoveryHint(wt) {
  *  be a git-ancestor of (or equal to) the CURRENT tip of its recorded base
  *  branch — i.e. landing it would be a pure no-op. Any ambiguity (missing
  *  path, mid-rebase, wrong branch, an unresolvable base, or a real ancestry
- *  divergence) returns null: this function only ever proves a no-op land
- *  when a live git check establishes it, never on a heuristic guess, so real
- *  unlanded work always falls through to the explicit-close guard. The locked
+ *  divergence) returns null. A missing base is the one exception: equality
+ *  between the live HEAD and recorded creation SHA proves no work was added.
+ *  This function only ever proves a no-op land from live Git state, never on
+ *  a heuristic guess, so real unlanded work always falls through to the explicit-close guard. The locked
  *  path re-checks this predicate before recording deferred cleanup; production
  *  code must always go through `autoDropCleanManagedWorktree`. */
 export function proveCleanEmptyManagedWorktree(wt) {
@@ -537,18 +578,23 @@ export function proveCleanEmptyManagedWorktree(wt) {
     const status = gitSync(['status', '--porcelain'], wt.path);
     if (status.status !== 0 || status.stdout.trim() !== '')
         return null;
-    let baseSha;
-    try {
-        baseSha = resolveLandableBase(wt.repo_root, wt.base_ref);
-    }
-    catch {
-        return null;
-    }
     const head = gitSync(['rev-parse', 'HEAD'], wt.path);
     if (head.status !== 0)
         return null;
     const branchSha = head.stdout.trim();
-    const ancestor = gitSync(['merge-base', '--is-ancestor', branchSha, baseSha], wt.repo_root);
+    let baseSha;
+    try {
+        baseSha = resolveLandableBase(wt.path, wt.base_ref);
+    }
+    catch (error) {
+        // A parent-first close can remove the recorded base branch. Equality with
+        // the durable creation SHA proves this clean child never added work.
+        if (error instanceof WorktreeError && error.code === 'missing_base_branch' && branchSha === wt.base_sha) {
+            return { branchSha, baseSha: wt.base_sha };
+        }
+        throw error;
+    }
+    const ancestor = gitSync(['merge-base', '--is-ancestor', branchSha, baseSha], wt.path);
     if (ancestor.status !== 0)
         return null;
     return { branchSha, baseSha };
@@ -612,7 +658,7 @@ export function autoDropCleanManagedWorktree(nodeId) {
     const pathAbsent = !existsSync(wt.path);
     if (pathAbsent ? proveAbsentPathManagedWorktree(wt) === null : proveCleanEmptyManagedWorktree(wt) === null)
         return null;
-    return withRepositoryWorktreeLock(wt.repo_root, () => {
+    return withRepositoryWorktreeLock(pathAbsent ? wt.repo_root : wt.path, () => {
         // Re-fetch inside the lock: state may have changed since the caller's
         // hasOpenManagedWorktree check ran outside it.
         const locked = openManagedWorktreeForNode(nodeId);

package/dist/daemon/__tests__/integration/api-startup-readiness.test.d.ts

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

package/dist/daemon/__tests__/integration/api-startup-readiness.test.js

@@ -0,0 +1,81 @@
+// Regression for NL-159 / #571: the daemon's pidfile/ownership claim must not
+// survive a failed mandatory Unix API bind. A directory at the socket path
+// deterministically makes `listen()` emit EADDRINUSE without touching crtrd's
+// real canvas or runtime homes.
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import test from 'node:test';
+import { closeDb } from '../../../core/canvas/db.js';
+import { claimDaemonOwnership, releaseDaemonOwnership } from '../../../core/canvas/daemon-owner.js';
+import { resetEventSourceForTests } from '../../../core/events/source.js';
+import { resetFleetForTests } from '../../../core/runtime/fleet.js';
+import { runDaemon } from '../../crtrd.js';
+import { spawnDaemon } from '../../manage.js';
+const isolatedEnvKeys = [
+    'HOME',
+    'CRTR_HOME',
+    'CRTR_PIDFILE',
+    'CRTR_RUNTIME_HOME',
+    'XDG_CACHE_HOME',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+    'PI_CODING_AGENT_DIR',
+];
+test('a Unix socket bind failure rejects readiness and releases daemon ownership', async () => {
+    const root = mkdtempSync('/tmp/crtr-api-bind-failure-');
+    const home = join(root, 'home');
+    const canvasHome = join(root, 'canvas');
+    const socketPath = join(canvasHome, 'crtrd.sock');
+    const previousCwd = process.cwd();
+    const previousEnv = new Map(isolatedEnvKeys.map((key) => [key, process.env[key]]));
+    mkdirSync(home, { recursive: true });
+    mkdirSync(socketPath, { recursive: true });
+    try {
+        process.chdir(home);
+        process.env['HOME'] = home;
+        process.env['CRTR_HOME'] = canvasHome;
+        process.env['CRTR_PIDFILE'] = join(canvasHome, 'crtrd.pid');
+        process.env['CRTR_RUNTIME_HOME'] = join(root, 'runtime');
+        process.env['XDG_CACHE_HOME'] = join(root, 'cache');
+        process.env['XDG_CONFIG_HOME'] = join(root, 'config');
+        process.env['XDG_DATA_HOME'] = join(root, 'data');
+        process.env['PI_CODING_AGENT_DIR'] = join(home, '.pi', 'agent');
+        closeDb();
+        resetEventSourceForTests();
+        resetFleetForTests();
+        await assert.rejects(() => runDaemon(), (error) => error.code === 'EADDRINUSE', 'the mandatory API socket bind must reject startup');
+        const pidfile = process.env['CRTR_PIDFILE'];
+        assert.equal(existsSync(pidfile), false, 'failed readiness removes the pidfile mirror');
+        assert.equal(existsSync(socketPath), true, 'the pre-existing directory was never mistaken for a serving socket');
+        assert.match(readFileSync(join(canvasHome, 'crtrd.log'), 'utf8'), /api\.server\.failed/, 'the bind failure is recorded for cold-start diagnostics');
+        writeFileSync(pidfile, String(process.pid));
+        assert.deepEqual(await spawnDaemon(), {
+            started: false,
+            existing_pid: process.pid,
+            running: true,
+            serving: false,
+            next: 'Run `crtr sys daemon stop` to release the non-serving daemon before starting it again.',
+        }, 'start distinguishes a live non-serving pidfile owner from a serving daemon');
+        rmSync(pidfile, { force: true });
+        const retryClaim = claimDaemonOwnership('post-api-bind-failure');
+        assert.equal(retryClaim.claimed, true, 'failed readiness releases the authoritative ownership claim');
+        if (retryClaim.claimed) {
+            assert.equal(releaseDaemonOwnership(retryClaim.claim).released, true, 'the test-only retry claim releases cleanly');
+        }
+    }
+    finally {
+        closeDb();
+        resetEventSourceForTests();
+        resetFleetForTests();
+        process.chdir(previousCwd);
+        for (const key of isolatedEnvKeys) {
+            const previous = previousEnv.get(key);
+            if (previous === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = previous;
+        }
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/daemon/api/__tests__/reopen-delivery.test.js

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { createNode, getNode, openDb } from '../../../core/canvas/index.js';
+import { armCron, getCron } from '../../../core/canvas/crons.js';
 import { closeDb } from '../../../core/canvas/db.js';
 import { viewSocketPath } from '../../../core/canvas/paths.js';
 import { readInboxSince } from '../../../core/feed/inbox.js';
@@ -98,6 +99,43 @@ function assertReopened(id) {
     assert.equal(meta?.lifecycle, 'resident');
     assert.equal(meta?.final_report, null);
 }
+function armDeadline(id) {
+    armCron({
+        cron_id: `${id}-deadline`,
+        name: `${id} deadline`,
+        command: 'echo stale deadline',
+        fire_at: new Date(Date.now() + 60_000).toISOString(),
+        recur: null,
+        tz: null,
+        expires_at: null,
+        anchor_node: id,
+        cancel_on_wake: true,
+        created_by: null,
+        cwd: home,
+        env_json: null,
+        profile: null,
+        scope: 'profile',
+        run_timeout_s: 30,
+        overlap: 'skip',
+        on_output: 'silent',
+        sink: '{}',
+        tier: 'normal',
+    });
+}
+test('live interactive delivery clears the target deadline', async () => {
+    const id = 'live-deadline';
+    createNode(node(id, 'terminal', 'active', process.pid));
+    armDeadline(id);
+    const broker = await startLiveBroker(id);
+    try {
+        const result = await sendMessage(id, { body: 'wake before deadline', delivery: 'interactive' });
+        assert.equal(result.body.delivered_via, 'engine');
+        assert.equal(getCron(`${id}-deadline`), null, 'the accepted engine delivery won the deadline race');
+    }
+    finally {
+        await broker.close();
+    }
+});
 test('reopen makes live terminal, finalized terminal, and parked targets resident and unlatched before delivery', async () => {
     const liveId = 'live-terminal';
     createNode(node(liveId, 'terminal', 'active', process.pid));

package/dist/daemon/api/__tests__/seam/api-server.test.js

@@ -117,6 +117,7 @@ test('A3: messages append inbox.jsonl; final report writes + notifies subscriber
     assert.ok(res.notified.includes(A), `final push notifies the spawn-subscribed manager A (notified=${JSON.stringify(res.notified)})`);
     assert.deepEqual(res.transitioned, { from: 'active', to: 'done' }, 'row transitioned active→done');
     assert.equal(h.node(B)?.status, 'done', 'row status is done after final');
+    await assert.rejects(() => client.pushReport(B, { tier: 'final', delivery_tier: 'deferred', body: 'invalid tiered final' }), (error) => error instanceof ApiError && error.code === 'usage' && error.message === 'delivery_tier is only valid for update reports', 'the API rejects a delivery tier on final before it can alter final delivery');
 });
 // A4 — WS attach reconstructs the same settled broker snapshot as a direct
 //      ViewSocketClient; ?revive=0 on a dormant node → 409 without launching a broker

package/dist/daemon/api/__tests__/seam/leaf-api-parity.test.js

@@ -30,6 +30,7 @@ import { registerPush } from '../../../../commands/push.js';
 import { registerNode } from '../../../../commands/node.js';
 import { createNode, getNode } from '../../../../core/canvas/canvas.js';
 import { createManagedWorktree } from '../../../../core/worktree.js';
+import { readInboxSince } from '../../../../core/feed/inbox.js';
 import { gitSync } from '../../../../core/git.js';
 import { InputError } from '../../../../core/io.js';
 // A terminal fabricated node (no broker needed) that OWNS a managed worktree —
@@ -72,11 +73,11 @@ function pushLeaf(tier) {
 // Drive the leaf as the given caller node — sets CRTR_NODE_ID (client-side
 // identity resolution stays in the CLI process, per the B-5 scope) around the
 // run, restoring it after.
-async function runPushAs(caller, tier, body) {
+async function runPushAs(caller, tier, body, input = {}) {
     const prev = process.env['CRTR_NODE_ID'];
     process.env['CRTR_NODE_ID'] = caller;
     try {
-        return (await pushLeaf(tier).run({ body }));
+        return (await pushLeaf(tier).run({ body, ...input }));
     }
     finally {
         if (prev === undefined)
@@ -151,6 +152,16 @@ test('`crtr push final` from a child writes a report, notifies the subscribed pa
     // — the re-homed guard only engages for a managed-worktree owner.
     assert.equal('worktree_auto_dropped' in out, false, 'a normal node final is unaffected by the worktree guard');
 });
+test('`crtr push update --tier deferred` fans a deferred pointer while preserving an update report', async () => {
+    const parent = h.spawnRoot('leaf-api-parity deferred parent');
+    const child = (await client.createNode({ kind: 'developer', parent, prompt: 'deferred worker' })).node_id;
+    await h.awaitBoot(child);
+    const out = await runPushAs(child, 'update', 'deferred progress', { tier: 'deferred' });
+    assert.ok(out['notified'].includes(parent), 'the subscribed parent receives the report pointer');
+    const entry = readInboxSince(parent).find((candidate) => candidate.from === child && candidate.label === 'deferred progress');
+    assert.equal(entry?.kind, 'update', 'the stored report remains an update');
+    assert.equal(entry?.tier, 'deferred', 'the requested delivery tier reaches the parent');
+});
 // Re-homed worktree guard/auto-drop (ambiguity-2 follow-up): the pre-B-5 CLI
 // `push final` worktree behavior now lives SERVER-side in handlers/reports.ts,
 // exercised end-to-end through the real push.ts leaf.

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

@@ -4,6 +4,7 @@
 import { appendInbox } from '../../../core/feed/inbox.js';
 import { contextDir, isSafeNodeId } from '../../../core/canvas/paths.js';
 import { getNode } from '../../../core/canvas/canvas.js';
+import { cancelCronsOnWake } from '../../../core/canvas/crons.js';
 import { isBrokerLive } from '../../../core/runtime/model-swap.js';
 import { assertNotFinalized } from '../../../core/runtime/reopen.js';
 import { reviveNode } from '../../../core/runtime/revive.js';
@@ -74,6 +75,7 @@ async function handleStop(ctx) {
         label: body.split('\n')[0].slice(0, 120),
         data: { body },
     });
+    cancelCronsOnWake(nodeId);
     const node = getNode(nodeId);
     if (node !== null && !isBrokerLive(node)) {
         try {