@north-light/crouter 0.3.263 → 0.3.270

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

@@ -11,7 +11,7 @@
 // the sanctioned place for it.
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, listNodes, pruneNodes, pruneToLimit, rebuildIndex, rosterEdges, rosterNodes, subscriptionsOf } from '../../../core/canvas/canvas.js';
+import { listNodes, pruneNodes, pruneToLimit, rebuildIndex, rosterEdges, rosterNodes } from '../../../core/canvas/canvas.js';
 import { activeBackgroundBashJobs } from '../../../core/bash-jobs.js';
 import { contextDir } from '../../../core/canvas/paths.js';
 import { nowIso } from '../../../core/fs-utils.js';
@@ -20,7 +20,7 @@ import { dashboardRowsAllFromSource, enrichRowsFromSource } from '../../../core/
 import { localCanvasSource } from '../../../core/canvas/source.js';
 import { listFocuses } from '../../../core/canvas/focuses.js';
 import { ticketCountsForNodes, ticketsAcrossCanvas } from '../../../core/canvas/attention.js';
-import { buildCorpus, resolveRef, } from '../../../core/canvas/history.js';
+import { buildCorpus, groupCorpus, resolveRef, } from '../../../core/canvas/history.js';
 import { nodeDir, nodesRoot } from '../../../core/canvas/paths.js';
 import { reapEmptyNodes } from '../../../core/runtime/placement.js';
 import { general, notFound, usage } from '../../../core/errors.js';
@@ -130,9 +130,36 @@ function buildCorpusFromQuery(q) {
         statuses: q.statuses,
         sinceMs: q.since_ms,
         untilMs: q.until_ms,
+        origins: q.origins,
+        roles: q.roles,
+        from: q.from,
     };
     return buildCorpus(scope, corpusFilter);
 }
+function parseStatsBody(body) {
+    if (body === undefined || body === null)
+        return {};
+    if (typeof body !== 'object')
+        throw usage('history stats body must be a JSON object');
+    return body;
+}
+const GROUP_KEYS = ['origin', 'node', 'kind', 'day', 'type', 'role'];
+function handleHistoryStats(ctx) {
+    const q = parseStatsBody(ctx.body);
+    const by = (q.group_by ?? 'type');
+    if (!GROUP_KEYS.includes(by)) {
+        throw usage(`--group-by must be one of: ${GROUP_KEYS.join(', ')}; received: ${String(q.group_by)}`);
+    }
+    const arts = buildCorpusFromQuery(q);
+    const groups = groupCorpus(arts, by);
+    const body = {
+        group_by: by,
+        groups,
+        total: groups.reduce((sum, g) => sum + g.count, 0),
+        scanned: arts.length,
+    };
+    return { status: 200, body };
+}
 function handleHistoryGrep(ctx) {
     const q = parseGrepBody(ctx.body);
     const limit = Math.min(100, Math.max(1, q.limit ?? 20));
@@ -254,7 +281,11 @@ function handleHistoryRead(ctx) {
         });
     }
     const source = resolved.source === 'report' && resolved.reportKind ? `report:${resolved.reportKind}` : resolved.source;
-    const content = includeFrontmatter && resolved.raw !== null ? resolved.raw : resolved.body;
+    // `raw` is the verbatim record; `--frontmatter` is the narrower legacy ask
+    // for the same bytes on a markdown artifact. Either one yields the raw form
+    // when the artifact has one.
+    const wantRaw = ctx.query.get('format') === 'raw' || includeFrontmatter;
+    const content = wantRaw && resolved.raw !== null ? resolved.raw : resolved.body;
     const body = {
         ref,
         node: `${resolved.nodeName} (${resolved.nodeId})`,
@@ -288,39 +319,53 @@ async function handleSnapshot(ctx) {
     const asks = ticketCountsForNodes(rows.map((r) => r.node_id));
     await enrichRowsFromSource(localCanvasSource, rows, asks);
     const nodes = rows.map((row) => {
-        const meta = getNode(row.node_id);
-        const hostKind = meta?.host_kind ?? 'tmux';
+        // Every field here comes from the NodeRow listNodes already fetched (stashed
+        // on the row as srcRow) — this handler opens no meta.json at all.
+        const src = row.srcRow;
+        const hostKind = src?.host_kind ?? 'tmux';
         return {
             node_id: row.node_id,
             name: row.name,
-            title: meta?.name ?? row.name,
-            description: meta?.description ?? null,
+            title: row.handle ?? row.name,
+            description: row.description ?? null,
             kind: row.kind,
             mode: row.mode,
-            lifecycle: row.lifecycle ?? meta?.lifecycle,
+            lifecycle: row.lifecycle ?? src?.lifecycle,
             status: row.status,
             cwd: row.cwd,
-            profile_id: meta?.profile_id ?? null,
-            parent: meta?.parent ?? null,
+            profile_id: row.profile_id ?? null,
+            parent: src?.parent ?? null,
             created: row.created,
             host_kind: hostKind,
             enterable: hostKind === 'broker',
             attention_count: row.asks,
-            ...(meta?.cycles !== undefined ? { cycles: meta.cycles } : {}),
+            ...(src?.cycles != null ? { cycles: src.cycles } : {}),
             ...(row.mtimeMs !== undefined ? { last_activity: new Date(row.mtimeMs).toISOString() } : {}),
             ctx_tokens: row.ctx_tokens,
             streaming: row.streaming ?? false,
-            jobs_active: meta !== null && isBrokerLive(meta)
+            jobs_active: src !== undefined && isBrokerLive(src)
                 ? activeBackgroundBashJobs(contextDir(row.node_id)).length
                 : 0,
-            waiting_for: meta?.waiting_for ?? null,
+            waiting_for: src?.waiting_for ?? null,
             hanging: (row.hanging ?? null),
             viewed: row.viewed ?? false,
-            final_report: meta?.final_report ?? null,
-            finalized_at: meta?.finalized_at ?? null,
+            final_report: src?.final_report ?? null,
+            finalized_at: src?.finalized_at ?? null,
         };
     });
-    const subscriptions = Object.fromEntries(rows.map((row) => [row.node_id, subscriptionsOf(row.node_id).map((ref) => ref.node_id)]));
+    // Opt 3: one rosterEdges() pass grouped by subscriber, replacing the per-node
+    // subscriptionsOf query. Both are `subscribes_to` edges (active + inactive)
+    // ORDER BY created, so grouping preserves the exact per-node ordering. Rows
+    // with no outgoing edge still get an empty array (iterate rows, not the map).
+    const edgesByFrom = new Map();
+    for (const e of rosterEdges()) {
+        const list = edgesByFrom.get(e.from_id);
+        if (list === undefined)
+            edgesByFrom.set(e.from_id, [e.to_id]);
+        else
+            list.push(e.to_id);
+    }
+    const subscriptions = Object.fromEntries(rows.map((row) => [row.node_id, edgesByFrom.get(row.node_id) ?? []]));
     const body = { generated_at: nowIso(), nodes, subscriptions };
     return { status: 200, body };
 }
@@ -479,6 +524,7 @@ export const canvasRoutes = [
     { method: 'POST', pattern: '/v1/canvas/history/search', handler: handleHistorySearch },
     { method: 'POST', pattern: '/v1/canvas/history/grep', handler: handleHistoryGrep },
     { method: 'GET', pattern: '/v1/canvas/history/read', handler: handleHistoryRead },
+    { method: 'POST', pattern: '/v1/canvas/history/stats', handler: handleHistoryStats },
     { method: 'GET', pattern: '/v1/canvas/snapshot', handler: handleSnapshot },
     { method: 'GET', pattern: '/v1/canvas/roster', handler: handleRoster },
     { method: 'POST', pattern: '/v1/canvas/prune', handler: handlePrune },

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

@@ -224,7 +224,7 @@ async function handleMessage(ctx) {
             commitReopen(id, expectedFinalReport);
         // 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 result = await reviveNode(id, { resume: false, capacity: 'refuse' });
         const body = {
             node_id: id,
             delivered: false,
@@ -249,7 +249,18 @@ async function handleMessage(ctx) {
         try {
             if (hasSidecar)
                 appendSituationalContext(id, sidecar);
-            await deliverLive(id, req.body, [...(hasSidecar ? [sidecar] : []), ...oneShotCards]);
+            await deliverLive(id, req.body, {
+                cards: [...(hasSidecar ? [sidecar] : []), ...oneShotCards],
+                // Same authorship the durable route would record for this send, so a
+                // reader cannot tell live from inbox delivery by the stamp.
+                origin: from === 'human'
+                    ? { type: 'human' }
+                    : {
+                        type: 'runtime',
+                        kind: 'inbox',
+                        entries: [{ ...(from === null ? {} : { from }), kind: 'message', tier }],
+                    },
+            });
             cancelCronsOnWake(id);
             const body = {
                 node_id: id,
@@ -340,7 +351,7 @@ async function handleMessage(ctx) {
             // 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' });
+            const result = await reviveNode(id, { resume: true, capacity: 'freeze' });
             revived = result.launch !== undefined;
             frozen = result.outcome === 'frozen';
         }

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

@@ -156,9 +156,10 @@ function buildRecipe(req, parent, cwd) {
 /** The warm-pool request this create is asking for, or null when it carries
  *  something a pre-booted spare cannot honor. A spare is a bare root with no
  *  kickoff, so anything that shapes the node AT BIRTH — a prompt to run, a
- *  forked conversation, a managed worktree, a caller-pinned node id, a spine
- *  parent — disqualifies it. `kind`, `mode`, `model`, `name`, `situational_context`
- *  and `output_schema` are all applied at claim time and so do not. A terminal
+ *  forked conversation, a managed worktree, a model override, a caller-pinned
+ *  node id, a spine parent — disqualifies it. `kind`, `mode`, `name`,
+ *  `situational_context` and `output_schema` are all applied at claim time and
+ *  so do not. A terminal
  *  root is not warm-compatible: every spare is resident. */
 function warmRequestFor(req, cwd, profileId) {
     if (!warmPoolEnabled())
@@ -171,6 +172,11 @@ function warmRequestFor(req, cwd, profileId) {
         return null;
     if ((req.prompt ?? '') !== '')
         return null;
+    // An explicit override freezes the requested model before the first turn;
+    // applying it to a live spare would switch models after its broker already
+    // launched its default route.
+    if (req.model !== undefined)
+        return null;
     if (req.fork_from !== undefined || req.worktree !== undefined || req.node_id !== undefined)
         return null;
     return {
@@ -196,6 +202,7 @@ async function assertNodeModelChangeRegistered(meta, target, registry) {
         lifecycle: target.lifecycle,
         hasManager: meta.parent !== null,
         model: target.model,
+        modelOverride: true,
         cwd: meta.cwd,
         profileId: meta.profile_id ?? null,
     })).launch;
@@ -367,6 +374,8 @@ async function handleSnapshot(ctx) {
         snapshot: {
             messages: read.snapshot.messages,
             ...(read.snapshot.messageIds === undefined ? {} : { messageIds: read.snapshot.messageIds }),
+            messageVisibility: read.snapshot.messageVisibility,
+            turnVisibility: read.snapshot.turnVisibility,
             stats: read.snapshot.stats,
             state: read.snapshot.state,
             display: read.snapshot.display,
@@ -416,6 +425,7 @@ async function handleMessages(ctx) {
         node_id: id,
         messages: read.messages,
         ...(read.messageIds === undefined ? {} : { message_ids: read.messageIds }),
+        message_visibility: read.messageVisibility,
         next_cursor: read.nextCursor,
         captured_at: nowIso(),
     };
@@ -484,7 +494,7 @@ async function handleFork(ctx) {
     const result = await forkNode(id);
     return { status: 201, body: detailOf(result.node.node_id) };
 }
-function handleRevive(ctx) {
+async function handleRevive(ctx) {
     const id = ctx.params['id'];
     requireMeta(id);
     const body = ctx.body;
@@ -500,7 +510,7 @@ function handleRevive(ctx) {
     // rather than a message. A cron id that no longer resolves (canceled or
     // consumed mid-run) simply yields no block — prose, never an error.
     const cron = !resume && body?.cron_id !== undefined ? getCron(body.cron_id) : null;
-    const result = reviveNode(id, {
+    const result = await 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.
@@ -622,8 +632,8 @@ function handleWait(ctx) {
     setMessageWait(id, req.controller);
     return { status: 200, body: detailOf(id) };
 }
-function handleReviveAll() {
-    const result = reviveAll();
+async function handleReviveAll() {
+    const result = await reviveAll();
     const body = {
         revived: [...result.revived],
         failed: [...result.failed],

package/dist/daemon/api/map.js

@@ -28,6 +28,8 @@ export function toNodeSummaryDTO(row) {
     return {
         node_id: row.node_id,
         name: row.name,
+        description: row.description,
+        cycles: row.cycles,
         kind: row.kind,
         mode: row.mode,
         lifecycle: row.lifecycle,

package/dist/daemon/cron/sinks.js

@@ -15,7 +15,7 @@ import { spawnChild } from '../../core/runtime/spawn.js';
 import { cronWakeOrigin } from '../../core/runtime/bearings.js';
 import { parseSink } from '../cron-sink.js';
 import { resolveLiveProfile, resolveLiveProfileName } from './armed-context.js';
-function deliverNodeSink(c, target, stdout) {
+async function deliverNodeSink(c, target, stdout) {
     const meta = getNode(target);
     if (meta === null)
         throw new Error(`node sink ${target} is gone`);
@@ -38,7 +38,7 @@ function deliverNodeSink(c, target, stdout) {
     // The durable append succeeds even if its best-effort wake fails.
     if (entry.tier !== 'deferred' && !isBrokerLive(meta)) {
         try {
-            reviveNode(target, { resume: true, capacity: 'freeze' });
+            await reviveNode(target, { resume: true, capacity: 'freeze' });
         }
         catch {
             /* best-effort wake — the entry is durably appended regardless */
@@ -93,7 +93,7 @@ export async function deliverToSink(c, stdout) {
     if (sink === null)
         return 'no sink armed — nothing delivered';
     if (sink.kind === 'node') {
-        deliverNodeSink(c, sink.node, stdout);
+        await deliverNodeSink(c, sink.node, stdout);
         return `delivered: node ${sink.node}`;
     }
     if (sink.kind === 'spawn') {

package/dist/daemon/fleet.js

@@ -343,7 +343,7 @@ export class DaemonFleet {
             },
         });
         try {
-            reviveNode(nodeId, {
+            await reviveNode(nodeId, {
                 // A recovery that loses the race for the last slot freezes and waits
                 // for one — the tick thaws it — rather than erroring the node away.
                 capacity: 'freeze',

package/dist/daemon/messaging/node-message.js

@@ -39,7 +39,21 @@ export async function deliverNodeMessage(args) {
             // card; only live delivery needs this message's own envelope.
             await deliverLive(args.node_id, args.runtime === undefined
                 ? args.body
-                : formatCard(args.runtime.kind, args.runtime.facts, args.body));
+                : formatCard(args.runtime.kind, args.runtime.facts, args.body), {
+                // The authorship the durable fallback below would record for this
+                // same send, so the two routes stamp identically.
+                origin: args.from === 'human'
+                    ? { type: 'human' }
+                    : {
+                        type: 'runtime',
+                        kind: 'inbox',
+                        entries: [{
+                                ...(args.from == null ? {} : { from: args.from }),
+                                kind: 'message',
+                                tier: 'normal',
+                            }],
+                    },
+            });
             // The broker acknowledgement is asynchronous to the SQLite guard. Recheck
             // before reporting an engine receipt so a final that committed during the
             // request is not represented as a routable delivery.
@@ -73,7 +87,7 @@ export async function deliverNodeMessage(args) {
             try {
                 // Mail is durable, so a wake denied for capacity waits for a slot
                 // rather than being lost: the row freezes and the tick relaunches it.
-                const result = reviveNode(args.node_id, { resume: true, capacity: 'freeze' });
+                const result = await reviveNode(args.node_id, { resume: true, capacity: 'freeze' });
                 revived = result.launch !== undefined;
                 if (result.outcome === 'frozen')
                     reason = 'capacity_frozen';

package/dist/daemon/profile-delete.js

@@ -216,7 +216,7 @@ async function detachProfile(plan) {
     const detached = new Set(detachedNodeIds);
     for (const nodeId of restartNodeIds) {
         if (detached.has(nodeId))
-            reviveNode(nodeId, { resume: true, recovery: true, capacity: 'freeze' });
+            await reviveNode(nodeId, { resume: true, recovery: true, capacity: 'freeze' });
     }
     return {
         ...resultForPlan(plan),

package/dist/daemon/reconcilers/broker-supervision.js

@@ -24,23 +24,30 @@ import { deliverLive } from '../../core/runtime/interactive-deliver.js';
 import { BrokerUnreachableError } from '../../core/runtime/broker-request.js';
 import { formatCard, PARK_SUMMARY_PROMPT } from '../../shared/generated-context.js';
 import { brokerThresholdsForDaemon } from '../../core/runtime/fleet.js';
+import { readConfig } from '../../core/config.js';
 import { beginPendingPark, consumePendingPark, pendingParkIds, pendingParkStartedAt } from '../park-pending.js';
 import { applyParkEvent, parkEvent } from './live-obligation.js';
-import { envNoDaemonAutostart, envTestParkSummaryGraceMs, envTestUnattendedParkMs, } from '../../shared/env.js';
+import { envNoDaemonAutostart, envTestParkSummaryGraceMs, envTestUnattendedParkMs, envUnattendedParkMs, } from '../../shared/env.js';
 const execFileAsync = promisify(execFile);
 export const YIELD_STALL_GRACE_MS = 3 * 60_000;
 const KILL_ESCALATE_MS = 20_000;
 export const WEDGE_QUIET_MS = 20 * 60_000;
 export const WEDGE_CPU_MAX_PERCENT = 2;
 const OVER_CAP_WARN_THROTTLE_MS = 5 * 60_000;
-const DEFAULT_UNATTENDED_PARK_MS = 15 * 60_000;
 // Longer than a summary turn and shorter than the unattended clock itself, so a
 // stuck parking turn cannot hold a broker for a whole extra clock period.
 const DEFAULT_PARK_SUMMARY_GRACE_MS = 5 * 60_000;
 export function unattendedParkMsForDaemon() {
+    // The `CRTR_UNATTENDED_PARK_MS` override wins whenever set, autostart or not.
+    const envOverride = envUnattendedParkMs();
+    if (envOverride !== undefined)
+        return envOverride;
+    // Otherwise the user-scope config value is the base (default 15 min), with the
+    // test-only override winning only when autostart is disabled.
+    const configured = readConfig('user').lifecycle.unattendedParkMs;
     if (!envNoDaemonAutostart())
-        return DEFAULT_UNATTENDED_PARK_MS;
-    return envTestUnattendedParkMs() ?? DEFAULT_UNATTENDED_PARK_MS;
+        return configured;
+    return envTestUnattendedParkMs() ?? configured;
 }
 export function parkSummaryGraceMsForDaemon() {
     return envTestParkSummaryGraceMs() ?? DEFAULT_PARK_SUMMARY_GRACE_MS;
@@ -149,6 +156,11 @@ export class BrokerSupervisionReconciler {
         ctx.lifecycle.registerDetached(warning);
     }
     async run(now, ctx) {
+        // Resolve the unattended-park interval once per tick — it reads user
+        // config.json, so a per-broker read would add one file read per eligible
+        // broker and could apply different values within one tick after a config
+        // write (mirrors how `runFleetPreamble` snapshots the broker thresholds).
+        const unattendedParkMs = unattendedParkMsForDaemon();
         for (const row of ctx.rows) {
             const id = row.node_id;
             const entry = ctx.fleet.get(id);
@@ -161,7 +173,7 @@ export class BrokerSupervisionReconciler {
                     this.handleYieldStall(row, entry.pid, now);
                     await this.handleWedgeDetection(id, entry.pid, row.pi_pid_identity, now);
                     this.handleFatalFault(id);
-                    this.handleUnattendedParking(id, getNode(id), entry.pid, now, ctx);
+                    this.handleUnattendedParking(id, getNode(id), entry.pid, now, ctx, unattendedParkMs);
                 }
                 catch (err) {
                     this.unattendedSince.delete(id);
@@ -211,7 +223,7 @@ export class BrokerSupervisionReconciler {
             return true;
         return hasUnseenWakeMail(id);
     }
-    handleUnattendedParking(id, row, livePid, now, ctx) {
+    handleUnattendedParking(id, row, livePid, now, ctx, unattendedParkMs) {
         // An unclaimed warm-pool spare is not a conversation: the booted broker it
         // holds IS its whole value, and nobody is meant to be attending it. Its
         // lifetime belongs to `reapStaleSpares` (warm-pool.ts) and its own TTL, so
@@ -269,7 +281,7 @@ export class BrokerSupervisionReconciler {
             this.unattendedSince.set(id, now);
             return;
         }
-        if (now - since < unattendedParkMsForDaemon())
+        if (now - since < unattendedParkMs)
             return;
         this.unattendedSince.delete(id);
         const event = parkEvent(id, row.lifecycle);
@@ -302,7 +314,9 @@ export class BrokerSupervisionReconciler {
      *  the node is working again and its clock simply restarts. */
     async requestParkSummary(id) {
         try {
-            const route = await deliverLive(id, formatCard('park', {}, PARK_SUMMARY_PROMPT));
+            const route = await deliverLive(id, formatCard('park', {}, PARK_SUMMARY_PROMPT), {
+                origin: { type: 'runtime', kind: 'park' },
+            });
             if (route === 'steer' && consumePendingPark(id))
                 return;
             emitEvent({
@@ -361,7 +375,10 @@ export class BrokerSupervisionReconciler {
                 if (client === '')
                     return;
                 try {
-                    await execFileAsync('tmux', ['display-message', '-d', '10000', '-c', client, msg], {
+                    // `-C` keeps the client's panes painting while the warning sits in
+                    // its status line; without it every attached viewer freezes for the
+                    // full 10s. The plain retry below covers a tmux without the flag.
+                    await execFileAsync('tmux', ['display-message', '-C', '-d', '10000', '-c', client, msg], {
                         encoding: 'utf8',
                         timeout: 2000,
                     });

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

@@ -11,10 +11,17 @@ export declare function hasLiveObligation(nodeId: string): boolean;
  *  Deferred mail deliberately does not count: it rides the node's next natural
  *  cycle rather than causing one. */
 export declare function hasPendingWake(nodeId: string): boolean;
+/** Whether a person is looking at this node right now: a focused viewer pane,
+ *  or a broker client that declared itself attending. A client that hellos with
+ *  `attends: false` is a system observer and deliberately does not count, which
+ *  is how Northlight Core identifies itself — so an open product page is
+ *  invisible here, while crouter's own local and remote viewers are not. */
+export declare function hasHumanViewer(nodeId: string): boolean;
 /** What parking an unattended node actually amounts to — the one rule both the
  *  live-broker park clock and the lifecycle tick apply.
  *
- *  `release` — something can still wake it, so parking is a pause.
+ *  `release` — something can still wake it, or a person is watching it, so
+ *              parking is a pause.
  *  `park`    — a resident with nothing left to wake it has completed its
  *              conversation, and the row becomes prunable history. The live
  *              clock asks it for a summary turn first; this verdict is what

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

@@ -28,9 +28,26 @@ export function hasPendingWake(nodeId) {
         return true;
     if (hasUnseenWakeMail(nodeId))
         return true;
+    return hasHumanViewer(nodeId);
+}
+/** Whether a person is looking at this node right now: a focused viewer pane,
+ *  or a broker client that declared itself attending. A client that hellos with
+ *  `attends: false` is a system observer and deliberately does not count, which
+ *  is how Northlight Core identifies itself — so an open product page is
+ *  invisible here, while crouter's own local and remote viewers are not. */
+export function hasHumanViewer(nodeId) {
     return focusOf(nodeId) !== null || hasAttachedBrokerViewers(nodeId);
 }
 export function parkEvent(nodeId, lifecycle) {
+    // Attendance defeats unattended parking outright: the grace exists to settle
+    // a conversation nobody is in, and terminalizing a node somebody is watching
+    // is the one outcome the grace must never reach. The live clock resets its
+    // own timer on the same test, so this covers the paths that reach a verdict
+    // without it — the settlement re-check after a parking turn, and the tick's
+    // sweep over already-idle rows. The live clock discards its timer on that
+    // same reset, so parking resumes a full grace after the last viewer detaches.
+    if (hasHumanViewer(nodeId))
+        return 'release';
     if (hasLiveObligation(nodeId))
         return 'release';
     if (lifecycle === 'resident')

package/dist/daemon/reconcilers/node-lifecycle/freeze-lane.js

@@ -83,9 +83,9 @@ export class FreezeLaneReconciler {
         const id = entry.row.node_id;
         try {
             if (entry.enact === 'thaw')
-                return this.enactThaw(entry.row);
+                return await this.enactThaw(entry.row);
             if (entry.enact === 'idle-release')
-                return this.enactIdleRelease(now, entry.row);
+                return await this.enactIdleRelease(now, entry.row);
             // The SAME policy table an exit event runs, so tick recovery and exit
             // recovery can never diverge. It relaunches through
             // `reviveNode(capacity: 'freeze')`, which freezes the row when the ledger
@@ -106,17 +106,17 @@ export class FreezeLaneReconciler {
             return 'skipped';
         }
     }
-    enactThaw(row) {
+    async enactThaw(row) {
         if (row.lifecycle === 'resident' && getNode(row.node_id)?.pi_session_id != null && !hasPendingWake(row.node_id)) {
             transition(row.node_id, 'release');
             clearFrozen(row.node_id);
             return 'skipped';
         }
-        return reviveNode(row.node_id, { resume: true, capacity: 'freeze', recovery: true }).outcome === 'frozen'
+        return (await reviveNode(row.node_id, { resume: true, capacity: 'freeze', recovery: true })).outcome === 'frozen'
             ? 'frozen'
             : 'launched';
     }
-    enactIdleRelease(now, row) {
+    async enactIdleRelease(now, row) {
         const id = row.node_id;
         const cursorNow = readCursor(id);
         const prior = this.relaunchState.get(id);
@@ -147,7 +147,7 @@ export class FreezeLaneReconciler {
         // A relaunch the broker cap froze got no slot and therefore proved nothing
         // about this delivery, so it must not spend an attempt: only a launch that
         // actually happened advances the episode toward exhaustion.
-        if (reviveNode(id, { resume: true, capacity: 'freeze' }).outcome === 'frozen')
+        if ((await reviveNode(id, { resume: true, capacity: 'freeze' })).outcome === 'frozen')
             return 'frozen';
         this.relaunchState.set(id, { cursor: cursorNow, attempts: attempts + 1, lastAttempt: now });
         emitEvent({

package/dist/hook-authoring.d.ts

@@ -6,6 +6,23 @@ export interface HookContext {
     cwd: string;
     providedParams: string[];
 }
+export interface LifecycleHookNode {
+    id: string;
+    name: string;
+    kind: string;
+    mode: string;
+    lifecycle: string;
+    cwd: string;
+    nodeDir: string;
+    contextDir: string;
+    jobDir: string;
+    reportsDir: string;
+}
+export interface LifecycleHookRuntime {
+    isBirth: boolean;
+    canvasHome: string;
+    profile: string | null;
+}
 interface HookRequestBase {
     protocolVersion: 1;
     op: string;
@@ -26,7 +43,20 @@ export interface AfterHookRequest extends HookRequestBase {
 export interface ReplaceHookRequest extends HookRequestBase {
     phase: 'replace';
 }
-export type HookRequest = BeforeHookRequest | AfterHookRequest | ReplaceHookRequest;
+/** Lifecycle handlers run on every matching event. They must be idempotent because `node:start` fires for birth and every revive. */
+export interface LifecycleHookRequest {
+    protocolVersion: 1;
+    op: string;
+    event: 'node:start';
+    phase: 'on';
+    operationId: string;
+    node: LifecycleHookNode;
+    runtime: LifecycleHookRuntime;
+    context: {
+        cwd: string;
+    };
+}
+export type HookRequest = BeforeHookRequest | AfterHookRequest | ReplaceHookRequest | LifecycleHookRequest;
 export interface HookSuccess {
     protocolVersion: 1;
     ok: true;

package/dist/hook-authoring.js

@@ -239,18 +239,40 @@ function concatBytes(chunks, total) {
 function validateRequest(value) {
     if (!isRecord(value))
         return invalid('request must be an object');
-    if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'phase', 'command', 'operationId', 'input', 'context', 'result'])) {
-        return invalid('request contains unknown fields');
-    }
     if (value['protocolVersion'] !== 1)
         return invalid('unsupported hook protocol version');
     if (typeof value['op'] !== 'string' || value['op'] === '')
         return invalid('op must be a non-empty string');
-    if (!isStringArray(value['command']) || value['command'].length === 0)
-        return invalid('command must be a non-empty string array');
     if (typeof value['operationId'] !== 'string' || !/^[0-9a-f]{32}$/.test(value['operationId'])) {
         return invalid('operationId must be a 32-character lowercase hexadecimal string');
     }
+    if (value['phase'] === 'on') {
+        if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'event', 'phase', 'operationId', 'node', 'runtime', 'context']))
+            return invalid('lifecycle request contains unknown fields');
+        if (value['event'] !== 'node:start')
+            return invalid('unsupported lifecycle event');
+        if (!isLifecycleNode(value['node']))
+            return invalid('lifecycle request node contains invalid fields');
+        if (!isLifecycleRuntime(value['runtime']))
+            return invalid('lifecycle request runtime contains invalid fields');
+        if (!isLifecycleContext(value['context']))
+            return invalid('lifecycle request context must contain cwd');
+        return valid({
+            protocolVersion: 1,
+            op: value['op'],
+            event: 'node:start',
+            phase: 'on',
+            operationId: value['operationId'],
+            node: value['node'],
+            runtime: value['runtime'],
+            context: value['context'],
+        });
+    }
+    if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'phase', 'command', 'operationId', 'input', 'context', 'result'])) {
+        return invalid('request contains unknown fields');
+    }
+    if (!isStringArray(value['command']) || value['command'].length === 0)
+        return invalid('command must be a non-empty string array');
     if (!isRecord(value['input']) || !isJson(value['input']))
         return invalid('input must be a JSON object');
     if (!isContext(value['context']))
@@ -317,6 +339,21 @@ function isContext(value) {
         && typeof value['cwd'] === 'string'
         && isStringArray(value['providedParams']);
 }
+function isLifecycleContext(value) {
+    return isRecord(value) && hasOnlyKeys(value, ['cwd']) && typeof value['cwd'] === 'string';
+}
+function isLifecycleNode(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['id', 'name', 'kind', 'mode', 'lifecycle', 'cwd', 'nodeDir', 'contextDir', 'jobDir', 'reportsDir'])
+        && ['id', 'name', 'kind', 'mode', 'lifecycle', 'cwd', 'nodeDir', 'contextDir', 'jobDir', 'reportsDir'].every((field) => typeof value[field] === 'string');
+}
+function isLifecycleRuntime(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['isBirth', 'canvasHome', 'profile'])
+        && typeof value['isBirth'] === 'boolean'
+        && typeof value['canvasHome'] === 'string'
+        && (typeof value['profile'] === 'string' || value['profile'] === null);
+}
 function isHookError(value) {
     return isRecord(value)
         && hasOnlyKeys(value, ['code', 'message', 'field', 'next'])