@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/core/__tests__/frame-decoder-perf.test.js

@@ -0,0 +1,198 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/frame-decoder-perf.test.ts
+//
+// Bug-regression suite for the FrameDecoder O(n²) typing-lag bug (2026-06-09).
+//
+// OBSERVED BUG: typing in `crtr attach` lagged after the headless-broker change.
+// Root cause #1: FrameDecoder.push() did `this.buf += str` and re-scanned the
+// WHOLE accumulated buffer (`this.buf.indexOf('\n')` + Buffer.byteLength over
+// the consumed prefix) on every ~64 KiB socket chunk, so one large frame (the
+// multi-MiB `welcome` snapshot, a big tool result) cost O(frame × chunks) —
+// measured ~254 ms of event-loop stall decoding a 16 MiB frame, with the stall
+// growing ~5× per size doubling. The decoder runs on BOTH the viewer and broker
+// read paths, so the stall blocked keystroke handling directly.
+//
+// The fix holds the carried partial line as an array of chunk strings and scans
+// each incoming chunk exactly once — amortized O(total bytes). Same 16 MiB frame:
+// ~12 ms.
+//
+// These tests lock in (a) behavioral equivalence with the old decoder across
+// randomized chunkings — frames, blank-line skip, malformed-JSON drop, multibyte
+// splits, and both FrameOverflowError caps with identical byte accounting — and
+// (b) the linear growth curve, so the quadratic shape cannot silently return.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { StringDecoder } from 'node:string_decoder';
+import { FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, } from '../runtime/broker-protocol.js';
+// ---------------------------------------------------------------------------
+// The PRE-FIX decoder, verbatim (git ed49e60), as the equivalence oracle.
+// ---------------------------------------------------------------------------
+class ReferenceFrameDecoder {
+    caps;
+    buf = '';
+    bufBytes = 0;
+    utf8 = new StringDecoder('utf8');
+    constructor(caps) {
+        this.caps = caps;
+    }
+    push(chunk) {
+        const str = typeof chunk === 'string' ? chunk : this.utf8.write(chunk);
+        this.buf += str;
+        this.bufBytes += Buffer.byteLength(str);
+        if (this.bufBytes > this.caps.maxTotalBytes) {
+            throw new FrameOverflowError('total', this.bufBytes, this.caps.maxTotalBytes);
+        }
+        const out = [];
+        let nl;
+        while ((nl = this.buf.indexOf('\n')) >= 0) {
+            const consumed = this.buf.slice(0, nl + 1);
+            this.bufBytes -= Buffer.byteLength(consumed);
+            const line = this.buf.slice(0, nl).trim();
+            this.buf = this.buf.slice(nl + 1);
+            if (line === '')
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* drop malformed */
+            }
+        }
+        if (this.bufBytes > this.caps.maxLineBytes) {
+            throw new FrameOverflowError('line', this.bufBytes, this.caps.maxLineBytes);
+        }
+        return out;
+    }
+}
+// Deterministic PRNG so a failure reproduces.
+let seed = 0xc0ffee;
+const rnd = () => {
+    seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+    return seed / 0x7fffffff;
+};
+const randInt = (lo, hi) => lo + Math.floor(rnd() * (hi - lo + 1));
+const MULTIBYTE = ['é', '漢', '🎉', '𝕏', 'ü', '한'];
+const randText = (len) => {
+    let s = '';
+    while (s.length < len) {
+        s += rnd() < 0.2 ? MULTIBYTE[randInt(0, MULTIBYTE.length - 1)] : String.fromCharCode(randInt(97, 122));
+    }
+    return s;
+};
+function run(dec, stream, cuts) {
+    const frames = [];
+    let prev = 0;
+    try {
+        for (const cut of [...cuts, stream.length]) {
+            if (cut <= prev)
+                continue;
+            frames.push(...dec.push(stream.subarray(prev, cut)));
+            prev = cut;
+        }
+        return { frames, err: null };
+    }
+    catch (e) {
+        if (e instanceof FrameOverflowError)
+            return { frames, err: `${e.kind}:${e.bytes}:${e.cap}` };
+        throw e;
+    }
+}
+test('FrameDecoder — behavior-equivalent to the pre-fix decoder across randomized chunkings (frames, blank lines, malformed JSON, multibyte splits, both overflow caps)', () => {
+    for (let t = 0; t < 1500; t++) {
+        // Small caps in ~30% of trials exercise both FrameOverflowError kinds with
+        // identical byte accounting; generous caps exercise the happy path.
+        const caps = rnd() < 0.3
+            ? { maxLineBytes: randInt(50, 1500), maxTotalBytes: randInt(100, 4000) }
+            : { maxLineBytes: 1 << 20, maxTotalBytes: 1 << 21 };
+        const pieces = [];
+        for (let i = 0, n = randInt(1, 12); i < n; i++) {
+            const kind = rnd();
+            if (kind < 0.55)
+                pieces.push(JSON.stringify({ type: 'x', t: randText(randInt(0, 2000)) }) + '\n');
+            else if (kind < 0.7)
+                pieces.push('\n'); // blank-line skip
+            else if (kind < 0.8)
+                pieces.push('   \n'); // whitespace-only skip
+            else if (kind < 0.9)
+                pieces.push('{not json' + randText(randInt(0, 50)) + '\n'); // malformed drop
+            else
+                pieces.push(randText(randInt(0, 300))); // trailing partial, no newline
+        }
+        const stream = Buffer.from(pieces.join(''));
+        // Byte-level cut points — these can and do split multibyte chars.
+        const cuts = Array.from({ length: randInt(0, 20) }, () => randInt(0, stream.length)).sort((a, b) => a - b);
+        const expected = run(new ReferenceFrameDecoder(caps), stream, cuts);
+        const actual = run(new FrameDecoder(caps), stream, cuts);
+        assert.deepEqual(actual, expected, `trial ${t}: caps=${JSON.stringify(caps)} cuts=${JSON.stringify(cuts)} stream=${JSON.stringify(stream.toString('utf8').slice(0, 300))}`);
+    }
+});
+test('FrameDecoder — mixed string/Buffer pushes stay equivalent', () => {
+    for (let t = 0; t < 300; t++) {
+        const caps = { maxLineBytes: 1 << 20, maxTotalBytes: 1 << 21 };
+        const ref = new ReferenceFrameDecoder(caps);
+        const dec = new FrameDecoder(caps);
+        const refF = [];
+        const decF = [];
+        for (let i = 0, n = randInt(1, 10); i < n; i++) {
+            const s = rnd() < 0.5 ? JSON.stringify({ i, t: randText(randInt(0, 200)) }) + '\n' : randText(randInt(0, 100));
+            const input = rnd() < 0.5 ? s : Buffer.from(s);
+            refF.push(...ref.push(input));
+            decF.push(...dec.push(input));
+        }
+        assert.deepEqual(decF, refF, `mixed trial ${t}`);
+    }
+});
+test('FrameDecoder — a frame exactly AT each cap passes; one byte over throws (cap accounting exact)', () => {
+    // line cap: an unterminated partial exactly at maxLineBytes is fine…
+    {
+        const caps = { maxLineBytes: 100, maxTotalBytes: 1000 };
+        const dec = new FrameDecoder(caps);
+        assert.deepEqual(dec.push('x'.repeat(100)), []);
+        // …and the 101st byte trips it, reporting the full buffered size.
+        assert.throws(() => dec.push('x'), (e) => e instanceof FrameOverflowError && e.kind === 'line' && e.bytes === 101 && e.cap === 100);
+    }
+    // total cap: carry + chunk exactly at maxTotalBytes is fine; one over throws.
+    {
+        const caps = { maxLineBytes: 1000, maxTotalBytes: 100 };
+        const dec = new FrameDecoder(caps);
+        assert.deepEqual(dec.push('x'.repeat(60)), []);
+        assert.deepEqual(dec.push('x'.repeat(40 - 60 > 0 ? 0 : 40)), []); // 60 + 40 = 100, at cap
+        assert.throws(() => dec.push('x'), (e) => e instanceof FrameOverflowError && e.kind === 'total' && e.bytes === 101 && e.cap === 100);
+    }
+    // multibyte accounting: bytes, not chars (é = 2 bytes).
+    {
+        const caps = { maxLineBytes: 10, maxTotalBytes: 1000 };
+        const dec = new FrameDecoder(caps);
+        assert.throws(() => dec.push('é'.repeat(6)), // 12 bytes > 10, only 6 chars
+        (e) => e instanceof FrameOverflowError && e.kind === 'line' && e.bytes === 12);
+    }
+});
+test('FrameDecoder — large-frame decode is linear, not quadratic (the observed attach-lag regression)', () => {
+    // Decode a single N-MiB frame in 64 KiB chunks; compare per-MiB cost at 2 MiB
+    // vs 8 MiB. Quadratic shape ⇒ per-MiB cost grows ~4× per 4× size (measured
+    // 5.5×+ pre-fix); linear stays ~flat. Threshold 3× is far above linear noise
+    // and far below the quadratic signature, so this fails ONLY on a complexity
+    // regression, not on a slow CI box.
+    const CHUNK = 64 * 1024;
+    const decodeMs = (mib) => {
+        const overhead = Buffer.byteLength('{"type":"welcome","blob":""}\n');
+        const frame = Buffer.from(`{"type":"welcome","blob":"${'x'.repeat(mib * 1024 * 1024 - overhead)}"}\n`);
+        let best = Infinity;
+        for (let rep = 0; rep < 3; rep++) {
+            const dec = new FrameDecoder(CLIENT_READ_CAPS);
+            const t0 = performance.now();
+            let n = 0;
+            for (let off = 0; off < frame.length; off += CHUNK) {
+                n += dec.push(frame.subarray(off, Math.min(off + CHUNK, frame.length))).length;
+            }
+            const ms = performance.now() - t0;
+            assert.equal(n, 1, 'decoded exactly one frame');
+            if (ms < best)
+                best = ms;
+        }
+        return best;
+    };
+    decodeMs(1); // warmup
+    const perMibSmall = decodeMs(2) / 2;
+    const perMibLarge = decodeMs(8) / 8;
+    assert.ok(perMibLarge < perMibSmall * 3, `per-MiB decode cost grew superlinearly: ${perMibSmall.toFixed(2)}ms/MiB @2MiB → ${perMibLarge.toFixed(2)}ms/MiB @8MiB (quadratic regression)`);
+});

package/dist/core/__tests__/helpers/harness.d.ts

@@ -43,6 +43,8 @@ export interface Harness {
     spawnRoot(task: string, o?: SpawnOpts): string;
     spawnChild(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
     cli(nodeId: string | null, args: string[]): CliResult;
+    spawnHeadlessChild(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
+    spawnHeadlessChildNoBoot(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
     turn(nodeId: string, text?: string): Promise<void>;
     stop(nodeId: string, reason?: 'stop' | 'length' | 'aborted' | 'error'): Promise<void>;
     finish(nodeId: string, finalText: string): Promise<void>;
@@ -65,6 +67,13 @@ export interface Harness {
     paneAlive(nodeId: string): boolean;
     inbox(nodeId: string): InboxEntry[];
     injected(nodeId: string): Injected[];
+    fakeCmd(nodeId: string, cmd: Record<string, unknown>): void;
+    dialogResults(nodeId: string): {
+        resolved: unknown;
+        ms: number;
+    }[];
+    brokerSock(nodeId: string): string;
+    bootCount(nodeId: string): number;
     subscribers(nodeId: string): {
         node_id: string;
         active: boolean;

package/dist/core/__tests__/helpers/harness.js

@@ -36,6 +36,11 @@ const HERE = dirname(fileURLToPath(import.meta.url)); // src/core/__tests__/help
 const CROUTER = join(HERE, '..', '..', '..', '..'); // package root
 const CLI_SRC = join(CROUTER, 'src', 'cli.ts');
 const FAKE_PI_HOST = join(HERE, '..', 'fixtures', 'fake-pi-host.ts');
+// The in-process fake BrokerEngine (the SDK analog of the fake-pi vehicle). The
+// REAL broker loads it via the CRTR_BROKER_ENGINE seam (broker-sdk.ts). Point at
+// the absolute `.ts` path — the broker runs under tsx (see NODE_OPTIONS below),
+// which resolves it.
+const FAKE_ENGINE = join(HERE, '..', 'fixtures', 'fake-engine.ts');
 const TSX_ESM = createRequire(import.meta.url).resolve('tsx/esm');
 // A multi-word launcher, baked verbatim ahead of the (shell-quoted) argv by the
 // seam. Absolute paths so it works regardless of the spawned window's cwd.
@@ -53,6 +58,7 @@ const CANVAS_ENV_KEYS = [
     'CRTR_NODE_ID',
     'CRTR_HOME',
     'CRTR_ROOT_SESSION',
+    'CRTR_SUBTREE',
     'CRTR_NODE_SESSION',
     'CRTR_PARENT_NODE_ID',
     'CRTR_FRONT_DOOR',
@@ -61,6 +67,10 @@ const CANVAS_ENV_KEYS = [
     'CRTR_LIFECYCLE',
     'CRTR_NODE_CWD',
     'CRTR_PI_BINARY',
+    // Scrubbed then re-added (controlled) in childEnv, mirroring CRTR_PI_BINARY —
+    // so the headless-broker seam can't leak the REAL engine into the isolated
+    // test, and the CLI subprocess that spawns a broker carries the FAKE one.
+    'CRTR_BROKER_ENGINE',
     'TMUX',
     'TMUX_PANE',
 ];
@@ -99,7 +109,18 @@ export async function createHarness(opts = {}) {
     const origHome = process.env['CRTR_HOME'];
     const origPiBinary = process.env['CRTR_PI_BINARY'];
     const origNodeSession = process.env['CRTR_NODE_SESSION'];
-    const home = mkdtempSync(join(tmpdir(), 'crtr-harness-home-'));
+    const origNodeOptions = process.env['NODE_OPTIONS'];
+    const origBrokerEngine = process.env['CRTR_BROKER_ENGINE'];
+    // The headless broker binds a unix socket at <home>/nodes/<id>/view.sock. A
+    // unix socket path (sun_path) has a ~104-char OS limit, and macOS's per-user
+    // $TMPDIR (/var/folders/<…>/T/, ~49 chars) alone pushes that path past the
+    // limit — server.listen() then fails EINVAL and the broker's loop drains
+    // (boots, never serves). NOT a production concern (~/.crouter/canvas/… is
+    // short); a test-only artifact of the long temp base. Use a SHORT base + short
+    // prefix for the canvas home so broker sockets fit. tmpHome (HOME) hosts no
+    // socket, so it can stay on the standard temp base.
+    const shortTmpBase = existsSync('/tmp') ? '/tmp' : tmpdir();
+    const home = mkdtempSync(join(shortTmpBase, 'crh-'));
     const tmpHome = mkdtempSync(join(tmpdir(), 'crtr-harness-HOME-'));
     const session = `${opts.sessionPrefix ?? 'crtr-harness'}-${process.pid}-${Date.now().toString(36)}`;
     // The harness reads/writes the isolated canvas in-process. CRTR_PI_BINARY in
@@ -108,7 +129,32 @@ export async function createHarness(opts = {}) {
     process.env['CRTR_HOME'] = home;
     process.env['CRTR_PI_BINARY'] = FAKE_PI_BINARY;
     delete process.env['CRTR_NODE_SESSION'];
+    // The headless broker (host.ts) launches `node <broker-cli.js> <id>` with a
+    // plain `process.execPath` (no tsx) and resolveBrokerEntry returns a `.js`
+    // path that, under the src test tree, only exists as `.ts`. Putting
+    // `--import <tsx/esm>` in the broker's NODE_OPTIONS makes the spawned broker
+    // run under tsx (resolving broker-cli.js→.ts AND the `.ts` fake engine). We set
+    // it on OUR process.env so it propagates to BOTH broker-launch callers: the
+    // in-process daemon revive (headlessBrokerHost.launch spreads {...process.env})
+    // and the initial `node new --headless` CLI subprocess (cleanBaseEnv copies it,
+    // since NODE_OPTIONS is deliberately NOT in CANVAS_ENV_KEYS). NODE_OPTIONS is
+    // read at process START, so setting it on the already-running harness does NOT
+    // re-trigger tsx here — it only propagates to spawned children (verified).
+    process.env['NODE_OPTIONS'] = [process.env['NODE_OPTIONS'], `--import ${TSX_ESM}`]
+        .filter((s) => s !== undefined && s !== '')
+        .join(' ');
+    process.env['CRTR_BROKER_ENGINE'] = FAKE_ENGINE;
     closeDb();
+    // Neutralize ensureDaemon (spawn.ts calls it on every `node new`): write a
+    // fake-live-daemon pidfile pointing at OUR (always-alive) pid, so
+    // isDaemonRunning() is true and no REAL crtrd is spawned against the isolated
+    // home. Required now that the broker's NODE_OPTIONS=--import tsx propagates to
+    // the crtrd spawn (pre-broker, the tsx-less `node crtrd-cli.js` spawn silently
+    // failed, so no daemon ever started); a stray real daemon would race the
+    // in-process superviseTick + the fixed-clock crash/grace scenarios. The harness
+    // drives the daemon pass itself via `tick()`. (fakeLiveDaemon pattern,
+    // home-session.test.ts.) home/ is rmSync'd in dispose.
+    writeFileSync(join(home, 'crtrd.pid'), String(process.pid), 'utf8');
     // Pre-create the isolated session on the DEFAULT server so teardown always
     // has a target and `node new`'s ensureSession no-ops.
     // ISOLATION ASSUMPTION (see header + MINOR-6): isolation is by SESSION NAME on
@@ -136,6 +182,7 @@ export async function createHarness(opts = {}) {
         e['HOME'] = tmpHome;
         e['CRTR_NODE_SESSION'] = session;
         e['CRTR_PI_BINARY'] = FAKE_PI_BINARY;
+        e['CRTR_BROKER_ENGINE'] = FAKE_ENGINE;
         if (nodeId !== null)
             e['CRTR_NODE_ID'] = nodeId;
         return e;
@@ -258,6 +305,42 @@ export async function createHarness(opts = {}) {
             await harness.awaitBoot(childId);
             return childId;
         },
+        async spawnHeadlessChild(parentId, task, o = {}) {
+            const before = new Set(nodeDirs());
+            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER, '--headless'];
+            if (o.kind)
+                args.push('--kind', o.kind);
+            if (o.mode)
+                args.push('--mode', o.mode);
+            const res = cli(parentId, args);
+            if (res.code !== 0) {
+                throw new Error(`spawnHeadlessChild(${parentId}) failed (code ${res.code})\n--stdout--\n${res.stdout}\n--stderr--\n${res.stderr}`);
+            }
+            const added = nodeDirs().filter((d) => !before.has(d));
+            if (added.length !== 1) {
+                throw new Error(`spawnHeadlessChild: expected exactly 1 new node dir, got [${added.join(', ')}]`);
+            }
+            const childId = added[0];
+            await harness.awaitBoot(childId);
+            return childId;
+        },
+        async spawnHeadlessChildNoBoot(parentId, task, o = {}) {
+            const before = new Set(nodeDirs());
+            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER, '--headless'];
+            if (o.kind)
+                args.push('--kind', o.kind);
+            if (o.mode)
+                args.push('--mode', o.mode);
+            const res = cli(parentId, args);
+            if (res.code !== 0) {
+                throw new Error(`spawnHeadlessChildNoBoot(${parentId}) failed (code ${res.code})\n--stdout--\n${res.stdout}\n--stderr--\n${res.stderr}`);
+            }
+            const added = nodeDirs().filter((d) => !before.has(d));
+            if (added.length !== 1) {
+                throw new Error(`spawnHeadlessChildNoBoot: expected exactly 1 new node dir, got [${added.join(', ')}]`);
+            }
+            return added[0];
+        },
         cli,
         async turn(nodeId, text = '') {
             const base = eventCount(nodeId, 'agent_end');
@@ -367,6 +450,25 @@ export async function createHarness(opts = {}) {
             return readInboxSince(nodeId);
         },
         injected,
+        fakeCmd(nodeId, cmd) {
+            sendCmd(nodeId, cmd);
+        },
+        dialogResults(nodeId) {
+            return readLines(join(nodeDir(nodeId), 'fake-pi.dialog.jsonl'))
+                .map((l) => {
+                try {
+                    return JSON.parse(l);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((x) => x !== null);
+        },
+        brokerSock(nodeId) {
+            return join(nodeDir(nodeId), 'view.sock');
+        },
+        bootCount,
         subscribers(nodeId) {
             closeDb();
             return subscribersOf(nodeId).map((s) => ({ node_id: s.node_id, active: s.active }));
@@ -400,6 +502,14 @@ export async function createHarness(opts = {}) {
                 delete process.env['CRTR_NODE_SESSION'];
             else
                 process.env['CRTR_NODE_SESSION'] = origNodeSession;
+            if (origNodeOptions === undefined)
+                delete process.env['NODE_OPTIONS'];
+            else
+                process.env['NODE_OPTIONS'] = origNodeOptions;
+            if (origBrokerEngine === undefined)
+                delete process.env['CRTR_BROKER_ENGINE'];
+            else
+                process.env['CRTR_BROKER_ENGINE'] = origBrokerEngine;
         },
     };
     return harness;

package/dist/core/__tests__/home-session.test.js

@@ -7,7 +7,7 @@
 //   - home_session round-trips through meta.json (it IS durable identity)
 //   - the birth-session decision (`resolveBirthSession`) for the child /
 //     inline-root / --root cases each site sets home_session from
-//   - demote-recycle + relaunch (pane-recycle) births populate home_session
+//   - recycle + relaunch (pane-recycle) births populate home_session
 //   - a legacy meta with NO home_session defaults to tmux_session ?? nodeSession()
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
@@ -17,10 +17,10 @@ import { join } from 'node:path';
 import { createNode, getNode, updateNode } from '../canvas/canvas.js';
 import { nodeMetaPath } from '../canvas/paths.js';
 import { closeDb } from '../canvas/db.js';
-import { resolveBirthSession, homeSessionOf } from '../runtime/nodes.js';
+import { resolveBirthSession, homeSessionOf, childBackstageOf } from '../runtime/nodes.js';
 import { nodeSession } from '../runtime/nodes.js';
 import { relaunchRoot } from '../runtime/reset.js';
-import { demoteNode } from '../runtime/demote.js';
+import { recycleNode } from '../runtime/recycle.js';
 let home;
 function node(id, over = {}) {
     return {
@@ -35,7 +35,7 @@ function node(id, over = {}) {
         ...over,
     };
 }
-/** Make ensureDaemon (called by demoteNode) a no-op by faking a live daemon
+/** Make ensureDaemon (called by recycleNode) a no-op by faking a live daemon
  *  pidfile pointing at THIS test process — so no real daemon is ever spawned. */
 function fakeLiveDaemon() {
     writeFileSync(join(home, 'crtrd.pid'), String(process.pid), 'utf8');
@@ -106,6 +106,39 @@ test('homeSessionOf: unknown node falls back to the backstage', () => {
     assert.equal(homeSessionOf('ghost'), nodeSession());
 });
 // ---------------------------------------------------------------------------
+// childBackstageOf — the session a node's CHILDREN spawn into (their
+// CRTR_ROOT_SESSION). REGRESSION for the front-door-root subtree-exile bug:
+// a refreshed inline root (home_session = a USER session it adopted) was
+// sourcing children's CRTR_ROOT_SESSION from home_session, so every yield
+// re-pointed its entire subtree into the user's working session. A root's
+// children must always flow to the shared backstage `nodeSession()`, never the
+// user session, while a managed child's children inherit its backstage
+// home_session. (Bug: node mq2u219p spawned all 13 children into `cli`.)
+// ---------------------------------------------------------------------------
+test('childBackstageOf: a managed child uses its backstage home_session', () => {
+    // A child's home_session is ALWAYS the backstage it was born into; its live
+    // tmux_session may be a user session (focus taint) but must NOT leak to kids.
+    createNode(node('child', { parent: 'p', home_session: 'crtr', tmux_session: 'user-sess' }));
+    assert.equal(childBackstageOf('child'), 'crtr', 'children inherit the backstage, not the tainted LOCATION');
+});
+test('childBackstageOf: a front-door ROOT routes children to the backstage, NOT its adopted user session', () => {
+    // The bug: an inline root adopts the user's session as home_session ('cli').
+    // Sourcing children's CRTR_ROOT_SESSION from home_session exiled the whole
+    // subtree into 'cli' on every refresh-yield. A root (parent === null) must
+    // route children to nodeSession() instead.
+    createNode(node('root', { parent: null, home_session: 'cli', tmux_session: 'cli' }));
+    assert.equal(childBackstageOf('root'), nodeSession(), "a root's children flow to the backstage");
+    assert.notEqual(childBackstageOf('root'), 'cli', 'NEVER the user session the root pane adopted');
+});
+test('childBackstageOf: a root honors CRTR_NODE_SESSION for the backstage', () => {
+    process.env['CRTR_NODE_SESSION'] = 'my-backstage';
+    createNode(node('root', { parent: null, home_session: 'cli' }));
+    assert.equal(childBackstageOf('root'), 'my-backstage', 'the backstage default is env-overridable');
+});
+test('childBackstageOf: unknown node falls back to the backstage', () => {
+    assert.equal(childBackstageOf('ghost'), nodeSession());
+});
+// ---------------------------------------------------------------------------
 // The birth-session decision each site sets home_session from. Pure, so the
 // child / inline-root / --root births are testable without a live tmux (the
 // real spawnChild/bootRoot are tmux + pi + process.exit coupled).
@@ -130,7 +163,7 @@ test('birth: the inline front door (bootRoot) homes to its adopted session', ()
 });
 // ---------------------------------------------------------------------------
 // Pane-recycle births populate home_session. relaunchRoot (option C) is fully
-// unit-testable (injected respawn, no tmux); demoteNode runs to completion with
+// unit-testable (injected respawn, no tmux); recycleNode runs to completion with
 // no tmux (respawn dispatch just fails) once the daemon spawn is neutralized.
 // ---------------------------------------------------------------------------
 test('relaunch birth: the fresh root homes to the recycled pane session', () => {
@@ -141,13 +174,13 @@ test('relaunch birth: the fresh root homes to the recycled pane session', () =>
     assert.ok(res !== null, 'relaunchRoot minted a fresh root');
     assert.equal(getNode(res.newNodeId)?.home_session, 'crtr', 'fresh root homes to the recycled pane session');
 });
-test('demote birth: the recycled root populates home_session (backstage when no pane location)', async () => {
+test('recycle birth: the recycled root populates home_session (backstage when no pane location)', async () => {
     createNode(node('M', { parent: null, lifecycle: 'resident', tmux_session: 'crtr', window: '@3' }));
     fakeLiveDaemon(); // createNode ensured the home dir; now neutralize ensureDaemon
     // No live tmux → paneLocation('%0') is null → home_session defaults to the
     // backstage. The respawn dispatch fails (no tmux), but the fresh root is still
     // born — and must carry a populated home_session.
-    const res = await demoteNode('M', '%0');
-    assert.ok(res.newRoot !== null, 'demote minted a fresh root');
+    const res = await recycleNode('M', '%0');
+    assert.ok(res.newRoot !== null, 'recycle minted a fresh root');
     assert.equal(getNode(res.newRoot)?.home_session, nodeSession(), 'recycled root homes to the backstage');
 });

package/dist/core/__tests__/human-new-window-regression.test.d.ts

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

package/dist/core/__tests__/human-new-window-regression.test.js

@@ -0,0 +1,101 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-new-window-regression.test.ts
+//
+// BUG REGRESSION: `crtr human ask|approve|review|notify` opened NO pane at all.
+//
+// spawnAndDetach's 'new-window' placement passed a tmux PANE id straight to
+// `new-window -t` (`new-window -d -a -t %<pane>`). tmux REJECTS a pane id for
+// new-window — it exits 1 with "can't specify pane here"; only `split-window -t`
+// accepts a pane. So once a node's watched window held >= max_panes_per_window
+// panes, pickPlacement (shared.ts) chose 'new-window', spawnAndDetach FAILED,
+// spawnHumanJob returned {spawned:false}, and the humanloop TUI never appeared.
+// Deterministic for any user whose watched window is already at the pane cap.
+//
+// Regression from 829c1a1 ("land prompts in the watched node's session"), which
+// began routing the TUI to the watched node's pane id but never converted it to
+// the session:window form new-window needs.
+//
+// THE FIX: spawnAndDetach resolves the target pane to its session:window
+// (`paneWindowTarget`) before `new-window -t`. This drives the REAL production
+// spawnAndDetach against a REAL but isolated tmux session — no mocks — mirroring
+// dead-pane-regression.test.ts.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { hasTmux } from './helpers/harness.js';
+import { spawnAndDetach } from '../spawn.js';
+const SKIP = !hasTmux();
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return { code: r.status ?? -1, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+}
+/** window id of a pane (across the server). '' on error. */
+function windowOfPane(pane) {
+    return tmux(['display-message', '-p', '-t', pane, '#{window_id}']).out;
+}
+/** Every pane in the session, across all its windows. */
+function sessionPanes(session) {
+    const r = tmux(['list-panes', '-s', '-t', session, '-F', '#{pane_id}']);
+    if (r.code !== 0)
+        return [];
+    return r.out.split('\n').filter((l) => l.trim() !== '');
+}
+test('human-new-window regression: spawnAndDetach new-window into a watched-pane SPAWNS (no longer "can\'t specify pane here")', { skip: SKIP ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
+    const session = `crtr-newwin-${process.pid}-${Date.now().toString(36)}`;
+    const origTmux = process.env['TMUX'];
+    let tmuxOverridden = false;
+    try {
+        // --- isolated session on whatever server the current env targets -------
+        const created = tmux(['new-session', '-d', '-s', session, '-c', process.cwd(), 'sleep 100000']);
+        assert.equal(created.code, 0, `create isolated session failed: ${created.err}`);
+        const info = tmux([
+            'display-message', '-p', '-t', `${session}:`,
+            '#{pane_id}\t#{window_id}\t#{socket_path}',
+        ]);
+        assert.equal(info.code, 0, `display-message failed: ${info.err}`);
+        const [basePane, baseWindow, socketPath] = info.out.split('\t');
+        assert.ok(basePane && baseWindow && socketPath, `parsed session info: ${info.out}`);
+        // ====================================================================
+        // CONTROL — prove the bug is REAL and the guard NON-VACUOUS: the pre-fix
+        // call shape (a PANE id straight into `new-window -t`) is REJECTED by tmux.
+        // ====================================================================
+        const ctl = tmux(['new-window', '-d', '-a', '-t', basePane, '-c', process.cwd(), 'sleep 100000']);
+        assert.notEqual(ctl.code, 0, 'CONTROL: new-window with a PANE id must FAIL (pre-fix call shape)');
+        assert.match(ctl.err, /can't specify pane here/i, `CONTROL: tmux rejects a pane id for new-window — got: ${ctl.err}`);
+        // spawnAndDetach gates on isInTmux() (Boolean(process.env.TMUX)) and shells
+        // `tmux` with no -L, so point TMUX at THIS session's socket — both our
+        // helpers and spawnAndDetach then drive the same server holding `session`.
+        process.env['TMUX'] = `${socketPath},0,0`;
+        tmuxOverridden = true;
+        // ====================================================================
+        // MAIN — the REAL production spawnAndDetach, 'new-window' placement,
+        // pinned to the watched PANE (exactly what detachHumanTui passes when
+        // pickPlacement returns 'new-window').
+        // ====================================================================
+        const res = spawnAndDetach({
+            command: 'sleep 100000', // long-lived stand-in for `crtr human _run`
+            cwd: process.cwd(),
+            placement: 'new-window',
+            detached: true, // don't switch the client (matches detachHumanTui)
+            killAfterSeconds: 0, // no self-kill of the originating pane
+            targetPane: basePane, // a PANE id — the exact value that used to break new-window
+        });
+        // (a) THE FIX: it SPAWNS (pre-fix this was 'spawn-failed' / no pane).
+        assert.equal(res.status, 'spawned', `spawnAndDetach should spawn a pane: ${res.message}`);
+        const pane = res.paneId;
+        assert.ok(pane && pane.startsWith('%'), `spawnAndDetach returned a %pane id: ${pane}`);
+        // (b) it landed in the SAME session as the watched pane (not stranded /
+        //     leaked into the global current session), in a NEW window.
+        assert.ok(sessionPanes(session).includes(pane), 'spawned pane lives in the watched pane\'s session');
+        assert.notEqual(windowOfPane(pane), baseWindow, 'spawned pane is in a NEW window (new-window placement), not the watched pane\'s window');
+    }
+    finally {
+        tmux(['kill-session', '-t', session]);
+        if (tmuxOverridden) {
+            if (origTmux === undefined)
+                delete process.env['TMUX'];
+            else
+                process.env['TMUX'] = origTmux;
+        }
+        assert.equal(spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0, false, 'isolated session killed — no stray');
+    }
+});