@north-light/crouter 0.3.230 → 0.3.232

package/dist/core/runtime/spawn.js

@@ -12,7 +12,7 @@
 import { accessSync, constants, cpSync, readdirSync, existsSync, rmSync } from 'node:fs';
 import { isAbsolute, resolve, join } from 'node:path';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId } from './nodes.js';
-import { loadProfileManifest } from '../profiles/manifest.js';
+import { resolveProfileOperand } from '../profiles/manifest.js';
 import { selectProfileForCwd, selectProfileForCwdReadOnly } from '../profiles/select.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
@@ -23,7 +23,7 @@ import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
 import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid } from '../canvas/index.js';
 import { jobDir } from '../canvas/paths.js';
-import { openViewerWindow, focusOf, windowOfPane, currentTmux, focusWindow, } from './placement.js';
+import { openViewerWindow, focusOf, windowOfPane, } from './placement.js';
 import { waitForBrokerViewSocket } from './placement-tmux.js';
 import { transition } from './lifecycle.js';
 import { beginBootFaultAttempt } from './fault.js';
@@ -33,6 +33,7 @@ import { ensureDaemon } from '../../daemon/manage.js';
 import { readConfig } from '../config.js';
 import { modelRequestFromConfig, unregisteredConcreteModel } from '../model-routes.js';
 import { openModelRegistry } from './model-registry.js';
+import { MODEL_SPEC_NEXT } from './model-selection.js';
 import { initializeForkContextExposure } from '../substrate/injected-store.js';
 // ---------------------------------------------------------------------------
 // Shared broker-launch wrapper — catch launch/preflight failures at the call
@@ -147,7 +148,7 @@ export function resolveForkSource(value) {
     return resolveSessionUuid(v);
 }
 /** Resolve the profile a spawned child runs under: an explicit `--profile`
- *  operand (id or name) validated through `loadProfileManifest`, else INHERIT
+ *  operand (id, name, or closest match) resolved through `resolveProfileOperand`, else INHERIT
  *  the spawner's current `profile_id` (null when the spawner has none). `--root`
  *  never resets this to null on its own; only an explicit override does. When
  *  there is NO spawner at all — `crtr node new --root` run directly from a
@@ -158,7 +159,10 @@ export async function resolveProfileId(explicit, spawner, cwd, options = {}) {
     if (explicit === null)
         return null;
     if (explicit !== undefined && explicit !== '') {
-        return loadProfileManifest(explicit).profileId;
+        // `explicit` originates as a user-typed `--profile`, so tolerate a near
+        // miss. The CLI normally resolves it to an id first; this covers callers
+        // that reach the daemon with a name.
+        return resolveProfileOperand(explicit).profileId;
     }
     if (spawner !== null)
         return getNode(spawner)?.profile_id ?? null;
@@ -183,7 +187,7 @@ export async function assertLaunchModelRegistered(request, options, registry) {
         return;
     throw usage(`model '${unknown.request.spec}' is not registered in this daemon.`, {
         received: unknown.request.spec,
-        next: 'Pass a registered provider/id, provider/tier where provider is anthropic|openai and tier is ultra|strong|medium|light, a bare tier (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku).',
+        next: MODEL_SPEC_NEXT,
     });
 }
 /** Resolve who a spawn is attributed to. A managed child needs a spine parent
@@ -272,6 +276,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             lifecycle,
             cwd: spawnCwd,
             name: opts.name ?? opts.kind,
+            description: opts.description,
             // A root has no spine parent (top-level, nobody subscribes); it still
             // records spawned_by=spawner when a node (not a human shell) spawned it.
             // A child's parent IS its manager.
@@ -331,11 +336,6 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         }
         // (The three scoped long-term memory stores are seeded for EVERY node at birth
         // in spawnNode — no orchestrator-gated seeding needed here.)
-        // An ATTENDED --root spawned from inside tmux opens its foreground viewer
-        // in the CALLER'S CURRENT session (below), so it appears where the spawner is
-        // working; a managed child is a headless broker with NO viewer at all, and
-        // so is an unattended terminal root (nobody asked to watch it).
-        const here = attendedRoot ? currentTmux() : null;
         const inv = buildPiArgv(meta, { prompt: kickoff, forkFrom });
         // CRTR_SUBTREE (the spine root) rides the detached broker's env so it can group
         // the subtree; the host sets CRTR_FRONT_DOOR itself.
@@ -377,30 +377,16 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
                 ? 'Resolve the cause named above, then retry.'
                 : `The broker engine exited before binding its view socket. Inspect ${jobDir(meta.node_id)}/broker.log for the underlying cause (a missing dependency, model auth, or a crash), then retry.`);
         }
-        // An ATTENDED --root is spawned to be DRIVEN directly: when the caller is
-        // inside tmux, open ONE foreground viewer in the caller's CURRENT session and
-        // bring it forefront so whoever asked for it picks up the conversation.
-        // Outside tmux a --root opens no viewer (an agent handing a root off); an
-        // UNATTENDED terminal root (rootLifecycle: 'terminal') opens none anywhere —
-        // stealing focus for machinery nobody is watching is the bug, not the
-        // feature. A managed child opens nothing. Viewer placement remains non-fatal
-        // after the readiness proof.
+        // A --root opens NO viewer from here. spawnChild runs daemon-side only, and
+        // the daemon is paneless by construction (manage.ts strips TMUX/TMUX_PANE
+        // from its env precisely so this code cannot resolve someone else's pane),
+        // so a root's foreground viewer is placed by whoever asked for it — the
+        // front door, or `node new`'s own openSpawnViewer in the CLI process. Only a
+        // managed child is placed here, and placement stays non-fatal after the
+        // readiness proof.
         let window = null;
         let session = null;
-        if (attendedRoot && here !== null) {
-            const viewer = openViewerWindow(meta.node_id, here.session, { name: fullName(meta), cwd: opts.cwd });
-            if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
-                session = here.session;
-                window = windowOfPane(viewer.pane);
-                if (window !== null) {
-                    try {
-                        focusWindow(here.session, window);
-                    }
-                    catch { /* best-effort */ }
-                }
-            }
-        }
-        else if (!root && spawner !== null && readConfig('user').auto_open_child_viewers) {
+        if (!root && spawner !== null && readConfig('user').auto_open_child_viewers) {
             // When enabled, a managed child opens beside a HUMAN actively watching
             // its spawner. Turning the setting off leaves every child headless until
             // someone explicitly focuses or attaches it. The broker is headless

package/dist/core/runtime/structured-output.d.ts

@@ -13,6 +13,12 @@ export type StructuredOutputState = {
     state: 'invalid';
     error: string;
 };
+/** The `--output-schema` transport clause, rendered verbatim by every leaf that
+ *  accepts one. Declared once so the call sites cannot drift apart. */
+export declare const OUTPUT_SCHEMA_TRANSPORT = "A .json file path, or inline JSON beginning with `{`.";
+/** Provider-constrained generation supports the structural subset below; every
+ *  other schema keyword remains model-visible and is checked after generation. */
+export declare const OUTPUT_SCHEMA_CONSTRAINTS = "Generation is constrained by structure alone \u2014 type, properties, required, items, anyOf, and the standard string formats; every other keyword (enum, pattern, minLength, numeric bounds) reaches the model as description text and is checked only after it answers, so an over-constrained schema costs retries.";
 export declare function outputSchemaPath(nodeId: string): string;
 export declare function outputResultPath(nodeId: string): string;
 export declare function parseOutputSchemaValue(value: string | undefined): Record<string, unknown> | null;

package/dist/core/runtime/structured-output.js

@@ -4,6 +4,12 @@ import { randomUUID } from 'node:crypto';
 import { nodeDir, contextDir } from '../canvas/paths.js';
 import { InputError } from '../io.js';
 import { isRecord } from '../../shared/predicates.js';
+/** The `--output-schema` transport clause, rendered verbatim by every leaf that
+ *  accepts one. Declared once so the call sites cannot drift apart. */
+export const OUTPUT_SCHEMA_TRANSPORT = 'A .json file path, or inline JSON beginning with `{`.';
+/** Provider-constrained generation supports the structural subset below; every
+ *  other schema keyword remains model-visible and is checked after generation. */
+export const OUTPUT_SCHEMA_CONSTRAINTS = 'Generation is constrained by structure alone — type, properties, required, items, anyOf, and the standard string formats; every other keyword (enum, pattern, minLength, numeric bounds) reaches the model as description text and is checked only after it answers, so an over-constrained schema costs retries.';
 export function outputSchemaPath(nodeId) {
     return `${nodeDir(nodeId)}/output-schema.json`;
 }

package/dist/core/substrate/__tests__/surface-match-command.test.d.ts

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

package/dist/core/substrate/__tests__/surface-match-command.test.js

@@ -0,0 +1,89 @@
+// Deliberate, user-approved exception to crouter's standing policy of not using unit tests: glob matching is pure string logic with a large space of near-miss inputs, where a table of real cases is the only economical way to pin behavior, and where BOTH false negatives and false positives are defects.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test src/core/substrate/__tests__/surface-match-command.test.ts
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { commandDeliveryRung, matchesCommandEntry } from '../surface-match.js';
+const subject = {
+    kind: 'developer',
+    mode: 'base',
+    lifecycle: 'terminal',
+    hasManager: false,
+    cwd: '/tmp/project',
+    scope: 'project',
+    orchestration: { depth: 0 },
+    profile: null,
+};
+function entry(match, on = 'command', at = 'preview') {
+    return { on, at, match };
+}
+test('real command globs match the direct invocation they describe', () => {
+    const cases = [
+        { name: 'linear issues', glob: 'linear *', command: 'linear issues list', expected: true },
+        { name: 'capture screenshot', glob: '*capture *', command: 'capture screenshot --url https://example.com', expected: true },
+        { name: 'grove status', glob: '*grove*', command: 'grove status', expected: true },
+        { name: 'crtr human send', glob: '*crtr human *', command: 'crtr human send --message "Approve this change"', expected: true },
+        { name: 'git commit', glob: '*git commit*', command: 'git commit -m "ship fix"', expected: true },
+        { name: 'git push', glob: '*git push*', command: 'git push origin main', expected: true },
+        { name: 'npm publish', glob: '*npm publish*', command: 'npm publish --access public', expected: true },
+        { name: 'pnpm publish', glob: '*pnpm publish*', command: 'pnpm publish --access public', expected: true },
+        { name: 'termrender doc check', glob: '*termrender*', command: 'termrender doc check ./README.md', expected: true },
+        { name: 'single-character question mark', glob: '*git p?sh*', command: 'git push origin main', expected: true },
+        { name: 'trailing star permits bare tool', glob: 'linear *', command: 'linear', expected: true },
+        { name: 'literal glob is an exact command', glob: 'git status', command: 'git status', expected: true },
+        { name: 'literal glob does not imply arguments', glob: 'git status', command: 'git status --short', expected: false },
+    ];
+    for (const testCase of cases) {
+        assert.equal(matchesCommandEntry(entry([testCase.glob]), subject, testCase.command), testCase.expected, testCase.name);
+    }
+});
+test('a command is found after ordinary shell composition and whitespace variation', () => {
+    const cases = [
+        { name: 'after directory change', glob: 'linear *', command: 'cd apps/core && linear issues list', expected: true },
+        { name: 'after semicolon', glob: '*grove*', command: 'printf ready; grove status', expected: true },
+        { name: 'after or-list', glob: '*crtr human *', command: 'test -f answer.txt || crtr human send --message "Choose one"', expected: true },
+        { name: 'leading environment assignment', glob: 'linear *', command: 'CI=1 linear issues list', expected: true },
+        { name: 'tool inside a pipeline', glob: '*termrender*', command: 'termrender doc check README.md | grep -q error', expected: true },
+        { name: 'tool on the right side of a pipe', glob: '*termrender*', command: 'cat README.md | termrender', expected: true },
+        { name: 'two spaces between tokens', glob: 'linear *', command: 'linear  issues list', expected: true },
+        { name: 'tab between tokens', glob: 'linear *', command: 'linear\tissues list', expected: true },
+        { name: 'trailing newline', glob: 'linear *', command: 'linear issues list\n', expected: true },
+    ];
+    for (const testCase of cases) {
+        assert.equal(matchesCommandEntry(entry([testCase.glob]), subject, testCase.command), testCase.expected, testCase.name);
+    }
+});
+test('command text and token near-misses do not wake a surface', () => {
+    const cases = [
+        { name: 'linear only appears in quoted text', glob: 'linear *', command: 'echo "linear issues list"', expected: false },
+        { name: 'capture only appears in quoted text', glob: '*capture *', command: 'echo "capture screenshot"', expected: false },
+        { name: 'git push only appears in a commit message', glob: '*git push*', command: 'git commit -m "please git push later"', expected: false },
+        { name: 'grove is part of a longer word', glob: '*grove*', command: 'echo grover', expected: false },
+        { name: 'capture is part of a longer word', glob: '*capture *', command: 'printf "%s\\n" mycapture', expected: false },
+        { name: 'linear is part of a filename', glob: 'linear *', command: 'python linear-regression.py', expected: false },
+        { name: 'git commit is a sibling subcommand', glob: '*git commit*', command: 'git commit-tree -m "ship fix"', expected: false },
+        { name: 'termrender only appears in quoted text', glob: '*termrender*', command: 'echo "termrender"', expected: false },
+        // A path mention is not an invocation: an unrelated listing should not wake the grove doc.
+        { name: 'grove only appears in an unrelated path', glob: '*grove*', command: 'ls /tmp/grove/config', expected: false },
+    ];
+    for (const testCase of cases) {
+        assert.equal(matchesCommandEntry(entry([testCase.glob]), subject, testCase.command), testCase.expected, testCase.name);
+    }
+});
+test('entry and match-list composition stays within the command event', () => {
+    const anyGlobCases = [
+        { name: 'second glob satisfies the list', globs: ['*npm publish*', '*pnpm publish*'], command: 'pnpm publish --access public', expected: true },
+        { name: 'no glob satisfies the list', globs: ['*npm publish*', '*pnpm publish*'], command: 'yarn publish', expected: false },
+    ];
+    for (const testCase of anyGlobCases) {
+        assert.equal(matchesCommandEntry(entry(testCase.globs), subject, testCase.command), testCase.expected, testCase.name);
+    }
+    assert.equal(commandDeliveryRung({ surfaces: [entry(['*npm publish*'], 'command', 'name'), entry(['*pnpm publish*'], 'command', 'content')] }, subject, 'pnpm publish --access public'), 'content', 'matching command entries OR together and retain the highest matching rung');
+    const otherEventCases = [
+        { name: 'read entry never fires for a command', on: 'read' },
+        { name: 'memory-read entry never fires for a command', on: 'memory-read' },
+    ];
+    for (const testCase of otherEventCases) {
+        assert.equal(matchesCommandEntry(entry(['linear *'], testCase.on), subject, 'linear issues list'), false, testCase.name);
+    }
+});

package/dist/core/substrate/on-read.js

@@ -20,7 +20,8 @@
 //     workspace-wide context arrives before the task rather than waiting for
 //     an arbitrary first file.
 //   • `command` — a `bash` tool call evaluates the executed command string
-//     against every doc's `command` entries (string globs, `*` crossing `/`).
+//     against every doc's `command` entries (per shell segment, wildcards at
+//     token granularity — see surface-match.ts).
 //
 // All channels register through one context exposure target, so a document
 // already loaded at the same or a higher rung does not repeat. Each candidate

package/dist/core/substrate/surface-match.js

@@ -102,21 +102,173 @@ export function matchesMemoryReadEntry(entry, routingAnchor, subject, name) {
         return false;
     return entry.match.some((g) => memoryReadGlobMatches(g, routingAnchor, name));
 }
-/** A command glob is a STRING glob over the whole command line, not a path
- *  glob: `*` crosses every character (including `/` — command lines carry
- *  paths), `?` matches one. Translated to a regex rather than fed to
- *  `matchesGlob`, whose `*` stops at path separators. */
-function commandGlobMatches(glob, command) {
-    const rx = glob
+function splitCommandSegments(command) {
+    const segments = [];
+    let current = '';
+    let quote = null;
+    let escaped = false;
+    const finish = () => {
+        segments.push(current);
+        current = '';
+    };
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\' && quote !== "'") {
+            current += ch;
+            escaped = true;
+            continue;
+        }
+        if (quote !== null) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            current += ch;
+            quote = ch;
+            continue;
+        }
+        if (ch === '\n' || ch === ';') {
+            finish();
+            continue;
+        }
+        if ((ch === '&' || ch === '|') && command[i + 1] === ch) {
+            finish();
+            i += 1;
+            continue;
+        }
+        if (ch === '|') {
+            finish();
+            continue;
+        }
+        current += ch;
+    }
+    finish();
+    return segments;
+}
+function tokenizeCommandSegment(segment) {
+    const tokens = [];
+    let text = '';
+    let opaque = false;
+    let started = false;
+    let quote = null;
+    let escaped = false;
+    const finish = () => {
+        if (started)
+            tokens.push({ text, opaque });
+        text = '';
+        opaque = false;
+        started = false;
+    };
+    for (let i = 0; i < segment.length; i += 1) {
+        const ch = segment[i];
+        if (escaped) {
+            text += ch;
+            started = true;
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\' && quote !== "'") {
+            escaped = true;
+            started = true;
+            continue;
+        }
+        if (quote !== null) {
+            started = true;
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                text += ch;
+            }
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            quote = ch;
+            opaque = true;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            finish();
+            continue;
+        }
+        text += ch;
+        started = true;
+    }
+    if (escaped)
+        text += '\\';
+    finish();
+    return tokens;
+}
+function commandSegments(command) {
+    return splitCommandSegments(command)
+        .map(tokenizeCommandSegment)
+        .map((tokens) => {
+        let first = 0;
+        while (first < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[first].text))
+            first += 1;
+        return tokens.slice(first);
+    })
+        .filter((tokens) => tokens.length > 0);
+}
+function commandGlobPattern(glob) {
+    const words = glob.trim().split(/\s+/);
+    if (words.length === 1 && words[0] === '')
+        return null;
+    const pattern = [];
+    for (const word of words) {
+        const parts = word.split('*');
+        for (let i = 0; i < parts.length; i += 1) {
+            if (parts[i] !== '')
+                pattern.push({ kind: 'literal', text: parts[i] });
+            if (i < parts.length - 1)
+                pattern.push({ kind: 'any' });
+        }
+    }
+    return pattern;
+}
+function tokenMatches(pattern, token) {
+    const rx = pattern
         .split('')
-        .map((ch) => (ch === '*' ? '[\\s\\S]*' : ch === '?' ? '[\\s\\S]' : ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')))
+        .map((ch) => (ch === '?' ? '[\\s\\S]' : ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')))
         .join('');
-    try {
-        return new RegExp(`^${rx}$`).test(command);
-    }
-    catch {
+    return new RegExp(`^${rx}$`).test(token);
+}
+function segmentMatches(pattern, tokens) {
+    const memo = new Map();
+    const match = (patternIndex, tokenIndex) => {
+        const key = `${patternIndex}:${tokenIndex}`;
+        const cached = memo.get(key);
+        if (cached !== undefined)
+            return cached;
+        let result;
+        if (patternIndex === pattern.length) {
+            result = tokenIndex === tokens.length;
+        }
+        else if (pattern[patternIndex].kind === 'any') {
+            result = match(patternIndex + 1, tokenIndex) || (tokenIndex < tokens.length && match(patternIndex, tokenIndex + 1));
+        }
+        else {
+            const token = tokens[tokenIndex];
+            result = token !== undefined && !token.opaque && tokenMatches(pattern[patternIndex].text, token.text) && match(patternIndex + 1, tokenIndex + 1);
+        }
+        memo.set(key, result);
+        return result;
+    };
+    return match(0, 0);
+}
+function commandGlobMatches(glob, command) {
+    const pattern = commandGlobPattern(glob);
+    if (pattern === null)
         return false;
-    }
+    return commandSegments(command).some((tokens) => segmentMatches(pattern, tokens));
 }
 /** Does a `command` entry fit the executed command string? */
 export function matchesCommandEntry(entry, subject, command) {

package/dist/core/termrender/version.d.ts

@@ -1 +1 @@
-export declare const TERMRENDER_VERSION = "4.12.8";
+export declare const TERMRENDER_VERSION = "4.12.11";

package/dist/core/termrender/version.js

@@ -1 +1 @@
-export const TERMRENDER_VERSION = '4.12.8';
+export const TERMRENDER_VERSION = '4.12.11';

package/dist/core/user-settings.js

@@ -197,7 +197,7 @@ export const CONFIG_SETTINGS_COVERAGE = {
         setting: {
             key: 'page_surface',
             label: 'Page human surface',
-            description: 'Prompt agents to use JSX pages by default for structured or interactive content shown to you.',
+            description: 'This host reads pages in a browser rather than a terminal. Agents are told the page module runs as written, HTML pages are offered, and document review and live display leave the command tree.',
             valueConstraint: 'true|false',
             applies: 'Applies when human command help is assembled.',
             group: 'display',

package/dist/daemon/api/__tests__/broker-settle-park.test.d.ts

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

package/dist/daemon/api/__tests__/broker-settle-park.test.js

@@ -0,0 +1,102 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/daemon/api/__tests__/broker-settle-park.test.ts
+//
+// The park clock hands terminalization to broker settlement: it arms a pending
+// park, delivers one summary prompt to the live engine, and this handler
+// decides what the ending turn meant. The defect surface is the re-evaluation —
+// the verdict the clock reached 15 minutes ago must not be enacted when the
+// summary turn itself created live work (a human ask, new wake-worthy mail, a
+// pushed final), and the pending park must be consumed exactly once regardless.
+import { after, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { createNode, getNode } from '../../../core/canvas/canvas.js';
+import { closeDb } from '../../../core/canvas/db.js';
+import { appendInbox } from '../../../core/feed/inbox.js';
+import { beginPendingPark, isPendingPark } from '../../park-pending.js';
+import { brokerOperationRoutes } from '../handlers/broker-ops.js';
+let home = '';
+let originalHome;
+const settleRoute = brokerOperationRoutes.find((route) => route.method === 'POST' && route.pattern === '/v1/nodes/:id/broker/settle');
+before(() => {
+    originalHome = process.env['CRTR_HOME'];
+    home = mkdtempSync('/tmp/crtr-settle-park-');
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    if (originalHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = originalHome;
+});
+/** A live resident mid-parking-turn: the clock armed the park and the summary
+ *  turn is what is now settling. */
+function residentMidParkingTurn(id) {
+    const meta = {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: home,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        status: 'active',
+    };
+    createNode(meta);
+    beginPendingPark(id, Date.now());
+}
+async function settle(id, over = {}) {
+    const ctx = {
+        method: 'POST',
+        path: `/v1/nodes/${id}/broker/settle`,
+        params: { id },
+        query: new URLSearchParams(),
+        body: {
+            stopReason: 'stop',
+            backgroundJobsRunning: false,
+            pushedFinal: false,
+            requestedHumanReply: false,
+            ...over,
+        },
+    };
+    return (await settleRoute.handler(ctx)).body;
+}
+test('a summary turn that ends with nothing new parks the node: done + intent=parked, no latch', async () => {
+    residentMidParkingTurn('summarized');
+    const directive = await settle('summarized');
+    assert.deepEqual(directive, { action: 'shutdown' });
+    const parked = getNode('summarized');
+    assert.equal(parked.status, 'done');
+    assert.equal(parked.intent, 'parked');
+    assert.equal(parked.final_report ?? null, null, 'a park never sets the finalization latch');
+    assert.equal(isPendingPark('summarized'), false, 'the pending park is consumed');
+});
+test('a human ask raised during the parking turn keeps the node live instead of parking it', async () => {
+    residentMidParkingTurn('asked');
+    const directive = await settle('asked', { requestedHumanReply: true });
+    assert.deepEqual(directive, { action: 'stay_dormant' });
+    assert.equal(getNode('asked').status, 'active', 'the node stays live awaiting its answer');
+    assert.equal(getNode('asked').intent ?? null, null);
+    assert.equal(isPendingPark('asked'), false, 'the park is discarded, not held for the next settle');
+});
+test('wake-worthy mail arriving during the parking turn flips the verdict back to release', async () => {
+    residentMidParkingTurn('mailed');
+    appendInbox('mailed', { from: null, tier: 'normal', kind: 'message', label: 'x', data: { body: 'work' } });
+    const directive = await settle('mailed');
+    assert.equal(directive.action, 'stay_dormant');
+    assert.equal(getNode('mailed').status, 'active', 're-evaluation saw the new obligation and did not park');
+    assert.equal(getNode('mailed').intent ?? null, null);
+    assert.equal(isPendingPark('mailed'), false);
+});
+test('a final pushed during the parking turn finishes the node rather than parking it', async () => {
+    residentMidParkingTurn('finished');
+    const directive = await settle('finished', { pushedFinal: true });
+    assert.deepEqual(directive, { action: 'shutdown' });
+    assert.equal(getNode('finished').intent ?? null, null, 'a pushed final is not a park');
+    assert.equal(isPendingPark('finished'), false);
+});

package/dist/daemon/api/__tests__/canvas-snapshot-fields.test.d.ts

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