@north-light/crouter 0.3.249 → 0.3.250

package/dist/clients/inbox/__tests__/integration/stale-row-activation.test.d.ts

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

package/dist/clients/inbox/__tests__/integration/stale-row-activation.test.js

@@ -0,0 +1,53 @@
+// A page ticket that settles out-of-band (answered from another surface, or a
+// row this inbox failed to drop) must not read as "being edited by another
+// inbox" when the reader presses Enter: its response.json already exists, so the
+// row is stale and this activation must report the settlement and drop it.
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ticketDir } from '#core/human/root';
+import { submitPage, takeoverAndCompletePage } from '#core/human/tickets';
+import { claimPath } from '#core/human/convention';
+import { InboxController } from '../../controller.js';
+const key = (part = {}) => ({ ctrl: false, meta: false, upArrow: false, downArrow: false, leftArrow: false, rightArrow: false, wordLeft: false, wordRight: false, home: false, end: false, pageUp: false, pageDown: false, del: false, return: false, newline: false, escape: false, tab: false, backspace: false, ...part });
+function fakeHost() {
+    const handle = { close() { }, invalidate() { }, onClose() { } };
+    return { capabilities: { remote: false, canFocusNode: false, selfPane: undefined }, mount: () => handle, notice() { }, suspendForChild: () => () => { }, focusNode: async () => false, pickReviewFile: async () => null };
+}
+const status = (c) => c.status;
+const temp = mkdtempSync(join(tmpdir(), 'crtr-stale-row-'));
+const sources = mkdtempSync(join(tmpdir(), 'crtr-stale-src-'));
+process.env['CRTR_HOME'] = temp;
+const sourceFile = join(sources, 'ask.tsx');
+writeFileSync(sourceFile, 'export default () => (\n  <Page title="Stale row page" subtitle="Pick one">\n    <UserQuestion id="choice" label="Restore?" body="Pick one." mode="single" options={[{ id: "yes", label: "Yes" }, { id: "no", label: "No" }]} />\n  </Page>\n);\n');
+const inboxDelivery = { placement: 'inline', inbox: true, reply: true };
+try {
+    const dir = ticketDir('stale-page');
+    submitPage({ dir, sourceFile, delivery: inboxDelivery });
+    // Seed the controller's in-memory list from disk while the ticket is pending.
+    const options = { cols: 100, rows: 24 };
+    const controller = new InboxController({ host: fakeHost(), onDirty() { }, onClosed() { }, ...options });
+    assert.equal(controller.snapshot().items.length, 1, 'pending page is listed');
+    // Settle it out of band, without letting the controller rescan: this is the
+    // stale-row state the bug leaves behind.
+    takeoverAndCompletePage(dir, { choice: { selectedOptionIds: ['yes'], comments: [] } }, { host: 'daemon', pid: 1 });
+    assert.equal(existsSync(join(dir, 'response.json')), true, 'response is published on disk');
+    assert.equal(existsSync(claimPath(dir)), false, 'completion leaves no claim behind');
+    assert.equal(controller.snapshot().items.length, 1, 'the in-memory row is still stale');
+    // Pressing Enter on the stale row must report the settlement and drop it,
+    // never claim it is edited by another inbox.
+    controller.handleKey('', key({ return: true }));
+    const reported = status(controller) ?? '';
+    assert.match(reported, /already resolved/, `stale-row activation reports the settlement, got: ${JSON.stringify(reported)}`);
+    assert.doesNotMatch(reported, /being edited/, 'a settled row is never "edited by another inbox"');
+    assert.equal(controller.snapshot().items.length, 0, 'the stale row drops on activation');
+    assert.equal(controller.snapshot().screen, 'list', 'a settled row never opens the detail pane');
+    controller.close();
+    console.log('stale-row regression passed');
+}
+finally {
+    rmSync(temp, { recursive: true, force: true });
+    rmSync(sources, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+}

package/dist/clients/inbox/controller.js

@@ -1,4 +1,6 @@
-import { statSync, watch } from 'node:fs';
+import { existsSync, statSync, watch } from 'node:fs';
+import { basename } from 'node:path';
+import { visibleWidth } from '@earendil-works/pi-tui';
 import { renderMarkdown } from '../../core/termrender/termrender.js';
 import { BOLD, CYAN, DIM, GRAY, RESET, YELLOW, clipLine } from './tui/ansi.js';
 import { buildInboxLines, recommendedLabel } from './tui.js';
@@ -8,7 +10,8 @@ import { resolvePageComponents } from '../../core/config.js';
 import { watchInboxActivity } from '../../core/human/root.js';
 import { claimTicket, heartbeatClaim, releaseClaim } from '../../core/human/claim.js';
 import { readPageTicket, readTicketResult } from '../../core/human/tickets.js';
-import { clearProgress, pagePath } from '../../core/human/convention.js';
+import { claimPath, clearProgress, isResolved, pagePath, responsePath } from '../../core/human/convention.js';
+import { emitEvent } from '../../core/events/emit.js';
 import { projectPageDisplayMarkdown } from '../../core/human/page-markdown.js';
 import { projectHtmlDocumentMarkdown } from '../../core/human/page-html-markdown.js';
 import { pageBodyLines } from './tui/page-body.js';
@@ -200,7 +203,13 @@ export class InboxController {
         }
         const claim = claimTicket(item.dir);
         if (claim === null) {
-            this.status = 'ticket is being edited by another inbox';
+            // A null claim means either the ticket already settled (its response.json
+            // exists) or a live claim is held. Only the latter is "another inbox";
+            // the former is a stale row this scan should drop.
+            const resolved = isResolved(item.dir);
+            this.status = resolved ? safeCanonicalResultStatus(item.dir) : 'ticket is being edited by another inbox';
+            if (resolved)
+                this.rescan();
             return;
         }
         const settled = item.fastAction.kind === 'acknowledge'
@@ -250,7 +259,10 @@ export class InboxController {
             return;
         const claim = claimTicket(item.dir);
         if (claim === null) {
-            this.status = 'ticket is being edited by another inbox';
+            const resolved = isResolved(item.dir);
+            this.status = resolved ? safeCanonicalResultStatus(item.dir) : 'ticket is being edited by another inbox';
+            if (resolved)
+                this.rescan();
             return;
         }
         this.claim = { dir: item.dir, token: claim.token };
@@ -361,6 +373,22 @@ export class InboxController {
         this.submittingDir = undefined;
         this.leaveDetail(false);
         this.rescan();
+        // A settled page whose row survives its own post-resolve rescan is the
+        // "row won't leave" defect. This records the disk truth at the exact moment
+        // the row should have dropped, so a live recurrence is diagnosable without a
+        // reproduction: was the response published, does the scan still list it, and
+        // was the claim left behind.
+        const stillListed = this.items.some((item) => item.dir === claim.dir);
+        emitEvent({
+            level: stillListed ? 'warn' : 'info',
+            event: 'inbox.page.resolved',
+            fields: {
+                ticket_id: basename(claim.dir),
+                response_published: existsSync(responsePath(claim.dir)),
+                still_listed: stillListed,
+                claim_left_behind: existsSync(claimPath(claim.dir)),
+            },
+        });
         this.markDirty();
     }
     /** Edit the active buffer while the host releases the terminal to $EDITOR. */
@@ -527,7 +555,6 @@ export class InboxController {
         }
     }
 }
-function visibleWidth(line) { return line.replace(/\x1b\[[0-9;]*m/g, '').length; }
 function canonicalResultStatus(result) {
     if (result === null)
         return 'ticket was already resolved';

package/dist/clients/inbox/tui/ansi.d.ts

@@ -33,7 +33,9 @@ export declare function hardWrap(text: string, maxWidth: number): string[];
  * them as cheap no-ops.
  */
 export declare function centerHorizontal(lines: string[], cols: number, contentWidth: number): string[];
-/** Visible width of a line in display cells (string-width ignores ANSI). */
+/** Visible width of a line in display cells. pi-tui's helper is the one
+ *  terminal-cell contract: it accounts for graphemes and wide cells while
+ *  ignoring SGR, OSC, and APC sequences. */
 export declare function visibleWidth(line: string): number;
 /**
  * The one display-cell containment primitive: the visible cells

package/dist/clients/inbox/tui/ansi.js

@@ -1,4 +1,5 @@
 import stringWidth from 'string-width';
+import { visibleWidth as piVisibleWidth } from '@earendil-works/pi-tui';
 // ── ANSI escape constants ─────────────────────────────────────────────────────
 // The single home for these — both the page renderer (render.ts) and the inbox
 // picker (inbox/tui.ts) import from here rather than keeping their own copies.
@@ -172,31 +173,34 @@ export function centerHorizontal(lines, cols, contentWidth) {
     const pad = ' '.repeat(extraPad);
     return lines.map((line) => (line === '' ? '' : pad + line));
 }
-/** Visible width of a line in display cells (string-width ignores ANSI). */
+/** Visible width of a line in display cells. pi-tui's helper is the one
+ *  terminal-cell contract: it accounts for graphemes and wide cells while
+ *  ignoring SGR, OSC, and APC sequences. */
 export function visibleWidth(line) {
-    return stringWidth(line);
+    return piVisibleWidth(line);
 }
 const ANSI_TOKEN = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b_[^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-^]/g;
 const OSC8_TOKEN = /\x1b\]8;[^;\x07\x1b]*;([^\x07\x1b]*)(\x07|\x1b\\)/g;
 const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
 /** ANSI escapes are tokens of their own; all printable text is segmented into
  * extended grapheme clusters before widths or slice boundaries are calculated.
- * `string-width` assigns display width to the complete cluster (not its
+ * `visibleWidth` assigns display width to the complete cluster (not its
  * constituent code points), which keeps ZWJ emoji, flags, skin tones and
- * combining sequences indivisible while panning. */
+ * combining sequences indivisible while panning, and counts a tab as the same
+ * cells the rest of the rectangle measures it at. */
 function displayTokens(line) {
     const tokens = [];
     let at = 0;
     ANSI_TOKEN.lastIndex = 0;
     for (let match = ANSI_TOKEN.exec(line); match !== null; match = ANSI_TOKEN.exec(line)) {
         for (const segment of GRAPHEMES.segment(line.slice(at, match.index))) {
-            tokens.push({ ansi: false, text: segment.segment, width: stringWidth(segment.segment) });
+            tokens.push({ ansi: false, text: segment.segment, width: visibleWidth(segment.segment) });
         }
         tokens.push({ ansi: true, text: match[0] });
         at = match.index + match[0].length;
     }
     for (const segment of GRAPHEMES.segment(line.slice(at))) {
-        tokens.push({ ansi: false, text: segment.segment, width: stringWidth(segment.segment) });
+        tokens.push({ ansi: false, text: segment.segment, width: visibleWidth(segment.segment) });
     }
     return tokens;
 }
@@ -284,8 +288,8 @@ function closeActiveOsc8(line) {
 export function clipLine(line, maxWidth) {
     if (maxWidth < 1)
         return '';
-    if (stringWidth(line) <= maxWidth)
-        return line; // string-width ignores ANSI
+    if (visibleWidth(line) <= maxWidth)
+        return line; // visibleWidth ignores ANSI
     return sliceCells(line, 0, maxWidth);
 }
 /**
@@ -300,7 +304,7 @@ export function clipLine(line, maxWidth) {
 export function panLine(line, offset, width) {
     if (width < 1)
         return '';
-    const w = stringWidth(line);
+    const w = visibleWidth(line);
     if (w <= width)
         return line;
     const max = w - width;
@@ -313,5 +317,5 @@ export function panLine(line, offset, width) {
 }
 /** Cells of `line` that fall outside a `width`-wide rectangle. */
 export function rowOverflow(line, width) {
-    return Math.max(0, stringWidth(line) - width);
+    return Math.max(0, visibleWidth(line) - width);
 }

package/dist/commands/__tests__/api-client-cold-start-diagnostic.test.js

@@ -2,7 +2,7 @@
 // `node inspect list`/etc used to surface a bare `daemon_unavailable` on a
 // cold-start timeout, discarding the real cause. `readColdStartDiagnostic`
 // (`../api-client.ts`) is what `cliClient()` wires into `CrtrClient` as
-// `coldStartDiagnostic` — this proves it reads a BOUNDED tail of crtrd.err
+// `coldStartDiagnostic` — this proves it reads a BOUNDED tail of crtrd.log
 // (never the whole file) and degrades to `undefined` (not a throw) when the
 // log is missing. The final test proves the READ itself is bounded (not just
 // the returned string) — the prior implementation `readFileSync`'d the whole
@@ -30,21 +30,21 @@ after(() => {
         process.env.CRTR_HOME = previousHome;
     rmSync(home, { recursive: true, force: true });
 });
-test('returns undefined when crtrd.err does not exist', () => {
+test('returns undefined when crtrd.log does not exist', () => {
     assert.equal(readColdStartDiagnostic(), undefined);
 });
-test('returns undefined for an empty/whitespace-only crtrd.err', () => {
-    writeFileSync(join(home, 'crtrd.err'), '   \n\n  \n');
+test('returns undefined for an empty/whitespace-only crtrd.log', () => {
+    writeFileSync(join(home, 'crtrd.log'), '   \n\n  \n');
     assert.equal(readColdStartDiagnostic(), undefined);
 });
 test('surfaces the tail of a real startup failure', () => {
-    writeFileSync(join(home, 'crtrd.err'), 'Error: listen EADDRINUSE: address already in use :::0\n');
+    writeFileSync(join(home, 'crtrd.log'), 'Error: listen EADDRINUSE: address already in use :::0\n');
     const diagnostic = readColdStartDiagnostic();
     assert.match(diagnostic ?? '', /EADDRINUSE/);
 });
 test('bounds the tail instead of leaking the whole log', () => {
     const lines = Array.from({ length: 5_000 }, (_, i) => `line ${i}: ${'x'.repeat(80)}`);
-    writeFileSync(join(home, 'crtrd.err'), lines.join('\n'));
+    writeFileSync(join(home, 'crtrd.log'), lines.join('\n'));
     const diagnostic = readColdStartDiagnostic();
     assert.ok(diagnostic !== undefined);
     // Bounded on both axes: never the full 5,000-line log, and never unbounded bytes.
@@ -62,7 +62,7 @@ test('bounds the READ itself — the tail window starts at an exact byte offset,
     const afterSentinel = 'AFTER-WINDOW-SENTINEL';
     const prefixFiller = 'p'.repeat(50_000 - beforeSentinel.length);
     const tailFiller = 'q'.repeat(COLD_START_DIAGNOSTIC_TAIL_BYTES - afterSentinel.length);
-    writeFileSync(join(home, 'crtrd.err'), prefixFiller + beforeSentinel + afterSentinel + tailFiller);
+    writeFileSync(join(home, 'crtrd.log'), prefixFiller + beforeSentinel + afterSentinel + tailFiller);
     const diagnostic = readColdStartDiagnostic() ?? '';
     assert.match(diagnostic, /AFTER-WINDOW-SENTINEL/);
     assert.doesNotMatch(diagnostic, /BEFORE-WINDOW-SENTINEL/);

package/dist/commands/api-client.d.ts

@@ -20,12 +20,12 @@ export declare function rethrowAsCliError(err: unknown, next?: string): never;
  *  404-only→null mapping as `ApiCanvasSource.orNull`, but returning the raw DTO
  *  and rethrowing non-404s as CLI errors rather than swallowing them. */
 export declare function getNodeOrNull(nodeId: string): Promise<NodeDetailDTO | null>;
-/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout.
+/** Bounded tail of crtrd.log surfaced on a cold-start `/healthz` timeout.
  *  Large enough to catch a real startup failure/stack trace,
  *  small enough that a runaway daemon log can never leak unbounded into a CLI
  *  error message. */
 export declare const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4096;
-/** Read a bounded tail of crtrd's stderr log to enrich a `daemon_unavailable`
+/** Read a bounded tail of crtrd's event log to enrich a `daemon_unavailable`
  *  cold-start timeout, so the actual startup failure is not discarded behind a
  *  bare message. Bounds the I/O itself — opens the file and reads only the
  *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,

package/dist/commands/api-client.js

@@ -56,13 +56,13 @@ export async function getNodeOrNull(nodeId) {
     }
 }
 // cliClient — the one place the CLI constructs a daemon client
-/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout.
+/** Bounded tail of crtrd.log surfaced on a cold-start `/healthz` timeout.
  *  Large enough to catch a real startup failure/stack trace,
  *  small enough that a runaway daemon log can never leak unbounded into a CLI
  *  error message. */
 export const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4_096;
 const COLD_START_DIAGNOSTIC_TAIL_LINES = 20;
-/** Read a bounded tail of crtrd's stderr log to enrich a `daemon_unavailable`
+/** Read a bounded tail of crtrd's event log to enrich a `daemon_unavailable`
  *  cold-start timeout, so the actual startup failure is not discarded behind a
  *  bare message. Bounds the I/O itself — opens the file and reads only the
  *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,
@@ -73,7 +73,7 @@ const COLD_START_DIAGNOSTIC_TAIL_LINES = 20;
 export function readColdStartDiagnostic() {
     let fd;
     try {
-        fd = openSync(join(crtrHome(), 'crtrd.err'), 'r');
+        fd = openSync(join(crtrHome(), 'crtrd.log'), 'r');
         const { size } = fstatSync(fd);
         const start = Math.max(0, size - COLD_START_DIAGNOSTIC_TAIL_BYTES);
         const length = size - start;
@@ -83,7 +83,7 @@ export function readColdStartDiagnostic() {
         readSync(fd, buffer, 0, length, start);
         const lines = buffer.toString('utf8').split('\n').filter((line) => line.trim() !== '');
         const tail = lines.slice(-COLD_START_DIAGNOSTIC_TAIL_LINES).join('\n').trim();
-        return tail === '' ? undefined : `crtrd.err (tail):\n${tail}`;
+        return tail === '' ? undefined : `crtrd.log (tail):\n${tail}`;
     }
     catch {
         return undefined;
@@ -124,7 +124,7 @@ export function cliClient(opts) {
             ensureDaemon();
         },
         // On a cold-start timeout, enrich the bare `daemon_unavailable` with the
-        // tail of crtrd's own stderr log instead of discarding it.
+        // tail of crtrd's event log instead of discarding it.
         coldStartDiagnostic: readColdStartDiagnostic,
         coldStartPollWindowMs: DAEMON_STARTUP_WINDOW_MS,
     });

package/dist/commands/canvas-browse.js

@@ -64,7 +64,7 @@ export const browseLeaf = defineLeaf({
             profileId,
             source,
             viewedNodeIds: async () => new Set((await cliClient().listFocuses()).map((focus) => focus.node_id)),
-            closeNode: (id) => cliClient().closeNode(id, { finish: true }).then((r) => ({ closed: r.closed })),
+            closeNode: (id) => cliClient().closeNode(id, { finish: true, caller_pid: process.ppid }).then((r) => ({ closed: r.closed })),
         });
     },
 });

package/dist/commands/node/create.js

@@ -211,7 +211,8 @@ async function runNodeCreation(input) {
     if (noKickoff && mode === 'orchestrator') {
         throw new InputError({ error: 'no_kickoff_orchestrator_unsupported', message: '--no-kickoff cannot be combined with --mode orchestrator', field: 'no-kickoff', next: 'Drop --no-kickoff and provide a prompt, or spawn in base mode.' });
     }
-    const parentId = parent ?? envNodeId();
+    const creator = envNodeId();
+    const parentId = parent ?? creator;
     mark('node_new.create_start', { root });
     const detail = await cliClient().createNode({
         ...(kind !== undefined ? { kind } : {}),
@@ -224,6 +225,7 @@ async function runNodeCreation(input) {
         ...(name !== undefined ? { name } : {}),
         prompt,
         ...(root ? { root: true } : { parent: parentId ?? null }),
+        ...(creator !== undefined ? { creator } : {}),
         ...(resident ? { root_lifecycle: 'resident' } : {}),
         ...(worktreeBase !== undefined ? { worktree: worktreeBase } : {}),
         ...(forkFrom !== undefined ? { fork_from: forkFrom } : {}),

package/dist/commands/node/inspect.js

@@ -214,6 +214,7 @@ const nodeShow = defineLeaf({
         ];
         if (node['parent'])
             meta.push(`- parent: ${node['parent']}`);
+        meta.push(`- creator: ${node['creator'] ?? 'an external process'}`);
         if (node['waiting_for'])
             meta.push(`- waiting for message: ${node['waiting_for']}`);
         parts.push(meta.join('\n'));

package/dist/commands/node/lifecycle.js

@@ -100,7 +100,7 @@ const nodeClose = defineLeaf({
             throw new InputError({ error: 'no_node', message: 'no node found in this pane to close', next: 'Pass --node <id>, or run from inside the agent\'s pane.' });
         }
         const res = await cliClient()
-            .closeNode(id)
+            .closeNode(id, { caller_pid: process.ppid })
             .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
         return { node_id: res.root, count: res.closed.length, closed_ids: res.closed, spared: res.spared };
     },

package/dist/commands/node/message.js

@@ -46,7 +46,7 @@ function messageSendParams() {
         { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --situational-context is supplied.' },
         { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
-        { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, default: 'normal', constraint: 'Delivery urgency. Deferred never wakes an idle node.' },
+        { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, default: 'normal', constraint: 'Delivery urgency. Deferred never wakes an idle node, except a terminal one, which has no later cycle to read it on and is raised to urgent.' },
         { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Non-empty hidden ambient context delivered beside the message, or alone.' },
         { kind: 'flag', name: 'reopen', type: 'bool', required: false, constraint: 'Re-task the target: commits it resident and clears any finalization latch before delivery. Valid for live, parked, and finalized targets.' },
     ];
@@ -97,9 +97,11 @@ async function runMessageEngine(input) {
     }).catch(rethrowAsCliError);
     const guidance = res.revived
         ? 'Delivered — the dormant target was revived to receive it.'
-        : tier === 'deferred'
-            ? "Delivered — held for the target's next natural cycle; not revived."
-            : 'Delivered.';
+        : tier !== 'deferred'
+            ? 'Delivered.'
+            : res.delivered_tier === undefined
+                ? "Delivered — held for the target's next natural cycle; not revived."
+                : 'Delivered — the target is terminal and takes no later cycle, so it was raised to urgent rather than held.';
     return { revived: res.revived, guidance };
 }
 const nodeMessageSend = defineLeaf({

package/dist/commands/node/wait.js

@@ -46,7 +46,7 @@ function deadlineHeredoc(body, nodeId) {
     const lines = new Set(body.split('\n'));
     while (lines.has(delimiter))
         delimiter = `CRTR_DEADLINE_${++suffix}`;
-    return `crtr node message send --to ${shellQuote(nodeId)} --tier urgent <<'${delimiter}'\n${body}\n${delimiter}`;
+    return `crtr cron cancel "$CRTR_CRON_ID" && crtr node message send --to ${shellQuote(nodeId)} --tier urgent <<'${delimiter}'\n${body}\n${delimiter}`;
 }
 const nodeWaitDeadline = defineLeaf({
     name: 'deadline',

package/dist/commands/push.js

@@ -1,15 +1,14 @@
 // `crtr push` — the one verb up the graph.
 //
-//   crtr push update [body]   — routine progress to subscribers
-//   crtr push urgent [body]   — force-wake subscribers
+//   crtr push update [body]   — report progress to subscribers
 //   crtr push final  [body]   — finish: write result, mark node done, close window
 //
-// "push" is THE verb a node uses to talk to its managers; the tier is the
-// subcommand. The caller's node is resolved from CRTR_NODE_ID (injected by the
-// runtime into every node process). Absent ⇒ InputError — push is only
-// meaningful inside a live node.
+// "push" is THE verb a node uses to talk to its managers. `update` reports
+// progress; its --tier sets delivery urgency. The caller's node is resolved from
+// CRTR_NODE_ID (injected by the runtime into every node process). Absent ⇒
+// InputError — push is only meaningful inside a live node.
 //
-// STAGE B-5: this verb is a PURE crtrd API client. Every tier goes through
+// STAGE B-5: this verb is a PURE crtrd API client. Every report goes through
 // `POST /nodes/{id}/reports` (`client.pushReport`); the report file write, the
 // per-subscriber inbox fan, and (final only) the lifecycle transition all happen
 // server-side inside feed `push()` (spec §7.4). This file reaches ZERO canvas
@@ -32,34 +31,32 @@ function requireCallerNode() {
     }
     return id.trim();
 }
-const TIER_BLURB = {
-    update: 'routine progress — fans a pointer to subscribers, no forced wake',
-    urgent: 'force-wake subscribers (inbox tier urgent)',
+const PUSH_BLURB = {
+    update: 'report progress to subscribers',
     final: 'finish: write the canonical result, mark the node done, close its window',
 };
-const TIER_WHENTOUSE = {
-    update: 'you have routine progress worth surfacing to your managers but nothing that needs them to act right now — a checkpoint, a finished sub-step, a status note while you keep working, a heads-up on a decision you made. Fans a lightweight pointer to every subscriber without forcing a wake. Nothing is pushed automatically — your managers see only what you push explicitly, so reach for this whenever you want a progress signal to reach them. Use push urgent instead when a manager must see it immediately, push final when the work is actually done.',
-    urgent: 'something your managers must see and act on immediately — you are blocked and need a decision, you hit an error that derails the plan, a discovery changes the scope, or a child reported something that has to travel further up the chain now. Same report mechanism as push update, but it force-wakes every subscriber instead of waiting for them to drain their feed on their own time. Use push update instead for progress that can wait, push final when you are handing back a finished result rather than raising an alarm.',
-    final: 'the work this node was spawned to do is complete and you are ready to hand back the canonical result — this writes that result, marks the node done, and closes its window, so it is the LAST thing you do here, not a progress note. Any node finishes this way. Use push update or push urgent instead while work is still in flight, and do not reach for this on a node working directly with the user: it has no manager to report up to and would close mid-conversation (the guard blocks it unless you pass --force after the user confirms).',
+const PUSH_WHEN_TO_USE = {
+    update: 'you have progress worth surfacing to your managers while work remains in flight. Use normal delivery unless it can wait for their next real wake (--tier deferred) or needs immediate attention (--tier urgent); use push final only when the work is actually done.',
+    final: 'the work this node was spawned to do is complete and you are ready to hand back the canonical result — this writes that result, marks the node done, and closes its window, so it is the LAST thing you do here, not a progress note. Use push update while work is still in flight, and do not reach for final on a node working directly with the user: it has no manager to report up to and would close mid-conversation (the guard blocks it unless you pass --force after the user confirms).',
 };
-function makeTierLeaf(tier) {
+function makePushLeaf(kind) {
     return defineLeaf({
-        name: tier,
-        description: TIER_BLURB[tier],
-        whenToUse: TIER_WHENTOUSE[tier],
+        name: kind,
+        description: PUSH_BLURB[kind],
+        whenToUse: PUSH_WHEN_TO_USE[kind],
         help: {
-            name: `push ${tier}`,
-            summary: TIER_BLURB[tier],
+            name: `push ${kind}`,
+            summary: PUSH_BLURB[kind],
             params: [
                 { kind: 'stdin', name: 'body', required: true, constraint: "Report body (markdown). Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes." },
-                ...(tier === 'final'
-                    ? [{ kind: 'flag', name: 'force', type: 'bool', required: false, default: false, constraint: 'Override the guard that blocks `push final` on a node the user is attending (a resident with no one to report up to). Only pass this after the user explicitly confirms they want this node finished.' }]
-                    : []),
+                ...(kind === 'update'
+                    ? [{ kind: 'flag', name: 'tier', type: 'enum', choices: ['deferred', 'normal', 'urgent'], required: false, default: 'normal', constraint: 'Delivery urgency: deferred holds for the receiver’s next non-deferred wake; normal wakes normally; urgent steers a live receiver and wakes an idle receiver.' }]
+                    : [{ kind: 'flag', name: 'force', type: 'bool', required: false, default: false, constraint: 'Override the guard that blocks `push final` on a node the user is attending (a resident with no one to report up to). Only pass this after the user explicitly confirms they want this node finished.' }]),
             ],
             output: [
                 { name: 'report_path', type: 'string', required: true, constraint: 'Absolute path of the written report.' },
                 { name: 'notified', type: 'string[]', required: true, constraint: 'Subscriber node ids that received an inbox pointer.' },
-                ...(tier === 'final'
+                ...(kind === 'final'
                     ? [
                         { name: 'transitioned', type: 'object', required: false, constraint: 'Present only for a final that flipped the node — { from, to } lifecycle-status transition applied server-side.' },
                         { name: 'worktree_auto_dropped', type: 'boolean', required: false, constraint: 'Present only when this node owned a managed worktree with zero commits ahead of its base and no uncommitted changes — the server auto-dropped it instead of requiring `node worktree close` first (see worktree_auto_dropped_path).' },
@@ -69,9 +66,9 @@ function makeTierLeaf(tier) {
             ],
             outputKind: 'object',
             effects: [
-                'Writes nodes/<nodeId>/reports/<ts>-<tier>.md (server-side).',
+                'Writes nodes/<nodeId>/reports/<ts>-<kind>.md (server-side).',
                 'Appends one inbox pointer per subscriber.',
-                ...(tier === 'final'
+                ...(kind === 'final'
                     ? [
                         'Marks the node done (status + intent) server-side; its engine shuts down on next stop.',
                         'When this node owns a managed worktree with zero commits ahead of its base and no uncommitted changes, the server auto-drops it instead of blocking on `node worktree close`; a worktree with real commits or real uncommitted changes still blocks with open_managed_worktree.',
@@ -96,7 +93,7 @@ function makeTierLeaf(tier) {
             // subscribers was deliberately terminalized to owe a final — it
             // self-completes server-side. This preflight reads the node through the
             // API (NodeDetailDTO), never canvas.db — no state-store reach.
-            if (tier === 'final' && input['force'] !== true) {
+            if (kind === 'final' && input['force'] !== true) {
                 let detail = null;
                 try {
                     detail = await client.getNode(nodeId);
@@ -118,8 +115,13 @@ function makeTierLeaf(tier) {
                 }
             }
             try {
-                const result = await client.pushReport(nodeId, { tier, body });
-                if (tier === 'final')
+                const deliveryTier = input['tier'];
+                const result = await client.pushReport(nodeId, {
+                    tier: kind,
+                    body,
+                    ...(deliveryTier === undefined ? {} : { delivery_tier: deliveryTier }),
+                });
+                if (kind === 'final')
                     markStopSignal(nodeId, 'pushedFinal');
                 return {
                     report_path: result.report_path,
@@ -136,30 +138,27 @@ function makeTierLeaf(tier) {
         },
         render: (r) => {
             const n = Array.isArray(r['notified']) ? r['notified'].length : 0;
-            const line = tier === 'final'
+            const line = kind === 'final'
                 ? 'Result recorded — node finished; its engine shuts down on next stop. Nothing more to do here: STOP your turn immediately. Reply with just "Done." and nothing else.'
-                : tier === 'urgent'
-                    ? `Urgent report fanned to ${n} subscriber(s) — they are force-woken.`
-                    : `Progress report fanned to ${n} subscriber(s).`;
+                : `Progress report fanned to ${n} subscriber(s).`;
             const dropNote = r['worktree_auto_dropped'] === true ? `\n\nAuto-dropped a clean, zero-commit managed worktree at ${String(r['worktree_auto_dropped_path'])} — nothing to land.` : '';
             return `${line}\n\n- report: ${r['report_path']}${dropNote}`;
         },
     });
 }
-// Registration
 export function registerPush() {
     return defineBranch({
         name: 'push',
         rootEntry: {
             concept: 'the one verb up the graph — a node reports to whoever subscribes to it',
-            desc: 'push a report (update / urgent / final) to your subscribers',
+            desc: 'push an update or final report to your subscribers',
             useWhen: 'sharing progress, raising an alert, or finishing your work',
         },
         help: {
             name: 'push',
             summary: 'push a report to your subscribers',
-            model: "A push writes a markdown report to the node's reports/ history and fans a lightweight pointer to every subscriber's inbox. Delivery inlines reports under 1,000 characters with their absolute path; larger reports remain pointers to dereference. Nothing is pushed automatically — the feed contains only what a node pushes explicitly, so push whenever you want a manager to see something. Pipe markdown via a single-quoted heredoc (`crtr push <tier> <<'EOF' … EOF`) so it reaches the report literally. `push final` is how ANY node finishes: write the canonical result, mark done, close the window.",
+            model: "A push writes a markdown report to the node's reports/ history and fans a lightweight pointer to every subscriber's inbox. Delivery inlines reports under 1,000 characters with their absolute path; larger reports remain pointers to dereference. Nothing is pushed automatically — the feed contains only what a node pushes explicitly, so push whenever you want a manager to see something. Pipe markdown via a single-quoted heredoc so it reaches the report literally. `push final` is how ANY node finishes: write the canonical result, mark done, close the window.",
         },
-        children: [makeTierLeaf('update'), makeTierLeaf('urgent'), makeTierLeaf('final')],
+        children: [makePushLeaf('update'), makePushLeaf('final')],
     });
 }