@north-light/crouter 0.3.218 → 0.3.220

package/dist/commands/sys/panels/broker-limits-panel.js

@@ -82,7 +82,7 @@ export class BrokerLimitsPanel {
     }
     render(width) {
         const out = [
-            truncateToWidth(`${theme.fg("accent", theme.bold("Broker limits"))}${theme.fg("dim", "  user scope · defaults 128 / 256")}`, width),
+            truncateToWidth(`${theme.fg("accent", theme.bold("Broker limits"))}${theme.fg("dim", "  user scope · defaults 16 / 32")}`, width),
             truncateToWidth(theme.fg("dim", "These bounds govern daemon automatic revive; explicit node revives remain available."), width),
             "",
         ];
@@ -91,8 +91,8 @@ export class BrokerLimitsPanel {
             out.push(truncateToWidth(`${selected ? theme.fg("accent", "▶") : " "} ${padAnsi(selected ? theme.fg("accent", label) : label, 24)} ${input.render(Math.max(8, width - 28))[0] ?? ""}`, width));
             out.push(truncateToWidth(theme.fg("dim", `    ${description}`), width));
         };
-        line(0, "Warning threshold", "Warn when live brokers reach this count. Default: 128.", this.warningInput);
-        line(1, "Automatic-revive hard cap", "Defer automatic revives at this count. Default: 256.", this.hardCapInput);
+        line(0, "Warning threshold", "Warn when live brokers reach this count. Default: 16.", this.warningInput);
+        line(1, "Automatic-revive hard cap", "Defer automatic revives at this count. Default: 32.", this.hardCapInput);
         out.push("");
         for (const text of wrapText(`Configured limits apply next tick. ${BROKER_LIMIT_OVERRIDE_PRECEDENCE}`, width))
             out.push(theme.fg("dim", text));

package/dist/core/__tests__/helpers/broker-clients.d.ts

@@ -27,6 +27,7 @@ export interface AttachKit {
     /** Connect a BrokerClient to a node's running broker, hello, await welcome. */
     attach(id: string, role: ClientRole, clientId: string, opts?: {
         snapshotTail?: number;
+        attends?: boolean;
     }): Promise<Attached>;
     /** Attach (as `role`) and retry until the welcome satisfies `pred`. */
     attachUntil(id: string, role: ClientRole, clientId: string, pred: (a: Attached) => boolean, label: string): Promise<Attached>;

package/dist/core/__tests__/helpers/broker-clients.js

@@ -70,6 +70,7 @@ export function createAttachKit(getH) {
             role,
             client_id: clientId,
             ...(opts.snapshotTail === undefined ? {} : { snapshot_tail: opts.snapshotTail }),
+            ...(opts.attends === undefined ? {} : { attends: opts.attends }),
         });
         let welcome;
         try {

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -19,20 +19,23 @@
 // they belong to the compiled seam tier; neither needs tmux.
 import { after, before, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { appendInbox, readCursor, readInboxSince } from '../../feed/inbox.js';
 import { registerWarmSpare, subscribe, updateNode } from '../../canvas/index.js';
 import { isPidAlive } from '../../canvas/pid.js';
 import { reviveNode } from '../../runtime/revive.js';
 import { createHarness } from '../helpers/harness.js';
+import { createAttachKit } from '../helpers/broker-clients.js';
 let h;
 let root;
+const attach = createAttachKit(() => h);
 before(async () => {
     h = await createHarness({ headless: true, sessionPrefix: 'crtr-dormancy' });
     root = h.spawnRoot('dormancy-release suite root');
 });
 after(async () => {
+    attach.closeAll();
     if (h !== undefined)
         await h.dispose();
 });
@@ -187,6 +190,39 @@ test('an unattended resident with no live obligation completes on the daemon clo
             process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
     }
 });
+test('a non-attending observer does not prevent unattended resident parking', { timeout: 30_000 }, async () => {
+    const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+    process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';
+    const nodeId = h.fabricateBrokerNode({
+        id: 'settled-with-system-observer',
+        parent: root,
+        lifecycle: 'resident',
+        status: 'idle',
+        intent: 'idle-release',
+    });
+    updateNode(nodeId, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
+    reviveNode(nodeId, { resume: true });
+    const boot = await h.awaitBoot(nodeId);
+    await attach.attach(nodeId, 'observer', 'system-observer-test', { attends: false });
+    assert.equal(JSON.parse(readFileSync(join(h.home, 'nodes', nodeId, 'job', 'attach.json'), 'utf8')).viewers, 0, 'a non-attending hello is not persisted as human attendance');
+    try {
+        const seenAt = 12_000;
+        await h.tick(seenAt);
+        await h.tick(seenAt + 1500);
+        await h.waitFor(() => h.node(nodeId)?.status === 'done' && !isPidAlive(boot.pid), {
+            timeoutMs: 10_000,
+            intervalMs: 20,
+            label: 'system-observed unattended completion and broker exit',
+        });
+        await h.awaitFleetExit(nodeId);
+    }
+    finally {
+        if (priorParkMs === undefined)
+            delete process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+        else
+            process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
+    }
+});
 test('a connected broker viewer keeps an obligation-free resident live', { timeout: 30_000 }, async () => {
     const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
     process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';

package/dist/core/runtime/broker/client-registry.d.ts

@@ -1,8 +1,9 @@
 import type { Socket } from 'node:net';
 import { FrameDecoder, type BrokerSnapshot, type BrokerToClient, type ClientRole } from '../broker-protocol.js';
-/** True when the live broker has at least one helloed terminal or web viewer.
- *  Callers establish broker liveness separately because a crash can leave the
- *  last persisted count behind. */
+/** True when the live broker has at least one client that declared itself to
+ * be attending the conversation. A system observer may read the same stream
+ * without keeping an otherwise idle broker alive. Callers establish broker
+ * liveness separately because a crash can leave the last persisted count behind. */
 export declare function hasAttachedBrokerViewers(nodeId: string): boolean;
 export interface BrokerClient {
     id: string;
@@ -10,6 +11,8 @@ export interface BrokerClient {
     socket: Socket;
     decoder: FrameDecoder;
     helloed: boolean;
+    /** Fixed by the first hello; absent `attends` remains backward-compatible true. */
+    attends: boolean;
     snapshotTail: number | undefined;
     pendingBytes: number;
     queuedFrames: number;

package/dist/core/runtime/broker/client-registry.js

@@ -5,9 +5,10 @@ import { encodeFrame, FrameDecoder, BROKER_READ_CAPS, } from '../broker-protocol
 /** Per-viewer outbound high-water mark. Slow viewers are shed rather than allowed to backpressure the shared engine indefinitely. */
 const MAX_QUEUED_FRAMES = 1000;
 const MAX_PENDING_BYTES = 32 * 1024 * 1024;
-/** True when the live broker has at least one helloed terminal or web viewer.
- *  Callers establish broker liveness separately because a crash can leave the
- *  last persisted count behind. */
+/** True when the live broker has at least one client that declared itself to
+ * be attending the conversation. A system observer may read the same stream
+ * without keeping an otherwise idle broker alive. Callers establish broker
+ * liveness separately because a crash can leave the last persisted count behind. */
 export function hasAttachedBrokerViewers(nodeId) {
     try {
         const record = JSON.parse(readFileSync(`${jobDir(nodeId)}/attach.json`, 'utf8'));
@@ -36,6 +37,7 @@ export class BrokerClientRegistry {
             socket,
             decoder: new FrameDecoder(BROKER_READ_CAPS),
             helloed: false,
+            attends: true,
             snapshotTail: undefined,
             pendingBytes: 0,
             queuedFrames: 0,
@@ -58,7 +60,7 @@ export class BrokerClientRegistry {
         try {
             let viewers = 0;
             for (const client of this.clients)
-                if (client.helloed)
+                if (client.helloed && client.attends)
                     viewers += 1;
             const dir = jobDir(this.nodeId);
             if (!existsSync(dir))

package/dist/core/runtime/broker/frame-dispatch.js

@@ -757,6 +757,7 @@ export function createFrameDispatchContext(deps) {
         if (firstHello) {
             client.helloed = true;
             client.role = frame.role === 'controller' ? 'controller' : 'observer';
+            client.attends = frame.attends !== false;
         }
         sendWelcome(client);
         if (firstHello)

package/dist/core/runtime/broker-protocol.d.ts

@@ -82,6 +82,10 @@ export interface HelloFrame {
     type: 'hello';
     role: ClientRole;
     client_id: string;
+    /** Whether this socket represents a person attending the conversation. Defaults
+     * true for backward compatibility; system observers set false without changing
+     * their read-only `role`. */
+    attends?: boolean;
     /** Per-attach welcome transcript bound; absent or invalid keeps the full history. */
     snapshot_tail?: number;
     /** Terminal geometry of a tmux-pane viewer; absent for a headless client. */

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