@crouton-kit/crouter 0.3.31 → 0.3.33

package/dist/core/__tests__/model-ladders.test.js

@@ -0,0 +1,160 @@
+// Run: node --import tsx/esm --test src/core/__tests__/model-ladders.test.ts
+//
+// The runtime model ladder is user-configurable: config.json can override the
+// provider default, the per-provider ladder cells, and persona-strength picks.
+// This test verifies both the merge shape and the cached sync read invalidation
+// on config edits.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readConfig } from '../config.js';
+import { buildLaunchSpec, equivalentOtherProviderModel, normalizeModel } from '../runtime/launch.js';
+let home;
+const crtrRoot = () => join(home, '.crouter');
+const configFile = () => join(crtrRoot(), 'config.json');
+function writeConfig(config) {
+    mkdirSync(crtrRoot(), { recursive: true });
+    writeFileSync(configFile(), `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-model-ladders-'));
+    process.env['HOME'] = home;
+});
+beforeEach(() => {
+    rmSync(crtrRoot(), { recursive: true, force: true });
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['HOME'];
+});
+test('config merge keeps ladder defaults while honoring overrides', () => {
+    writeConfig({
+        modelLadders: {
+            defaultProvider: 'openai',
+            anthropic: {
+                ultra: 'anthropic/custom-ultra-1',
+                strong: 'anthropic/custom-strong-1',
+                medium: 'anthropic/custom-medium-1',
+                light: 'anthropic/custom-light-1',
+            },
+            openai: {
+                ultra: 'openai/custom-ultra-1',
+                strong: 'openai/custom-strong-1',
+                medium: 'openai/custom-medium-1',
+                light: 'openai/custom-light-1',
+            },
+        },
+        personaStrengths: {
+            developer: 'light',
+        },
+    });
+    const cfg = readConfig('user');
+    assert.equal(cfg.modelLadders.defaultProvider, 'openai');
+    assert.equal(cfg.modelLadders.openai.strong, 'openai/custom-strong-1');
+    assert.equal(cfg.modelLadders.anthropic.light, 'anthropic/custom-light-1');
+    assert.equal(cfg.personaStrengths.developer, 'light');
+});
+test('normalizeModel and buildLaunchSpec honor config overrides, and edits invalidate the cache', () => {
+    writeConfig({
+        modelLadders: {
+            defaultProvider: 'openai',
+            anthropic: {
+                ultra: 'anthropic/custom-ultra-1',
+                strong: 'anthropic/custom-strong-1',
+                medium: 'anthropic/custom-medium-1',
+                light: 'anthropic/custom-light-1',
+            },
+            openai: {
+                ultra: 'openai/custom-ultra-1',
+                strong: 'openai/custom-strong-1',
+                medium: 'openai/custom-medium-1',
+                light: 'openai/custom-light-1',
+            },
+        },
+        personaStrengths: {
+            developer: 'light',
+        },
+    });
+    assert.equal(normalizeModel('strong'), 'openai/custom-strong-1', 'config default provider wins over env/default');
+    assert.equal(normalizeModel('opus'), 'anthropic/custom-strong-1', 'family aliases still map to anthropic');
+    const override = buildLaunchSpec('developer', 'base', {
+        lifecycle: 'terminal',
+        hasManager: true,
+        model: 'medium',
+    });
+    assert.equal(override.launch.model, 'openai/custom-medium-1', 'meta.model_override wins over personaStrengths');
+    const persona = buildLaunchSpec('developer', 'base', {
+        lifecycle: 'terminal',
+        hasManager: true,
+    });
+    assert.equal(persona.launch.model, 'openai/custom-light-1', 'personaStrengths wins over persona frontmatter');
+    writeConfig({
+        modelLadders: {
+            defaultProvider: 'anthropic',
+            anthropic: {
+                ultra: 'anthropic/custom-ultra-2',
+                strong: 'anthropic/custom-strong-2',
+                medium: 'anthropic/custom-medium-2',
+                light: 'anthropic/custom-light-2',
+            },
+            openai: {
+                ultra: 'openai/custom-ultra-2',
+                strong: 'openai/custom-strong-2',
+                medium: 'openai/custom-medium-2',
+                light: 'openai/custom-light-2',
+            },
+        },
+        personaStrengths: {
+            developer: 'strong',
+        },
+    });
+    assert.equal(normalizeModel('strong'), 'anthropic/custom-strong-2', 'a config edit invalidates the cached sync read');
+    const edited = buildLaunchSpec('developer', 'base', {
+        lifecycle: 'terminal',
+        hasManager: true,
+    });
+    assert.equal(edited.launch.model, 'anthropic/custom-strong-2', 'edited personaStrengths are picked up on the next launch');
+});
+test('equivalentOtherProviderModel maps a failed ladder model to the other provider at the same strength', () => {
+    writeConfig({
+        modelLadders: {
+            defaultProvider: 'anthropic',
+            anthropic: {
+                ultra: 'anthropic/custom-ultra',
+                strong: 'anthropic/custom-strong:high',
+                medium: 'anthropic/custom-medium',
+                light: 'anthropic/custom-light',
+            },
+            openai: {
+                ultra: 'openai/custom-ultra',
+                strong: 'openai/custom-strong:xhigh',
+                medium: 'openai/custom-medium',
+                light: 'openai/custom-light',
+            },
+        },
+    });
+    assert.deepEqual(equivalentOtherProviderModel('anthropic/custom-strong:medium'), {
+        fromProvider: 'anthropic',
+        toProvider: 'openai',
+        strength: 'strong',
+        model: 'openai/custom-strong:xhigh',
+    });
+    assert.deepEqual(equivalentOtherProviderModel('openai/custom-light'), {
+        fromProvider: 'openai',
+        toProvider: 'anthropic',
+        strength: 'light',
+        model: 'anthropic/custom-light',
+    });
+    assert.equal(equivalentOtherProviderModel('anthropic/custom-strong:medium', new Set(['anthropic'])), null);
+    assert.equal(equivalentOtherProviderModel('some-provider/not-in-ladder'), null);
+});
+test('malformed existing user config surfaces instead of falling back to defaults', () => {
+    mkdirSync(crtrRoot(), { recursive: true });
+    writeFileSync(configFile(), '{\n', 'utf8');
+    assert.throws(() => buildLaunchSpec('developer', 'base', {
+        lifecycle: 'terminal',
+        hasManager: true,
+    }), /JSON|Unexpected token|Unexpected end/);
+});

package/dist/core/__tests__/node-env.test.d.ts

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

package/dist/core/__tests__/node-env.test.js

@@ -0,0 +1,26 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { nodeEnv } from '../runtime/nodes.js';
+function meta(over = {}) {
+    return {
+        node_id: 'n',
+        name: 'alpha-beta',
+        created: '2026-01-01T00:00:00.000Z',
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+test('nodeEnv exports CRTR_CYCLES from meta.cycles', () => {
+    const env = nodeEnv(meta({ cycles: 9 }));
+    assert.equal(env.CRTR_CYCLES, '9');
+});
+test('nodeEnv defaults CRTR_CYCLES to 0 when meta.cycles is absent', () => {
+    const withoutCycles = meta();
+    delete withoutCycles.cycles;
+    const env = nodeEnv(withoutCycles);
+    assert.equal(env.CRTR_CYCLES, '0');
+});

package/dist/core/__tests__/push-final-guard.test.js

@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, setStatus } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
-import { registerPush } from '../../commands/push.js';
+import { registerPush, mapFinalizeTransitionRaceError } from '../../commands/push.js';
 import { InputError } from '../io.js';
 let home;
 const prevNodeId = process.env['CRTR_NODE_ID'];
@@ -69,3 +69,9 @@ test('push final on a dead node is also caught cleanly', async () => {
     process.env['CRTR_NODE_ID'] = id;
     await assert.rejects(() => finalLeaf().run({ body: 'x' }), (e) => e instanceof InputError && e.payload.error === 'already_finalized');
 });
+test('a raw finalize-transition race is normalized to already_finalized', () => {
+    const mapped = mapFinalizeTransitionRaceError('canceled', new Error("illegal lifecycle transition: 'finalize' from status='canceled' (node raceNode)"));
+    assert.ok(mapped instanceof InputError, 'the raw transition error is converted');
+    assert.equal(mapped?.payload.error, 'already_finalized');
+    assert.equal(mapped?.payload.message, 'This node is already canceled — `push final` finishes a node once and cannot finalize it again.');
+});

package/dist/core/__tests__/relaunch-root.test.js

@@ -36,7 +36,7 @@ function makeDeps(pid) {
     const deps = {
         launchBroker: (nodeId) => {
             launched.push(nodeId);
-            return { pid };
+            return { pid, exited: new Promise(() => { }) };
         },
         waitForViewSocket: () => true,
         respawnViewer: () => true,
@@ -57,7 +57,7 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
-test('relaunchRoot parks the old root done and mints a fresh active root, reaping descendants', () => {
+test('relaunchRoot parks the old root done and mints a fresh active root, reaping descendants', async () => {
     // root → child → grandchild (a parent that subscribes to its workers).
     createNode(node('root', { parent: null, lifecycle: 'resident', cwd: '/tmp/proj' }));
     createNode(node('child', { parent: 'root' }));
@@ -65,7 +65,7 @@ test('relaunchRoot parks the old root done and mints a fresh active root, reapin
     subscribe('root', 'child', true);
     subscribe('child', 'grand', true);
     const { deps, launched } = makeDeps(4242);
-    const res = relaunchRoot('root', deps);
+    const res = await relaunchRoot('root', deps);
     // A fresh, DIFFERENT node id was minted and booted.
     assert.ok(res, 'relaunchRoot returns the new node id');
     const newId = res.newNodeId;
@@ -86,14 +86,14 @@ test('relaunchRoot parks the old root done and mints a fresh active root, reapin
     assert.equal(getNode('child')?.status, 'canceled', 'descendant child canceled');
     assert.equal(getNode('grand')?.status, 'canceled', 'descendant grandchild canceled');
 });
-test('relaunchRoot on a boot failure leaves the old root + descendants fully intact', () => {
+test('relaunchRoot on a boot failure leaves the old root + descendants fully intact', async () => {
     // The mint-and-boot-FIRST ordering: a launch failure (pid=null) must occur
     // BEFORE the old root is parked or its descendants reaped.
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('child', { parent: 'root' }));
     subscribe('root', 'child', true);
     const { deps, launched } = makeDeps(null); // broker never starts
-    const res = relaunchRoot('root', deps);
+    const res = await relaunchRoot('root', deps);
     assert.equal(res, null, 'a boot failure returns null');
     // Old root + descendant untouched: still live, ready to keep running.
     assert.equal(getNode('root')?.status, 'active', 'old root left active + untouched');
@@ -102,13 +102,13 @@ test('relaunchRoot on a boot failure leaves the old root + descendants fully int
     assert.equal(launched.length, 1, 'one broker launch was attempted');
     assert.equal(getNode(launched[0])?.status, 'dead', 'the half-born new node is crashed (dead)');
 });
-test('relaunchRoot is a no-op for a non-root child and an already-parked root', () => {
+test('relaunchRoot is a no-op for a non-root child and an already-parked root', async () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('child', { parent: 'root' }));
     createNode(node('done-root', { parent: null, status: 'done' }));
     const { deps, launched } = makeDeps(1);
-    assert.equal(relaunchRoot('child', deps), null, 'a child is not a relaunchable root');
-    assert.equal(relaunchRoot('done-root', deps), null, 'a done root is not relaunched again (double /new)');
-    assert.equal(relaunchRoot('ghost', deps), null, 'an unknown node is a no-op');
+    assert.equal(await relaunchRoot('child', deps), null, 'a child is not a relaunchable root');
+    assert.equal(await relaunchRoot('done-root', deps), null, 'a done root is not relaunched again (double /new)');
+    assert.equal(await relaunchRoot('ghost', deps), null, 'an unknown node is a no-op');
     assert.deepEqual(launched, [], 'no broker was booted for any of the no-op cases');
 });

package/dist/core/__tests__/revive.test.js

@@ -1,11 +1,11 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/revive.test.ts
 //
 // HEADLESS RETARGET (foundation-spec §C.13 + §E). Covers the session-picker fix
-// (resume by ABSOLUTE session-file path, cwd-immune, falling back to the bare
-// uuid for older nodes) AND the double-revive guard that keeps two pi processes
-// off one session file. The argv selection is unit-tested via the pure
-// `resumeArgs` + `buildPiArgv`; the guard + the cycle-counter bump are now driven
-// against a fabricated BROKER-hosted node — ZERO real tmux, ZERO real boot.
+// (resume by ABSOLUTE session-file path, cwd-immune) and the double-revive guard
+// that keeps two pi processes off one session file. The argv selection is
+// unit-tested via the pure `resumeArgs` + `buildPiArgv`; the guard + the
+// cycle-counter bump are now driven against a fabricated BROKER-hosted node —
+// ZERO real tmux, ZERO real boot.
 //
 // (1) BUG LOCKED — the double-revive guard (revive.ts:114): a node already up
 //     (its engine container alive AND its pi pid live) must NOT be re-launched —
@@ -30,13 +30,14 @@
 //     goes RED.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { createNode } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { buildPiArgv } from '../runtime/launch.js';
+import { headlessBrokerHost } from '../runtime/host.js';
 import { resumeArgs, reviveNode } from '../runtime/revive.js';
 import { createHarness } from './helpers/harness.js';
 let home;
@@ -211,11 +212,15 @@ test('reviveNode PROCEEDS when the broker engine is DOWN (dead pid) — cycle co
         // circuit → reviveNode proceeds. It bumps cycles BEFORE the detached (fake-
         // engine) launch, so the bump is observable instantly; the throwaway broker is
         // killed by dispose().
+        const sessionFile = join(home, 'sessions', 'crtr-revive-proceed.jsonl');
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
         const M = h.fabricateBrokerNode({
             status: 'active',
             intent: null,
             pi_pid: deadPid(),
             pi_session_id: 'uuid-1',
+            pi_session_file: sessionFile,
         });
         assert.equal(h.node(M).cycles ?? 0, 0, 'fabricated at cycle 0 (no revive yet)');
         reviveNode(M, { resume: true });
@@ -225,3 +230,28 @@ test('reviveNode PROCEEDS when the broker engine is DOWN (dead pid) — cycle co
         await h.dispose();
     }
 });
+test('reviveNode crashes and clears pid when launch/preflight throws', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-fail' });
+    const originalLaunch = headlessBrokerHost.launch;
+    try {
+        const sessionFile = join(home, 'sessions', 'crtr-revive-fail.jsonl');
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: deadPid(),
+            pi_session_id: 'uuid-2',
+            pi_session_file: sessionFile,
+        });
+        headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
+        assert.throws(() => reviveNode(M, { resume: true }), /refusing to revive/i);
+        const after = h.node(M);
+        assert.equal(after.status, 'dead', 'failed revive marks the node dead');
+        assert.equal(after.pi_pid, null, 'failed revive clears the stale pid');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/spawn-root.test.js

@@ -10,7 +10,8 @@ import { createNode, getNode, getRow, subscribersOf } from '../canvas/canvas.js'
 import { closeDb } from '../canvas/db.js';
 import { nodeDir } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
-import { resolveSpawner } from '../runtime/spawn.js';
+import { spawnChild, resolveSpawner } from '../runtime/spawn.js';
+import { headlessBrokerHost } from '../runtime/host.js';
 let home;
 function spawner(id) {
     return {
@@ -81,3 +82,25 @@ test('unknown parent: spawnNode throws and mints NO node dir / row (validate bef
     assert.equal(getRow(orphanId), null, 'no index row written for the orphan');
     assert.equal(existsSync(nodeDir(orphanId)), false, 'no node dir scaffolded for the orphan');
 });
+test('spawnChild crashes the node when launch/preflight throws', async () => {
+    const parentId = 'A';
+    createNode(spawner(parentId));
+    const originalLaunch = headlessBrokerHost.launch;
+    let launchedNodeId = null;
+    try {
+        headlessBrokerHost.launch = (nodeId, _inv, _opts) => {
+            launchedNodeId = nodeId;
+            throw new Error('boom');
+        };
+        await assert.rejects(async () => spawnChild({ kind: 'developer', cwd: '/tmp/work', parent: parentId, prompt: 'task' }), /refusing to launch/i);
+        assert.ok(launchedNodeId !== null, 'the launch hook saw the spawned node id');
+        const after = getNode(launchedNodeId);
+        assert.equal(after.status, 'dead', 'failed spawn marks the node dead');
+        assert.equal(after.pi_pid, null, 'failed spawn clears the stale pid');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        closeDb();
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/core/__tests__/stop-guard.test.js

@@ -80,3 +80,13 @@ test('pushedFinal → finished; askedHuman → escalated (both short-circuit bef
     assert.deepEqual(evaluateStop('t', { pushedFinal: true, askedHuman: false }), { action: 'allow', reason: 'finished' });
     assert.deepEqual(evaluateStop('t', { pushedFinal: false, askedHuman: true }), { action: 'allow', reason: 'escalated' });
 });
+test('already-terminal stored statuses are allowed without a stall reprompt', () => {
+    for (const [id, status] of [
+        ['doneNode', 'done'],
+        ['deadNode', 'dead'],
+        ['canceledNode', 'canceled'],
+    ]) {
+        createNode(node(id, { parent: 'mgr', lifecycle: 'terminal', status }));
+        assert.deepEqual(evaluateStop(id, noSignals), { action: 'allow', reason: 'finished' });
+    }
+});

package/dist/core/__tests__/stranded-relaunch.test.d.ts

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

package/dist/core/__tests__/stranded-relaunch.test.js

@@ -0,0 +1,72 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/stranded-relaunch.test.ts
+//
+// BUG-REGRESSION (observed 2026-06-15 on the live canvas). A broker-hosted node
+// whose row carries pi_pid=NULL but pi_session_id SET was read by
+// handleNodeLiveness as "a relaunch in flight — leave it" UNCONDITIONALLY, with
+// no timeout. reviveNode clears pi_pid right after launch and the fresh engine
+// re-records it within a tick or two — but a relaunch whose broker DIED in that
+// gap (after the pid-clear, before re-record) never re-records, so the node sat
+// 'active' with no engine FOREVER and its parent waited on a dead child. Six such
+// stranded resident roots had accumulated and the daemon would never recover or
+// reap any of them.
+//
+// THE FIX — give the pid==null + session-set case the SAME REVIVE_GRACE_MS boot
+// grace as the never-booted case: a healthy relaunch always re-records its pid
+// well inside the grace (and the pid-alive branch clears the clock); if the grace
+// ELAPSES with still no pid, the relaunch is dead → grace-revive RESUME on the
+// saved session. The 20s grace doubles as the double-spawn guard.
+//
+// WHY MODEL-LEVEL, NOT TMUX CHROME — the stranding lives entirely in pure daemon
+// logic (the pid==null branch of handleNodeLiveness + the unhealthySince clock).
+// A fabricated broker row carrying pi_pid=null + a recorded pi_session_id
+// reproduces the exact stranded state with no process at all; h.tick(now) walks a
+// deterministic clock across the grace boundary and getNode().cycles (reviveNode
+// bumps cycles + transition('revive') BEFORE the detached spawn) makes the revive
+// observable instantly.
+//
+// HOW IT FAILS IF THE BUG REGRESSES — restore the unconditional
+// `if (meta.pi_session_id != null) return;` and the PAST-grace tick never revives
+// → cycles stays 0 → the final assert goes RED.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHarness } from './helpers/harness.js';
+// REVIVE_GRACE_MS is 20_000 (crtrd.ts). Offsets well inside / well past it keep
+// the test robust to the exact value without importing it.
+const NOW = 7_000_000;
+const WITHIN_GRACE = NOW + 10_000; // < 20s after first-observed-null → still pending
+const PAST_GRACE = NOW + 25_000; //  > 20s after first-observed-null → revive
+test('stranded relaunch: pid=null + session set is revived once the boot grace elapses, not left active forever', { timeout: 30_000 }, async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-stranded' });
+    try {
+        // The EXACT stranded state: a broker row that booted once (pi_session_id
+        // captured) whose relaunch then died after the pid-clear — pi_pid NULL,
+        // intent null (so it is neither the refresh nor the idle-release path).
+        const B = h.fabricateBrokerNode({
+            kind: 'developer',
+            status: 'active',
+            intent: null,
+            pi_pid: null,
+            pi_session_id: 'sess-stranded-B',
+        });
+        const b0 = h.node(B);
+        assert.equal(b0.host_kind, 'broker', 'B is broker-hosted (paneless)');
+        assert.equal(b0.pi_pid ?? null, null, 'row pi_pid is null (relaunch never re-recorded)');
+        assert.equal(b0.pi_session_id, 'sess-stranded-B', 'session is set (booted once)');
+        assert.equal(b0.cycles ?? 0, 0, 'no revive yet — cycles at 0');
+        // --- TICK 1 @ NOW: first observation of null pid → start the boot grace
+        //     clock, do NOT revive (a healthy relaunch re-records its pid here). ---
+        await h.tick(NOW);
+        assert.equal(h.node(B).cycles ?? 0, 0, 'first tick: no revive — grace clock started');
+        // --- TICK 2 @ NOW+10s (WITHIN grace): still pending. This is the
+        //     double-spawn guard — a healthy relaunch would have re-recorded by now. ---
+        await h.tick(WITHIN_GRACE);
+        assert.equal(h.node(B).cycles ?? 0, 0, 'within REVIVE_GRACE_MS: still no revive (healthy relaunch grace, not a strand yet)');
+        // --- TICK 3 @ NOW+25s (PAST grace): the relaunch is dead → grace-revive
+        //     RESUME on the saved session; reviveNode bumps cycles immediately. ---
+        await h.tick(PAST_GRACE);
+        assert.equal(h.node(B).cycles ?? 0, 1, 'past REVIVE_GRACE_MS: the stranded relaunch is revived (cycles bumped) — NOT left active forever');
+    }
+    finally {
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/tmux-surface.test.js

@@ -68,7 +68,11 @@ test('§2.2 driver invariant: every placement verb in tmux.ts passes an explicit
         found++;
         const verb = m[1];
         const arr = enclosingArray(src, m.index);
-        assert.ok(arr.includes(`'-t'`), `tmux verb '${verb}' is invoked WITHOUT an explicit -t target — a latent ` +
+        // The invariant is "name a specific tmux object, never fall back to the
+        // GLOBAL current one". `-t` targets a destination; `break-pane` (and the
+        // deleted swap/join/move-pane) instead name their SOURCE with `-s` — which
+        // satisfies the invariant identically. Accept either explicit target flag.
+        assert.ok(arr.includes(`'-t'`) || arr.includes(`'-s'`), `tmux verb '${verb}' is invoked WITHOUT an explicit -t/-s target — a latent ` +
             `instance of the unbidden-window bug (§2.2). Offending args array:\n${arr}`);
     }
     // Sanity: the driver really does contain placement verbs (so a refactor that

package/dist/core/__tests__/unknown-path.test.js

@@ -3,7 +3,7 @@
 //
 // The `next` road sign must name a command that actually exists: the FULL path
 // to the deepest matched node, not just its local name. A prior bug emitted
-// `crtr find -h` (dropping the `skill` parent) when `crtr skill find bogus` was
+// `crtr inspect -h` (dropping the `pkg` parent) when `crtr pkg inspect bogus` was
 // invoked, sending the caller to a nonexistent top-level command.
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
@@ -15,25 +15,25 @@ const leaf = defineLeaf({
     help: { name: 'search', summary: 'search', output: [], outputKind: 'object', effects: ['None. Read-only.'] },
     run: async () => ({}),
 });
-const findBranch = defineBranch({
-    name: 'find',
-    description: 'find',
+const inspectBranch = defineBranch({
+    name: 'inspect',
+    description: 'inspect',
     whenToUse: 'x',
-    help: { name: 'find', summary: 'find' },
+    help: { name: 'inspect', summary: 'inspect' },
     children: [leaf],
 });
-const skillBranch = defineBranch({
-    name: 'skill',
-    description: 'skill',
+const pkgBranch = defineBranch({
+    name: 'pkg',
+    description: 'pkg',
     whenToUse: 'x',
-    help: { name: 'skill', summary: 'skill' },
-    rootEntry: { concept: 'skill', desc: 'skill', useWhen: 'x' },
-    children: [findBranch],
+    help: { name: 'pkg', summary: 'pkg' },
+    rootEntry: { concept: 'pkg', desc: 'pkg', useWhen: 'x' },
+    children: [inspectBranch],
 });
 const root = defineRoot({
     tagline: 'test runtime',
     globals: [],
-    subtrees: [skillBranch],
+    subtrees: [pkgBranch],
 });
 function nextHint(...tokens) {
     const { node, path, remaining } = walk(root, tokens);
@@ -44,15 +44,15 @@ describe('unknown-path error: recovery hint names the full valid path', () => {
     test('root-level unknown points at `crtr -h`', () => {
         assert.match(nextHint('bogus'), /Run `crtr -h`/);
     });
-    test('one-level unknown points at `crtr skill -h`', () => {
-        assert.match(nextHint('skill', 'bogus'), /Run `crtr skill -h`/);
+    test('one-level unknown points at `crtr pkg -h`', () => {
+        assert.match(nextHint('pkg', 'bogus'), /Run `crtr pkg -h`/);
     });
-    test('two-level unknown points at `crtr skill find -h`, not `crtr find -h`', () => {
-        const hint = nextHint('skill', 'find', 'bogus');
-        assert.match(hint, /Run `crtr skill find -h`/);
-        assert.doesNotMatch(hint, /Run `crtr find -h`/);
+    test('two-level unknown points at `crtr pkg inspect -h`, not `crtr inspect -h`', () => {
+        const hint = nextHint('pkg', 'inspect', 'bogus');
+        assert.match(hint, /Run `crtr pkg inspect -h`/);
+        assert.doesNotMatch(hint, /Run `crtr inspect -h`/);
     });
     test('valid children of the matched node are listed', () => {
-        assert.match(nextHint('skill', 'find', 'bogus'), /Valid children: search\./);
+        assert.match(nextHint('pkg', 'inspect', 'bogus'), /Valid children: search\./);
     });
 });

package/dist/core/__tests__/yield-ensures-daemon.test.d.ts

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

package/dist/core/__tests__/yield-ensures-daemon.test.js

@@ -0,0 +1,54 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/yield-ensures-daemon.test.ts
+//
+// Regression: `crtr node yield` timed out into "broker gone" instead of reviving
+// in the same pane (observed 2026-06-18). The yield arms intent='refresh' and
+// the broker shuts down expecting the DAEMON to relaunch it — but requestYield
+// never ensured the daemon was running, unlike the spawn/recycle paths. With a
+// dead daemon, the broker exited and nothing revived it; the viewer redialed its
+// view.sock for ~30s and reported "broker gone". This locks in that requestYield
+// ensures the supervisor before arming the refresh.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { requestYield } from '../runtime/promote.js';
+let home;
+function mkOrchestrator(id) {
+    const meta = {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'orchestrator', // already an orchestrator → yield skips the promote path
+        lifecycle: 'terminal',
+        status: 'active', // LIVE, so transition('yield') is legal
+    };
+    createNode(meta);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-yield-ensure-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('requestYield ensures the daemon before arming intent=refresh', () => {
+    mkOrchestrator('n1');
+    let ensured = 0;
+    const res = requestYield('n1', {}, { ensure: () => { ensured += 1; } });
+    // The supervisor that performs the refresh-revive must have been ensured...
+    assert.equal(ensured, 1, 'requestYield must ensure the daemon is running');
+    // ...and the yield must still arm the refresh.
+    assert.equal(res.willRefresh, true);
+    assert.equal(getNode('n1')?.intent, 'refresh');
+});