@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/commands/skill/read.js

@@ -7,6 +7,8 @@ import { readText } from '../../core/fs-utils.js';
 import { appendNeighbors } from './shared.js';
 export const readLeaf = defineLeaf({
     name: 'read',
+    description: 'load SKILL.md body + metadata for a named skill',
+    whenToUse: 'a task in front of you matches a skill that is already loaded — read it BEFORE you start improvising, not after. Reach for it the moment you are about to do something a skill covers: adopting a documented workflow that fits the task at hand, following a methodology before writing a spec or a plan, picking up the house conventions for a tool or framework, replaying a runbook for an operation you have run before. Takes the crtr skill name as a positional (a crtr identifier, never a file path — do not cat or find SKILL.md off disk) and returns the SKILL.md body plus its resolution metadata; add --no-body to just confirm a skill exists or locate it. Reach for `crtr skill find` first when you do not yet know which skill applies.',
     help: {
         name: 'skill read',
         summary: 'load SKILL.md body and resolution metadata for a named skill',

package/dist/commands/skill/state.js

@@ -19,6 +19,8 @@ async function toggleSkill(input, enabled) {
 }
 export const stateEnable = defineLeaf({
     name: 'enable',
+    description: 'enable a skill',
+    whenToUse: 're-enable a skill that was previously disabled, making it visible to list and agent discovery again in the target scope.',
     help: {
         name: 'skill state enable',
         summary: 'enable a skill in the given scope',
@@ -38,6 +40,8 @@ export const stateEnable = defineLeaf({
 });
 export const stateDisable = defineLeaf({
     name: 'disable',
+    description: 'disable a skill',
+    whenToUse: 'hide a skill from list and agent discovery without deleting it — writes a disable flag to config.json in the target scope; reverse it later with `crtr skill state enable`.',
     help: {
         name: 'skill state disable',
         summary: 'disable a skill in the given scope, hiding it from list and agent discovery',
@@ -57,13 +61,11 @@ export const stateDisable = defineLeaf({
 });
 export const stateBranch = defineBranch({
     name: 'state',
+    description: 'enable or disable skills',
+    whenToUse: 'turn a skill on or off in a scope — disable to hide it from discovery without removing it, enable to bring it back.',
     help: {
         name: 'skill state',
         summary: 'enable or disable skills',
-        children: [
-            { name: 'enable', desc: 'enable a skill', useWhen: 'making a previously disabled skill available again' },
-            { name: 'disable', desc: 'disable a skill', useWhen: 'hiding a skill from list and agent discovery without removing it' },
-        ],
     },
     children: [stateEnable, stateDisable],
 });

package/dist/commands/skill.js

@@ -21,12 +21,6 @@ export function registerSkill() {
             summary: 'discover, read, author, and manage skill state',
             model: '`find` when you do not yet know which skill applies — it locates candidates by topic, keyword, or body text. `read` (leaf) loads SKILL.md by name; takes the name as a positional, returns body + metadata, accepts --no-body to skip the body. `author` when you are writing a new skill — it carries the template workflow and the scaffolder. `state` when a skill should be hidden from discovery without being removed. Append `-h` at any branch or leaf for its full schema.',
             dynamicState: buildSkillCatalog,
-            children: [
-                { name: 'find', desc: 'list, search, or grep skills', useWhen: 'discovering what skills are available' },
-                { name: 'read', desc: 'load SKILL.md body + metadata for a named skill', useWhen: 'loading a skill to act on it' },
-                { name: 'author', desc: 'create and scaffold skills', useWhen: 'writing a new skill' },
-                { name: 'state', desc: 'enable or disable skills', useWhen: 'toggling skill visibility' },
-            ],
         },
         children: [findBranch, readLeaf, authorBranch, stateBranch],
     });

package/dist/commands/sys/config.js

@@ -11,6 +11,7 @@ const TOP_LEVEL_KEYS = new Set([
     'marketplaces',
     'plugins',
     'max_panes_per_window',
+    'canvasNav',
 ]);
 function getNestedValue(obj, key) {
     const parts = key.split('.');
@@ -59,6 +60,16 @@ function setNestedValue(cfg, key, value) {
         cfg.max_panes_per_window = Math.floor(value);
         return;
     }
+    if (topKey === 'canvasNav') {
+        // Only the scalar prefixKey is settable here; the prefixBinds/graphBinds
+        // record tables are edited directly in config.json (run `crtr sys config
+        // path` to locate it).
+        if (key === 'canvasNav.prefixKey') {
+            cfg.canvasNav.prefixKey = String(value);
+            return;
+        }
+        throw usage(`canvasNav.${parts.slice(1).join('.') || '*'} is a record table — edit config.json directly (run \`crtr sys config path\`). Only canvasNav.prefixKey is settable via this command.`);
+    }
     if (parts.length === 1) {
         cfg[topKey] = value;
         return;
@@ -75,11 +86,13 @@ function setNestedValue(cfg, key, value) {
 // ---------------------------------------------------------------------------
 const configGet = defineLeaf({
     name: 'get',
+    description: 'read a config value by key',
+    whenToUse: 'you want to read a single config value by its dotted key — the current auto_update policy, max_panes_per_window, the canvasNav prefix key — optionally from a specific scope. Use sys config set instead to change a value, sys config path to locate the file for hand-editing.',
     help: {
         name: 'sys config get',
         summary: 'read a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window.' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, canvasNav (read whole; edit canvasNav.prefixBinds/graphBinds in config.json directly).' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Scope to read from. Default: user.' },
         ],
         output: [
@@ -103,11 +116,13 @@ const configGet = defineLeaf({
 });
 const configSet = defineLeaf({
     name: 'set',
+    description: 'write a config value by key',
+    whenToUse: 'you want to change a crtr setting — flip auto_update.crtr or auto_update.content to notify, apply, or off, raise max_panes_per_window, rebind canvasNav.prefixKey — written to the user or project scope. Use sys config get instead to read a value; the canvasNav record tables are not settable here, so edit config.json directly (sys config path) for those.',
     help: {
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window.' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, canvasNav.prefixKey. The canvasNav.prefixBinds/graphBinds record tables are not settable here — edit config.json directly (`crtr sys config path`).' },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. Stored as-is if quoted; coerced to number or boolean when unambiguous.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user.' },
         ],
@@ -135,6 +150,8 @@ const configSet = defineLeaf({
 });
 const configPath = defineLeaf({
     name: 'path',
+    description: 'print path(s) to config.json',
+    whenToUse: 'you need the absolute path to config.json — typically to hand-edit settings sys config set cannot reach, like the canvasNav.prefixBinds and graphBinds record tables.',
     help: {
         name: 'sys config path',
         summary: 'print absolute path(s) to config.json',
@@ -173,14 +190,11 @@ const configPath = defineLeaf({
 });
 export const configBranch = defineBranch({
     name: 'config',
+    description: 'read and write configuration',
+    whenToUse: 'inspecting or changing crtr settings — read a value with sys config get, change one with sys config set (auto_update policy, max_panes_per_window, canvasNav.prefixKey), or locate config.json with sys config path to hand-edit the record tables set cannot reach.',
     help: {
         name: 'sys config',
         summary: 'read and write crtr configuration',
-        children: [
-            { name: 'get', desc: 'read a config value by key', useWhen: 'inspecting current configuration' },
-            { name: 'set', desc: 'write a config value by key', useWhen: 'changing a configuration setting' },
-            { name: 'path', desc: 'print path(s) to config.json', useWhen: 'locating the config file for manual inspection' },
-        ],
     },
     children: [configGet, configSet, configPath],
 });

package/dist/commands/sys/doctor.js

@@ -325,6 +325,8 @@ function runChecksForScope(scope, opts) {
 }
 export const sysDoctorLeaf = defineLeaf({
     name: 'doctor',
+    description: 'diagnose installation health',
+    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or skill frontmatter has drifted from its filename. Reports each problem with a structured remediation; pass --fix to apply the repairs.',
     help: {
         name: 'sys doctor',
         summary: 'diagnose missing manifests, broken config entries, and skill frontmatter drift',

package/dist/commands/sys/update.js

@@ -6,6 +6,8 @@ import { nowIso } from '../../core/fs-utils.js';
 import { readPackageVersion } from './shared.js';
 export const sysUpdateLeaf = defineLeaf({
     name: 'update',
+    description: 'update binary and content',
+    whenToUse: 'upgrading crtr or its installed plugins and marketplaces — pull the latest binary, refresh installed content, or both; pass --check first to see what is out of date without applying anything.',
     help: {
         name: 'sys update',
         summary: 'update the crtr binary and/or installed plugins and marketplaces',
@@ -98,6 +100,8 @@ export const sysUpdateLeaf = defineLeaf({
 });
 export const sysVersionLeaf = defineLeaf({
     name: 'version',
+    description: 'print installed version',
+    whenToUse: 'you need the installed crtr version — to report it in a bug or confirm an upgrade landed.',
     help: {
         name: 'sys version',
         summary: 'print the installed crtr version',

package/dist/commands/sys.js

@@ -15,12 +15,6 @@ export function registerSys() {
         help: {
             name: 'sys',
             summary: 'crtr system configuration, diagnostics, and self-management',
-            children: [
-                { name: 'config', desc: 'read and write configuration', useWhen: 'inspecting or changing crtr settings' },
-                { name: 'doctor', desc: 'diagnose installation health', useWhen: 'troubleshooting missing manifests or broken config' },
-                { name: 'update', desc: 'update binary and content', useWhen: 'upgrading crtr or its installed plugins/marketplaces' },
-                { name: 'version', desc: 'print installed version', useWhen: 'checking which version of crtr is installed' },
-            ],
         },
         children: [configBranch, sysDoctorLeaf, sysUpdateLeaf, sysVersionLeaf],
     });

package/dist/commands/tmux-spread.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const tmuxSpreadLeaf: LeafDef;

package/dist/commands/tmux-spread.js

@@ -0,0 +1,130 @@
+// `crtr canvas tmux-spread <id>` — expand a node + its live children into one
+// tiled tmux window: the target wide in the LEFT (main) pane, its live children
+// stacked as panes on the RIGHT, then grab focus.
+//
+// Reuses the presence/tmux machinery: revive a dormant target/child so it has a
+// live pane, `join-pane` each child's existing pane into the target's window
+// (preserving its running pi), `select-layout main-vertical`, then focus.
+//
+// CRITICAL fix-up: a joined child physically changes windows, so its
+// meta.{tmux_session,window} goes stale — `windowAlive` would then report it
+// dormant and the daemon would spuriously revive it. After each join we
+// re-derive the child's location from its (stable) pane id and updateNode it,
+// mirroring the swap fix-up in presence.ts.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { readConfig } from '../core/config.js';
+import { reviveNode } from '../core/runtime/revive.js';
+import { isNodePaneAlive, spreadNode } from '../core/runtime/placement.js';
+import { inTmux } from '../core/runtime/tmux.js';
+import { nodeInPane } from './node.js';
+import { getNode, subscriptionsOf } from '../core/canvas/index.js';
+export const tmuxSpreadLeaf = defineLeaf({
+    name: 'tmux-spread',
+    description: 'tile a node + its live children into one window and focus it',
+    whenToUse: 'tiling a node and its live children into one window — the node wide on the left, its workers stacked on the right — to watch an orchestrator and its team together (alt+c → e / GRAPH e)',
+    help: {
+        name: 'canvas tmux-spread',
+        summary: 'tile a node and its live children into one window — target wide on the left, children stacked on the right — and focus it. Revives dormant nodes first; caps children by max_panes_per_window.',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node',
+                required: false,
+                constraint: 'Node id to spread. Defaults to the node occupying --pane (or your current pane).',
+            },
+            {
+                kind: 'flag',
+                name: 'pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id to resolve the node from when no positional is given. The alt+c menu passes this for you.',
+            },
+        ],
+        output: [
+            { name: 'window', type: 'string', required: false, constraint: 'The window all panes were tiled into.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The tmux session that window lives in.' },
+            { name: 'children_joined', type: 'string[]', required: true, constraint: 'Child node ids whose panes were joined into the window.' },
+            { name: 'overflow', type: 'string[]', required: true, constraint: 'Live children left out because max_panes_per_window was reached.' },
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the window was brought forefront.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Revives the target (and joined children) if dormant — opens tmux windows running pi.',
+            'Moves each joined child\'s pane into the target window (join-pane) and re-points its canvas record to the new window.',
+            'Applies a main-vertical layout and focuses the window.',
+        ],
+    },
+    run: async (input) => {
+        if (!inTmux()) {
+            throw new InputError({
+                error: 'not_in_tmux',
+                message: 'tmux-spread needs a tmux server (no $TMUX)',
+                next: 'Run from inside the shared crtr tmux session.',
+            });
+        }
+        const pane = input['pane'];
+        let id = input['node'];
+        if (id === undefined || id === '')
+            id = nodeInPane(pane);
+        if (id === undefined || id === '') {
+            throw new InputError({
+                error: 'no_node',
+                message: 'no node to spread (pass a node id, or run from inside its pane)',
+                next: 'Pass `crtr canvas tmux-spread <id>` or --pane <pane-id>.',
+            });
+        }
+        if (getNode(id) === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no node: ${id}`,
+                next: 'List nodes with `crtr node inspect list`.',
+            });
+        }
+        // 1. Revive the target if it has no live pane (placement is pane-keyed).
+        if (!isNodePaneAlive(id)) {
+            try {
+                reviveNode(id, { resume: true });
+            }
+            catch { /* fall through */ }
+        }
+        if (!isNodePaneAlive(id)) {
+            throw new InputError({
+                error: 'no_window',
+                message: `could not open a live window for ${id}`,
+                next: 'Try `crtr canvas revive <id>` then retry.',
+            });
+        }
+        // 2. Live children, capped: the target owns one pane, so up to max-1 join.
+        const max = readConfig('user').max_panes_per_window;
+        const budget = Math.max(0, max - 1);
+        const liveChildren = subscriptionsOf(id)
+            .map((r) => r.node_id)
+            .filter((cid) => {
+            const s = getNode(cid)?.status;
+            return s === 'active' || s === 'idle';
+        });
+        const selected = liveChildren.slice(0, budget);
+        const overflow = liveChildren.slice(budget);
+        // 3. Revive any dormant selected child so it has a live pane, then hand the
+        //    join + pane-fix-up (reconcile FOLLOWS each joined pane) + layout + focus
+        //    to placement.
+        for (const cid of selected) {
+            if (!isNodePaneAlive(cid)) {
+                try {
+                    reviveNode(cid, { resume: true });
+                }
+                catch { /* skip on failure */ }
+            }
+        }
+        const spread = spreadNode(id, selected);
+        return {
+            window: spread.window,
+            session: spread.session,
+            children_joined: spread.joined,
+            overflow,
+            focused: spread.focused,
+        };
+    },
+    render: (r) => `<spread node window="${r['window'] ?? ''}" joined="${r['children_joined'].length}" overflow="${r['overflow'].length}" focused="${r['focused']}"/>`,
+});

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -11,6 +11,8 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
 import { appendInbox } from '../feed/inbox.js';
+import { createNode, setIntent } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
 // Mirror the watcher's internal cadence (TICK_MS=800, DEBOUNCE_MS=1000): allow a
 // resolve+seed tick, a read tick, and the debounce window before asserting.
 const TICK_MS = 800;
@@ -86,6 +88,29 @@ describe('canvas inbox watcher — finished-node delivery', () => {
         assert.equal(pi.injected.length, 1);
         assert.equal(pi.injected[0].deliverAs, 'followUp', 'a normal update is not urgent → followUp');
     });
+    test('refresh-yield in flight: inbox entries are HELD, then delivered once intent clears (no loss)', async () => {
+        freshNode('node-refresh');
+        closeDb(); // rebind the canvas db to this test's fresh home
+        const meta = {
+            node_id: 'node-refresh', name: 'r', created: new Date().toISOString(),
+            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
+            status: 'active', intent: 'refresh',
+        };
+        createNode(meta);
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // Streaming (mid-turn) when a child finishes — normally this would steer.
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-refresh', { from: 'child-x', tier: 'urgent', kind: 'final', label: 'done' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 0, 'entries are held while a refresh-yield is in flight (no steer-hijack)');
+        // The fresh pi clears intent on boot; the held entry must then be delivered
+        // — the cursor was never advanced, so nothing is lost.
+        setIntent('node-refresh', null);
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1, 'the held entry is delivered once the refresh clears');
+    });
     test('idle: a finished node triggers a fresh turn (no deliverAs)', async () => {
         freshNode('node-idle');
         const pi = makeFakePi();

package/dist/core/__tests__/child-followup.test.d.ts

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

package/dist/core/__tests__/child-followup.test.js

@@ -0,0 +1,83 @@
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { jobDir } from '../canvas/paths.js';
+import { readContextTokens } from '../canvas/telemetry.js';
+import { childFollowUp } from '../../commands/node.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,
+    };
+}
+/** Write a telemetry.json with a live context gauge for a node. */
+function writeTelemetry(id, over) {
+    const dir = jobDir(id);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'telemetry.json'), JSON.stringify({ tokens_in: 0, tokens_out: 0, model: 'm', updated_at: new Date().toISOString(), ...over }));
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-followup-'));
+    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'];
+});
+const STD = 'Two moves only';
+const YIELD = 'crtr node yield';
+test('readContextTokens: prefers context_tokens, falls back to tokens_in, else null', () => {
+    createNode(node('n1'));
+    writeTelemetry('n1', { context_tokens: 120_000, tokens_in: 5_000 });
+    assert.equal(readContextTokens('n1'), 120_000);
+    createNode(node('n2'));
+    writeTelemetry('n2', { tokens_in: 42_000 });
+    assert.equal(readContextTokens('n2'), 42_000);
+    createNode(node('n3'));
+    assert.equal(readContextTokens('n3'), null); // no telemetry at all
+});
+test('childFollowUp: orchestrator past 100k → yield nudge with rounded k', () => {
+    createNode(node('orch', { mode: 'orchestrator' }));
+    writeTelemetry('orch', { context_tokens: 134_500 });
+    const msg = childFollowUp('orch');
+    assert.match(msg, /crtr node yield/);
+    assert.match(msg, /~135k/); // rounded
+    assert.doesNotMatch(msg, /Two moves only/);
+});
+test('childFollowUp: orchestrator below 100k → standard road sign', () => {
+    createNode(node('orch', { mode: 'orchestrator' }));
+    writeTelemetry('orch', { context_tokens: 80_000 });
+    assert.match(childFollowUp('orch'), new RegExp(STD));
+    assert.doesNotMatch(childFollowUp('orch'), new RegExp(YIELD));
+});
+test('childFollowUp: base spawner past 100k → standard (only orchestrators yield)', () => {
+    createNode(node('base', { mode: 'base' }));
+    writeTelemetry('base', { context_tokens: 150_000 });
+    assert.match(childFollowUp('base'), new RegExp(STD));
+});
+test('childFollowUp: orchestrator with no telemetry → standard (unknown size)', () => {
+    createNode(node('orch', { mode: 'orchestrator' }));
+    assert.match(childFollowUp('orch'), new RegExp(STD));
+});
+test('childFollowUp: missing / undefined spawner → standard', () => {
+    assert.match(childFollowUp(undefined), new RegExp(STD));
+    assert.match(childFollowUp(''), new RegExp(STD));
+    assert.match(childFollowUp('ghost'), new RegExp(STD)); // no such node
+});

package/dist/core/__tests__/close.test.d.ts

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

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

@@ -0,0 +1,148 @@
+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, getNode, subscribe } from '../canvas/canvas.js';
+import { openFocusRow, getFocusByNode } from '../canvas/focuses.js';
+import { closeDb } from '../canvas/db.js';
+import { closeNode } from '../runtime/close.js';
+import { readInboxSince } from '../feed/inbox.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,
+    };
+}
+/** Wire `parent subscribes_to child` — the spawn-time edge (parent wakes on the
+ *  child's pushes). The child is the publisher/down, the parent the manager/up. */
+function spawnEdge(parent, child) {
+    subscribe(parent, child, true);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-close-'));
+    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('closes the root and its exclusive descendants; spares a shared node', () => {
+    // N ─▶ A ─▶ C        (A, C exclusive to the N subtree)
+    // N ─▶ B ◀─ M        (B also subscribed to by external manager M)
+    for (const id of ['N', 'A', 'B', 'C', 'M'])
+        createNode(node(id, { pane: `%${id.toLowerCase()}` }));
+    spawnEdge('N', 'A');
+    spawnEdge('N', 'B');
+    spawnEdge('A', 'C');
+    spawnEdge('M', 'B'); // external manager keeps B alive
+    const res = closeNode('N');
+    assert.deepEqual([...res.closed].sort(), ['A', 'C', 'N']);
+    assert.deepEqual(res.spared, ['B']);
+    // Closed nodes → canceled, intent cleared, presence (incl. the pane) dropped.
+    for (const id of ['N', 'A', 'C']) {
+        const m = getNode(id);
+        assert.equal(m.status, 'canceled', `${id} canceled`);
+        assert.equal(m.intent, null, `${id} intent cleared`);
+        assert.equal(m.window ?? null, null, `${id} window cleared`);
+        assert.equal(m.tmux_session ?? null, null, `${id} session cleared`);
+        // Step 7: tearDownNode is pane-keyed and nulls the durable pane handle too.
+        // Non-vacuous: each node was given a pane (`%n`/`%a`/`%c`) above, so an impl
+        // that didn't route close through tearDownNode would leave it set.
+        assert.equal(m.pane ?? null, null, `${id} pane cleared`);
+    }
+    // Spared node and the unrelated manager are untouched.
+    assert.equal(getNode('B').status, 'active');
+    assert.equal(getNode('M').status, 'active');
+});
+test('kill order is leaves-first, root-last ("cascades up")', () => {
+    for (const id of ['N', 'A', 'C'])
+        createNode(node(id));
+    spawnEdge('N', 'A');
+    spawnEdge('A', 'C');
+    const res = closeNode('N');
+    assert.deepEqual(res.closed, ['C', 'A', 'N']);
+});
+test('appends a resume notice naming the dead children to each closed node', () => {
+    for (const id of ['N', 'A', 'C'])
+        createNode(node(id));
+    spawnEdge('N', 'A');
+    spawnEdge('A', 'C');
+    closeNode('N');
+    const nNotice = readInboxSince('N').at(-1);
+    assert.equal(nNotice.from, null);
+    assert.equal(nNotice.kind, 'message');
+    assert.match(nNotice.label, /CLOSED by the user/);
+    assert.match(nNotice.label, /A \(A\)/); // dead child named
+    assert.deepEqual(nNotice.data?.['canceled_children'], ['A']);
+    assert.equal(nNotice.data?.['cascade_root'], 'N');
+    const aNotice = readInboxSince('A').at(-1);
+    assert.match(aNotice.label, /CANCELED/);
+    assert.match(aNotice.label, /C \(C\)/);
+    // A leaf has no dead children — gets the short "session preserved" notice.
+    const cNotice = readInboxSince('C').at(-1);
+    assert.match(cNotice.label, /session is preserved/);
+    assert.deepEqual(cNotice.data?.['canceled_children'], []);
+});
+test('diamond: a node reachable via two closing parents is closed', () => {
+    // N ─▶ A ─▶ D
+    // N ─▶ B ─▶ D   (D managed by A and B, both inside the closing set)
+    for (const id of ['N', 'A', 'B', 'D'])
+        createNode(node(id));
+    spawnEdge('N', 'A');
+    spawnEdge('N', 'B');
+    spawnEdge('A', 'D');
+    spawnEdge('B', 'D');
+    const res = closeNode('N');
+    assert.deepEqual([...res.closed].sort(), ['A', 'B', 'D', 'N']);
+    assert.deepEqual(res.spared, []);
+    assert.equal(getNode('D').status, 'canceled');
+});
+test('diamond with one external parent spares the shared node and its subtree', () => {
+    // N ─▶ A ─▶ D ─▶ E ; D also managed by external M  ⇒ D, E spared
+    for (const id of ['N', 'A', 'D', 'E', 'M'])
+        createNode(node(id));
+    spawnEdge('N', 'A');
+    spawnEdge('A', 'D');
+    spawnEdge('D', 'E');
+    spawnEdge('M', 'D');
+    const res = closeNode('N');
+    assert.deepEqual([...res.closed].sort(), ['A', 'N']);
+    assert.deepEqual(res.spared, ['D']);
+    assert.equal(getNode('D').status, 'active');
+    assert.equal(getNode('E').status, 'active'); // not descended into
+});
+test('closing a leaf node closes only itself', () => {
+    createNode(node('solo'));
+    const res = closeNode('solo');
+    assert.deepEqual(res.closed, ['solo']);
+    assert.deepEqual(res.spared, []);
+    assert.equal(getNode('solo').status, 'canceled');
+});
+test('throws on an unknown node', () => {
+    assert.throws(() => closeNode('ghost'), /unknown node/);
+});
+test('Step 7: closing a FOCUSED node closes its focus row + nulls its pane (tearDownNode)', () => {
+    createNode(node('N', { pane: '%x' }));
+    openFocusRow('fN', '%x', 'Sa', 'N');
+    closeNode('N');
+    // tearDownNode closes the focus row the node occupied and nulls its LOCATION.
+    // Non-vacuous: pre-Step-7 close used closeWindow/setFocus('') and never touched
+    // the focuses table, so getFocusByNode('N') would still return fN.
+    assert.equal(getFocusByNode('N'), null, 'focus row closed by tearDownNode');
+    assert.equal(getNode('N').pane ?? null, null, 'pane nulled (pane-keyed teardown)');
+    assert.equal(getNode('N').status, 'canceled', 'node canceled as before');
+});

package/dist/core/__tests__/context-intro.test.d.ts

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