@north-light/crouter 0.3.217 → 0.3.219

package/dist/daemon/api/bridge.js

@@ -33,6 +33,40 @@ import { probeViewSocket, waitForBrokerViewSocket } from '../../core/runtime/vie
  *  client cap) so a remote peer cannot buffer 256MiB before the broker's 24MiB
  *  decoder rejects the message. */
 const wss = new WebSocketServer({ noServer: true, maxPayload: BROKER_READ_CAPS.maxLineBytes });
+/** Keep an otherwise quiet observer connection alive through common 60s proxy
+ * idle limits. A viewer only observes a broker, so a missed heartbeat may close
+ * this socket but must never affect the broker or its in-flight work. */
+export const REMOTE_ATTACH_HEARTBEAT_MS = 25_000;
+export function startRemoteAttachHeartbeat(ws, intervalMs = REMOTE_ATTACH_HEARTBEAT_MS) {
+    let alive = true;
+    let stopped = false;
+    const acknowledge = () => { alive = true; };
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        ws.off('pong', acknowledge);
+    };
+    ws.on('pong', acknowledge);
+    const timer = setInterval(() => {
+        if (!alive) {
+            stop();
+            ws.terminate();
+            return;
+        }
+        alive = false;
+        try {
+            ws.ping();
+        }
+        catch {
+            stop();
+            ws.terminate();
+        }
+    }, intervalMs);
+    timer.unref();
+    return stop;
+}
 /** A WS close reason is capped at 123 UTF-8 bytes by the protocol. */
 function clampReason(reason) {
     const buf = Buffer.from(reason, 'utf8');
@@ -106,6 +140,7 @@ function bridgeConnection(ws, nodeId) {
     const decoder = new FrameDecoder(CLIENT_READ_CAPS);
     let closed = false;
     let viewerFaultRecorded = false;
+    let stopHeartbeat;
     socket.on('connect', () => {
         clearFault(nodeId, { link: 'relay↔broker' });
     });
@@ -113,6 +148,7 @@ function bridgeConnection(ws, nodeId) {
         if (closed)
             return;
         closed = true;
+        stopHeartbeat?.();
         if (!socket.destroyed) {
             try {
                 socket.destroy();
@@ -128,6 +164,7 @@ function bridgeConnection(ws, nodeId) {
             /* ignore */
         }
     };
+    stopHeartbeat = startRemoteAttachHeartbeat(ws);
     // socket → WS: bounded decode, one WS text message per complete frame.
     socket.on('data', (chunk) => {
         let frames;
@@ -183,7 +220,7 @@ function bridgeConnection(ws, nodeId) {
                 link: 'viewer↔crtrd',
                 op: 'remote attach websocket',
                 kind: classification.kind,
-                retry: { disposition: 'manual' },
+                retry: { disposition: 'auto' },
                 message: reasonText || `remote attach closed (${code})`,
             });
         }
@@ -197,7 +234,7 @@ function bridgeConnection(ws, nodeId) {
                 link: 'viewer↔crtrd',
                 op: 'remote attach websocket',
                 kind: classification.kind,
-                retry: { disposition: 'manual' },
+                retry: { disposition: 'auto' },
                 message: 'remote attach websocket error',
             });
         }

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

@@ -278,6 +278,7 @@ function handleSnapshot() {
             lifecycle: row.lifecycle ?? meta?.lifecycle,
             status: row.status,
             cwd: row.cwd,
+            profile_id: meta?.profile_id ?? null,
             parent: meta?.parent ?? null,
             created: row.created,
             host_kind: hostKind,
@@ -289,6 +290,8 @@ function handleSnapshot() {
             streaming: row.streaming ?? false,
             hanging: (row.hanging ?? null),
             viewed: row.viewed ?? false,
+            final_report: meta?.final_report ?? null,
+            finalized_at: meta?.finalized_at ?? null,
         };
     });
     const subscriptions = Object.fromEntries(rows.map((row) => [row.node_id, subscriptionsOf(row.node_id).map((ref) => ref.node_id)]));

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

@@ -226,11 +226,12 @@ function handleList() {
 // GET /v1/human/inbox/history?node_id=<id> — page ticket history
 // ===========================================================================
 function handleHistory(ctx) {
+    // Home-wide when `node_id` is absent; an explicitly empty param is a caller bug.
     const nodeId = ctx.query.get('node_id');
-    if (!nodeId || typeof nodeId !== 'string') {
-        throw new ApiError(400, 'invalid_request', 'history requires a node_id query param');
+    if (nodeId === '') {
+        throw new ApiError(400, 'invalid_request', 'node_id must be nonempty when present');
     }
-    const history = scanPageHistory(nodeId);
+    const history = scanPageHistory(nodeId ?? undefined);
     const canonicalRoot = realpathSync(ticketsRoot());
     const tickets = history.map((item) => pageSummaryToDTO(item, canonicalRoot));
     return { status: 200, body: { tickets } };

package/dist/daemon/api/handlers/nodes.d.ts

@@ -6,6 +6,7 @@ interface NodeHandlerDeps {
 }
 export declare function resolveCreateKind(kind: string | undefined, profile: ReturnType<typeof assertProfileActive>): string;
 export declare function handleCreate(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
+export declare function handleList(ctx: RequestContext): HandlerResult;
 export declare function handlePromote(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare function handleYield(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare function handleConfig(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;

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

@@ -7,26 +7,26 @@
 //
 // `{id}` is the target node.
 import { readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { appendSituationalContext, closeNode, getNode, listNodes, nowIso, reviveNode, } from '../../../index.js';
 import { formatSituationalProse } from '../../../core/runtime/situational-context.js';
 import { assertLaunchModelRegistered, forkNode, resolveProfileId, spawnChild } from '../../../core/runtime/spawn.js';
 import { childrenOf, subscribersOf, subscriptionsOf, setMessageWait, updateNode } from '../../../core/canvas/canvas.js';
 import { subtreeIds } from '../../../core/canvas/nav-model.js';
+import { ticketCountsForNodes } from '../../../core/canvas/attention.js';
 import { contextDir, reportsDir } from '../../../core/canvas/paths.js';
 import { nodeArtifacts } from '../../../core/canvas/history.js';
 import { readNodeMessagesPage, readNodeSession, readNodeSnapshot, transcriptMarkdown } from '../../../core/runtime/node-read.js';
 import { assembleNodeSubject } from '../../../core/substrate/subject.js';
 import { reviveAll } from '../../../core/runtime/revive-all.js';
-import { promote, requestYield, reshapeNode } from '../../../core/runtime/promote.js';
+import { promoteAsync, requestYieldAsync, reshapeNodeAsync } from '../../../core/runtime/promote.js';
 import { recycleNode } from '../../../core/runtime/recycle.js';
 import { relaunchRoot } from '../../../core/runtime/reset.js';
 import { assertReopenGate } from '../../../core/runtime/reopen.js';
 import { writeYieldMessage, readGoal } from '../../../core/runtime/kickoff.js';
 import { hasRoadmap, seedRoadmap } from '../../../core/runtime/roadmap.js';
 import { renameWindow } from '../../../core/runtime/placement.js';
-import { readMergedLaunchConfig } from '../../../core/config.js';
-import { buildLaunchSpec, isProviderPinnedModelToken, normalizeModel } from '../../../core/runtime/launch.js';
+import { buildLaunchSpecAsync, isProviderPinnedModelToken, normalizeModel, readMergedLaunchConfigAsync } from '../../../core/runtime/launch.js';
 import { modelRequestFromConfig } from '../../../core/model-routes.js';
 import { BrokerUnreachableError } from '../../../core/runtime/broker-request.js';
 import { isBrokerLive, persistDormantModel, setModelLive } from '../../../core/runtime/model-swap.js';
@@ -34,6 +34,7 @@ import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
 import { claimWarmNode, refillWarmPool, warmPoolEnabled } from '../../../core/runtime/warm-pool.js';
 import { assertProfileActive, profileHome } from '../../../core/profiles/manifest.js';
 import { fullName } from '../../../core/canvas/labels.js';
+import { reportsForNode } from './reports.js';
 import { getCron } from '../../../core/canvas/crons.js';
 import { cronWakeOrigin } from '../../../core/runtime/bearings.js';
 import { notFound, usage } from '../../../core/errors.js';
@@ -194,13 +195,13 @@ function requestFromLaunch(launch) {
     return modelRequestFromConfig(launch.model, intent, launch.modelExact === true);
 }
 async function assertNodeModelChangeRegistered(meta, target, registry) {
-    const launch = buildLaunchSpec(target.kind, target.mode, {
+    const launch = (await buildLaunchSpecAsync(target.kind, target.mode, {
         lifecycle: target.lifecycle,
         hasManager: meta.parent !== null,
         model: target.model,
         cwd: meta.cwd,
         profileId: meta.profile_id ?? null,
-    }).launch;
+    })).launch;
     await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd: meta.cwd, profileId: meta.profile_id ?? null }, registry);
 }
 export async function handleCreate(ctx, deps = {}) {
@@ -232,16 +233,16 @@ export async function handleCreate(ctx, deps = {}) {
     const profileId = await resolveProfileId(req.profile, parent ?? null, contextCwd);
     const profile = assertProfileActive(profileId);
     const kind = resolveCreateKind(req.kind, profile);
-    assertKindServer(kind);
     const resolvedReq = { ...req, kind };
     const cwd = resolveNodeCwd(resolvedReq, parent, profileId, contextCwd);
-    const launch = buildLaunchSpec(kind, (resolvedReq.mode ?? 'base'), {
+    await assertKindServer(kind, cwd, profileId);
+    const launch = (await buildLaunchSpecAsync(kind, (resolvedReq.mode ?? 'base'), {
         lifecycle: req.root === true ? (req.root_lifecycle ?? 'resident') : 'terminal',
         hasManager: req.root !== true,
         ...(req.model !== undefined ? { model: req.model } : {}),
         cwd,
         profileId,
-    }).launch;
+    })).launch;
     await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd, profileId }, deps.modelRegistry);
     // --- Warm path: hand out an already-booted spare instead of paying a full
     //     engine boot. A miss is not a failure — it falls through to the cold
@@ -266,26 +267,106 @@ export async function handleCreate(ctx, deps = {}) {
 // ---------------------------------------------------------------------------
 // GET /v1/nodes — list (filters) ; GET /v1/nodes/{id} — detail
 // ---------------------------------------------------------------------------
-function handleList(ctx) {
-    const status = ctx.query.get('status');
-    const kind = ctx.query.get('kind');
-    const mode = ctx.query.get('mode');
-    const under = ctx.query.get('under');
-    const hanging = ctx.query.get('hanging');
-    let rows = status !== null ? listNodes({ status }) : listNodes();
-    if (kind !== null)
-        rows = rows.filter((r) => r.kind === kind);
-    if (mode !== null)
-        rows = rows.filter((r) => r.mode === mode);
-    if (under !== null) {
-        const scope = new Set(subtreeIds(under));
-        rows = rows.filter((r) => scope.has(r.node_id));
+function singleQueryValue(ctx, name) {
+    const values = ctx.query.getAll(name);
+    if (values.length > 1)
+        throw usage(`${name} must appear at most once`);
+    return values[0];
+}
+function optionalBoolean(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (value === '1' || value === 'true')
+        return true;
+    if (value === '0' || value === 'false')
+        return false;
+    throw usage(`${name} must be true or false`);
+}
+function oneOf(value, name, allowed) {
+    if (value === undefined)
+        return undefined;
+    if (allowed.includes(value))
+        return value;
+    throw usage(`${name} must be one of: ${allowed.join(', ')}`);
+}
+function parseListQuery(ctx) {
+    const allowed = new Set([
+        'status', 'lifecycle', 'kind', 'mode', 'profile_id', 'profile_prefix',
+        'parent', 'top_level', 'under', 'hanging', 'include',
+    ]);
+    for (const [name] of ctx.query) {
+        if (!allowed.has(name))
+            throw usage(`unknown nodes query parameter: ${name}`);
     }
-    if (hanging === '1' || hanging === 'true') {
-        // A dangling manager edge: a non-root whose recorded parent is gone.
-        rows = rows.filter((r) => r.parent !== null && getNode(r.parent) === null);
+    const status = oneOf(singleQueryValue(ctx, 'status'), 'status', ['active', 'idle', 'done', 'dead', 'canceled']);
+    const lifecycle = oneOf(singleQueryValue(ctx, 'lifecycle'), 'lifecycle', ['terminal', 'resident']);
+    const kind = singleQueryValue(ctx, 'kind');
+    const mode = oneOf(singleQueryValue(ctx, 'mode'), 'mode', ['base', 'orchestrator']);
+    const profileId = singleQueryValue(ctx, 'profile_id');
+    const profilePrefix = singleQueryValue(ctx, 'profile_prefix');
+    const parent = singleQueryValue(ctx, 'parent');
+    const topLevel = optionalBoolean(singleQueryValue(ctx, 'top_level'), 'top_level');
+    const under = singleQueryValue(ctx, 'under');
+    const hanging = optionalBoolean(singleQueryValue(ctx, 'hanging'), 'hanging');
+    const include = oneOf(singleQueryValue(ctx, 'include'), 'include', ['activity']);
+    if (parent !== undefined && topLevel === true) {
+        throw usage('parent and top_level=true cannot be combined');
     }
-    const body = rows.map(toNodeSummaryDTO);
+    return {
+        ...(status !== undefined ? { status } : {}),
+        ...(lifecycle !== undefined ? { lifecycle } : {}),
+        ...(kind !== undefined ? { kind } : {}),
+        ...(mode !== undefined ? { mode } : {}),
+        ...(profileId !== undefined ? { profile_id: profileId } : {}),
+        ...(profilePrefix !== undefined ? { profile_prefix: profilePrefix } : {}),
+        ...(parent !== undefined ? { parent } : {}),
+        ...(topLevel !== undefined ? { top_level: topLevel } : {}),
+        ...(under !== undefined ? { under } : {}),
+        ...(hanging !== undefined ? { hanging } : {}),
+        ...(include !== undefined ? { include: include } : {}),
+    };
+}
+export function handleList(ctx) {
+    const query = parseListQuery(ctx);
+    let rows = query.status !== undefined ? listNodes({ status: query.status }) : listNodes();
+    if (query.lifecycle !== undefined)
+        rows = rows.filter((row) => row.lifecycle === query.lifecycle);
+    if (query.kind !== undefined)
+        rows = rows.filter((row) => row.kind === query.kind);
+    if (query.mode !== undefined)
+        rows = rows.filter((row) => row.mode === query.mode);
+    if (query.profile_id !== undefined)
+        rows = rows.filter((row) => row.profile_id === query.profile_id);
+    if (query.profile_prefix !== undefined)
+        rows = rows.filter((row) => row.profile_id?.startsWith(query.profile_prefix));
+    if (query.parent !== undefined)
+        rows = rows.filter((row) => row.parent === query.parent);
+    if (query.top_level === true)
+        rows = rows.filter((row) => row.parent === null);
+    if (query.under !== undefined) {
+        const scope = new Set(subtreeIds(query.under));
+        rows = rows.filter((row) => scope.has(row.node_id));
+    }
+    if (query.hanging === true) {
+        rows = rows.filter((row) => row.parent !== null && getNode(row.parent) === null);
+    }
+    const counts = query.include === 'activity'
+        ? ticketCountsForNodes(rows.map((row) => row.node_id))
+        : null;
+    const body = rows.map((row) => {
+        const node = toNodeSummaryDTO(row);
+        if (counts !== null) {
+            const reports = reportsForNode(row.node_id);
+            node.activity = {
+                latest_report: reports[0] ?? null,
+                final_report: row.final_report === null
+                    ? null
+                    : reports.find((report) => basename(report.path) === row.final_report) ?? null,
+                pending_human_count: counts[row.node_id] ?? 0,
+            };
+        }
+        return node;
+    });
     return { status: 200, body };
 }
 function handleDetail(ctx) {
@@ -473,12 +554,12 @@ async function handleRecycle(ctx) {
         },
     };
 }
-function handleDemote(ctx) {
+async function handleDemote(ctx) {
     const id = ctx.params['id'];
     requireMeta(id);
     // Use the canonical reshape primitive to ensure modelExact, provider
     // pin/intent, and default-name migration are all preserved.
-    reshapeNode(id, { lifecycle: 'terminal' });
+    await reshapeNodeAsync(id, { lifecycle: 'terminal' });
     return { status: 200, body: detailOf(id) };
 }
 export async function handlePromote(ctx, deps = {}) {
@@ -493,7 +574,7 @@ export async function handlePromote(ctx, deps = {}) {
             model: req.model,
         }, deps.modelRegistry);
     }
-    const result = promote(id, {
+    const result = await promoteAsync(id, {
         ...(req.kind !== undefined ? { kind: req.kind } : {}),
         ...(req.resident === true ? { resident: true } : {}),
         ...(req.model !== undefined ? { model: req.model } : {}),
@@ -520,7 +601,7 @@ export async function handleYield(ctx, deps = {}) {
     }
     const note = req.note ?? 'Refresh: continue against your roadmap or goal.';
     writeYieldMessage(id, note);
-    const result = requestYield(id, {
+    const result = await requestYieldAsync(id, {
         ...(req.promote === true ? { promote: true } : {}),
         ...(req.kind !== undefined ? { kind: req.kind } : {}),
         ...(req.model !== undefined ? { model: req.model } : {}),
@@ -563,7 +644,7 @@ export async function handleConfig(ctx, deps = {}) {
     }
     if (patch.model !== undefined) {
         const pinned = isProviderPinnedModelToken(patch.model);
-        const ladders = readMergedLaunchConfig(meta.cwd, meta.profile_id ?? null).modelLadders;
+        const ladders = (await readMergedLaunchConfigAsync(meta.cwd, meta.profile_id ?? null)).modelLadders;
         const spec = normalizeModel(patch.model, ladders);
         await assertLaunchModelRegistered({ kind: 'concrete', spec }, { cwd: meta.cwd, profileId: meta.profile_id ?? null }, deps.modelRegistry);
         const persistDormant = () => {
@@ -599,7 +680,7 @@ export async function handleConfig(ctx, deps = {}) {
     // --- kind / mode / lifecycle: reshape via canonical primitive (CLI parity). ---
     if (patch.kind !== undefined || patch.mode !== undefined || patch.lifecycle !== undefined) {
         if (patch.kind !== undefined)
-            assertKindServer(patch.kind);
+            await assertKindServer(patch.kind, meta.cwd, meta.profile_id ?? null);
         const newKind = patch.kind ?? meta.kind;
         const newMode = (patch.mode ?? meta.mode);
         const newLifecycle = patch.lifecycle ?? meta.lifecycle;
@@ -615,7 +696,7 @@ export async function handleConfig(ctx, deps = {}) {
         }
         // Use canonical reshape primitive to preserve modelExact, provider pin/intent,
         // and default-name migration.
-        meta = reshapeNode(id, {
+        meta = await reshapeNodeAsync(id, {
             ...(patch.kind !== undefined ? { kind: newKind } : {}),
             ...(patch.mode !== undefined ? { mode: newMode } : {}),
             ...(patch.lifecycle !== undefined ? { lifecycle: newLifecycle } : {}),
@@ -633,8 +714,8 @@ export async function handleConfig(ctx, deps = {}) {
 }
 /** Validate a `--kind` against the installed personas server-side (crtrd reads
  *  the merged launch config). Mirrors the CLI's assertKind. */
-function assertKindServer(kind) {
-    const kinds = Object.keys(readMergedLaunchConfig().kinds);
+async function assertKindServer(kind, cwd, profileId) {
+    const kinds = Object.keys((await readMergedLaunchConfigAsync(cwd, profileId)).kinds);
     if (!kinds.includes(kind)) {
         throw usage(`unknown kind: ${kind}`, { received: kind, next: `Valid kinds: ${kinds.sort().join(', ')}.` });
     }

package/dist/daemon/api/handlers/reports.d.ts

@@ -1,2 +1,6 @@
+import type { ReportDTO } from '../../../api/index.js';
 import type { RouteTable } from '../router.js';
+/** Read one node's pushed reports, newest first. This stays in the daemon so
+ * collection projections can include report activity without client-side N+1s. */
+export declare function reportsForNode(id: string): ReportDTO[];
 export declare const reportRoutes: RouteTable;

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

@@ -110,12 +110,9 @@ function compactToIso(stamp) {
     const m = stamp.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})$/);
     return m === null ? stamp : `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}`;
 }
-function handleList(ctx) {
-    const id = ctx.params['id'];
-    requireNode(id);
-    const tierFilter = ctx.query.get('tier');
-    const limitRaw = ctx.query.get('limit');
-    const limit = limitRaw !== null ? Number(limitRaw) : undefined;
+/** Read one node's pushed reports, newest first. This stays in the daemon so
+ * collection projections can include report activity without client-side N+1s. */
+export function reportsForNode(id) {
     const dir = reportsDir(id);
     let files;
     try {
@@ -136,9 +133,18 @@ function handleList(ctx) {
             (m ? compactToIso(m[1]) : new Date(statSync(abs).mtimeMs).toISOString());
         reports.push({ path: abs, tier, body: body.trim(), created });
     }
-    // Newest first, then apply the optional tier + limit filters.
     reports.sort((a, b) => (a.created < b.created ? 1 : a.created > b.created ? -1 : 0));
-    let out = tierFilter !== null ? reports.filter((r) => r.tier === tierFilter) : reports;
+    return reports;
+}
+function handleList(ctx) {
+    const id = ctx.params['id'];
+    requireNode(id);
+    const tierFilter = ctx.query.get('tier');
+    const limitRaw = ctx.query.get('limit');
+    const limit = limitRaw !== null ? Number(limitRaw) : undefined;
+    let out = reportsForNode(id);
+    if (tierFilter !== null)
+        out = out.filter((report) => report.tier === tierFilter);
     if (limit !== undefined && Number.isFinite(limit) && limit >= 0)
         out = out.slice(0, limit);
     return { status: 200, body: out };

package/dist/daemon/crtrd.js

@@ -62,7 +62,7 @@ import { StorageMaintenanceReconciler } from './reconcilers/storage-maintenance.
 import { captureLivenessSnapshot, capturePidCommand, captureTeardownSnapshot, isPidAlive, killProcessTreePids, } from '../core/canvas/pid.js';
 import { bindFleet, boundFleet } from '../core/runtime/fleet.js';
 import { bindDaemonControl, clearDaemonControl } from './control.js';
-import { spawnDaemon } from './manage.js';
+import { execDaemon, spawnDaemon } from './manage.js';
 import { reconcileAndMigrateBoot } from '../core/canvas/boot.js';
 import { resolveInstallId } from '../core/canvas/install-id.js';
 import { setInstallId } from '../core/runtime/nodes.js';
@@ -480,11 +480,10 @@ export async function runDaemon(opts = {}) {
         }, HANDOVER_ACK_GRACE_MS);
         return { graceMs: HANDOVER_ACK_GRACE_MS };
     }
-    /** Quiesce exactly as a SIGTERM would, then spawn the successor and exit.
+    /** Quiesce exactly as a SIGTERM would, then start the successor.
      *  Ordering is forced: the successor's claim can only be won after this
-     *  daemon has released its own, so teardown strictly precedes the spawn. The
-     *  successor resolves its entry through `runtime/selected`, which is how it
-     *  picks up a generation this process never loaded. */
+     *  daemon has released its own. PID 1 is replaced in place so a container
+     *  does not stop between daemon generations; ordinary hosts spawn and exit. */
     async function performHandover() {
         try {
             await requestCleanup();
@@ -495,6 +494,9 @@ export async function runDaemon(opts = {}) {
             process.exit(1);
         }
         try {
+            if (process.pid === 1) {
+                await execDaemon();
+            }
             const spawned = await spawnDaemon();
             operationIdContext.fresh(() => {
                 emitEvent({

package/dist/daemon/manage.d.ts

@@ -36,6 +36,9 @@ export declare function findDaemonPids(): number[];
  *  reaped. Best-effort throughout: a pid that dies between enumeration and signal
  *  just no-ops. */
 export declare function sweepStrayDaemons(keepPid: number | null): number[];
+/** Replace PID 1 with the selected daemon generation. Docker keeps a container
+ *  alive only while PID 1 lives, so a handover there must preserve its pid. */
+export declare function execDaemon(): Promise<never>;
 export interface SpawnDaemonResult {
     /** True when a new daemon process was spawned. */
     started: boolean;

package/dist/daemon/manage.js

@@ -190,6 +190,20 @@ export function sweepStrayDaemons(keepPid) {
     }
     return strays;
 }
+// ---------------------------------------------------------------------------
+// daemon launch — low-level spawn/exec
+// ---------------------------------------------------------------------------
+/** Replace PID 1 with the selected daemon generation. Docker keeps a container
+ *  alive only while PID 1 lives, so a handover there must preserve its pid. */
+export async function execDaemon() {
+    const execve = process.execve;
+    if (execve === undefined) {
+        throw new Error(`this Node.js ${process.version} runtime cannot replace PID 1 with the successor daemon`);
+    }
+    const executable = hostExecPath();
+    const launchArgs = await resolveDaemonLaunch();
+    return execve(executable, [executable, ...launchArgs, '--canvas-home', crtrHome()], sanitizedDaemonEnv());
+}
 // Daemon lifecycle transitions are bounded so callers never claim a state
 // change before the pidfile and process liveness agree.
 //

package/dist/pi-extensions/canvas-bash-valve.d.ts

@@ -4,9 +4,10 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
  *  not open with a sleep (or its duration isn't statically knowable). */
 export declare function leadingSleepSeconds(command: string): number | null;
 /** The valve's BashOperations backend. Each tool execution closes over its own
- * `takePurpose`, so concurrent calls cannot exchange labels. It is consumed even
- * when the command is invalid or refused, leaving no state to leak later. */
-export declare function createValveOperations(nodeId: string, contextDir: string, takePurpose?: () => string | null): BashOperations;
+ * `takePurpose` and its own preview-result path, so concurrent calls cannot
+ * exchange labels or result mirrors. The purpose is consumed even when the
+ * command is invalid or refused, leaving no state to leak later. */
+export declare function createValveOperations(nodeId: string, contextDir: string, takePurpose?: () => string | null, previewPath?: string): BashOperations;
 type BashToolDefinition = ReturnType<typeof createBashToolDefinition>;
 /** Build the valve-backed bash tool and, when configured, add `purpose` to its
  * schema. Bind each purpose directly to its own execution: Pi may preflight a

package/dist/pi-extensions/canvas-bash-valve.js

@@ -27,8 +27,10 @@
 import { spawn } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
+import { dirname } from 'node:path';
 import { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId, normalizeBashJobPurpose } from '../core/bash-jobs.js';
 import { readConfig } from '../core/config.js';
+import { PREVIEW_RESULT_PATH_ENV, previewResultPath } from '../core/preview-result-path.js';
 import { resolveAdmittedHostCommand } from '../core/runtime/spawn-env.js';
 import { Type } from 'typebox';
 import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
@@ -218,9 +220,10 @@ function resolveExecutionCwd(cwd) {
     };
 }
 /** The valve's BashOperations backend. Each tool execution closes over its own
- * `takePurpose`, so concurrent calls cannot exchange labels. It is consumed even
- * when the command is invalid or refused, leaving no state to leak later. */
-export function createValveOperations(nodeId, contextDir, takePurpose = () => null) {
+ * `takePurpose` and its own preview-result path, so concurrent calls cannot
+ * exchange labels or result mirrors. The purpose is consumed even when the
+ * command is invalid or refused, leaving no state to leak later. */
+export function createValveOperations(nodeId, contextDir, takePurpose = () => null, previewPath) {
     return {
         exec: (command, cwd, { onData, signal, timeout, env }) => {
             return new Promise((resolve, reject) => {
@@ -309,12 +312,20 @@ export function createValveOperations(nodeId, contextDir, takePurpose = () => nu
                 const execution = resolveExecutionCwd(cwd);
                 if (execution.warning)
                     onData(Buffer.from(execution.warning));
-                const shellPath = resolveAdmittedHostCommand('bash', env ?? process.env, execution.cwd);
+                // The preview path reaches crtr through the environment, never through
+                // the command text: cmd.sh, job inspection, and the doc substrate's
+                // `command` surfaces all read that text as the agent's own words.
+                let childEnv = env ?? process.env;
+                if (previewPath !== undefined) {
+                    mkdirSync(dirname(previewPath), { recursive: true });
+                    childEnv = { ...childEnv, [PREVIEW_RESULT_PATH_ENV]: previewPath };
+                }
+                const shellPath = resolveAdmittedHostCommand('bash', childEnv, execution.cwd);
                 const child = spawn(shellPath, ['-c', SUPERVISOR_SCRIPT, '--', paths.cmdSh, paths.jobLog, paths.jobExit, paths.jobRun, paths.jobDone, paths.jobBg, paths.jobId, nodeId, shellPath], {
                     cwd: execution.cwd,
                     detached: true,
                     stdio: 'ignore',
-                    env: env ?? process.env,
+                    env: childEnv,
                 });
                 child.on('error', (err) => {
                     finish(() => reject(err));
@@ -418,7 +429,9 @@ export function createValveToolDefinition(nodeId, contextDir, cwd, exposePurpose
     const schemaDefinition = exposePurpose ? withPurpose(baseDefinition) : baseDefinition;
     const execute = (toolCallId, params, signal, onUpdate, ctx) => {
         const purpose = exposePurpose ? normalizeBashJobPurpose(params['purpose']) : null;
-        const definition = createBashToolDefinition(cwd, { operations: createValveOperations(nodeId, contextDir, () => purpose) });
+        const definition = createBashToolDefinition(cwd, {
+            operations: createValveOperations(nodeId, contextDir, () => purpose, previewResultPath(toolCallId)),
+        });
         return definition.execute(toolCallId, params, signal, onUpdate, ctx);
     };
     return { ...schemaDefinition, execute };

package/dist/pi-extensions/canvas-preview-result.d.ts

@@ -1,17 +1,9 @@
-interface ToolCallEvent {
-    toolName: string;
-    toolCallId: string;
-    input: {
-        command?: string;
-    };
-}
 interface ToolResultEvent {
     toolName: string;
     toolCallId: string;
     details?: Record<string, unknown>;
 }
 interface PiLike {
-    on(event: 'tool_call', handler: (event: ToolCallEvent) => void): void;
     on(event: 'tool_result', handler: (event: ToolResultEvent) => {
         details: Record<string, unknown>;
     } | void): void;