@north-light/crouter 0.3.235 → 0.3.237

package/dist/core/memory/lint.d.ts

@@ -33,6 +33,9 @@ export type MemoryLintRule =
  | 'dangling-link'
 /** A `memory-read` route that matches no canonical name. */
  | 'memory-read-route'
+/** A document no reachability path routes an agent to — no surface delivers
+ *  it, no reached document links it, and no reached directory lists it. */
+ | 'orphan'
 /** A project store's workspace front door is missing or not its root doc. */
  | 'front-door'
 /** Boot entries in a nested store, which never rides the boot catalog. */
@@ -91,6 +94,22 @@ export declare function lintShortPreviewBody(fm: Record<string, unknown>, body:
  *  answers with its own document and its listing. Derived from the canonical
  *  tree, never from string prefixes of a name. */
 export declare function resolvableCanonicalNames(docs: readonly MemoryDoc[]): Set<string>;
+/** The orphan rule. A document is reachable when an agent is routed to it
+ *  without knowing its name: a surface delivers it (a `memory-read` surface is
+ *  deliberate companion wiring and counts), it is invocable as a slash command,
+ *  a reached document's real `[[link]]` names it, or a reached CURATED INDEX
+ *  document's listing includes it. The listing edge routes only through a
+ *  directory that carries its own non-root index document — a bare directory
+ *  has no curator, and a store's root front door is delivered with the whole
+ *  boot tree, so treating either listing as a route would reach every doc and
+ *  defeat the rule (the same reason the corpus root is never seeded). Curated
+ *  BODY LINKS on those docs still route. Reachability is computed over the
+ *  WHOLE target view — a doc linked only from another store is still reachable.
+ *  `flagStoreRoot` restricts which store's unreachable docs are flagged while
+ *  every store still participates in the graph as a potential linker. */
+export declare function lintOrphans(viewDocs: readonly MemoryDoc[], options?: {
+    flagStoreRoot?: string;
+}): MemoryLintFinding[];
 export interface MemoryLintStoreOptions {
     /** Canonical names a `[[link]]` or route may target — the target view the
      *  store's documents are read in. Omit to skip reference checks entirely

package/dist/core/memory/lint.js

@@ -133,6 +133,98 @@ export function resolvableCanonicalNames(docs) {
     walk(buildMemoryTree(docs).root);
     return names;
 }
+/** The orphan rule. A document is reachable when an agent is routed to it
+ *  without knowing its name: a surface delivers it (a `memory-read` surface is
+ *  deliberate companion wiring and counts), it is invocable as a slash command,
+ *  a reached document's real `[[link]]` names it, or a reached CURATED INDEX
+ *  document's listing includes it. The listing edge routes only through a
+ *  directory that carries its own non-root index document — a bare directory
+ *  has no curator, and a store's root front door is delivered with the whole
+ *  boot tree, so treating either listing as a route would reach every doc and
+ *  defeat the rule (the same reason the corpus root is never seeded). Curated
+ *  BODY LINKS on those docs still route. Reachability is computed over the
+ *  WHOLE target view — a doc linked only from another store is still reachable.
+ *  `flagStoreRoot` restricts which store's unreachable docs are flagged while
+ *  every store still participates in the graph as a potential linker. */
+export function lintOrphans(viewDocs, options = {}) {
+    const tree = buildMemoryTree(viewDocs);
+    const index = new Map();
+    const indexWalk = (node) => {
+        if (node.name !== '')
+            index.set(node.name, node);
+        for (const child of node.childDirectories)
+            indexWalk(child);
+        for (const child of node.childDocuments)
+            index.set(child.name, child);
+    };
+    indexWalk(tree.root);
+    const reachable = new Set();
+    const queue = [];
+    const enqueue = (name) => {
+        if (name === '' || reachable.has(name) || !index.has(name))
+            return;
+        reachable.add(name);
+        queue.push(name);
+    };
+    // Roots: a doc an agent reaches without a name — any surface entry, or a
+    // slash command. A `memory-read` surface counts (deliberate companion wiring).
+    for (const doc of viewDocs) {
+        const fm = doc.frontmatter ?? {};
+        if (parsedSubstrateSurfaces(fm).length > 0 || fm['slash'] === true)
+            enqueue(doc.name);
+    }
+    // Fixpoint: reading a reachable node routes to its real links, and — when the
+    // node is a curated non-root index — to the members its listing renders.
+    while (queue.length > 0) {
+        const node = index.get(queue.shift());
+        const doc = node.document;
+        if (doc !== null) {
+            for (const target of docLinkNames(doc.body))
+                if (index.has(target))
+                    enqueue(target);
+        }
+        if (doc === null || doc.localName === '')
+            continue;
+        for (const child of node.childDirectories) {
+            if (child.document?.frontmatter?.['unlisted'] === true)
+                continue;
+            enqueue(child.name);
+        }
+        for (const child of node.childDocuments) {
+            if (child.document.frontmatter?.['unlisted'] === true)
+                continue;
+            enqueue(child.name);
+        }
+    }
+    const findings = [];
+    for (const doc of viewDocs) {
+        if (options.flagStoreRoot !== undefined && doc.store.storeRoot !== options.flagStoreRoot)
+            continue;
+        if (reachable.has(doc.name))
+            continue;
+        // Not the running user's to fix, but still a linker in the graph above.
+        if (doc.scope === 'builtin' || doc.plugin !== undefined)
+            continue;
+        // A store's root document is its entry point by definition.
+        if (doc.localName === '')
+            continue;
+        // Persona layers are read by construction, same as the length rule.
+        if (doc.name === 'kinds' || doc.name.startsWith('kinds/'))
+            continue;
+        if (ignoresRule(doc.frontmatter ?? {}, 'orphan'))
+            continue;
+        findings.push({
+            severity: 'warning',
+            rule: 'orphan',
+            path: doc.path,
+            name: doc.name,
+            scope: doc.scope,
+            ...(doc.store.storeRoot === '' ? {} : { storeRoot: doc.store.storeRoot }),
+            message: `\`${doc.name}\` is unreachable: no surface delivers it, no reached document links it, and no reached directory lists it — it is findable only by deliberate search. Give it a surface, link it from a reached doc (a cluster index, or its directory's own ${INDEX_SEGMENT}.md), or accept it with \`lint-ignore: orphan\`.`,
+        });
+    }
+    return findings;
+}
 const FRONT_DOOR_REMEDY = 'the store\'s root INDEX.md is the workspace front door: give it `surfaces: [{on: workspace-open, at: content}, {on: read, match: "./**", at: content}]` (run `crtr memory write -h` first)';
 const GLOB_META_RE = /[*?[\]{}]/;
 function safeGlob(target, glob) {
@@ -566,6 +658,11 @@ export function lintMemoryTarget(options = {}) {
             walk(child);
     };
     walk(tree.root);
+    // Reachability is a whole-view property, so it runs once over the target view
+    // and only in the unfiltered view — a `--scope` slice hides the surfaced or
+    // linking docs that make a doc reachable and would report false orphans.
+    if (options.scope === undefined)
+        findings.push(...lintOrphans(view.docs));
     return {
         ...makeResult(findings, checked, documents, storesLinted),
         stores: view.stores,

package/dist/core/memory-resolver.d.ts

@@ -184,6 +184,10 @@ export interface MemoryTarget {
      *  or null outside a node. */
     nodeId: string | null;
 }
+/** The target the ambient process describes: cwd + the two env seams every
+ *  profile/node-aware memory path reads through (`CRTR_PROFILE_ID`,
+ *  `CRTR_NODE_ID`). */
+export declare function ambientMemoryTarget(): MemoryTarget;
 /** The exact project store owned by `ownerDir` — the `--dir` selector's store,
  *  loaded whatever its mount status so lint and migration can inspect a store
  *  the runtime refuses to mount. */

package/dist/core/memory-resolver.js

@@ -18,7 +18,7 @@ import { associateRepository } from './memory/repository-association.js';
 /** The target the ambient process describes: cwd + the two env seams every
  *  profile/node-aware memory path reads through (`CRTR_PROFILE_ID`,
  *  `CRTR_NODE_ID`). */
-function ambientTarget() {
+export function ambientMemoryTarget() {
     return {
         cwd: process.cwd(),
         profileId: envProfileId() || null,
@@ -27,7 +27,7 @@ function ambientTarget() {
 }
 /** The selected profile id from the process env, or '' when none. */
 function selectedProfileId() {
-    return ambientTarget().profileId ?? '';
+    return ambientMemoryTarget().profileId ?? '';
 }
 // Store discovery: which physical stores a target sees, in what order, and
 // whether each one's namespace lets it mount.
@@ -287,7 +287,7 @@ export function memoryStoresInPrecedence(target, scope, includeDescendants = fal
  *  how a DELETED doc's revision log is still found: history outlives the doc,
  *  so its lookup cannot go through document resolution. */
 export function nativeMemoryStoresInPrecedence(scope, includeDescendants = false) {
-    return memoryStoresInPrecedence(ambientTarget(), scope, includeDescendants)
+    return memoryStoresInPrecedence(ambientMemoryTarget(), scope, includeDescendants)
         .filter((store) => store.mountStatus === 'ready' && store.scope !== 'builtin' && store.plugin === undefined)
         .map((store) => ({ scope: store.scope, memoryDir: store.storeRoot, store }));
 }
@@ -475,9 +475,9 @@ export function listProjectMemoryDocs(startDir = process.cwd(), profileId = sele
  *  candidates stay in source order, so a caller's first-wins dedup yields the
  *  address winners. */
 export function listAllMemoryDocs(scope, quiet = false, includeDescendants = false) {
-    return [...loadMemoryTargetView(ambientTarget(), { ...(scope ? { scope } : {}), quiet, includeDescendants }).docs];
+    return [...loadMemoryTargetView(ambientMemoryTarget(), { ...(scope ? { scope } : {}), quiet, includeDescendants }).docs];
 }
-export function createMemoryDocSnapshot(target = ambientTarget()) {
+export function createMemoryDocSnapshot(target = ambientMemoryTarget()) {
     // Quiet: a snapshot feeds command registration and migration planning, where
     // another doc's frontmatter health is noise — corpus health is `lint`'s job.
     const view = loadMemoryTargetView(target, { quiet: true });
@@ -513,7 +513,7 @@ export function readMemoryDocContent(path, includeFrontmatter = false) {
 }
 /** The address winner for an exact canonical name in the ambient target. */
 export function resolveMemoryDoc(rawName, opts = {}) {
-    return resolveMemoryDocForTarget(rawName, ambientTarget(), opts);
+    return resolveMemoryDocForTarget(rawName, ambientMemoryTarget(), opts);
 }
 /** Resolve a memory document as ANOTHER node would see it — the same precedence
  *  chain (node-local > project stack > profile > user > builtin), read from the
@@ -527,7 +527,7 @@ export function resolveMemoryDocForTarget(rawName, target, opts = {}) {
  *  in source order — what path-aware inventory, diagnostics, and automatic
  *  event eligibility consume instead of the winner alone. */
 export function resolveMemoryCandidates(rawName, opts = {}) {
-    return resolveMemoryCandidatesForTarget(rawName, ambientTarget(), opts);
+    return resolveMemoryCandidatesForTarget(rawName, ambientMemoryTarget(), opts);
 }
 export function resolveMemoryCandidatesForTarget(rawName, target, opts = {}) {
     const view = loadMemoryTargetView(target, { ...opts, quiet: true });

package/dist/core/preview-registry.js

@@ -11,7 +11,7 @@
 // Source of truth: this Set must mirror every leaf that declares
 // `help.preview.suppressOutput: true` in its own command file (currently
 // canvas roster, canvas snapshot, node inspect snapshot, node inspect show,
-// and sys sysprompt). There is no automated sync — when you add or remove a leaf's
+// and sys context sysprompt). There is no automated sync — when you add or remove a leaf's
 // `preview.suppressOutput`, update this Set in the same commit.
 // `preview-registry-sync.test.ts` (which imports the real command tree — safe
 // in a test, never in the attach bundle) asserts the two stay identical.
@@ -22,7 +22,7 @@ export const SUPPRESS_OUTPUT_LEAVES = new Set([
     'canvas snapshot',
     'node inspect snapshot',
     'node inspect show',
-    'sys sysprompt',
+    'sys context sysprompt',
 ]);
 /** True when the leaf at this full help-name path (e.g. "canvas snapshot")
  *  declares `preview.suppressOutput: true`. */
@@ -162,8 +162,8 @@ export const LEAF_ICON_CP = {
     'sys settings': 0xf013,
     'sys setup': 0xf0ad,
     'sys doctor': 0xf0f1,
-    'sys sysprompt': 0xf15c,
-    'sys prompt-review': 0xf002,
+    'sys context sysprompt': 0xf15c,
+    'sys context prompt-review': 0xf002,
     'sys feedback': 0xf075,
     'sys update': 0xf021,
     'sys version': 0xf02b,

package/dist/core/review/realize.js

@@ -83,7 +83,7 @@ function cancelInvisibleBridge(nodeId) {
     // cannot produce a final report or notify the origin.
     const node = getNode(nodeId);
     if (node !== null && node.status !== 'done' && node.status !== 'canceled')
-        transition(nodeId, 'cancel');
+        transition(nodeId, 'cancel', { reason: 'retired' });
 }
 /** Assert the only route a bridge has back to its origin before ticket exposure. */
 function ensureBridgeSubscription(review, bridgeNodeId) {
@@ -168,8 +168,10 @@ export async function realizeReview(reviewId) {
     const companion = getNode(review.companion_node_id);
     if (companion === null)
         throw companionUnbound(review.review_id, 0);
+    // Realization is bounded by the bind deadline below, which only a live broker
+    // can meet: refuse at the cap rather than freeze into a certain timeout.
     if (companion.pi_session_id === null)
-        reviveNode(companion.node_id, { resume: false });
+        reviveNode(companion.node_id, { resume: false, capacity: 'refuse' });
     // R4: session_start is the durable bind boundary.
     if (!await awaitCompanionBind(review.companion_node_id, COMPANION_BIND_DEADLINE_MS)) {
         throw companionUnbound(review.review_id, COMPANION_BIND_DEADLINE_MS);

package/dist/core/runtime/close.js

@@ -188,7 +188,7 @@ export function closeNode(rootId, opts = {}) {
                         transition(id, 'finish');
                 }
                 else {
-                    transition(id, 'cancel');
+                    transition(id, 'cancel', { reason: 'closed' });
                 }
                 // 2) Tear the node's ENGINE down: send the `shutdown` frame so the broker
                 //    PROCESS exits and releases the sole .jsonl writer. Then proactively

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

@@ -1,4 +1,17 @@
+import { InputError } from '../io.js';
 import type { HostHandle } from './host.js';
+/** The daemon's live-broker thresholds. The hard cap is the ledger's admission
+ *  bound; `warning` is the saturation notice supervision fires below it. Lives
+ *  here — beside the ledger that enforces it — so the ledger, a refusal
+ *  message, and supervision's warning all read ONE definition. */
+export declare function brokerThresholdsForDaemon(): {
+    warning: number;
+    automaticReviveCap: number;
+};
+/** The typed refusal a caller that cannot wait gets when the ledger is full.
+ *  An InputError so its details round-trip through crtrd's error body and reach
+ *  a CLI caller as the real cap text instead of an opaque 5xx. */
+export declare function brokerCapReached(cap: number, live: number): InputError;
 /** Real child-exit status, exactly as Node reports it. Codes/signals are
  *  diagnostics only — never policy inputs (design D-4). */
 export interface FleetExitStatus {
@@ -32,8 +45,19 @@ export interface FleetRegistry {
     has(nodeId: string): boolean;
     /** Live-fleet checks pass (yield-stall, wedge, fatal-fault). */
     get(nodeId: string): FleetEntry | undefined;
-    /** The capacity count (design D-7: capacity = fleet.size(), exact). */
+    /** The capacity count: registered brokers only, excluding reservations. */
     size(): number;
+    /** Every slot the cap accounts for — registered brokers plus in-flight
+     *  reservations (a launch that has claimed a slot but not yet registered, and
+     *  an exited broker whose exit-policy job has not yet run). */
+    occupancy(): number;
+    /** Claim a slot for `nodeId`. True means the caller may launch; false means
+     *  the cap is reached and the caller must freeze or refuse. Idempotent — a
+     *  node that already holds a slot (reserved or registered) gets true without
+     *  consuming a second one. */
+    reserveSlot(nodeId: string): boolean;
+    /** Give back a slot claimed by `reserveSlot` and not consumed by a launch. */
+    releaseReservation(nodeId: string): void;
     entries(): Iterable<[string, FleetEntry]>;
     /** Drop an entry without policy (terminal exits + close paths). */
     forget(nodeId: string): void;
@@ -45,6 +69,10 @@ export interface FleetRegistry {
     /** Test seam — delivers a synthetic exit through the SAME path as
      *  onChildExit, so fabricated-row tests drive policy without a process. */
     deliverExit(nodeId: string, status: FleetExitStatus): void;
+    /** The node-lifecycle tick's enactment entry: classify a row known to have no
+     *  live engine and enact through the SAME policy table exit events use, so
+     *  tick recovery and exit recovery can never diverge. */
+    applyDeadRowPolicy(nodeId: string): Promise<void>;
 }
 /** Inject the daemon's fleet registry. Idempotent for the same instance;
  *  throws on a conflicting rebind (one registry per process, ever). */

package/dist/core/runtime/fleet.js

@@ -11,6 +11,29 @@
 // the structural enforcement that broker launches happen only inside crtrd
 // (design D-2): a CLI or library process has no fleet and cannot launch an
 // unowned broker.
+import { readConfig } from '../config.js';
+import { InputError } from '../io.js';
+import { envMaxLiveBrokers, envWarnLiveBrokers } from '../../shared/env.js';
+/** The daemon's live-broker thresholds. The hard cap is the ledger's admission
+ *  bound; `warning` is the saturation notice supervision fires below it. Lives
+ *  here — beside the ledger that enforces it — so the ledger, a refusal
+ *  message, and supervision's warning all read ONE definition. */
+export function brokerThresholdsForDaemon() {
+    const configured = readConfig('user').brokerThresholds;
+    const automaticReviveCap = envMaxLiveBrokers() ?? configured.automaticReviveCap;
+    const warning = envWarnLiveBrokers() ?? configured.warning;
+    return { warning: Math.min(warning, automaticReviveCap), automaticReviveCap };
+}
+/** The typed refusal a caller that cannot wait gets when the ledger is full.
+ *  An InputError so its details round-trip through crtrd's error body and reach
+ *  a CLI caller as the real cap text instead of an opaque 5xx. */
+export function brokerCapReached(cap, live) {
+    return new InputError({
+        error: 'broker_cap_reached',
+        message: `no broker slot is free — ${live} live brokers at the cap of ${cap}.`,
+        next: `Finish or close a live node (\`crtr canvas render\` shows them), or raise the cap with CRTR_MAX_LIVE_BROKERS, then retry.`,
+    });
+}
 let bound;
 /** Inject the daemon's fleet registry. Idempotent for the same instance;
  *  throws on a conflicting rebind (one registry per process, ever). */

package/dist/core/runtime/host.js

@@ -22,7 +22,7 @@ import { buildBrokerEnv } from './spawn-env.js';
 import { hostExecPath } from './branded-host.js';
 import { isPidAlive, killProcessTreePids, isAnyPidAlive, captureTeardownSnapshot } from '../canvas/pid.js';
 import { assertMandatoryCanvasExtensions } from './canvas-extensions.js';
-import { boundFleet } from './fleet.js';
+import { boundFleet, brokerCapReached, brokerThresholdsForDaemon } from './fleet.js';
 import { emitEvent } from '../events/emit.js';
 import { bindBrokerEventSource, eventSource } from '../events/source.js';
 import { envBrokerEngine } from '../../shared/env.js';
@@ -193,6 +193,19 @@ export const headlessBrokerHost = {
     launch(nodeId, inv, opts) {
         // Fast-fail known launch errors before we detach a broker process.
         preflightBrokerLaunch(nodeId, inv, opts.cwd);
+        // Resolve the fleet BEFORE opening any handle: an unbound-fleet launch must
+        // fail fast with nothing to clean up (design D-2 — broker launches happen
+        // only inside crtrd, or a test harness that explicitly bound a fleet).
+        const fleet = boundFleet();
+        // The ledger is the ONE admission gate for a broker process: every launch
+        // path (revive, spawn, recycle, reset) funnels through here, so claiming
+        // the slot before anything is opened — and giving it back on any path that
+        // does not end in a registered handle — is what makes the cap real rather
+        // than advisory. A caller that cannot proceed without a slot sees this
+        // typed refusal; a caller that can wait catches it and freezes instead.
+        if (!fleet.reserveSlot(nodeId)) {
+            throw brokerCapReached(brokerThresholdsForDaemon().automaticReviveCap, fleet.size());
+        }
         // Redirect the detached broker's stdout+stderr to a per-node log under the
         // node's existing job/ dir. It retains arbitrary engine/process residue and
         // failed-canonical fatal fallback output. Append-mode preserves crash-revive history.
@@ -233,10 +246,6 @@ export const headlessBrokerHost = {
         }
         if (eventSource() === undefined)
             bindBrokerEventSource(nodeId);
-        // Resolve the fleet BEFORE spawning: an unbound-fleet launch must fail
-        // fast with nothing to clean up (design D-2 — broker launches happen only
-        // inside crtrd, or a test harness that explicitly bound a fleet).
-        const fleet = boundFleet();
         // `--canvas-home` declares broker ownership in argv so the daemon's
         // startup epoch census can match its own canvas' brokers exactly (crtrd's
         // brokerCommandDeclaresCanvasHome) instead of inferring from install
@@ -244,12 +253,20 @@ export const headlessBrokerHost = {
         // daemon's census reaps every prior-epoch broker without adoption (D-8).
         // Both precede the node id: the node id is by contract the FINAL argv
         // token (both broker-cli and the ps census parse it that way).
-        const child = spawn(hostExecPath(), [resolveBrokerEntry(), '--canvas-home', crtrHome(), '--epoch', fleet.epoch(), nodeId], {
-            cwd: opts.cwd,
-            detached: true,
-            stdio: ['ignore', logFd, logFd],
-            env: childEnv,
-        });
+        let child;
+        try {
+            child = spawn(hostExecPath(), [resolveBrokerEntry(), '--canvas-home', crtrHome(), '--epoch', fleet.epoch(), nodeId], {
+                cwd: opts.cwd,
+                detached: true,
+                stdio: ['ignore', logFd, logFd],
+                env: childEnv,
+            });
+        }
+        catch (error) {
+            fleet.releaseReservation(nodeId);
+            closeSync(logFd);
+            throw error;
+        }
         // The child holds its own dup of the fd; release the parent's copy so the
         // launching process (CLI or daemon) never leaks it.
         closeSync(logFd);
@@ -299,6 +316,10 @@ export const headlessBrokerHost = {
             fleet.register(nodeId, handle);
             void exited.then((status) => fleet.onChildExit(nodeId, status));
         }
+        else {
+            // Nothing was registered, so nothing will ever free this slot at exit.
+            fleet.releaseReservation(nodeId);
+        }
         return handle;
     },
     isAlive(node) {

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

@@ -4,5 +4,5 @@
  *  before. ALL runtime/spine/lifecycle/kind prompting now lives as gated builtin
  *  memory docs (src/builtin-memory/), spliced in fresh every turn — this scaffold
  *  must never duplicate that prose. Imported by launch.ts (its own systemPrompt)
- *  and `sys prompt-review` so the two can never drift. */
+ *  and `sys context prompt-review` so the two can never drift. */
 export declare const LAUNCH_SYSTEM_PROMPT: string;

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

@@ -1,5 +1,5 @@
 // launch-prompt.ts — the minimal static system-prompt scaffold, isolated from
-// launch.ts so CLI consumers (`sys prompt-review`) can import the exact string
+// launch.ts so CLI consumers (`sys context prompt-review`) can import the exact string
 // boot uses WITHOUT pulling launch.ts's canvas-db reach (editorLabel et al.).
 // Pure: zero imports.
 /** The minimal static system prompt every node launches with — a thin launcher
@@ -8,6 +8,6 @@
  *  before. ALL runtime/spine/lifecycle/kind prompting now lives as gated builtin
  *  memory docs (src/builtin-memory/), spliced in fresh every turn — this scaffold
  *  must never duplicate that prose. Imported by launch.ts (its own systemPrompt)
- *  and `sys prompt-review` so the two can never drift. */
+ *  and `sys context prompt-review` so the two can never drift. */
 export const LAUNCH_SYSTEM_PROMPT = 'You are a node in the crtr canvas — an agentic runtime.\n\nGuidelines:\n' +
     '- Use the crtr canvas and memory substrate according to injected context.';

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/lifecycle.d.ts

@@ -1,4 +1,4 @@
-import type { NodeMeta, NodeStatus, ExitIntent } from '../canvas/types.js';
+import type { NodeMeta, NodeStatus, ExitIntent, TerminalReason } from '../canvas/types.js';
 /** The lifecycle events — the only vocabulary for moving a node's status/intent.
  *  Each maps (in the table below) to a target status and/or intent plus the set
  *  of from-statuses it is legal from. */
@@ -9,7 +9,9 @@ export type LifecycleEvent = 'finish' | 'park' | 'cancel' | 'crash' | 'yield' |
  *
  *  Throws on an unknown node or an illegal move. The conditional update makes
  *  legality authoritative at SQLite write time rather than at a stale read. */
-export declare function transition(nodeId: string, event: LifecycleEvent): NodeMeta;
+export declare function transition(nodeId: string, event: LifecycleEvent, opts?: {
+    reason?: TerminalReason;
+}): NodeMeta;
 /** Whether this row is a PARKED node — terminalized by the unattended clock
  *  rather than by finishing its own work. The one read of the park marker:
  *  `done` qualified by `intent='parked'`, both written in the same atomic

package/dist/core/runtime/lifecycle.js

@@ -33,6 +33,14 @@
 // inside `core/canvas/`).
 import { getNode, cancelCronsOnWake, transitionStatusIntent } from '../canvas/index.js';
 const ANY = '*';
+const TERMINAL_REASONS = {
+    finish: 'finished',
+    park: 'parked',
+    cancel: 'stranded',
+    crash: 'crashed',
+    'refresh-launch': null,
+    revive: null,
+};
 /** The supervised statuses — a live node the daemon watches. */
 const LIVE = ['active', 'idle'];
 /** The legal transition table — derived directly from the (status, intent) pairs
@@ -69,15 +77,18 @@ const TRANSITIONS = {
  *
  *  Throws on an unknown node or an illegal move. The conditional update makes
  *  legality authoritative at SQLite write time rather than at a stale read. */
-export function transition(nodeId, event) {
+export function transition(nodeId, event, opts) {
     const spec = TRANSITIONS[event];
     const writeStatus = Object.prototype.hasOwnProperty.call(spec, 'status');
     const writeIntent = Object.prototype.hasOwnProperty.call(spec, 'intent');
+    const reason = opts?.reason ?? TERMINAL_REASONS[event];
     const fields = {};
     if (writeStatus)
         fields.status = spec.status;
     if (writeIntent)
         fields.intent = spec.intent ?? null;
+    if (reason !== undefined)
+        fields.terminal_reason = reason;
     // A committed canonical result is protected from a concurrent close.
     const changes = transitionStatusIntent(nodeId, fields, {
         fromStatuses: spec.from === ANY ? undefined : spec.from,

package/dist/core/runtime/memory.js

@@ -8,7 +8,7 @@ import { join } from 'node:path';
 // Import the pure path helper from paths.ts directly, NOT the canvas/index.js
 // barrel: the barrel re-exports `openDb`/canvas.ts accessors, so pulling it here
 // would drag canvas.db into the runtime graph of every pure-client CLI leaf that
-// resolves memory docs (e.g. `memory origin`, `sys prompt-review`). Stage B-9.
+// resolves memory docs (e.g. `memory origin`, `sys context prompt-review`). Stage B-9.
 import { contextDir } from '../canvas/paths.js';
 /** The node-local memory directory in a node's context dir — holds substrate
  *  docs (.md files with kind/when/why frontmatter). */

package/dist/core/runtime/reopen.js

@@ -38,8 +38,9 @@
 // mutating the live pointer — the explicit operation must not retract a
 // canonical final unless it can actually enact the requested re-task.
 import { join } from 'node:path';
-import { clearFinalReportIfMatches, getFinalReport, reportsDir, updateNode } from '../canvas/index.js';
+import { clearFinalReportIfMatches, getFinalReport, getNode, reportsDir, updateNode } from '../canvas/index.js';
 import { InputError } from '../io.js';
+import { transition } from './lifecycle.js';
 function currentFinalReport(nodeId) {
     return getFinalReport(nodeId);
 }
@@ -106,6 +107,14 @@ export function commitReopen(nodeId, expectedFinalReport) {
 export function commitReopenResident(nodeId) {
     const finalReport = currentFinalReport(nodeId);
     updateNode(nodeId, { lifecycle: 'resident' });
+    // A reopened node that is still parked in a terminal status has to come back
+    // to `active`, or its row keeps claiming it is finished while a broker runs
+    // its new mandate. Gated on terminal so a message landing on a live node
+    // never rewrites the intent it is working under.
+    const meta = getNode(nodeId);
+    if (meta !== null && (meta.status === 'done' || meta.status === 'canceled' || meta.status === 'dead')) {
+        transition(nodeId, 'revive');
+    }
     if (finalReport !== null)
         commitReopen(nodeId, finalReport);
 }

package/dist/core/runtime/reset.js

@@ -50,7 +50,7 @@ export function reapDescendants(rootId) {
             // sole .jsonl writer; tearDownNode then proactively closes the on-screen
             // viewer pane + registry row (attach auto-reconnects, so the viewer must be
             // closed here or it lingers ~30s in a misleading "reconnecting…" state).
-            transition(id, 'cancel');
+            transition(id, 'cancel', { reason: 'closed' });
             headlessBrokerHost.teardown(id);
             tearDownNode(id);
             reaped.push(id);

package/dist/core/runtime/revive-all.d.ts

@@ -52,6 +52,9 @@ export interface ReviveAllResult {
         node_id: string;
         error: string;
     }[];
+    /** Node ids the cap turned away. They are not failures: each row is frozen
+     *  and the daemon's tick relaunches it as slots free. */
+    frozen: string[];
 }
 /** RESUME every disconnected node. reviveNode is the ONLY sanctioned launcher
  *  and self-guards the double-spawn (a node whose broker pid is already live is a

package/dist/core/runtime/revive-all.js

@@ -92,13 +92,19 @@ export function listDisconnected() {
  *  with resume:true. One failing node never aborts the sweep — its error is
  *  collected and the rest proceed. */
 export function reviveAll() {
-    const result = { revived: [], failed: [] };
+    const result = { revived: [], failed: [], frozen: [] };
     for (const meta of listDisconnected()) {
         try {
             // Reconnecting a disconnected broker is recovery, not a wake — a node
-            // waiting on an armed deadline keeps it across the sweep.
-            reviveNode(meta.node_id, { resume: true, recovery: true });
-            result.revived.push(meta.node_id);
+            // waiting on an armed deadline keeps it across the sweep. A sweep over a
+            // whole canvas is the likeliest way to meet the cap, and every node in it
+            // is one the daemon wants back: freeze the overflow and let the tick
+            // bring them up as slots free.
+            const outcome = reviveNode(meta.node_id, { resume: true, recovery: true, capacity: 'freeze' }).outcome;
+            if (outcome === 'frozen')
+                result.frozen.push(meta.node_id);
+            else
+                result.revived.push(meta.node_id);
         }
         catch (err) {
             result.failed.push({ node_id: meta.node_id, error: err.message });

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

@@ -51,7 +51,18 @@ export interface ReviveResult {
      *  Present only when a fresh launch actually happened (absent on the
      *  double-revive no-op, where nothing was cleared or relaunched). */
     faultExplanation?: () => string | null;
+    /** What this call actually did. `already-live` means a broker was already
+     *  running for the node and nothing was launched; `frozen` means no slot was
+     *  free and the row is now waiting for one — the tick thaws it. */
+    outcome: ReviveOutcome;
 }
+export type ReviveOutcome = 'launched' | 'already-live' | 'frozen';
+/** What a caller wants when the broker cap is full. `freeze` suits a caller
+ *  whose reason to run survives waiting (durable mail, a cron sink, a recovery
+ *  respawn): the row is marked frozen and the tick relaunches it when a slot
+ *  frees. `refuse` suits a caller that must have a live broker NOW (an attach,
+ *  a bridge, a companion bind) and can only report the refusal. */
+export type ReviveCapacityPolicy = 'freeze' | 'refuse';
 /** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
  *  meta. Opens no viewer (engine-only).
  *
@@ -66,6 +77,7 @@ export interface ReviveResult {
  */
 export declare function reviveNode(nodeId: string, opts: {
     resume: boolean;
+    capacity: ReviveCapacityPolicy;
     wakeReason?: ReviveWakeReason;
     recovery?: boolean;
 }): ReviveResult;