@north-light/crouter 0.3.248 → 0.3.250

package/dist/daemon/api/handlers/broker-ops.js

@@ -1,7 +1,8 @@
 // Broker-originated canvas operations. The broker sends Pi lifecycle facts;
 // crtrd validates and commits their durable effects while the handler stays
 // strictly canvas-write-only — no broker launch, kill, or view.sock round trip.
-import { canonicalSessionFile, findNodeBySessionFile, getNode, isWarmSpare, listNodes, recordPid, setPresence, subscriptionsOf, updateNode } from '../../../core/canvas/canvas.js';
+import { canonicalSessionFile, findNodeBySessionFile, getNode, isWarmSpare, listNodes, recordPid, recordSettledTurn, setPresence, subscriptionsOf, updateNode } from '../../../core/canvas/canvas.js';
+import { isPidAlive } from '../../../core/canvas/pid.js';
 import { editorLabel } from '../../../core/canvas/labels.js';
 import { assembleNodeSubject } from '../../../core/substrate/subject.js';
 import { withCanvasWrite } from '../../../core/canvas/db.js';
@@ -13,7 +14,7 @@ import { focusOf, tearDownNode } from '../../../core/runtime/placement.js';
 import { hasAttachedBrokerViewers } from '../../../core/runtime/broker/client-registry.js';
 import { handleNewSession } from '../../../core/runtime/reset.js';
 import { evaluateStop } from '../../../core/runtime/stop-guard.js';
-import { clearFault } from '../../../core/runtime/fault.js';
+import { clearFault, recordFault } from '../../../core/runtime/fault.js';
 import { updateModelRecipe } from '../../../core/runtime/model-swap.js';
 import { completeCompanionRequestedSubmit } from '../../review/finish.js';
 import { consumePendingPark } from '../../park-pending.js';
@@ -187,6 +188,25 @@ function handleSessionBound(ctx) {
     const sessionFile = request.sessionFile === null ? null : canonicalSessionFile(request.sessionFile);
     const result = withCanvasWrite(() => {
         const before = requireNode(nodeId);
+        // A transcript is one broker's identity. Check ownership before every
+        // session-bound mutation: a live owner wins, and the claimant must stop
+        // rather than overwrite its own process-scoped identity onto that file.
+        const owner = sessionFile === null ? null : findNodeBySessionFile(sessionFile);
+        if (owner !== null && owner.node_id !== nodeId) {
+            if (isPidAlive(owner.pi_pid)) {
+                recordFault(nodeId, {
+                    link: 'daemon→node',
+                    op: 'session-file-ownership',
+                    kind: 'protocol',
+                    retry: { disposition: 'fatal' },
+                    message: `refusing to bind ${sessionFile}: it is owned by live node ${owner.node_id}`,
+                });
+                return { action: 'shutdown' };
+            }
+            // The prior owner is dead, so transfer the durable coordinate before the
+            // claimant writes it; the UNIQUE projection and both meta files agree.
+            updateNode(owner.node_id, { pi_session_id: null, pi_session_file: null });
+        }
         // The broker reports the markers present in Pi's current branch; crtrd owns
         // the review binding and decides whether that branch belongs to this node.
         const reviewId = before.review_binding?.review_id;
@@ -247,6 +267,7 @@ function settleBroker(nodeId, request) {
             return { action: 'stay_dormant' };
         throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
     }
+    recordSettledTurn(nodeId, new Date().toISOString());
     if (request.stopReason === 'quit') {
         if ((node.status === 'active' || node.status === 'idle') && node.intent === null) {
             transition(nodeId, 'finish');

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

@@ -37,7 +37,7 @@ function handleCreateBridge(ctx) {
         throw new ApiError(400, 'invalid_request', 'bridge `parent` must be a node id or null');
     }
     try {
-        const node = spawnNode({ kind: 'human', parent, cwd, name, lifecycle: 'terminal' });
+        const node = spawnNode({ kind: 'human', parent, creator: parent, cwd, name, lifecycle: 'terminal' });
         return { status: 200, body: { node_id: node.node_id, name: node.name } };
     }
     catch (error) {

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

@@ -8,6 +8,7 @@ import { isBrokerLive } from '../../../core/runtime/model-swap.js';
 import { deliverLive, interruptLive } from '../../../core/runtime/interactive-deliver.js';
 import { isProfilePaused } from '../../../core/profiles/manifest.js';
 import { getNode, withFreshTerminalGuard } from '../../../core/canvas/canvas.js';
+import { cancelCronsOnWake } from '../../../core/canvas/crons.js';
 import { assertNotFinalized, assertFinalizedForReopen, commitReopen, commitReopenResident, } from '../../../core/runtime/reopen.js';
 import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
 import { appendSituationalContext, formatSituationalProse } from '../../../core/runtime/situational-context.js';
@@ -249,6 +250,7 @@ async function handleMessage(ctx) {
             if (hasSidecar)
                 appendSituationalContext(id, sidecar);
             await deliverLive(id, req.body, [...(hasSidecar ? [sidecar] : []), ...oneShotCards]);
+            cancelCronsOnWake(id);
             const body = {
                 node_id: id,
                 delivered: true,
@@ -323,11 +325,17 @@ async function handleMessage(ctx) {
         return deliverImmediate();
     };
     const entry = deliver();
+    // Deferred mail normally waits for a natural cycle, but a frozen row already
+    // owes a thaw; consume its deadline when that durable future wake arrives.
+    if (tier !== 'deferred' || meta.frozen_at !== null)
+        cancelCronsOnWake(id);
     // 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.
+    // this; deferred never wakes — it rides the target's next natural cycle. The
+    // APPENDED entry's tier decides, because a terminal target's deferred was
+    // already raised to a wake-capable tier by the append.
     let revived = false;
     let frozen = false;
-    if (tier !== 'deferred' && !paused && !isBrokerLive(meta)) {
+    if (entry.tier !== 'deferred' && !paused && !isBrokerLive(meta)) {
         try {
             // 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
@@ -346,6 +354,7 @@ async function handleMessage(ctx) {
         revived,
         ...(frozen ? { not_revived_reason: 'capacity_frozen' } : {}),
         delivered_at: entry.ts,
+        ...(entry.tier === tier ? {} : { delivered_tier: entry.tier }),
         ...(req.delivery === 'interactive' ? { delivered_via: 'inbox' } : {}),
     };
     return { status: 201, body };

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

@@ -102,6 +102,9 @@ function parseCreateBody(body) {
     if (b['description'] !== undefined && (typeof b['description'] !== 'string' || b['description'].trim() === '')) {
         throw usage('description must be a non-empty string when provided');
     }
+    if (b['creator'] !== undefined && (typeof b['creator'] !== 'string' || b['creator'].trim() === '')) {
+        throw usage('creator must be a non-empty node id when provided');
+    }
     const rootLifecycle = b['root_lifecycle'];
     if (rootLifecycle !== undefined &&
         rootLifecycle !== 'resident' &&
@@ -125,6 +128,8 @@ function buildRecipe(req, parent, cwd) {
         recipe.description = req.description;
     if (parent !== undefined)
         recipe.parent = parent;
+    if (req.creator !== undefined)
+        recipe.creator = req.creator;
     if (req.root === true)
         recipe.root = true;
     if (req.root_lifecycle !== undefined) {
@@ -174,6 +179,7 @@ function warmRequestFor(req, cwd, profileId) {
         model: req.model ?? null,
         situationalContext: req.situational_context ?? null,
         name: req.name ?? null,
+        creator: req.creator ?? null,
     };
 }
 export { resolveCreateKind } from '../../../core/runtime/launch-target.js';
@@ -508,7 +514,13 @@ function handleClose(ctx) {
     // `finish` selects the root disposition: finalize to `done` (browse `x`) vs the
     // default cancel.
     const body = ctx.body;
-    const result = closeNode(id, { rootEvent: body?.finish === true ? 'finish' : 'cancel' });
+    if (body?.caller_pid !== undefined && (!Number.isInteger(body.caller_pid) || body.caller_pid <= 0)) {
+        throw usage('caller_pid must be a positive integer when provided');
+    }
+    const result = closeNode(id, {
+        rootEvent: body?.finish === true ? 'finish' : 'cancel',
+        callerPid: body?.caller_pid,
+    });
     return { status: 200, body: toCloseResultDTO(result) };
 }
 async function handleRecycle(ctx) {

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

@@ -1,6 +1,7 @@
 // Report handlers (spec §6.4, §7.4). `POST /nodes/{id}/reports` is the single
-// push route — the tier is a body field; `final` drives the server-side
-// lifecycle transition inside feed `push()` (the sanctioned path). `GET
+// push route — `tier` is the report kind and update-only `delivery_tier` sets
+// subscriber delivery urgency; `final` drives the server-side lifecycle
+// transition inside feed `push()` (the sanctioned path). `GET
 // /nodes/{id}/reports` lists the node's stored report files.
 //
 // `{id}` is the REPORTING node (client-side = CRTR_NODE_ID).
@@ -24,14 +25,21 @@ function parsePushBody(body) {
         throw usage('a push report requires a JSON body { tier, body }');
     }
     const tier = body.tier;
+    const deliveryTier = body.delivery_tier;
     const text = body.body;
     if (tier !== 'update' && tier !== 'urgent' && tier !== 'final') {
         throw usage(`invalid report tier: ${String(tier)} (expected update|urgent|final)`);
     }
+    if (deliveryTier !== undefined && deliveryTier !== 'deferred' && deliveryTier !== 'normal' && deliveryTier !== 'urgent') {
+        throw usage(`invalid delivery_tier: ${String(deliveryTier)} (expected deferred|normal|urgent)`);
+    }
+    if (tier === 'final' && deliveryTier !== undefined) {
+        throw usage('delivery_tier is only valid for update reports');
+    }
     if (typeof text !== 'string' || text.trim() === '') {
         throw usage('a push report requires a non-empty body');
     }
-    return { tier, body: text };
+    return { tier, ...(deliveryTier === undefined ? {} : { delivery_tier: deliveryTier }), body: text };
 }
 async function handlePush(ctx) {
     const id = ctx.params['id'];
@@ -68,7 +76,7 @@ async function handlePush(ctx) {
         }
         autoDroppedPath = dropped.worktree_path;
     }
-    const result = await pushOrRethrow(id, req.tier, req.body);
+    const result = await pushOrRethrow(id, req);
     const transitioned = req.tier === 'final' && before !== undefined
         ? { from: before, to: getNode(id)?.status ?? 'done' }
         : undefined;
@@ -83,9 +91,9 @@ async function handlePush(ctx) {
  *  survives (a bare 409 would otherwise collapse to the generic `conflict`
  *  code). `unknown_node` is unreachable here (`requireNode` guards above), so
  *  it falls through as the generic 404. */
-async function pushOrRethrow(id, tier, body) {
+async function pushOrRethrow(id, req) {
     try {
-        return await push(id, { kind: tier, body });
+        return await push(id, { kind: req.tier, body: req.body, ...(req.delivery_tier === undefined ? {} : { deliveryTier: req.delivery_tier }) });
     }
     catch (err) {
         if (err instanceof FinalizationError && err.code === 'already_finalized') {

package/dist/daemon/api/map.js

@@ -119,6 +119,7 @@ export function toNodeDetailDTO(meta, edges) {
         pane: meta.pane ?? null,
         final_report: meta.final_report ?? null,
         finalized_at: meta.finalized_at ?? null,
+        creator: meta.creator ?? null,
         edges: toNodeEdgesDTO(meta, edges),
         paths: toNodePathsDTO(meta.node_id),
     };

package/dist/daemon/api/server.d.ts

@@ -4,20 +4,17 @@ export interface CreateApiServerOptions {
     tcp?: string;
 }
 export interface ApiServer {
+    /** Settles only after the mandatory Unix socket binds; rejects on its bind failure. */
+    ready: Promise<void>;
     /** Tear down both listeners and unlink the socket file. Double-close safe. */
     close(): Promise<void>;
 }
-/** Create and start the crtrd API server (A-9). Returns immediately with a
- *  `close()` handle; the listeners bind asynchronously (a unix socket's file is
- *  created on `listen`, so its 0600 chmod happens in the listen callback). A
- *  bind failure or a post-listen accept error is emitted and swallowed — it must
- *  NEVER become an unhandled 'error' that crashes the daemon.
+/** Create and start the crtrd API server. Returns immediately with a `close()`
+ *  handle and a `ready` promise for the mandatory Unix socket bind. TCP remains
+ *  opt-in, and its bind or post-listen accept errors are emitted but non-fatal.
  *
- *  NOTE (correction to the plan's "one http.Server bound twice"): a Node
- *  `net.Server`/`http.Server` binds exactly ONE handle — a second `.listen()`
- *  on the same instance throws `ERR_SERVER_ALREADY_LISTEN`. So the two listeners
- *  are two `http.Server` instances SHARING the same request + upgrade handler
- *  functions (the standard way to bind one logical API to two transports). The
- *  Router and attach bridge are process-wide singletons, so both servers route
- *  into identical state. */
+ *  A Node `net.Server`/`http.Server` binds exactly ONE handle, so the two
+ *  listeners are separate `http.Server` instances sharing request and upgrade
+ *  handlers. The Router and attach bridge are process-wide singletons, so both
+ *  servers route into identical state. */
 export declare function createApiServer(opts?: CreateApiServerOptions): ApiServer;

package/dist/daemon/api/server.js

@@ -1,6 +1,7 @@
 // server.ts — the crtrd HTTP+WS API server (spec §4, esp. §4.1/§5). A-9.
 //
-// ONE `http.Server`, bound TWICE (the dockerd model, §4.1):
+// Two `http.Server` listeners share one logical API (a Node server can bind one
+// handle only):
 //   - the unix socket at `apiSocketPath()` — ALWAYS bound, owner-only (mode
 //     0600 = the fs-perms-are-auth model);
 //   - an opt-in TCP listener, bound only when `--tcp <host:port>` / `CRTRD_TCP`
@@ -121,19 +122,14 @@ function closeServer(server) {
         server.close(() => resolve());
     });
 }
-/** Create and start the crtrd API server (A-9). Returns immediately with a
- *  `close()` handle; the listeners bind asynchronously (a unix socket's file is
- *  created on `listen`, so its 0600 chmod happens in the listen callback). A
- *  bind failure or a post-listen accept error is emitted and swallowed — it must
- *  NEVER become an unhandled 'error' that crashes the daemon.
+/** Create and start the crtrd API server. Returns immediately with a `close()`
+ *  handle and a `ready` promise for the mandatory Unix socket bind. TCP remains
+ *  opt-in, and its bind or post-listen accept errors are emitted but non-fatal.
  *
- *  NOTE (correction to the plan's "one http.Server bound twice"): a Node
- *  `net.Server`/`http.Server` binds exactly ONE handle — a second `.listen()`
- *  on the same instance throws `ERR_SERVER_ALREADY_LISTEN`. So the two listeners
- *  are two `http.Server` instances SHARING the same request + upgrade handler
- *  functions (the standard way to bind one logical API to two transports). The
- *  Router and attach bridge are process-wide singletons, so both servers route
- *  into identical state. */
+ *  A Node `net.Server`/`http.Server` binds exactly ONE handle, so the two
+ *  listeners are separate `http.Server` instances sharing request and upgrade
+ *  handlers. The Router and attach bridge are process-wide singletons, so both
+ *  servers route into identical state. */
 export function createApiServer(opts = {}) {
     const router = buildRouter();
     const sockPath = apiSocketPath();
@@ -199,17 +195,32 @@ export function createApiServer(opts = {}) {
         }
     };
     const bindErrorHandler = (server) => {
-        // A bind failure or post-listen accept error must not be an unhandled
-        // 'error' that crashes the process — emit and carry on.
+        // TCP is opt-in, so neither its bind failure nor a later accept error can
+        // make the mandatory Unix API unavailable.
         server.on('error', (err) => {
             emitEvent({ event: 'api.server.failed', level: 'error', error: err });
         });
     };
-    // Unix socket — ALWAYS bound. Unlink any stale socket first (mirror
-    // broker.ts's listener setup), listen, then chmod 0600 once the file exists.
+    // Unix socket — ALWAYS bound. Its bind result is startup readiness; after
+    // that point, accept errors remain observable but do not tear the daemon down.
     const socketServer = createServer(onRequest);
     socketServer.on('upgrade', onUpgrade);
-    bindErrorHandler(socketServer);
+    let socketBound = false;
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    socketServer.once('listening', () => {
+        socketBound = true;
+        resolveReady();
+    });
+    socketServer.on('error', (err) => {
+        emitEvent({ event: 'api.server.failed', level: 'error', error: err });
+        if (!socketBound)
+            rejectReady(err);
+    });
     try {
         if (existsSync(sockPath))
             unlinkSync(sockPath);
@@ -265,5 +276,5 @@ export function createApiServer(opts = {}) {
             /* best-effort cleanup */
         }
     };
-    return { close };
+    return { ready, close };
 }

package/dist/daemon/companion-retire.js

@@ -5,7 +5,7 @@
 import { getNode } from '../core/canvas/canvas.js';
 import { FinalizationError, pushFinal } from '../core/feed/feed.js';
 import { transition } from '../core/runtime/lifecycle.js';
-import { headlessBrokerHost } from '../core/runtime/host.js';
+import { requestBrokerTeardown } from '../core/runtime/host.js';
 /** Retire a companion only through the terminal transition legal for its current status. */
 export async function retireCompanion(nodeId, outcome) {
     const node = getNode(nodeId);
@@ -23,18 +23,12 @@ export async function retireCompanion(nodeId, outcome) {
                 throw error;
             result = 'already';
         }
-        try {
-            headlessBrokerHost.teardown(nodeId);
-        }
-        catch { /* the canonical final is authoritative */ }
+        requestBrokerTeardown(nodeId);
         return result;
     }
     transition(nodeId, 'cancel', { reason: 'retired' });
     if (node.status === 'active' || node.status === 'idle') {
-        try {
-            headlessBrokerHost.teardown(nodeId);
-        }
-        catch { /* the terminal transition is authoritative */ }
+        requestBrokerTeardown(nodeId);
     }
     return 'retired';
 }

package/dist/daemon/cron/sinks.js

@@ -5,6 +5,7 @@ import { ticketDir } from '../../core/human/root.js';
 import { preparePage, publishPage } from '../../core/human/tickets.js';
 import { resolvePageComponents } from '../../core/config.js';
 import { getNode } from '../../core/canvas/canvas.js';
+import { cancelCronsOnWake } from '../../core/canvas/crons.js';
 import { appendInbox } from '../../core/feed/inbox.js';
 import { hasNoNaturalCycle } from '../../core/runtime/revive-all.js';
 import { isParked } from '../../core/runtime/lifecycle.js';
@@ -23,15 +24,19 @@ function deliverNodeSink(c, target, stdout) {
         throw new Error(`node sink ${target} has no natural cycle ahead (done or finalized)`);
     }
     const from = c.created_by != null && getNode(c.created_by) !== null ? c.created_by : null;
-    appendInbox(target, {
+    const entry = appendInbox(target, {
         from,
         tier: c.tier,
         kind: 'message',
         label: `⏰ cron ${c.name}`,
         data: { body: stdout },
     });
+    if (c.tier !== 'deferred' || meta.frozen_at !== null)
+        cancelCronsOnWake(target);
+    // The APPENDED tier decides the wake, not the cron's requested one: a deferred
+    // cron aimed at a terminal node was raised out of `deferred` by the append.
     // The durable append succeeds even if its best-effort wake fails.
-    if (c.tier !== 'deferred' && !isBrokerLive(meta)) {
+    if (entry.tier !== 'deferred' && !isBrokerLive(meta)) {
         try {
             reviveNode(target, { resume: true, capacity: 'freeze' });
         }

package/dist/daemon/crtrd.js

@@ -668,8 +668,11 @@ export async function runDaemon(opts = {}) {
         // no adoption across epochs, ever.
         await operationIdContext.fresh(() => reapPriorEpochBrokers(epoch));
         writePidfile();
-        // Start the HTTP+WS API server (§4): unix socket always, TCP when opted in.
+        // The Unix API socket is the daemon's readiness boundary. A rejected bind
+        // enters the existing startup catch, which closes resources and releases
+        // this invocation's pidfile mirror and ownership claim before propagating.
         apiServer = createApiServer({ tcp: opts.tcp });
+        await apiServer.ready;
         // Pre-warm the node pool for the most recent project recipes, so the first
         // create after a boot is warm too. Fire-and-forget (the mints run off the
         // work lane), so it never delays supervision. Boot-time dead rows are the

package/dist/daemon/fleet.d.ts

@@ -1,7 +1,7 @@
 import { type NodeMeta } from '../core/canvas/index.js';
 import { type FleetEntry, type FleetExitStatus, type FleetRegistry } from '../core/runtime/fleet.js';
 import type { HostHandle } from '../core/runtime/host.js';
-/** Surface a vehicle that never booted (or exhausted its respawn budget).
+/** Surface a vehicle that never booted.
  *
  *  A pi that dies before its first session_start (so `pi_session_id` was never
  *  recorded) is invisible to its parent — the spawn returned optimistically.
@@ -43,16 +43,6 @@ export type DeadNodeRow = Pick<NodeMeta, 'status' | 'intent' | 'pi_session_id' |
  *  would drive a turn if the engine came back. It selects row 4b and defaults
  *  to `true`, so an uninformed caller keeps the conservative respawn. */
 export declare function classifyDeadNode(row: DeadNodeRow | null, busy: boolean, pendingWake?: boolean): DeadNodeAction;
-/** An exit with uptime at or above this resets the consecutive-failure
- *  counter before classification; a shorter-lived exit increments it. */
-export declare const HEALTHY_UPTIME_MS = 60000;
-/** At this many consecutive short-lived exits the respawn loop terminalizes:
- *  transition('crash') + surfaceBootFailure + doctrine wake, counter cleared. */
-export declare const MAX_RESPAWN_ATTEMPTS = 6;
-/** Backoff before the next respawn given the consecutive-failure count.
- *  Zero failures → immediate (the sub-second yield respawn D-3 buys); the
- *  n-th delayed attempt waits min(5s·2^n, 10min). */
-export declare function respawnBackoffMs(consecutiveFailures: number): number;
 export interface DaemonFleetOpts {
     /** This daemon's epoch id (randomBytes(8).toString('hex'), minted by
      *  runDaemon after the ownership claim). */
@@ -78,16 +68,12 @@ export declare class DaemonFleet implements FleetRegistry {
     forget(nodeId: string): void;
     onChildExit(nodeId: string, status: FleetExitStatus): void;
     deliverExit(nodeId: string, status: FleetExitStatus): void;
-    /** The node-lifecycle tick's enactment entry: classify a known-dead row and
-     *  enact immediately through the SAME policy table exit events use, so tick
-     *  recovery and exit recovery can never diverge. */
+    /** The node-lifecycle tick's enactment entry. */
     applyDeadRowPolicy(nodeId: string): Promise<void>;
     /** A revive refusal before its launch try/catch leaves the row active but
      *  with no fleet entry. Convert that otherwise-silent strand into the same
      *  terminal outcome as a boot failure. The fresh read avoids duplicating
      *  reviveNode's launch-failure crash path. */
     terminalizeIfStillNonTerminal(nodeId: string, event: string, error: unknown): Promise<boolean>;
-    /** Daemon shutdown: cancel every pending backoff respawn. Live processes
-     *  are torn down by the daemon's fleet-teardown stage, not here. */
     dispose(): void;
 }