@north-light/crouter 0.3.234 → 0.3.236

package/dist/core/__tests__/watchdog-abort-arms-retry.test.js

@@ -14,7 +14,7 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
 });
 test('only a watchdog-stamped aborted settlement records an automatic connection fault', () => {
-    const settleAbort = (nodeId, stagedWatchdogAbort, stagedRefreshAbort, stopReason = 'aborted') => {
+    const settleAbort = (nodeId, stagedWatchdogAbort, stagedRefreshAbort, stopReason = 'aborted', errorText) => {
         const session = {
             sessionManager: { getLeafId: () => 'leaf-entry' },
             model: undefined,
@@ -27,7 +27,7 @@ test('only a watchdog-stamped aborted settlement records an automatic connection
                 messages: [{
                         role: 'assistant',
                         stopReason,
-                        errorMessage: stopReason === 'error' ? 'This operation was aborted' : 'Request was aborted',
+                        errorMessage: errorText ?? (stopReason === 'error' ? 'This operation was aborted' : 'Request was aborted'),
                     }],
             },
             stagedWatchdogAbort,
@@ -53,14 +53,19 @@ test('only a watchdog-stamped aborted settlement records an automatic connection
     settleAbort('human-node', false, false);
     assert.equal(readFault('human-node'), null, 'an otherwise-identical human abort must not arm recovery');
     // Pi 0.84 currently serializes a host abort from `node yield` as an `error`
-    // settlement. Only the refresh-abort provenance suppresses that provider-looking error.
+    // settlement.
     const refresh = settleAbort('refresh-node', false, true, 'error');
     assert.equal(readFault('refresh-node'), null, 'a refresh-aborted error settlement must not enter provider fault recovery');
     assert.equal(refresh.generation.stagedRefreshAbort, false, 'settlement consumes the one-shot refresh provenance');
-    settleAbort('provider-node', false, false, 'error');
+    // #683 — an abort that lands between requests settles as an error carrying
+    // AbortError text. It stopped because something asked it to; a fatal fault
+    // here parks the node and fans a false permanent-failure notice.
+    settleAbort('aborted-node', false, false, 'error');
+    assert.equal(readFault('aborted-node'), null, 'an abort-shaped error settlement must not record a provider fault');
+    settleAbort('provider-node', false, false, 'error', 'connection reset by peer');
     const providerFault = readFault('provider-node');
-    assert.equal(providerFault?.kind, 'other', 'the same provider error without refresh provenance still classifies');
-    assert.deepEqual(providerFault?.retry, { disposition: 'fatal' }, 'the same provider error without refresh provenance still records its fault');
+    assert.equal(providerFault?.kind, 'connection', 'a real provider error still classifies');
+    assert.equal(providerFault?.retry.disposition, 'auto', 'a real provider error still records its fault');
 });
 test('a failed retry settlement carries the episode forward instead of restarting it', () => {
     // The episode marker a daemon retry records before re-prompting: original

package/dist/core/canvas/canvas.js

@@ -164,8 +164,18 @@ function runtimeFromRow(nodeId) {
  *  row (identity + runtime from the incoming meta). Returns the hydrated view. */
 export function createNode(meta) {
     ensureHome();
+    const scaffolded = !existsSync(nodeDir(meta.node_id));
     ensureNodeDirs(meta.node_id);
-    writeMeta(meta);
+    try {
+        writeMeta(meta);
+    }
+    catch (error) {
+        // No row exists yet, so a dir left here is invisible to every surface and to
+        // ghost-row reaping. Only unwind a dir this call created.
+        if (scaffolded)
+            rmSync(nodeDir(meta.node_id), { recursive: true, force: true });
+        throw error;
+    }
     seedRow(meta);
     return getNode(meta.node_id);
 }

package/dist/core/canvas/meta-file.js

@@ -1,7 +1,8 @@
 // Durable node-meta file primitives shared by normal canvas writes and forward migrations.
 import { randomUUID } from 'node:crypto';
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 function parseObject(path, strict) {
     if (!existsSync(path))
         return null;
@@ -36,40 +37,30 @@ export function readMetaObject(path) {
  *  re-entrant — the operation must use {@link writeMetaObjectLocked}, never the
  *  lock-taking {@link writeJsonFileDurably}. */
 export function withMetaLock(path, operation) {
-    const lock = `${path}.lock`;
-    const wait = new Int32Array(new SharedArrayBuffer(4));
-    const deadline = Date.now() + 5_000;
-    for (;;) {
-        try {
-            mkdirSync(lock);
-            break;
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST' || Date.now() >= deadline)
-                throw error;
-            Atomics.wait(wait, 0, 0, 10);
-        }
-    }
-    try {
-        return operation();
-    }
-    finally {
-        rmSync(lock, { recursive: true, force: true });
-    }
+    return withExclusiveDirectoryLock(`${path}.lock`, operation, {
+        timeoutMs: 5_000,
+        timeoutError: () => new Error(`timed out waiting to write node metadata: ${path}`),
+    });
 }
 /** Collision-free durable write (fsync file + parent dir), assuming the caller
  *  already holds {@link withMetaLock} for `path`. */
 export function writeMetaObjectLocked(path, value) {
     const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    const fd = openSync(tmp, 'w');
     try {
-        writeSync(fd, JSON.stringify(value, null, 2));
-        fsyncSync(fd);
+        const fd = openSync(tmp, 'w');
+        try {
+            writeSync(fd, JSON.stringify(value, null, 2));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
     }
-    finally {
-        closeSync(fd);
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
     }
-    renameSync(tmp, path);
     const dirFd = openSync(dirname(path), 'r');
     try {
         fsyncSync(dirFd);

package/dist/core/canvas/remote-canvas-source.d.ts

@@ -31,6 +31,14 @@ export interface RemoteShowResponse {
         session_file?: string | null;
     };
     follow_up: string;
+    fault?: {
+        link: string;
+        kind: string;
+        retry: {
+            disposition: string;
+        };
+        since: string;
+    } | null;
 }
 export declare class RemoteCanvasSource implements CanvasSource {
     private readonly previewEndpoint;

package/dist/core/canvas/remote-canvas-source.js

@@ -47,6 +47,14 @@ function isValidShowResponse(x) {
         return false;
     if (typeof x['follow_up'] !== 'string')
         return false;
+    const fault = x['fault'];
+    if (fault !== undefined && fault !== null) {
+        if (!isPlainObject(fault) || typeof fault['link'] !== 'string' || typeof fault['kind'] !== 'string' || typeof fault['since'] !== 'string')
+            return false;
+        const retry = fault['retry'];
+        if (!isPlainObject(retry) || typeof retry['disposition'] !== 'string')
+            return false;
+    }
     return true;
 }
 /** A `reports`/`managers` entry (`RemoteShowResponse`) — validated per-element
@@ -121,7 +129,7 @@ export class RemoteCanvasSource {
         // node/inspect.ts's remote `show` passthrough render — see only well-formed
         // neighbor entries, never a malformed one they'd dereference unguarded.
         const res = isValidShowResponse(raw)
-            ? { ...raw, reports: raw.reports.filter(isValidNeighborEntry), managers: raw.managers.filter(isValidNeighborEntry) }
+            ? { ...raw, fault: raw.fault ?? null, reports: raw.reports.filter(isValidNeighborEntry), managers: raw.managers.filter(isValidNeighborEntry) }
             : null;
         this.nodeCache.set(id, { value: res, at: Date.now() });
         return res;

package/dist/core/canvas/types.d.ts

@@ -11,8 +11,8 @@
  *  only `dead` is a fault. */
 export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
 /** Does stopping finalize the node? terminal = worker (finalizes on push --final);
- *  resident = interactable while attached or holding a live obligation. An
- *  unattended obligation-free resident completes after the daemon grace. */
+ *  resident = an interactable conversation that parks and remains wakeable
+ *  without being forced to submit a final. */
 export type Lifecycle = 'terminal' | 'resident';
 /** base = hands-on worker; orchestrator = delegating manager. Bespoke per kind. */
 export type Mode = 'base' | 'orchestrator';

package/dist/core/command-manifests/registry.d.ts

@@ -24,6 +24,8 @@ export type LeafAdapter = (leaf: DeclLeafBase, commandPath: readonly string[]) =
 export interface CommandContribution {
     contributor: CommandContributorRef;
     node: DeclBranch<DeclLeafBase>;
+    /** Root name from the manifest, before collision qualification. */
+    manifestName: string;
     adaptLeaf: LeafAdapter;
 }
 /** Per-contributor collision issue. */

package/dist/core/command-plugins/compose.js

@@ -6,15 +6,17 @@ export function adaptPluginContributions(contributions) {
         contributions: contributions.map((contribution) => ({
             contributor: { name: contribution.plugin.name, scope: contribution.plugin.scope, sourceMarketplace: contribution.plugin.sourceMarketplace },
             node: contribution.node,
+            manifestName: contribution.manifestName,
             adaptLeaf: (leaf, commandPath) => {
                 const transport = contribution.transport;
+                const manifestCommandPath = [contribution.manifestName, ...commandPath.slice(1)];
                 if (transport.kind === 'exec') {
                     const executable = transport.executable;
                     if (executable === undefined)
                         throw new Error(`exec plugin "${contribution.plugin.name}" has an executable leaf without transport.executable`);
                     return {
                         outputKind: 'object',
-                        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable, commandPath: [...commandPath], output: leaf.output }, input),
+                        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable, commandPath: manifestCommandPath, output: leaf.output }, input),
                     };
                 }
                 const httpLeaf = leaf;
@@ -24,7 +26,7 @@ export function adaptPluginContributions(contributions) {
                         registration: { name: contribution.plugin.name, endpoint: transport.endpoint, ...(transport.authEnv !== undefined ? { authEnv: transport.authEnv } : {}) },
                         ...(contribution.manifest?.baseUrl !== undefined ? { baseUrl: contribution.manifest.baseUrl } : {}),
                         ...(contribution.manifest?.timeouts !== undefined ? { timeouts: contribution.manifest.timeouts } : {}),
-                        params: httpLeaf.params, rest: httpLeaf.rest, output: httpLeaf.output, commandPath: [...commandPath],
+                        params: httpLeaf.params, rest: httpLeaf.rest, output: httpLeaf.output, commandPath: manifestCommandPath,
                     }, input, context),
                 };
             },

package/dist/core/command-plugins/discovery.d.ts

@@ -14,6 +14,7 @@ export interface ValidatedContribution {
     transport: PluginTransport;
     node: DeclBranchGeneric<DeclLeafGeneric>;
     manifest: ValidatedCommandManifest;
+    manifestName: string;
 }
 export interface PluginCommandValidation {
     plugin: InstalledPlugin;

package/dist/core/command-plugins/discovery.js

@@ -130,7 +130,7 @@ export function validatePluginCommands(plugin, reservedNames = new Set(), coreCo
         : transport;
     if (resolvedTransport === undefined)
         return { plugin, manifestPath, transport, contributions: [], issues };
-    return { plugin, manifestPath, transport: resolvedTransport, manifest: validation.manifest, contributions: validation.manifest.roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest })), issues };
+    return { plugin, manifestPath, transport: resolvedTransport, manifest: validation.manifest, contributions: validation.manifest.roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest, manifestName: node.name })), issues };
 }
 export function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
     return effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin));

package/dist/core/command.js

@@ -138,9 +138,9 @@ export function defineRoot(opts) {
 /** Validate and return child names for an unknown-path error. */
 function childNames(node) {
     if (node.kind === 'root')
-        return node.subtrees.map((s) => s.name);
+        return node.subtrees.filter((s) => s.tier !== 'hidden').map((s) => s.name);
     if (node.kind === 'branch')
-        return node.children.map((c) => c.name);
+        return node.children.filter((c) => c.tier !== 'hidden').map((c) => c.name);
     return [];
 }
 /** Walk argv tokens to the deepest matched node.

package/dist/core/fault-classifier.js

@@ -42,6 +42,10 @@ function classifyProviderText(message) {
         return 'context-overflow';
     if (/websocket.*(?:closed.*\b(?:1002|1003|1007|1008|1009|1010)\b|protocol error|policy violation|unsupported data|invalid (?:frame|payload)|message too big|mandatory extension)/i.test(m))
         return 'protocol';
+    // proper-lockfile contention on a credential file: another process holds the
+    // mutex right now, so the same request wins once it releases.
+    if (/lock file is already being held/i.test(m))
+        return 'overloaded';
     if (/overloaded|\b5\d\d\b|internal server error|api.?error|capacity|server.{0,3}busy|temporarily unavailable/i.test(m))
         return 'overloaded';
     if (/connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout|\bterminated\b|other side closed|premature close|websocket\s+(?:was\s+)?closed|websocket stream closed before response\.completed|websocket\s+error|websocket.*interrupt/i.test(m))
@@ -55,6 +59,10 @@ function classifyErrno(raw) {
     if (/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOENT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/i.test(code)) {
         return 'connection';
     }
+    // A held filesystem mutex, not a broken link: back off on time rather than
+    // behind the online probe a connection fault waits on.
+    if (/^ELOCKED$/i.test(code))
+        return 'overloaded';
     return null;
 }
 function classifyHttp(raw) {

package/dist/core/pagination.d.ts

@@ -16,6 +16,8 @@ export interface PaginateOpts<T> {
     /** Returns the stable sort key for an item. Must match the sort order of the
      *  input array — ascending by this key. */
     keyOf: (item: T) => string;
+    /** Compares sort keys when their order is not raw code-unit order. */
+    compareKeys?: (left: string, right: string) => number;
     /** 'count' → compute and return `total`; 'omit' → return `null`. */
     total: 'count' | 'omit';
 }

package/dist/core/pagination.js

@@ -67,9 +67,10 @@ export function paginate(allItemsSortedAscByKey, params, opts) {
     let startIndex = 0;
     if (params.cursor !== undefined) {
         const cursorKey = decodeCursor(params.cursor); // throws CrtrError on bad cursor
+        const compareKeys = opts.compareKeys ?? ((left, right) => left < right ? -1 : left > right ? 1 : 0);
         // Find the first item whose key is strictly greater than cursorKey.
         // Linear scan; callers with large datasets should pre-filter upstream.
-        startIndex = allItemsSortedAscByKey.findIndex((item) => opts.keyOf(item) > cursorKey);
+        startIndex = allItemsSortedAscByKey.findIndex((item) => compareKeys(opts.keyOf(item), cursorKey) > 0);
         if (startIndex === -1) {
             // All items are at or before the cursor key — list is exhausted.
             startIndex = allItemsSortedAscByKey.length;

package/dist/core/runtime/broker/fault-retry.js

@@ -9,6 +9,7 @@ import { emitEvent } from '../../events/emit.js';
 import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, formatCard, formatModelFallbackRecovery } from '../../../shared/generated-context.js';
 import { markFatalOnExhaust, nextFaultRetry, policyFor } from '../fault-recovery.js';
 import { parseModelSpec } from '../model-selection.js';
+import { endedByAbort } from '../session-cycles.js';
 import { resolveProviderCandidates } from '../../subscription-state.js';
 const MAX_TIMEOUT_MS = 2_147_483_647;
 /** Owns provider fallback and daemon-driven fault retry state for one broker session. */
@@ -90,6 +91,11 @@ export class FaultRetry {
         if (refreshAbort)
             return;
         const raw = typeof last.errorMessage === 'string' ? last.errorMessage : 'engine error (no errorMessage recorded)';
+        // An abort landing between requests reaches pi's catch as a bare AbortError
+        // and settles as an error rather than `aborted`. Something asked that turn
+        // to stop, so there is no provider fault to record.
+        if (endedByAbort({ stopReason: 'error', errorMessage: raw }))
+            return;
         const uncompactedOverflow = isContextOverflow(last, settledSession.model?.contextWindow);
         const classified = classify('pi→provider', last);
         const coolingDeadline = extractCoolingDeadline(last);

package/dist/core/runtime/broker/rebind.js

@@ -8,6 +8,55 @@ import { abortSessionFromExtension } from './extension-abort.js';
 const MAX_ADMITTED_REPLACEMENTS = 2;
 const REPLACEMENT_DEADLINE_MS = 30_000;
 const REPLACEMENT_DEADLINE_EXCEEDED = Symbol('replacement-deadline-exceeded');
+const TRAILING_THINKING_PLACEHOLDER = '(interrupted)';
+const TRAILING_THINKING_GUARD = Symbol.for('crtr.trailing-thinking-guard');
+/** The last block an Anthropic request will actually carry: the serializer
+ *  drops whitespace-only text and signature-less empty thinking. */
+function lastSerializedBlock(content) {
+    for (let i = content.length - 1; i >= 0; i--) {
+        const block = content[i];
+        if (block === undefined)
+            continue;
+        if (block.type === 'text') {
+            if (block.text.trim().length === 0)
+                continue;
+            return block;
+        }
+        if (block.type === 'thinking') {
+            const signature = block.thinkingSignature;
+            const hasSignature = typeof signature === 'string' && signature.trim().length > 0;
+            if (block.redacted !== true && block.thinking.trim().length === 0 && !hasSignature)
+                continue;
+            return block;
+        }
+        return block;
+    }
+    return undefined;
+}
+function guardTrailingThinking(messages) {
+    return messages.map((message) => {
+        if (message.role !== 'assistant')
+            return message;
+        if (lastSerializedBlock(message.content)?.type !== 'thinking')
+            return message;
+        return { ...message, content: [...message.content, { type: 'text', text: TRAILING_THINKING_PLACEHOLDER }] };
+    });
+}
+/** Crouter aborts live streams (watchdog, extension abort, viewer esc), which
+ *  persists assistant turns that end on a thinking block. Anthropic rejects a
+ *  request whose final assistant block is `thinking`, and pi-ai's serializer
+ *  has no guard for it, so every later turn re-fails on embedded history. */
+function installTrailingThinkingGuard(agent) {
+    const inner = agent.convertToLlm;
+    if (inner[TRAILING_THINKING_GUARD] === true)
+        return;
+    const wrapped = (messages) => {
+        const converted = inner(messages);
+        return converted instanceof Promise ? converted.then(guardTrailingThinking) : guardTrailingThinking(converted);
+    };
+    wrapped[TRAILING_THINKING_GUARD] = true;
+    agent.convertToLlm = wrapped;
+}
 /** Owns session subscription replacement, its serialization lane, and replacement admission policy. */
 export class RebindDriver {
     deps;
@@ -86,6 +135,7 @@ export class RebindDriver {
                 });
                 agent.steeringMode = 'all';
                 agent.followUpMode = 'all';
+                installTrailingThinkingGuard(agent);
             }
             if (this.deps.cfg.editorName !== undefined && this.deps.cfg.editorName !== '') {
                 try {

package/dist/core/runtime/launch-target.js

@@ -32,7 +32,7 @@ export async function resolveLaunchTarget(req, options = {}) {
         await assertLaunchKind(kind, cwd, profileId);
     const mode = (req.mode ?? 'base');
     const launch = (await buildLaunchSpecAsync(kind, mode, {
-        lifecycle: req.root === true ? (req.root_lifecycle ?? 'resident') : 'terminal',
+        lifecycle: req.root_lifecycle ?? (req.root === true ? 'resident' : 'terminal'),
         hasManager: req.root !== true,
         ...(req.model !== undefined ? { model: req.model } : {}),
         cwd,

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

@@ -15,8 +15,8 @@ export type { PortableModelSelection } from './model-selection.js';
  *  stays unpinned. */
 export declare function isProviderPinnedModelToken(model: string): boolean;
 /** True when `model` is a PORTABLE ladder token — a bare strength/alias
- *  (`ultra`, `normal`, `opus`, …) or a `anthropic|openai / strength` pair —
- *  i.e. a form `normalizeModel` resolves through the ladders rather than
+ *  (`ultra`, `normal`, `opus`, …), an `anthropic|openai / strength` pair, or
+ *  an anthropic family alias — i.e. a form `normalizeModel` resolves through the ladders rather than
  *  passing through as a concrete id. Portable tokens are safe to PERSIST as
  *  defaults (`persistDefaultKindModel`): they re-resolve against whatever
  *  ladder the running build ships, so they never freeze a stale concrete

package/dist/core/runtime/launch.js

@@ -85,10 +85,14 @@ function findLadderCell(normalized, ladders, providers) {
  *      strong/medium/light, ALWAYS anthropic (ignores the env/config default).
  *   4. Anything else → pass through unchanged. */
 function modelTokenStrength(model) {
-    const rest = model.includes('/') ? model.slice(model.indexOf('/') + 1) : model;
+    const slash = model.indexOf('/');
+    const provider = slash === -1 ? undefined : model.slice(0, slash);
+    const rest = slash === -1 ? model : model.slice(slash + 1);
     const strength = STRENGTH_ALIASES[rest];
     if (strength !== undefined)
         return strength;
+    if (provider !== undefined && provider !== 'anthropic')
+        return null;
     if (rest === 'opus')
         return 'strong';
     if (rest === 'sonnet')
@@ -133,8 +137,8 @@ export function isProviderPinnedModelToken(model) {
     return model.includes('/') && !isPortableModelToken(model);
 }
 /** True when `model` is a PORTABLE ladder token — a bare strength/alias
- *  (`ultra`, `normal`, `opus`, …) or a `anthropic|openai / strength` pair —
- *  i.e. a form `normalizeModel` resolves through the ladders rather than
+ *  (`ultra`, `normal`, `opus`, …), an `anthropic|openai / strength` pair, or
+ *  an anthropic family alias — i.e. a form `normalizeModel` resolves through the ladders rather than
  *  passing through as a concrete id. Portable tokens are safe to PERSIST as
  *  defaults (`persistDefaultKindModel`): they re-resolve against whatever
  *  ladder the running build ships, so they never freeze a stale concrete
@@ -144,7 +148,8 @@ export function isPortableModelToken(model) {
         const slash = model.indexOf('/');
         const provider = model.slice(0, slash);
         const rest = model.slice(slash + 1);
-        return (provider === 'anthropic' || provider === 'openai') && STRENGTH_ALIASES[rest] !== undefined;
+        return (provider === 'anthropic' || provider === 'openai') && (STRENGTH_ALIASES[rest] !== undefined
+            || (provider === 'anthropic' && (rest === 'opus' || rest === 'sonnet' || rest === 'haiku')));
     }
     return STRENGTH_ALIASES[model] !== undefined || model === 'opus' || model === 'sonnet' || model === 'haiku';
 }
@@ -168,6 +173,14 @@ export function normalizeModel(model, ladders = modelLadders()) {
         if (strength !== undefined && (provider === 'anthropic' || provider === 'openai')) {
             return ladderFor(provider, ladders)[strength];
         }
+        if (provider === 'anthropic') {
+            if (rest === 'opus')
+                return ladders.anthropic.strong;
+            if (rest === 'sonnet')
+                return ladders.anthropic.medium;
+            if (rest === 'haiku')
+                return ladders.anthropic.light;
+        }
         // Concrete `provider/id` (optionally `...:thinking`) — pass through.
         return model;
     }

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

@@ -15,19 +15,11 @@ export interface SpawnChildOpts {
      *  subscription back to the spawner, spawned_by=spawner. Resident and brought
      *  forefront by default — see `rootLifecycle` for the unattended variant. */
     root?: boolean;
-    /** Only meaningful with `root`. The independent node's lifecycle.
-     *
-     *  `'resident'` (default) is the ATTENDED root: a standing conversation a
-     *  human picks up, so it owes no final, never reaps on its own, and is
-     *  brought forefront in tmux on spawn.
-     *
-     *  `'terminal'` is the UNATTENDED root: still parentless (nobody subscribes,
-     *  so nothing receives its push) but it still owes a final, so it reaps when
-     *  its work is done — and it is NEVER brought forefront. This is what
-     *  machinery firing with no human present must birth: the cron executor
-     *  spawns one when its cron's creating node is gone. A resident root there
-     *  would accrete one permanently-live node per fire (the count-based prune
-     *  never deletes live nodes) and steal the human's tmux focus every time. */
+    /** Lifecycle for the new node. Roots default to resident and managed
+     *  children default to terminal. A resident child remains an interactable,
+     *  wakeable conversation without owing a final; a terminal child remains a
+     *  bounded worker that must finalize. For roots, terminal keeps the
+     *  unattended no-viewer behavior. */
     rootLifecycle?: Lifecycle;
     /** Direct root creation waits until the broker accepts viewers before it
      *  returns. Cron-launched births use `launch`: the daemon must never wait in

package/dist/core/runtime/spawn.js

@@ -209,16 +209,10 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     const root = opts.root === true;
     const spawner = resolveSpawner(opts.parent, ctx.nodeId ?? null, root);
     const mode = opts.mode ?? 'base';
-    // Lifecycle keys on ROOT-ness only, independent of mode: an independent root
-    // (or `--root`) is resident by default (a conversation that persists, woken by
-    // inbox/human); every spawned child is terminal — it owes a final up the spine
-    // and reaps when done. A child born as an orchestrator is terminal/orchestrator
-    // (delegates + holds a roadmap, but still reports up), NOT resident.
-    //
-    // `rootLifecycle: 'terminal'` is the one deliberate exception: a parentless
-    // node that STILL owes a final (see the option's docblock). It is unattended
-    // by construction, so `attendedRoot` below also suppresses viewer placement.
-    const lifecycle = root ? (opts.rootLifecycle ?? 'resident') : 'terminal';
+    // Roots are resident by default; managed children are terminal workers by
+    // default. The one lifecycle option deliberately applies to both shapes so a
+    // child can be born as a standing, wakeable conversation too.
+    const lifecycle = opts.rootLifecycle ?? (root ? 'resident' : 'terminal');
     const attendedRoot = root && lifecycle === 'resident';
     // Born WITHOUT a name — the canvas-goal-capture extension names it async from
     // its first message (the kickoff task) inside its own pi process, so spawn

package/dist/core/runtime/stop-guard.js

@@ -17,8 +17,10 @@
 //   • finished/asked → it pushed --final (done) or called `crtr ask` this turn.
 //                      Also fine.
 //   • structured     → a TERMINAL node has a pending structured-output request.
-//                      Valid requests reprompt with the schema; invalid requests
-//                      reprompt with an error and require manual cleanup.
+//                      A valid request reprompts with the schema unless the node
+//                      also holds a wake source, which it may sleep on first;
+//                      an invalid request reprompts with an error and requires
+//                      manual cleanup.
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
 import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCancelOnWakeCron, getNode, contextDir } from '../canvas/index.js';
@@ -39,6 +41,19 @@ function formatInvalidStructuredOutputReprompt(error) {
         `After resolving the file, retry the submission. ` +
         `If this is unexpected, escalate to the user using \`crtr human send\`.`);
 }
+/** The wake sources that legitimize a terminal node's dormancy: a pending
+ * cancel-on-wake deadline, an active subscription to a live publisher, an
+ * explicit live controller wait, or a live background bash job whose completion
+ * sends an inbox message. Parentage alone is deliberately absent. */
+function wakeCapableWait(nodeId, backgroundJobsRunning) {
+    if (hasPendingCancelOnWakeCron(nodeId))
+        return 'scheduled';
+    if (hasActiveLiveSubscription(nodeId)
+        || hasLiveMessageWait(nodeId)
+        || backgroundJobsRunning)
+        return 'awaiting';
+    return null;
+}
 /** Decide what to do when a node stops. crtrd supplies every current-canvas
  * fact; the broker contributes only whether its Pi-owned background job registry
  * is still running work. */
@@ -49,9 +64,14 @@ export function evaluateStop(nodeId, signals, backgroundJobsRunning = activeBack
         return { action: 'allow', reason: 'escalated' };
     // A pending structured-output request overrides every stored-state dormancy
     // path: a post-final one-off follow-up still owes `submit` before it may stop.
-    // Invalid requests surface an explicit error and require manual cleanup.
+    // A wake source is the exception — the request outlives the sleep, so
+    // reprompting instead would busy-wait the node against its own child, deadline,
+    // or job. Invalid requests surface an explicit error and require manual cleanup.
     const outputState = readOutputRequest(nodeId);
     if (outputState.state === 'valid') {
+        const pendingWait = wakeCapableWait(nodeId, backgroundJobsRunning);
+        if (pendingWait !== null)
+            return { action: 'allow', reason: pendingWait };
         return {
             action: 'reprompt',
             reason: 'stalled',
@@ -82,19 +102,11 @@ export function evaluateStop(nodeId, signals, backgroundJobsRunning = activeBack
     if (node !== null && node.lifecycle === 'resident') {
         return { action: 'allow', reason: 'dormant' };
     }
-    // A terminal node with a pending cancel-on-wake deadline is legitimately
-    // waiting on the clock, so it should idle-release rather than busy-wait
-    // holding its broker.
-    if (hasPendingCancelOnWakeCron(nodeId))
-        return { action: 'allow', reason: 'scheduled' };
-    // A terminal node holding something live to wake it is legitimately awaiting.
-    // Parentage alone is deliberately absent: only an active subscription, an
-    // explicit controller wait, or a live background bash job whose completion
-    // sends an inbox message can suppress the stall guard.
-    if (hasActiveLiveSubscription(nodeId)
-        || hasLiveMessageWait(nodeId)
-        || backgroundJobsRunning)
-        return { action: 'allow', reason: 'awaiting' };
+    // A terminal node holding a wake source is legitimately waiting: it should
+    // idle-release rather than busy-wait holding its broker.
+    const pendingWait = wakeCapableWait(nodeId, backgroundJobsRunning);
+    if (pendingWait !== null)
+        return { action: 'allow', reason: pendingWait };
     // A terminal node with nothing live and no final pushed has stalled.
     return {
         action: 'reprompt',

package/dist/core/substrate/frontmatter-validation.d.ts

@@ -1,4 +1,5 @@
 import { type SurfaceEntry } from './schema.js';
+export declare const SUPPRESSIBLE_RULES: readonly string[];
 /** Strict validation of one raw routing entry. Runtime parsing deliberately
  * tolerates malformed docs; this authoring/preflight contract does not. */
 export declare function lintSubstrateSurfaces(value: unknown): string | null;

package/dist/core/substrate/frontmatter-validation.js

@@ -1,7 +1,7 @@
 import { isDocKind, parseSubstrateFrontmatter, SURFACE_EVENTS, SURFACE_RUNGS } from './schema.js';
 const RETIRED_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
 const SURFACE_ENTRY_KEYS = ['on', 'match', 'match-frontmatter', 'gate', 'at'];
-const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read'];
+export const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read'];
 /** Strict validation of one raw routing entry. Runtime parsing deliberately
  * tolerates malformed docs; this authoring/preflight contract does not. */
 export function lintSubstrateSurfaces(value) {