@crouton-kit/crouter 0.3.14 → 0.3.15

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

@@ -0,0 +1,73 @@
+// spawnNode: provenance (spawned_by) is decoupled from the spine (parent +
+// subscription). A managed child gets both; an independent root gets provenance
+// only — no subscription wires back to the spawner.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+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';
+let home;
+function spawner(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        status: 'active',
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-spawn-root-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+test('managed child: parent on the spine + active subscription + provenance', () => {
+    createNode(spawner('A'));
+    const child = spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'A' });
+    const meta = getNode(child.node_id);
+    assert.equal(meta.parent, 'A', 'child keeps its spine parent');
+    assert.equal(meta.spawned_by, 'A', 'child provenance defaults to its parent');
+    assert.equal(meta.lifecycle, 'terminal', 'a plain child is terminal');
+    const subs = subscribersOf(child.node_id);
+    assert.equal(subs.length, 1, 'exactly one subscriber (the parent)');
+    assert.equal(subs[0].node_id, 'A');
+    assert.equal(subs[0].active, true, 'parent subscription is active');
+});
+test('independent root: provenance only, no parent, no subscription', () => {
+    createNode(spawner('A'));
+    const root = spawnNode({
+        kind: 'developer',
+        cwd: '/tmp/work',
+        parent: null,
+        spawnedBy: 'A',
+        lifecycle: 'resident',
+    });
+    const meta = getNode(root.node_id);
+    assert.equal(meta.parent, null, 'a root has no spine parent (top-level)');
+    assert.equal(meta.spawned_by, 'A', 'a root still records who spawned it');
+    assert.equal(meta.lifecycle, 'resident', 'a root is resident');
+    assert.equal(subscribersOf(root.node_id).length, 0, 'nobody is subscribed to an independent root — the spawner is not woken by it');
+});
+test('unknown parent: spawnNode throws and mints NO node dir / row (validate before create)', () => {
+    // Pre-allocate the would-be id so we can prove nothing was scaffolded for it.
+    const orphanId = 'orphan-under-ghost';
+    assert.throws(() => spawnNode({ kind: 'developer', cwd: '/tmp/work', parent: 'ghost', nodeId: orphanId }), /cannot spawn under unknown parent node: ghost/);
+    // No half-born orphan: no meta (getNode null), no db row, no node dir on disk.
+    assert.equal(getNode(orphanId), null, 'no meta.json written for the orphan');
+    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');
+});

package/dist/core/__tests__/steer-note.test.d.ts

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

package/dist/core/__tests__/steer-note.test.js

@@ -0,0 +1,39 @@
+// Run: node --import tsx/esm --test src/core/__tests__/steer-note.test.ts
+//
+// Context-size steering text (canvas-stophook `steerNote`) is keyed on MODE
+// first, then LIFECYCLE — NOT on lifecycle alone. The key regression this
+// guards: a TERMINAL/ORCHESTRATOR must get roadmap-checkpoint-and-yield
+// guidance (it has a roadmap), never the worker "push final" text.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { steerNote } from '../../pi-extensions/canvas-stophook.js';
+test('an orchestrator (terminal) is steered to checkpoint roadmap + yield, never push final', () => {
+    const msg = steerNote(150_000, 'terminal', 'orchestrator');
+    assert.match(msg, /roadmap\.md/, 'points at the roadmap to checkpoint');
+    assert.match(msg, /node yield/, 'steers it to yield');
+    assert.doesNotMatch(msg, /push final/, 'an orchestrator never finishes with push final');
+});
+test('an orchestrator (resident) gets the same roadmap/yield steering as a terminal orchestrator', () => {
+    const t = steerNote(150_000, 'terminal', 'orchestrator');
+    const r = steerNote(150_000, 'resident', 'orchestrator');
+    assert.equal(r, t, 'mode drives the message, not lifecycle');
+});
+test('a terminal BASE worker is steered to promote / push final', () => {
+    const msg = steerNote(170_000, 'terminal', 'base');
+    assert.match(msg, /node promote/, 'a base worker is told it can promote');
+    assert.match(msg, /push final/, 'and to finish with push final when nearly done');
+    assert.doesNotMatch(msg, /roadmap\.md/, 'a base worker has no roadmap to checkpoint');
+});
+test('a resident BASE root is steered to promote-or-wrap-up, never at a roadmap', () => {
+    const msg = steerNote(150_000, 'resident', 'base');
+    assert.match(msg, /node promote/, 'a root growing into a job is told to promote');
+    assert.doesNotMatch(msg, /roadmap\.md/, 'a root has no roadmap to point at');
+    assert.doesNotMatch(msg, /push final/, 'a resident node never finishes with push final');
+});
+test('below the first band there is no nudge boundary issue — pushy escalation kicks in at 185k', () => {
+    // Sanity: the orchestrator branch escalates (pushy) at/after 185k.
+    const firm = steerNote(150_000, 'terminal', 'orchestrator');
+    const pushy = steerNote(185_000, 'terminal', 'orchestrator');
+    assert.notEqual(firm, pushy, 'the 185k band reads differently from the 150k band');
+    assert.match(pushy, /overflow/i, 'the pushy band warns about overflow');
+});

package/dist/core/__tests__/stop-guard.test.d.ts

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

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

@@ -0,0 +1,82 @@
+// Run: node --import tsx/esm --test src/core/__tests__/stop-guard.test.ts
+//
+// The stop-guard keys "is this stop legitimate?" on the LIFECYCLE value, not on
+// parent/mode: a resident node is interactable and never forced to submit a
+// final, so it may go dormant regardless of whether it has a parent.
+import { test, before, after, beforeEach } 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, subscribe, setStatus } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { evaluateStop } from '../runtime/stop-guard.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+const noSignals = { pushedFinal: false, askedHuman: false };
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-stopguard-'));
+    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('a RESIDENT node is allowed to go dormant — even WITH a parent (keyed on lifecycle, not parent)', () => {
+    createNode(node('parent', { parent: null, lifecycle: 'resident' }));
+    // A resident sub-orchestrator with a parent and NOTHING live to await: under
+    // the old parent===null rule this would have stalled; now it goes dormant.
+    createNode(node('sub', { parent: 'parent', lifecycle: 'resident', mode: 'orchestrator' }));
+    const d = evaluateStop('sub', noSignals);
+    assert.deepEqual(d, { action: 'allow', reason: 'dormant' });
+});
+test('a resident ROOT (no parent) is allowed to go dormant', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    const d = evaluateStop('root', noSignals);
+    assert.deepEqual(d, { action: 'allow', reason: 'dormant' });
+});
+test('a TERMINAL node awaiting a live worker is "awaiting" (not stalled)', () => {
+    createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
+    subscribe('mgr', 'worker', true); // active sub to a live publisher
+    const d = evaluateStop('mgr', noSignals);
+    assert.equal(d.action, 'allow');
+    assert.equal(d.reason, 'awaiting');
+});
+test('a TERMINAL node with nothing live to await and no final pushed is reprompted (stalled)', () => {
+    createNode(node('lonely', { parent: 'mgr', lifecycle: 'terminal' }));
+    const d = evaluateStop('lonely', noSignals);
+    assert.equal(d.action, 'reprompt');
+    assert.equal(d.reason, 'stalled');
+});
+test('a TERMINAL node whose only worker is dead is stalled (no LIVE subscription)', () => {
+    createNode(node('mgr', { parent: null, lifecycle: 'terminal' }));
+    createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal' }));
+    subscribe('mgr', 'worker', true);
+    setStatus('worker', 'dead'); // publisher no longer live
+    const d = evaluateStop('mgr', noSignals);
+    assert.equal(d.action, 'reprompt');
+    assert.equal(d.reason, 'stalled');
+});
+test('pushedFinal → finished; askedHuman → escalated (both short-circuit before lifecycle)', () => {
+    createNode(node('t', { parent: 'mgr', lifecycle: 'terminal' }));
+    assert.deepEqual(evaluateStop('t', { pushedFinal: true, askedHuman: false }), { action: 'allow', reason: 'finished' });
+    assert.deepEqual(evaluateStop('t', { pushedFinal: false, askedHuman: true }), { action: 'allow', reason: 'escalated' });
+});

package/dist/core/__tests__/subcommand-tier.test.js

@@ -1,53 +1,55 @@
 // Tests for the subcommand visibility tier (hidden | normal | common | important)
-// and the "[+N subcommands]" affordance.
+// and the parent-level listing affordance.
 // Run with: node --import tsx/esm --test src/core/__tests__/subcommand-tier.test.ts
 //
 // Contract:
+//  - Each child def (defineLeaf/defineBranch) owns its own description /
+//    whenToUse / tier; defineBranch assembles `help.listing` from those defs —
+//    the parent never copies a child's self-description (principle 16).
 //  - renderRoot promotes a subtree's `important` children (name + shortform
 //    desc) and `common` children (bare qualified path) into that command's
 //    block, then names how many other non-hidden subcommands stay behind
 //    `crtr <name> -h`.
 //  - `hidden` children never appear (not even in the subtree's own -h) and are
 //    not counted in any "[+N]" remainder.
-//  - renderBranch drops hidden children and flags branch children that own
-//    subcommands with "[+N subcommands]".
+//  - renderBranch renders one self-closing <subcommand> per non-hidden child
+//    and adds a `subcommands="N"` attribute when a branch child owns children.
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
 import { defineRoot, defineBranch, defineLeaf } from '../command.js';
 import { renderRoot, renderBranch } from '../help.js';
-const leaf = (name) => defineLeaf({
+const leaf = (name, opts = {}) => defineLeaf({
     name,
+    description: opts.description,
+    whenToUse: opts.whenToUse,
+    tier: opts.tier,
     help: { name, summary: name, output: [], outputKind: 'object', effects: ['None. Read-only.'] },
     run: async () => ({}),
 });
-// A nested branch so we can assert the "[+N subcommands]" depth flag.
+// A nested branch so we can assert the `subcommands="N"` depth flag. Its own
+// parent-level self-description (description/whenToUse) lives on the def, as a
+// sibling of `name`.
 const inspect = defineBranch({
     name: 'inspect',
-    help: {
-        name: 'thing inspect',
-        summary: 'inspect',
-        children: [
-            { name: 'list', desc: 'list', useWhen: 'x' },
-            { name: 'show', desc: 'show', useWhen: 'x' },
-        ],
-    },
-    children: [leaf('list'), leaf('show')],
+    description: 'inspect things',
+    whenToUse: 'x',
+    help: { name: 'thing inspect', summary: 'inspect' },
+    children: [
+        leaf('list', { description: 'list', whenToUse: 'x' }),
+        leaf('show', { description: 'show', whenToUse: 'x' }),
+    ],
 });
 const thing = defineBranch({
     name: 'thing',
     rootEntry: { concept: 'a thing', desc: 'things', useWhen: 'doing things' },
-    help: {
-        name: 'thing',
-        summary: 'do things',
-        children: [
-            { name: 'make', desc: 'make a thing', useWhen: 'x', tier: 'important' },
-            { name: 'promote', desc: 'promote a thing', useWhen: 'x', tier: 'common' },
-            { name: 'inspect', desc: 'inspect things', useWhen: 'x' },
-            { name: 'secret', desc: 'secret op', useWhen: 'x', tier: 'hidden' },
-            { name: 'plain', desc: 'plain op', useWhen: 'x' },
-        ],
-    },
-    children: [leaf('make'), leaf('promote'), inspect, leaf('secret'), leaf('plain')],
+    help: { name: 'thing', summary: 'do things' },
+    children: [
+        leaf('make', { description: 'make a thing', whenToUse: 'x', tier: 'important' }),
+        leaf('promote', { description: 'promote a thing', whenToUse: 'x', tier: 'common' }),
+        inspect,
+        leaf('secret', { description: 'secret op', whenToUse: 'x', tier: 'hidden' }),
+        leaf('plain', { description: 'plain op', whenToUse: 'x' }),
+    ],
 });
 const root = defineRoot({ tagline: 'test runtime', globals: [], subtrees: [thing] });
 describe('renderRoot: subcommand promotion', () => {
@@ -70,28 +72,28 @@ describe('renderRoot: commands with no promotions', () => {
         const bare = defineBranch({
             name: 'bare',
             rootEntry: { concept: 'bare', desc: 'bare', useWhen: 'x' },
-            help: { name: 'bare', summary: 'bare', children: [{ name: 'one', desc: 'one', useWhen: 'x' }] },
-            children: [leaf('one')],
+            help: { name: 'bare', summary: 'bare' },
+            children: [leaf('one', { description: 'one', whenToUse: 'x' })],
         });
         const r = defineRoot({ tagline: 't', globals: [], subtrees: [bare] });
         const out = renderRoot(r.help);
         assert.match(out, /\[\+1 subcommand — `crtr bare -h`\]/); // singular, no "other"
     });
 });
-describe('renderBranch: hidden filter + depth flag', () => {
+describe('renderBranch: hidden filter + depth flag (XML)', () => {
     const out = renderBranch(thing.help);
     test('hidden child is dropped from the branch listing', () => {
         assert.doesNotMatch(out, /secret/);
     });
-    test('all non-hidden children are listed', () => {
+    test('all non-hidden children are listed as <subcommand> rows', () => {
         for (const n of ['make', 'promote', 'inspect', 'plain']) {
-            assert.match(out, new RegExp(`\\n {2}${n} `));
+            assert.match(out, new RegExp(`name="${n}"`));
         }
     });
     test('a branch child flags how many subcommands it owns', () => {
-        assert.match(out, /inspect .* \[\+2 subcommands\]/);
+        assert.match(out, /name="inspect"[^>]*subcommands="2"/);
     });
     test('leaf children carry no subcommand flag', () => {
-        assert.doesNotMatch(out, /make .* \[\+\d+ subcommands\]/);
+        assert.doesNotMatch(out, /name="make"[^>]*subcommands=/);
     });
 });

package/dist/core/__tests__/tmux-surface.test.d.ts

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

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

@@ -0,0 +1,106 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/tmux-surface.test.ts
+//
+// STEP 2 of the placement/focus migration: guards on the tmux Surface (driver).
+//
+//   1. The §2.2 HARD DRIVER INVARIANT (GREEN now): every create/placement verb
+//      in the driver — new-window / split-window / swap-pane / break-pane /
+//      join-pane / move-pane / respawn-pane — MUST pass an explicit `-t` target.
+//      Omitting `-t` lets tmux resolve against its GLOBAL current session, which
+//      can leak a pane into a user session — the exact unbidden-window bug this
+//      redesign kills. This guards the bug's blast radius and should pass today.
+//
+//   2. The §5.1 "only placement.ts / tmux-chrome.ts import tmux.ts" lint guard
+//      (SKIPPED — warn only this step): placement.ts does not exist yet and many
+//      modules still import the driver directly, so this CANNOT pass until the
+//      migration completes. It flips to a hard assertion in Step 8.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, basename } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SRC_ROOT = join(__dirname, '..', '..'); // .../src
+const TMUX_TS = join(SRC_ROOT, 'core', 'runtime', 'tmux.ts');
+/** The placement verbs the §2.2 invariant governs. */
+const PLACEMENT_VERBS = [
+    'new-window',
+    'split-window',
+    'swap-pane',
+    'break-pane',
+    'join-pane',
+    'move-pane',
+    'respawn-pane',
+];
+/** The smallest `[ … ]` array literal that encloses `matchIdx`: scan back to the
+ *  nearest `[` (the array open — the verb is always its first element), then
+ *  forward with bracket-depth counting to the matching `]` (handles nested
+ *  arrays like splitWindow's `? [] : ['-h']`). Returns the array source slice. */
+function enclosingArray(src, matchIdx) {
+    let open = matchIdx;
+    while (open >= 0 && src[open] !== '[')
+        open--;
+    assert.ok(open >= 0, `no enclosing [ for the verb at index ${matchIdx}`);
+    let depth = 0;
+    for (let i = open; i < src.length; i++) {
+        if (src[i] === '[')
+            depth++;
+        else if (src[i] === ']') {
+            depth--;
+            if (depth === 0)
+                return src.slice(open, i + 1);
+        }
+    }
+    throw new Error('unbalanced [ ] while bracket-matching the verb array');
+}
+test('§2.2 driver invariant: every placement verb in tmux.ts passes an explicit -t target', () => {
+    const src = readFileSync(TMUX_TS, 'utf8');
+    // Match only the QUOTED JS string forms (`'new-window'`, …) — these are real
+    // args-array elements; the jsdoc prose mentions the verbs unquoted / in
+    // backticks, so this never trips on a comment.
+    const re = new RegExp(`'(${PLACEMENT_VERBS.join('|')})'`, 'g');
+    let found = 0;
+    for (let m = re.exec(src); m !== null; m = re.exec(src)) {
+        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 ` +
+            `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
+    // renames them can't make this assertion vacuously pass).
+    assert.ok(found >= 4, `expected to scan ≥4 placement verbs, saw ${found}`);
+});
+// ---------------------------------------------------------------------------
+// Lint guard — §5.1. WARN ONLY this step. Skipped because it cannot pass yet:
+// placement.ts (the sole sanctioned importer) does not exist, and the driver is
+// still imported directly by the runtime/daemon/command/stophook modules the
+// migration has not yet routed through placement. Step 8 deletes the skip and
+// turns the body into the enforced boundary.
+// ---------------------------------------------------------------------------
+/** Every `.ts` file under `src` (recursively), excluding nothing. */
+function allTsFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        if (statSync(p).isDirectory())
+            out.push(...allTsFiles(p));
+        else if (entry.endsWith('.ts'))
+            out.push(p);
+    }
+    return out;
+}
+/** Files (basename) sanctioned to import the driver, per §2.1. */
+const ALLOWED_IMPORTERS = new Set(['tmux.ts', 'placement.ts', 'tmux-chrome.ts']);
+function importsDriver(file) {
+    const src = readFileSync(file, 'utf8');
+    // A specifier whose basename is exactly `tmux.js` (so `tmux-chrome.js` and
+    // `tmux-spread.js` are NOT matched). Covers `from '...'` and `import('...')`.
+    return [...src.matchAll(/(?:from|import\s*\()\s*'([^']+)'/g)].some((m) => basename(m[1]) === 'tmux.js');
+}
+test('§5.1 lint: only placement.ts / tmux-chrome.ts import the tmux driver', { skip: 'WARN-ONLY in Step 2 — placement.ts does not exist yet and many modules still import tmux.ts directly. Step 8 flips this to a hard error.' }, () => {
+    const offenders = allTsFiles(SRC_ROOT)
+        .filter((f) => !ALLOWED_IMPORTERS.has(basename(f)))
+        .filter(importsDriver)
+        .map((f) => f.slice(SRC_ROOT.length + 1));
+    assert.deepEqual(offenders, [], `modules importing tmux.ts directly: ${offenders.join(', ')}`);
+});

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

@@ -10,17 +10,23 @@ import assert from 'node:assert/strict';
 import { defineRoot, defineBranch, defineLeaf, walk, unknownPathError } from '../command.js';
 const leaf = defineLeaf({
     name: 'search',
+    description: 'search',
+    whenToUse: 'x',
     help: { name: 'search', summary: 'search', output: [], outputKind: 'object', effects: ['None. Read-only.'] },
     run: async () => ({}),
 });
 const findBranch = defineBranch({
     name: 'find',
-    help: { name: 'find', summary: 'find', children: [{ name: 'search', desc: 'search', useWhen: 'x' }] },
+    description: 'find',
+    whenToUse: 'x',
+    help: { name: 'find', summary: 'find' },
     children: [leaf],
 });
 const skillBranch = defineBranch({
     name: 'skill',
-    help: { name: 'skill', summary: 'skill', children: [{ name: 'find', desc: 'find', useWhen: 'x' }] },
+    description: 'skill',
+    whenToUse: 'x',
+    help: { name: 'skill', summary: 'skill' },
     rootEntry: { concept: 'skill', desc: 'skill', useWhen: 'x' },
     children: [findBranch],
 });

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

@@ -17,6 +17,16 @@ export declare function countAsks(nodeId: string): number;
  * Returns only entries with count > 0.
  */
 export declare function pendingAsksForView(rootId: string): AskEntry[];
+/**
+ * Per-node pending ask counts for an explicit set of node ids — the batched
+ * counterpart to `countAsks`, used by the nav chrome to label every visible
+ * node in ONE pass. Groups ids by their cwd so each distinct interactions dir
+ * is scanned exactly once, then buckets the decks by the `source.nodeId` stamp
+ * (same attribution as `countForCwd(cwd, nodeId)`). Asks with no node stamp are
+ * not attributable to any node and are excluded. Every requested id appears in
+ * the result (0 when it has none). Never throws.
+ */
+export declare function asksForNodes(ids: string[]): Record<string, number>;
 /**
  * Pending asks across the entire canvas — every distinct cwd among all known
  * nodes. Returns only entries with count > 0.

package/dist/core/canvas/attention.js

@@ -77,6 +77,46 @@ export function pendingAsksForView(rootId) {
     }
     return Array.from(seen.values()).filter((e) => e.count > 0);
 }
+/**
+ * Per-node pending ask counts for an explicit set of node ids — the batched
+ * counterpart to `countAsks`, used by the nav chrome to label every visible
+ * node in ONE pass. Groups ids by their cwd so each distinct interactions dir
+ * is scanned exactly once, then buckets the decks by the `source.nodeId` stamp
+ * (same attribution as `countForCwd(cwd, nodeId)`). Asks with no node stamp are
+ * not attributable to any node and are excluded. Every requested id appears in
+ * the result (0 when it has none). Never throws.
+ */
+export function asksForNodes(ids) {
+    const counts = {};
+    for (const id of ids)
+        counts[id] = 0;
+    // Bucket the requested ids by cwd so we scan each inbox once, not per id.
+    const idsByCwd = new Map();
+    for (const id of ids) {
+        const node = getNode(id);
+        if (node === null)
+            continue;
+        const arr = idsByCwd.get(node.cwd) ?? [];
+        arr.push(id);
+        idsByCwd.set(node.cwd, arr);
+    }
+    for (const [cwd, cwdIds] of idsByCwd) {
+        let items;
+        try {
+            items = scanInbox([interactionsRoot(cwd)]);
+        }
+        catch {
+            continue; // humanloop missing / no interactions dir — leave these at 0
+        }
+        const want = new Set(cwdIds);
+        for (const i of items) {
+            const nid = i.source?.nodeId;
+            if (nid !== undefined && want.has(nid))
+                counts[nid] = (counts[nid] ?? 0) + 1;
+        }
+    }
+    return counts;
+}
 /**
  * Pending asks across the entire canvas — every distinct cwd among all known
  * nodes. Returns only entries with count > 0.

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

@@ -1,14 +1,41 @@
-import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
-/** Create a node: scaffold its dirs, write meta.json, index the row. */
+import type { NodeMeta, NodeIdentity, NodeRow, NodeStatus, ExitIntent, SubscriptionRef } from './types.js';
+/** Create a node: scaffold its dirs, persist identity to meta.json, and seed the
+ *  row (identity + runtime from the incoming meta). Returns the hydrated view. */
 export declare function createNode(meta: NodeMeta): NodeMeta;
-/** The canonical node record (from meta.json), or null if unknown. */
+/** The canonical node record: durable identity (meta.json) ∪ authoritative
+ *  runtime (the row). Null if unknown. */
 export declare function getNode(nodeId: string): NodeMeta | null;
 /** The indexed row (from the db) — cheap for queries that don't need full meta. */
 export declare function getRow(nodeId: string): NodeRow | null;
-/** Merge a patch into a node's meta.json and re-index its row. */
-export declare function updateNode(nodeId: string, patch: Partial<NodeMeta>): NodeMeta;
-/** Convenience for the most common mutation. */
+/** The node row whose durable LOCATION pane is `pane`, or null. Lets placement
+ *  resolve "who sits in this pane" by the first-class `%pane_id` handle (e.g.
+ *  to adopt a caller's pane as a focus). pane is not UNIQUE in the schema, but a
+ *  live pane backs at most one node, so this returns the single match. */
+export declare function getRowByPane(pane: string): NodeRow | null;
+/** Merge an IDENTITY patch into a node's meta.json and re-index its identity
+ *  columns. Identity has a single writer per node, so this read-modify-write is
+ *  safe (the contended runtime fields were moved out — see the atomic setters
+ *  below). Returns the hydrated view (runtime included). */
+export declare function updateNode(nodeId: string, patch: Partial<NodeIdentity>): NodeMeta;
+/** Set a node's status. Atomic single-column write. */
 export declare function setStatus(nodeId: string, status: NodeStatus): void;
+/** Set a node's exit intent. Atomic single-column write. */
+export declare function setIntent(nodeId: string, intent: ExitIntent): void;
+/** Set a node's tmux presence in one atomic write: the durable LOCATION anchor
+ *  `pane` (the `%pane_id`) plus its derived cache (`tmux_session` + `window`).
+ *  All three move together — `pane` joins the others inside the single UPDATE so
+ *  a move never half-writes the location. `pane` is optional: a caller that does
+ *  not yet track it (every caller, until the placement layer lands) writes null,
+ *  which is harmless because nothing reads `pane` yet. */
+export declare function setPresence(nodeId: string, presence: {
+    tmux_session?: string | null;
+    window?: string | null;
+    pane?: string | null;
+}): void;
+/** Record the live pi pid (daemon liveness signal). Atomic single-column write. */
+export declare function recordPid(nodeId: string, pid: number): void;
+/** Clear the pi pid (window-backed relaunch, before the fresh pi re-records it). */
+export declare function clearPid(nodeId: string): void;
 /** All rows, optionally filtered by status. */
 export declare function listNodes(filter?: {
     status?: NodeStatus | NodeStatus[];
@@ -35,6 +62,38 @@ export declare function view(root: string): string[];
  *  If so, stopping is a legitimate await; if not, it must finish or escalate. */
 export declare function hasActiveLiveSubscription(nodeId: string): boolean;
 /** Rebuild node rows from on-disk metas (the db node table is a derived index).
+ *  Only the IDENTITY columns are rebuilt — they are a projection of meta. The
+ *  runtime columns (status/intent/pi_pid/window/tmux_session/pane) are NOT in meta
+ *  and NOT re-derivable from it: they describe live process/presence state, so
+ *  an existing row keeps them and a freshly re-created row takes the schema's
+ *  quiescent defaults (status='active', the rest null). The daemon reconciles
+ *  liveness from tmux reality, not from a stale file.
  *  Edges are left intact — subscribes_to is db-authoritative; spawned_by is
- *  re-derived from each meta's `parent`. */
+ *  re-derived from each meta's `spawned_by` (fallback: `parent` for legacy metas). */
 export declare function rebuildIndex(): void;
+/** A node selected for pruning (or that would be, under --dry-run). */
+export interface PrunedNode {
+    node_id: string;
+    status: NodeStatus;
+    created: string;
+}
+export interface PruneResult {
+    /** The nodes pruned (or, under dryRun, the nodes that WOULD be pruned). */
+    pruned: PrunedNode[];
+    dryRun: boolean;
+}
+/** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
+ *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
+ *  node rows + dirs. The edges→nodes FK (`ON DELETE CASCADE`, migration v4) GCs
+ *  each pruned node's edges automatically; the on-disk `nodes/<id>/` dir is
+ *  removed too. Live nodes are NEVER touched: active | idle are the daemon's
+ *  domain, a DISJOINT status set, so prune and supervision can't interfere.
+ *
+ *  The row deletes run in ONE transaction (so the sweep is all-or-nothing); the
+ *  dir removals follow after COMMIT — the fs isn't transactional, and by then the
+ *  rows are gone, so a re-run never re-finds a half-deleted node. `dryRun`
+ *  reports the candidate set and deletes NOTHING. */
+export declare function pruneNodes(opts: {
+    ttlDays: number;
+    dryRun?: boolean;
+}): PruneResult;