@north-light/crouter 0.3.218 → 0.3.219

package/dist/core/runtime/launch-config-worker.d.ts

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

package/dist/core/runtime/launch-config-worker.js

@@ -0,0 +1,12 @@
+// Runs the synchronous configuration resolver outside crtrd's process. A
+// network filesystem can block a native read indefinitely; unlike a worker
+// thread, this subprocess can be killed at the launch-config timeout.
+import { readMergedLaunchConfig } from '../config.js';
+process.once('message', (message) => {
+    try {
+        process.send?.({ config: readMergedLaunchConfig(message.cwd, message.profileId) });
+    }
+    catch (error) {
+        process.send?.({ error: error instanceof Error ? error.message : String(error) });
+    }
+});

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

@@ -1,3 +1,4 @@
+import { type MergedLaunchConfig } from '../config.js';
 import type { PiInvocation } from './invocation.js';
 export { CANVAS_EXTENSIONS, CANVAS_STOPHOOK_PATH, CANVAS_INBOX_WATCHER_PATH, CANVAS_RECAP_PATH, CANVAS_GOAL_CAPTURE_PATH, CANVAS_PASSIVE_CONTEXT_PATH, CANVAS_CONTEXT_INTRO_PATH, CANVAS_TOOL_GUIDE_PATH, CANVAS_DOC_SUBSTRATE_PATH, CANVAS_STRUCTURED_OUTPUT_PATH, CANVAS_BASH_VALVE_PATH, } from './canvas-extensions.js';
 import type { NodeMeta, LaunchSpec, Mode, Lifecycle } from '../canvas/index.js';
@@ -59,7 +60,7 @@ export declare function nextLadderModel(currentSpec: string, direction?: 1 | -1,
  *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
  *  as-given, never derived from persona frontmatter. The two canvas
  *  extensions are always first; kind-declared extensions follow. */
-export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
+export interface LaunchBuildOptions {
     lifecycle: Lifecycle;
     hasManager: boolean;
     extraEnv?: Record<string, string>;
@@ -101,10 +102,23 @@ export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
      *  broker's launch-time/turn-time resolution paths must bypass every
      *  fallback for and fail closed on unavailability. */
     modelExact?: boolean;
-}): {
+}
+/** Build a launch recipe for callers that are not on crtrd's event loop. */
+export declare function buildLaunchSpec(kind: string, mode: Mode, opts: LaunchBuildOptions): {
     launch: LaunchSpec;
     lifecycle: 'terminal' | 'resident';
 };
+/**
+ * Resolve launch config in a bounded subprocess before building a recipe.
+ * crtrd is single-threaded: project/profile roots can live on a network
+ * filesystem, so even an ordinary synchronous config read must never run on
+ * its event loop.
+ */
+export declare function buildLaunchSpecAsync(kind: string, mode: Mode, opts: LaunchBuildOptions): Promise<{
+    launch: LaunchSpec;
+    lifecycle: 'terminal' | 'resident';
+}>;
+export declare function readMergedLaunchConfigAsync(cwd: string, profileId: string | null): Promise<MergedLaunchConfig>;
 export type { PiInvocation } from './invocation.js';
 /** Construct the pi invocation for a node.
  *  - fresh start: pass `prompt` (the node's first user message), no resume.

package/dist/core/runtime/launch.js

@@ -11,6 +11,8 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { readMergedLaunchConfig } from '../config.js';
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { LAUNCH_SYSTEM_PROMPT } from './launch-prompt.js';
 import { nodeEnv } from './nodes.js';
 import { editorLabel } from '../canvas/index.js';
@@ -232,27 +234,7 @@ export function nextLadderModel(currentSpec, direction = 1, providers) {
         return order[0];
     return order[(idx + direction + order.length) % order.length];
 }
-// ---------------------------------------------------------------------------
-// Build the launch spec from {kind, mode}
-// ---------------------------------------------------------------------------
-/** Compose a node's full pi launch recipe from the kind registry. The system
- *  prompt is now a minimal static scaffold (`LAUNCH_SYSTEM_PROMPT`) — runtime/
- *  spine/lifecycle/kind prose is spliced per-turn from gated builtin memory docs,
- *  not baked in here. Launch KNOBS (model/tools/extensions) still come from the
- *  kind registry (`resolveKindConfig`), keyed on the FULL kind string (top-level
- *  or sub-kind). Model precedence, strongest to weakest:
- *   1. Caller-supplied `opts.model` (durable on `meta.model_override`, re-passed
- *      on every polymorph).
- *   2. The kind's registered model — mode-aware: orchestrator mode prefers
- *      `orchestratorModel`, falling back to `model`; base mode always uses
- *      `model`.
- *   3. Unset → pi default.
- *  Callers pass the authoritative lifecycle + hasManager (`parent !== null`) so
- *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
- *  as-given, never derived from persona frontmatter. The two canvas
- *  extensions are always first; kind-declared extensions follow. */
-export function buildLaunchSpec(kind, mode, opts) {
-    const merged = readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null));
+function buildLaunchSpecFromMerged(kind, mode, opts, merged) {
     const kindConfig = merged.kinds[kind];
     const ladders = merged.modelLadders;
     const kindModel = mode === 'orchestrator' ? kindConfig?.orchestratorModel ?? kindConfig?.model : kindConfig?.model;
@@ -274,6 +256,58 @@ export function buildLaunchSpec(kind, mode, opts) {
     };
     return { launch, lifecycle: opts.lifecycle };
 }
+/** Build a launch recipe for callers that are not on crtrd's event loop. */
+export function buildLaunchSpec(kind, mode, opts) {
+    return buildLaunchSpecFromMerged(kind, mode, opts, readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null)));
+}
+/**
+ * Resolve launch config in a bounded subprocess before building a recipe.
+ * crtrd is single-threaded: project/profile roots can live on a network
+ * filesystem, so even an ordinary synchronous config read must never run on
+ * its event loop.
+ */
+export async function buildLaunchSpecAsync(kind, mode, opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const profileId = opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null);
+    const merged = await readMergedLaunchConfigAsync(cwd, profileId);
+    return buildLaunchSpecFromMerged(kind, mode, opts, merged);
+}
+const LAUNCH_CONFIG_TIMEOUT_MS = 15_000;
+export function readMergedLaunchConfigAsync(cwd, profileId) {
+    return new Promise((resolve, reject) => {
+        const child = fork(fileURLToPath(new URL('./launch-config-worker.js', import.meta.url)), [], {
+            stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+            serialization: 'advanced',
+        });
+        child.send({ cwd, profileId });
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (child.connected)
+                child.disconnect();
+            if (!child.killed)
+                child.kill('SIGKILL');
+            fn();
+        };
+        const timeout = setTimeout(() => finish(() => reject(new Error(`timed out after ${LAUNCH_CONFIG_TIMEOUT_MS}ms reading launch config for ${cwd}`))), LAUNCH_CONFIG_TIMEOUT_MS);
+        child.once('message', (message) => {
+            if (message.error !== undefined)
+                finish(() => reject(new Error(message.error)));
+            else if (message.config !== undefined)
+                finish(() => resolve(message.config));
+            else
+                finish(() => reject(new Error('launch config subprocess returned no result')));
+        });
+        child.once('error', (error) => finish(() => reject(error)));
+        child.once('exit', (code, signal) => {
+            if (code !== 0 && signal !== 'SIGKILL')
+                finish(() => reject(new Error(`launch config subprocess exited with code ${code}`)));
+        });
+    });
+}
 // ---------------------------------------------------------------------------
 // Build the pi argv to launch / revive a node
 // ---------------------------------------------------------------------------

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

@@ -14,13 +14,17 @@ export interface PromoteResult {
  *  is what a plain `crtr node yield --kind/--model` reshape rides, with no
  *  mode flip and no roadmap seeding. `promote()` below is a thin wrapper that
  *  also forces mode→orchestrator and seeds the roadmap. */
-export declare function reshapeNode(nodeId: string, opts?: {
+type ReshapeOptions = {
     kind?: string;
     model?: string;
     mode?: Mode;
     lifecycle?: Lifecycle;
     profileId?: string | null;
-}, beforePersist?: () => void): NodeMeta;
+};
+/** Synchronous reshape for CLI callers outside the daemon. */
+export declare function reshapeNode(nodeId: string, opts?: ReshapeOptions, beforePersist?: () => void): NodeMeta;
+/** Daemon-safe reshape: network-backed config resolution happens off its event loop. */
+export declare function reshapeNodeAsync(nodeId: string, opts?: ReshapeOptions, beforePersist?: () => void): Promise<NodeMeta>;
 /** Promote a node to an orchestrator (mode→orchestrator), optionally
  *  specializing its kind (e.g. a `general` worker becoming a
  *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
@@ -33,6 +37,12 @@ export declare function promote(nodeId: string, opts?: {
     resident?: boolean;
     model?: string;
 }): PromoteResult;
+/** Daemon-safe promotion variant; preserves the same validation/seed ordering. */
+export declare function promoteAsync(nodeId: string, opts?: {
+    kind?: string;
+    resident?: boolean;
+    model?: string;
+}): Promise<PromoteResult>;
 export interface YieldResult {
     meta: NodeMeta;
     /** True iff `promote:true` was passed — a plain yield never flips mode. */
@@ -49,6 +59,13 @@ export interface YieldResult {
  *  same path `crtr node promote` would — mode flips to orchestrator and a
  *  roadmap scaffold is seeded. Sets intent='refresh'; the stophook shuts the
  *  process down on the next stop and the daemon revives it fresh. */
+export declare function requestYieldAsync(nodeId: string, opts?: {
+    kind?: string;
+    model?: string;
+    promote?: boolean;
+}, deps?: {
+    ensure?: () => void;
+}): Promise<YieldResult>;
 export declare function requestYield(nodeId: string, opts?: {
     kind?: string;
     model?: string;
@@ -56,3 +73,4 @@ export declare function requestYield(nodeId: string, opts?: {
 }, deps?: {
     ensure?: () => void;
 }): YieldResult;
+export {};

package/dist/core/runtime/promote.js

@@ -21,75 +21,48 @@
 import { getNode, updateNode } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { ensureDaemon } from '../../daemon/manage.js';
-import { buildLaunchSpec } from './launch.js';
+import { buildLaunchSpec, buildLaunchSpecAsync } from './launch.js';
 import { hasRoadmap, seedRoadmap, roadmapPath } from './roadmap.js';
 import { readGoal, goalPath } from './kickoff.js';
-/** Shared reshape machinery: rewrite kind and/or model tier — and, when the
- *  caller supplies them, mode/lifecycle — by rebuilding the launch spec so the
- *  change is durable across a future revive. MODE-PRESERVING by default (omit
- *  `mode`/`lifecycle` and the node's own current values carry through) — this
- *  is what a plain `crtr node yield --kind/--model` reshape rides, with no
- *  mode flip and no roadmap seeding. `promote()` below is a thin wrapper that
- *  also forces mode→orchestrator and seeds the roadmap. */
-export function reshapeNode(nodeId, opts = {}, beforePersist) {
+function reshapeInputs(nodeId, opts) {
     const node = getNode(nodeId);
     if (node === null)
         throw new Error(`unknown node: ${nodeId}`);
-    // The node may specialize as it reshapes; default to its current kind.
-    const targetKind = opts.kind ?? node.kind;
-    // ...and may raise/change its model tier; default to its current pin (so a
-    // reshape with no --model preserves whatever it was running on).
-    const targetModel = opts.model ?? node.model_override ?? undefined;
-    const targetMode = opts.mode ?? node.mode;
-    const targetLifecycle = opts.lifecycle ?? node.lifecycle;
-    const targetProfileId = opts.profileId === undefined ? node.profile_id : opts.profileId;
-    // Rewrite the launch spec to the target kind/mode's persona so the *next*
-    // revive comes back as this exact shape (polymorph stage 2). nodeEnv reads
-    // meta.{kind,mode}, so CRTR_KIND/CRTR_MODE flip immediately for the live
-    // process's children too.
-    const { launch } = buildLaunchSpec(targetKind, targetMode, {
-        lifecycle: targetLifecycle,
-        hasManager: node.parent !== null,
-        // A model tier chosen on this call (opts.model) overrides the persona
-        // default and is persisted below; absent one, the existing pin carries
-        // across the polymorph (the persona default is recomputed fresh for
-        // targetKind).
-        model: targetModel,
-        // opts.model given — an explicit new pick — lets buildLaunchSpec re-decide
-        // the pin from ITS raw shape (undefined here). No opts.model — targetModel
-        // just re-supplies the current value for resolution, not a new user
-        // choice — so carry the node's existing pin verbatim instead.
-        modelProviderPinned: opts.model === undefined ? node.launch?.modelProviderPinned : undefined,
-        modelIntent: opts.model === undefined ? node.launch?.modelIntent : undefined,
-        // Exact-model human-work forks must stay fail-closed after a polymorph.
-        // Dropping this bit produces a recipe reviveNode refuses to relaunch.
-        modelExact: opts.model === undefined ? node.launch?.modelExact : undefined,
-        // Resolve kind/ladder config against the NODE's own cwd + profile, not
-        // this process's ambient scope.
-        cwd: node.cwd,
-        profileId: targetProfileId,
-    });
-    // Promotion seeds after its target launch has been built but before the
-    // mutation is persisted, preserving the original promote() failure order.
+    const kind = opts.kind ?? node.kind;
+    const mode = opts.mode ?? node.mode;
+    const lifecycle = opts.lifecycle ?? node.lifecycle;
+    const profileId = opts.profileId === undefined ? node.profile_id ?? null : opts.profileId;
+    return {
+        node, kind, mode, lifecycle, profileId,
+        launchOpts: {
+            lifecycle, hasManager: node.parent !== null, model: opts.model ?? node.model_override ?? undefined,
+            modelProviderPinned: opts.model === undefined ? node.launch?.modelProviderPinned : undefined,
+            modelIntent: opts.model === undefined ? node.launch?.modelIntent : undefined,
+            modelExact: opts.model === undefined ? node.launch?.modelExact : undefined,
+            cwd: node.cwd, profileId,
+        },
+    };
+}
+function persistReshape(nodeId, opts, input, launch, beforePersist) {
     beforePersist?.();
-    // If the handle is still the spawn-time kind default (name === old kind),
-    // carry it to the new kind so the "name === kind ⇒ default, drop it" invariant
-    // in fullName() holds across a kind change. Otherwise a node spawned `general`
-    // (name="general") that reshapes to `plan` would surface a stale "general"
-    // handle in front of its real description.
-    const carriesDefaultHandle = node.name === node.kind && targetKind !== node.kind;
+    const carriesDefaultHandle = input.node.name === input.node.kind && input.kind !== input.node.kind;
     return updateNode(nodeId, {
-        kind: targetKind,
-        mode: targetMode,
-        lifecycle: targetLifecycle,
-        profile_id: targetProfileId,
-        launch,
-        ...(carriesDefaultHandle ? { name: targetKind } : {}),
-        // Persist a newly-chosen tier so it is durable across future revives; omit
-        // when unchanged so the existing pin (or persona default) stands.
+        kind: input.kind, mode: input.mode, lifecycle: input.lifecycle, profile_id: input.profileId, launch,
+        ...(carriesDefaultHandle ? { name: input.kind } : {}),
         ...(opts.model !== undefined ? { model_override: opts.model } : {}),
     });
 }
+/** Synchronous reshape for CLI callers outside the daemon. */
+export function reshapeNode(nodeId, opts = {}, beforePersist) {
+    const input = reshapeInputs(nodeId, opts);
+    return persistReshape(nodeId, opts, input, buildLaunchSpec(input.kind, input.mode, input.launchOpts).launch, beforePersist);
+}
+/** Daemon-safe reshape: network-backed config resolution happens off its event loop. */
+export async function reshapeNodeAsync(nodeId, opts = {}, beforePersist) {
+    const input = reshapeInputs(nodeId, opts);
+    const { launch } = await buildLaunchSpecAsync(input.kind, input.mode, input.launchOpts);
+    return persistReshape(nodeId, opts, input, launch, beforePersist);
+}
 /** Promote a node to an orchestrator (mode→orchestrator), optionally
  *  specializing its kind (e.g. a `general` worker becoming a
  *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
@@ -129,6 +102,25 @@ export function promote(nodeId, opts = {}) {
         goalPath: goalPath(nodeId),
     };
 }
+/** Daemon-safe promotion variant; preserves the same validation/seed ordering. */
+export async function promoteAsync(nodeId, opts = {}) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    let roadmapWritten = false;
+    const meta = await reshapeNodeAsync(nodeId, {
+        ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+        ...(opts.model !== undefined ? { model: opts.model } : {}),
+        mode: 'orchestrator', lifecycle: opts.resident === true ? 'resident' : node.lifecycle,
+    }, () => {
+        if (!hasRoadmap(nodeId)) {
+            const goal = readGoal(nodeId);
+            seedRoadmap(nodeId, goal !== null && goal.trim() !== '' ? { goal: goal.trim() } : {});
+            roadmapWritten = true;
+        }
+    });
+    return { meta, roadmapWritten, roadmapPath: roadmapPath(nodeId), goalPath: goalPath(nodeId) };
+}
 /** Request a refresh-yield: discard in-memory context and revive fresh, mode
  *  and lifecycle UNCHANGED, against the roadmap if one exists else the
  *  original goal (`buildReviveKickoff` falls back to it). A plain yield is
@@ -138,6 +130,18 @@ export function promote(nodeId, opts = {}) {
  *  same path `crtr node promote` would — mode flips to orchestrator and a
  *  roadmap scaffold is seeded. Sets intent='refresh'; the stophook shuts the
  *  process down on the next stop and the daemon revives it fresh. */
+export async function requestYieldAsync(nodeId, opts = {}, deps = {}) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    if (opts.promote === true) {
+        await promoteAsync(nodeId, { ...(opts.kind !== undefined ? { kind: opts.kind } : {}), ...(opts.model !== undefined ? { model: opts.model } : {}) });
+    }
+    else if (opts.kind !== undefined || opts.model !== undefined) {
+        await reshapeNodeAsync(nodeId, { ...(opts.kind !== undefined ? { kind: opts.kind } : {}), ...(opts.model !== undefined ? { model: opts.model } : {}) });
+    }
+    return { ...requestYield(nodeId, {}, deps), promoted: opts.promote === true };
+}
 export function requestYield(nodeId, opts = {}, deps = {}) {
     const ensure = deps.ensure ?? ensureDaemon;
     const node = getNode(nodeId);

package/dist/core/runtime/recycle.js

@@ -21,7 +21,7 @@ import { getNode, setPresence, setFocusOccupant, fullName } from '../canvas/inde
 import { reportsDir } from '../canvas/paths.js';
 import { pushFinal } from '../feed/feed.js';
 import { spawnNode, rootOfSpine } from './nodes.js';
-import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { focusOf, respawnPaneSync, setPaneOption } from './placement.js';
 import { waitForBrokerViewSocket, viewerSplitEnv } from './placement-tmux.js';
 import { headlessBrokerHost } from './host.js';
@@ -102,7 +102,7 @@ export async function recycleNode(nodeId, callerPane) {
     // ambient scope) and carry the profile onto the fresh root — it is the same
     // person's seat, so profile-scope defaults (e.g. a persisted /model default)
     // must keep applying.
-    const { launch } = buildLaunchSpec('general', 'base', { lifecycle: 'resident', hasManager: false, cwd: meta.cwd, profileId: meta.profile_id });
+    const { launch } = await buildLaunchSpecAsync('general', 'base', { lifecycle: 'resident', hasManager: false, cwd: meta.cwd, profileId: meta.profile_id });
     const root = spawnNode({
         kind: 'general',
         mode: 'base',

package/dist/core/runtime/reset.js

@@ -25,7 +25,7 @@ import { transition } from './lifecycle.js';
 import { headlessBrokerHost } from './host.js';
 import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPane, renameWindow, } from './placement.js';
 import { viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
-import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { spawnNode, rootOfSpine } from './nodes.js';
 // ---------------------------------------------------------------------------
 // reapDescendants — tear down a root's descendant sub-DAG (shared helper)
@@ -83,7 +83,7 @@ export async function relaunchRoot(oldId, deps = {}) {
     // --- mint + boot the NEW broker FIRST (a failure here leaves the old root
     //     untouched) ---
     // A relaunched root is a fresh resident base, exactly like the front door.
-    const { launch } = buildLaunchSpec(old.kind, 'base', {
+    const { launch } = await buildLaunchSpecAsync(old.kind, 'base', {
         lifecycle: 'resident',
         hasManager: false,
         model: old.model_override ?? undefined,

package/dist/core/runtime/spawn.js

@@ -14,7 +14,7 @@ import { isAbsolute, resolve, join } from 'node:path';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId } from './nodes.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
 import { selectProfileForCwd } from '../profiles/select.js';
-import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
 import { usage, brokerLaunchFailed } from '../errors.js';
 import { writeGoal } from './kickoff.js';
@@ -237,7 +237,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     if (opts.nodeId !== undefined)
         preflightNodeId(opts.nodeId);
     const profileId = await resolveProfileId(opts.profile, spawner, opts.cwd);
-    const preflightLaunch = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: opts.cwd, profileId }).launch;
+    const preflightLaunch = (await buildLaunchSpecAsync(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: opts.cwd, profileId })).launch;
     await assertLaunchModelRegistered(requestFromLaunch(preflightLaunch), { cwd: opts.cwd, profileId });
     const forkFrom = opts.forkFrom !== undefined ? resolveForkSource(opts.forkFrom) : undefined;
     let managedWorktree;
@@ -255,7 +255,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // this process's ambient scope (a front-door shell has no CRTR_PROFILE_ID,
         // which silently hid every profile-scope kind override).
         const launch = wantsWorktree
-            ? buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: spawnCwd, profileId }).launch
+            ? (await buildLaunchSpecAsync(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: spawnCwd, profileId })).launch
             : preflightLaunch;
         if (wantsWorktree) {
             await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd: spawnCwd, profileId });

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

@@ -62,7 +62,7 @@ import { claimWarmSpare, deleteNode, getNode, listNodes, listWarmSpares, registe
 import { recordedPidLiveness } from '../canvas/pid.js';
 import { nowIso } from '../fs-utils.js';
 import { spawnChildPrepared } from './spawn.js';
-import { buildLaunchSpec } from './launch.js';
+import { buildLaunchSpecAsync } from './launch.js';
 import { setModelLive } from './model-swap.js';
 import { setSituationalContextLive } from './situational-live.js';
 import { deliverBearingsLive } from './deliver-live.js';
@@ -100,8 +100,8 @@ function warmRecipeKey(cwd, profileId, launch) {
 }
 /** Resolve a request's frozen half. Both cwd and profile arrive already
  *  resolved from the create handler, so this is pure launch-spec construction. */
-function resolveRecipe(request) {
-    const { launch } = buildLaunchSpec(request.kind, request.mode, {
+async function resolveRecipe(request) {
+    const { launch } = await buildLaunchSpecAsync(request.kind, request.mode, {
         lifecycle: 'resident',
         hasManager: false,
         ...(request.model !== null ? { model: request.model } : {}),
@@ -114,7 +114,7 @@ function resolveRecipe(request) {
  *  pool cannot serve it. The caller falls back to a cold spawn; a claim never
  *  fails the create. */
 export async function claimWarmNode(request) {
-    const recipe = resolveRecipe(request);
+    const recipe = await resolveRecipe(request);
     const created = nowIso();
     // The row's stamp moves inside the claim transaction; meta.json (the identity
     // source of truth `rebuildIndex` re-derives the row from) follows with the
@@ -261,7 +261,9 @@ export function refillWarmPool(request) {
         // Mint at the kind's DEFAULT model and with NO situational context: both
         // are claim-time properties, so baking either in would only narrow who the
         // spare can serve.
-        mint(resolveRecipe({ ...request, model: null, situationalContext: null }));
+        void resolveRecipe({ ...request, model: null, situationalContext: null })
+            .then(mint)
+            .catch((err) => console.error(`[warm-pool] recipe resolution failed: ${err.message}`));
     }
     catch (err) {
         console.error(`[warm-pool] recipe resolution failed: ${err.message}`);
@@ -349,7 +351,7 @@ export function prewarmRecentRecipes() {
             // `general`/`base` is only the shape the spare BOOTS as — the key it is
             // filed under excludes everything a claim can reshape, so any kind can
             // claim it.
-            mint(resolveRecipe({
+            void resolveRecipe({
                 kind: 'general',
                 mode: 'base',
                 cwd: candidate.cwd,
@@ -357,7 +359,7 @@ export function prewarmRecentRecipes() {
                 model: null,
                 situationalContext: null,
                 name: null,
-            }));
+            }).then(mint).catch((err) => console.error(`[warm-pool] prewarm failed for ${candidate.cwd}: ${err.message}`));
         }
         catch (err) {
             console.error(`[warm-pool] prewarm failed for ${candidate.cwd}: ${err.message}`);

package/dist/daemon/api/__tests__/bridge-heartbeat.test.d.ts

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

package/dist/daemon/api/__tests__/bridge-heartbeat.test.js

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import test from 'node:test';
+import { startRemoteAttachHeartbeat } from '../bridge.js';
+class FakeSocket extends EventEmitter {
+    pings = 0;
+    terminated = 0;
+    ping() { this.pings += 1; }
+    terminate() { this.terminated += 1; }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+test('remote attach heartbeat pings an idle viewer and keeps a ponging observer alive', async () => {
+    const ws = new FakeSocket();
+    const stop = startRemoteAttachHeartbeat(ws, 20);
+    await sleep(25);
+    assert.equal(ws.pings, 1, 'an idle attach receives a WebSocket ping before proxy idle timeout');
+    ws.emit('pong');
+    await sleep(10);
+    assert.equal(ws.terminated, 0, 'a pong renews the heartbeat without terminating the observer');
+    stop();
+});
+test('remote attach heartbeat drops only an unresponsive observer socket', async () => {
+    const ws = new FakeSocket();
+    const stop = startRemoteAttachHeartbeat(ws, 5);
+    await sleep(16);
+    assert.equal(ws.terminated, 1, 'two missed heartbeat intervals terminate the detached viewer');
+    stop();
+});

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

@@ -169,6 +169,36 @@ test('A4a: WS attach welcome.snapshot is byte-identical to a direct ViewSocketCl
     assert.equal(JSON.stringify(wsWelcome.snapshot), JSON.stringify(direct.welcome.snapshot), 'WS welcome.snapshot is byte-identical to the direct ViewSocketClient snapshot');
     direct.close();
 });
+test('A4a regression: reconnecting an observer keeps the live broker instance', async () => {
+    const root = h.spawnRoot('a4 reconnect root');
+    const id = (await client.createNode({ kind: 'developer', parent: root, prompt: 'a4 reconnect worker' })).node_id;
+    await h.awaitBoot(id);
+    const pid = h.node(id)?.pi_pid;
+    const boots = h.bootCount(id);
+    const attachOnce = () => new Promise((resolveAttach, rejectAttach) => {
+        const ws = new WebSocket(`ws+unix://${sockPath}:/v1/nodes/${id}/attach`);
+        const timer = setTimeout(() => {
+            ws.terminate();
+            rejectAttach(new Error('timed out waiting for observer welcome'));
+        }, 15_000);
+        ws.on('open', () => ws.send(JSON.stringify({ type: 'hello', role: 'observer', client_id: `a4-reconnect-${Math.random()}` })));
+        ws.on('message', (data) => {
+            if (JSON.parse(data.toString('utf8'))['type'] !== 'welcome')
+                return;
+            clearTimeout(timer);
+            ws.close();
+            resolveAttach();
+        });
+        ws.on('error', (error) => {
+            clearTimeout(timer);
+            rejectAttach(error);
+        });
+    });
+    await attachOnce();
+    await attachOnce();
+    assert.equal(h.bootCount(id), boots, 'observer reconnect did not relaunch the broker');
+    assert.equal(h.node(id)?.pi_pid, pid, 'the in-flight broker instance was retained');
+});
 test('A4b: ?revive=0 on a dormant node refuses 409 without launching a broker', async () => {
     const root = h.spawnRoot('a4b root');
     // A dormant row: no live broker, no pi_pid, view.sock absent.

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

@@ -1,5 +1,11 @@
 import type { IncomingMessage } from 'node:http';
 import type { Duplex } from 'node:stream';
+import { type WebSocket } from 'ws';
+/** 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 declare const REMOTE_ATTACH_HEARTBEAT_MS = 25000;
+export declare function startRemoteAttachHeartbeat(ws: WebSocket, intervalMs?: number): () => void;
 /** Handle the HTTP upgrade for `GET /v1/nodes/{id}/attach`. A-9 matches the
  *  route, extracts `{id}`, and calls this with the raw upgrade triplet; this
  *  owns the WS handshake (its own noServer `wss` above) AND the spec §5.3

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',
             });
         }