@north-light/crouter 0.3.220 → 0.3.222

package/dist/core/__tests__/serial/broker-sdk-wiring.test.js

@@ -26,9 +26,10 @@ import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../../runtime/broker-sdk.js';
-import { buildBrokerSession, makeBrokerUiContext } from '../../runtime/broker.js';
-import { isLeadingEngineCommand, resolveSteerCall, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, engineLeadingCommandTokens, } from '../../runtime/broker/frame-dispatch.js';
+import { buildBrokerSession, makeBrokerUiContext, snapshotMessages } from '../../runtime/broker.js';
+import { isLeadingEngineCommand, resolveSteerCall, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, promptWithAdvertisedCommandInvocation, isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, engineLeadingCommandTokens, } from '../../runtime/broker/frame-dispatch.js';
 import { CANVAS_EXTENSIONS } from '../../runtime/launch.js';
+import { prepareAdvertisedCommandPersistence } from '../../runtime/advertised-command-invocation.js';
 // The REAL engine, assembled from broker-sdk's static SDK re-exports — bypasses
 // the CRTR_BROKER_ENGINE seam entirely so these tests can never accidentally hit
 // the fake (the whole point: prove the wiring the mock hid).
@@ -403,6 +404,105 @@ test('C5 — isLeadingEngineCommand against a REAL session (registered extension
         rmSync(cwd, { recursive: true, force: true });
     }
 });
+test('an advertised custom command persists its exact raw invocation without replacing expanded agent input', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-advertised-command-'));
+    try {
+        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
+        try {
+            const raw = '/gatewaycmd   exact  spacing  ';
+            await promptWithAdvertisedCommandInvocation(session, raw, () => session.prompt(raw, {}));
+            const custom = session.sessionManager
+                .buildSessionContext()
+                .messages.find((message) => message.role === 'custom' && message.customType === 'fixture-output');
+            assert.deepEqual(custom, {
+                role: 'custom',
+                customType: 'fixture-output',
+                content: 'expanded agent input',
+                display: true,
+                details: { fixture: true },
+                crouterAdvertisedCommandInvocation: { raw },
+                timestamp: custom?.timestamp,
+            });
+            const welcome = snapshotMessages(session);
+            assert.ok(welcome);
+            const welcomeCustom = welcome.filter(({ message }) => message.role === 'custom' && message.customType === 'fixture-output');
+            assert.equal(welcomeCustom.length, 1, 'welcome reconstructs one advertised custom message');
+            assert.deepEqual(welcomeCustom[0].message
+                .crouterAdvertisedCommandInvocation, { raw }, 'welcome preserves the exact advertised invocation spacing');
+            const persisted = session.sessionManager
+                .getEntries()
+                .find((entry) => entry.type === 'custom_message' &&
+                entry.customType === 'fixture-output');
+            assert.equal(persisted?.type, 'custom_message');
+            if (persisted?.type !== 'custom_message')
+                assert.fail('custom message was not persisted');
+            assert.equal(persisted.content, 'expanded agent input');
+            assert.deepEqual(persisted.details, {
+                crouterPersistenceEnvelope: true,
+                crouterAdvertisedCommandInvocation: { raw },
+                extensionDetails: { fixture: true },
+            });
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
+test('advertised invocation metadata survives nextTurn delivery and null content normalization', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-advertised-next-turn-'));
+    try {
+        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
+        try {
+            const rawA = '/gatewaynext  first exact text ';
+            const rawB = '/gatewaynext  second exact text ';
+            for (const raw of [rawA, rawB]) {
+                await promptWithAdvertisedCommandInvocation(session, raw, () => session.prompt(raw, {}));
+            }
+            const pending = session._pendingNextTurnMessages;
+            assert.deepEqual(pending.map((queued) => ({
+                content: queued.content,
+                details: queued.details,
+                invocation: queued.crouterAdvertisedCommandInvocation,
+            })), [
+                {
+                    content: [],
+                    details: 'extension-details',
+                    invocation: { raw: rawA },
+                },
+                {
+                    content: [],
+                    details: 'extension-details',
+                    invocation: { raw: rawB },
+                },
+            ]);
+            // Simulate a queue policy draining B before A. Payload equality cannot
+            // identify them; the app-message metadata must bind each persistence.
+            for (const queued of [pending[1], pending[0]]) {
+                prepareAdvertisedCommandPersistence(session, queued);
+                session.sessionManager.appendCustomMessageEntry(queued.customType, queued.content, queued.display, queued.details);
+            }
+            const restored = session.sessionManager
+                .buildSessionContext()
+                .messages.slice(-2);
+            assert.deepEqual(restored.map((message) => ({
+                details: message.details,
+                invocation: message.crouterAdvertisedCommandInvocation,
+            })), [
+                { details: 'extension-details', invocation: { raw: rawB } },
+                { details: 'extension-details', invocation: { raw: rawA } },
+            ]);
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
 test('C5 — chooseGuidanceDeliveryMode truth table (pure)', () => {
     // idle prompt (routeCall='prompt', not streaming) -> guidance precedes the
     // human call, in the SAME turn.

package/dist/core/bootstrap.js

@@ -14,6 +14,12 @@ function shouldSkipForArgv(argv) {
     const sub = argv[2];
     if (sub === undefined)
         return true;
+    // `sys migrate` converges state that every other read already depends on:
+    // resolving a scope here would read the selected profile through the current
+    // reader (blind to a pre-migration manifest) and could scaffold a cwd scope
+    // the migration then has to treat as real. It owns its own discovery.
+    if (sub === 'sys' && argv[3] === 'migrate')
+        return true;
     return SKIP_SUBCOMMANDS.has(sub);
 }
 export function ensureProjectScope(argv) {

package/dist/core/canvas/browse/app.js

@@ -10,6 +10,7 @@
 import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render-source.js';
+import { fullName } from '../labels.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
 import { loadPins, savePins } from './pins.js';
@@ -483,8 +484,10 @@ export async function runBrowse(opts) {
                 /* best-effort — a rename failure never wedges the picker */
             }
             const n = tree.nodes.get(id);
-            if (n !== undefined)
-                n.row.name = name;
+            if (n !== undefined) {
+                n.row.handle = name;
+                n.row.name = fullName({ name, kind: n.row.kind, description: n.row.description });
+            }
         }
         recompute(state.renameTarget ?? undefined);
         scheduleFlush();

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

@@ -70,11 +70,8 @@ export interface SnippetLine {
     text: string;
     hi: Set<number>;
 }
-/** Highlight indices for the preview: the literal case-insensitive SUBSTRING span
- *  when present (so "where does this text appear?" is answered exactly), else the
- *  scattered subsequence indices, else empty (empty query). This is a different,
- *  stricter model than the subsequence super-search on purpose — a contiguous span
- *  is what reads as a highlight. */
+/** The literal case-insensitive substring span in a conversation preview.
+ *  Scattered letters are not a message match and never receive a highlight. */
 export declare function highlightIndices(query: string, text: string): Set<number>;
 /**
  * Build the preview snippet for `text` under the live `query`: up to `maxLines`
@@ -91,17 +88,27 @@ export declare function previewSnippet(query: string, text: string, width: numbe
  *  windowed in the preview, so search matches a prompt from ANYWHERE in the
  *  conversation, not just the first one. */
 export declare function promptText(row: DashboardRow): string;
-/** Does this row match the live query? Super-search spans name (which already
- *  folds in the pi-generated description), kind, short-id, AND every user prompt
- *  in the conversation (`promptText`). Empty query matches everything. */
+/** Does this row match the live query? Empty query matches everything; a
+ *  non-empty query uses the same fields and match tiers as relevance ranking. */
 export declare function queryMatch(query: string, row: DashboardRow): boolean;
-/** Score how well `query` matches one field, 0 (no match) → 1 (exact). Tiers:
- *  exact > prefix > word-boundary substring > interior substring > subsequence.
- *  An interior match decays slightly the later it starts so leading matches win. */
-export declare function fieldScore(query: string, text: string): number;
-/** Weighted relevance of a row to the query across all searched fields. 0 means
- *  no field matched (excluded from relevance results, same as `queryMatch`). */
-export declare function scoreRow(query: string, row: DashboardRow): number;
+export type MatchTier = 0 | 1 | 2 | 3;
+export interface FieldMatch {
+    /** 3 = bounded word/phrase, 2 = contiguous partial, 1 = subsequence. */
+    tier: MatchTier;
+    /** Tie-break quality within one tier. */
+    quality: number;
+}
+export interface RelevanceScore {
+    tier: MatchTier;
+    strength: number;
+}
+/** One field's best match. Match class is deliberately separate from quality:
+ *  a bounded literal always outranks a contiguous partial, which always outranks
+ *  a scattered subsequence, regardless of field weights. */
+export declare function fieldMatch(query: string, text: string): FieldMatch;
+/** Rank a row by its strongest match class, then by weighted evidence only from
+ *  that class. Weaker classes cannot add up to beat one stronger literal match. */
+export declare function scoreRow(query: string, row: DashboardRow): RelevanceScore;
 /** The "most recent message" signal for the attention sort: the pi session-file
  *  mtime (ms) the snapshot stamps on each row, falling back to the `created`
  *  birth timestamp when no session file exists. Larger = more recent.
@@ -111,6 +118,9 @@ export declare function scoreRow(query: string, row: DashboardRow): number;
  *  update this single accessor. `created` is ISO 8601, so its epoch-ms is a
  *  monotonic stand-in within the same tier. */
 export declare function attentionMtime(row: DashboardRow): number;
+/** Up to a 10% relevance lift for recent conversation activity, halving after a
+ *  week. Match tier remains separate, so freshness never promotes fuzzy over literal. */
+export declare function relevanceFreshness(row: DashboardRow, now: number): number;
 /** Attention tier (lower = higher priority, shown first):
  *    T0 — attached AND streaming (`viewed && streaming`)
  *    T1 — attached, not streaming (`viewed`)

package/dist/core/canvas/browse/model.js

@@ -160,24 +160,18 @@ export function matchIndices(query, text) {
 }
 /** Chars of leading context kept before the match start when windowing. */
 const SNIPPET_LEAD = 12;
-/** Highlight indices for the preview: the literal case-insensitive SUBSTRING span
- *  when present (so "where does this text appear?" is answered exactly), else the
- *  scattered subsequence indices, else empty (empty query). This is a different,
- *  stricter model than the subsequence super-search on purpose — a contiguous span
- *  is what reads as a highlight. */
+/** The literal case-insensitive substring span in a conversation preview.
+ *  Scattered letters are not a message match and never receive a highlight. */
 export function highlightIndices(query, text) {
     if (query === '')
         return new Set();
-    const lower = text.toLowerCase();
-    const q = query.toLowerCase();
-    const sub = lower.indexOf(q);
-    if (sub >= 0) {
-        const out = new Set();
-        for (let i = sub; i < sub + q.length; i++)
-            out.add(i);
-        return out;
-    }
-    return matchIndices(query, text);
+    const sub = text.toLowerCase().indexOf(query.toLowerCase());
+    if (sub < 0)
+        return new Set();
+    const out = new Set();
+    for (let i = sub; i < sub + query.length; i++)
+        out.add(i);
+    return out;
 }
 /** Greedy word-wrap of single-spaced `s` (caller normalizes whitespace) to `width`
  *  cols × `maxLines` lines, returning each line's text AND its start offset in `s`.
@@ -233,17 +227,7 @@ export function previewSnippet(query, text, width, maxLines) {
         return [];
     // 1. Locate the match in the normalized text + choose a window start that keeps
     //    a little leading context, snapped to a word boundary.
-    let matchStart = -1;
-    if (query !== '') {
-        const sub = norm.toLowerCase().indexOf(query.toLowerCase());
-        if (sub >= 0)
-            matchStart = sub;
-        else {
-            const ix = matchIndices(query, norm);
-            if (ix.size > 0)
-                matchStart = Math.min(...ix);
-        }
-    }
+    const matchStart = query === '' ? -1 : norm.toLowerCase().indexOf(query.toLowerCase());
     let windowStart = 0;
     if (matchStart > SNIPPET_LEAD) {
         let s = matchStart - SNIPPET_LEAD;
@@ -274,52 +258,69 @@ function shortId(id) {
 export function promptText(row) {
     return row.prompts ?? row.goal ?? '';
 }
-/** Does this row match the live query? Super-search spans name (which already
- *  folds in the pi-generated description), kind, short-id, AND every user prompt
- *  in the conversation (`promptText`). Empty query matches everything. */
+/** Does this row match the live query? Empty query matches everything; a
+ *  non-empty query uses the same fields and match tiers as relevance ranking. */
 export function queryMatch(query, row) {
-    if (query === '')
-        return true;
-    const prompt = promptText(row);
-    return (fuzzyMatch(query, row.name) ||
-        fuzzyMatch(query, row.kind) ||
-        fuzzyMatch(query, shortId(row.node_id)) ||
-        (prompt !== '' && fuzzyMatch(query, prompt)));
+    return query === '' || scoreRow(query, row).tier > 0;
 }
-// ---------------------------------------------------------------------------
-// Relevance scoring (super-search)
-// ---------------------------------------------------------------------------
-/** Score how well `query` matches one field, 0 (no match) → 1 (exact). Tiers:
- *  exact > prefix > word-boundary substring > interior substring > subsequence.
- *  An interior match decays slightly the later it starts so leading matches win. */
-export function fieldScore(query, text) {
+const NO_MATCH = { tier: 0, quality: 0 };
+const WORD_CHAR = /[\p{L}\p{N}]/u;
+function isWordChar(char) {
+    return char !== undefined && WORD_CHAR.test(char);
+}
+/** One field's best match. Match class is deliberately separate from quality:
+ *  a bounded literal always outranks a contiguous partial, which always outranks
+ *  a scattered subsequence, regardless of field weights. */
+export function fieldMatch(query, text) {
     if (query === '' || text === '')
-        return 0;
+        return NO_MATCH;
     const q = query.toLowerCase();
     const t = text.toLowerCase();
-    const idx = t.indexOf(q);
-    if (idx === 0)
-        return t.length === q.length ? 1 : 0.85; // exact | prefix
-    if (idx > 0) {
-        const prev = t[idx - 1] ?? '';
-        const boundary = /[\s_\-/.:]/.test(prev) ? 0.1 : 0; // word-boundary bonus
-        return 0.55 + boundary - Math.min(0.2, idx / 400); // interior, decays late
+    const firstIdx = t.indexOf(q);
+    if (firstIdx >= 0) {
+        for (let idx = firstIdx; idx >= 0; idx = t.indexOf(q, idx + 1)) {
+            const end = idx + q.length;
+            const leftBounded = !isWordChar(q[0]) || !isWordChar(t[idx - 1]);
+            const rightBounded = !isWordChar(q[q.length - 1]) || !isWordChar(t[end]);
+            if (leftBounded && rightBounded)
+                return { tier: 3, quality: t === q ? 1 : 0.95 };
+        }
+        const position = Math.min(0.2, firstIdx / 400);
+        return { tier: 2, quality: (firstIdx === 0 ? 1 : 0.8) - position };
     }
-    return fuzzyMatch(q, t) ? 0.2 : 0; // scattered subsequence
+    const indices = [...matchIndices(q, t)];
+    if (indices.length === 0)
+        return NO_MATCH;
+    const span = indices[indices.length - 1] - indices[0] + 1;
+    return { tier: 1, quality: q.length / span };
+}
+/** Explicit handles and user prompts are primary. The generated description is
+ *  searchable but lower-weight; assistant replies are preview-only. */
+const FIELD_WEIGHTS = { handle: 4, prompt: 4, kind: 2, description: 1.5, id: 1 };
+function explicitHandle(row) {
+    const handle = row.handle ?? row.name;
+    return handle === row.kind ? '' : handle;
 }
-/** Per-field weights — name (handle + description) dominates, the conversation
- *  prompts are the long-tail super-search field. */
-const FIELD_WEIGHTS = { name: 4, kind: 2, id: 1, prompt: 1.5 };
-/** Weighted relevance of a row to the query across all searched fields. 0 means
- *  no field matched (excluded from relevance results, same as `queryMatch`). */
+/** Rank a row by its strongest match class, then by weighted evidence only from
+ *  that class. Weaker classes cannot add up to beat one stronger literal match. */
 export function scoreRow(query, row) {
     if (query === '')
-        return 0;
-    const prompt = promptText(row);
-    return (FIELD_WEIGHTS.name * fieldScore(query, row.name) +
-        FIELD_WEIGHTS.kind * fieldScore(query, row.kind) +
-        FIELD_WEIGHTS.id * fieldScore(query, shortId(row.node_id)) +
-        FIELD_WEIGHTS.prompt * (prompt !== '' ? fieldScore(query, prompt) : 0));
+        return { tier: 0, strength: 0 };
+    const fields = [
+        { text: explicitHandle(row), weight: FIELD_WEIGHTS.handle, minimumTier: 1 },
+        // Scattered subsequences in long messages are random noise, not matches.
+        { text: promptText(row), weight: FIELD_WEIGHTS.prompt, minimumTier: 2 },
+        { text: row.kind, weight: FIELD_WEIGHTS.kind, minimumTier: 1 },
+        { text: row.description ?? '', weight: FIELD_WEIGHTS.description, minimumTier: 1 },
+        { text: shortId(row.node_id), weight: FIELD_WEIGHTS.id, minimumTier: 1 },
+    ];
+    const matches = fields.map(({ text, weight, minimumTier }) => {
+        const match = fieldMatch(query, text);
+        return { match: match.tier >= minimumTier ? match : NO_MATCH, weight };
+    });
+    const tier = Math.max(...matches.map(({ match }) => match.tier));
+    const strength = matches.reduce((sum, { match, weight }) => sum + (match.tier === tier ? match.quality * weight : 0), 0);
+    return { tier, strength };
 }
 // ---------------------------------------------------------------------------
 // Attention tiering (default sort)
@@ -339,6 +340,14 @@ export function attentionMtime(row) {
     const t = Date.parse(row.created);
     return Number.isFinite(t) ? t : 0;
 }
+const RELEVANCE_RECENCY_MAX_BOOST = 0.1;
+const RELEVANCE_RECENCY_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Up to a 10% relevance lift for recent conversation activity, halving after a
+ *  week. Match tier remains separate, so freshness never promotes fuzzy over literal. */
+export function relevanceFreshness(row, now) {
+    const age = Math.max(0, now - attentionMtime(row));
+    return 1 + RELEVANCE_RECENCY_MAX_BOOST / (1 + age / RELEVANCE_RECENCY_HALF_LIFE_MS);
+}
 /** Attention tier (lower = higher priority, shown first):
  *    T0 — attached AND streaming (`viewed && streaming`)
  *    T1 — attached, not streaming (`viewed`)
@@ -427,9 +436,21 @@ export function flatten(tree, opts) {
         }
         else {
             const score = new Map();
+            const rowOf = (id) => tree.nodes.get(id).row;
+            const now = Date.now();
             for (const id of ids)
-                score.set(id, scoreRow(query, tree.nodes.get(id).row));
-            ids.sort((a, b) => (pinRank(a) - pinRank(b)) || (score.get(b) - score.get(a)) || byRecency(a, b));
+                score.set(id, scoreRow(query, rowOf(id)));
+            ids.sort((a, b) => {
+                const aScore = score.get(a);
+                const bScore = score.get(b);
+                const aStrength = aScore.strength * relevanceFreshness(rowOf(a), now);
+                const bStrength = bScore.strength * relevanceFreshness(rowOf(b), now);
+                return (pinRank(a) - pinRank(b))
+                    || (bScore.tier - aScore.tier)
+                    || (bStrength - aStrength)
+                    || (attentionMtime(rowOf(b)) - attentionMtime(rowOf(a)))
+                    || byRecency(a, b);
+            });
         }
         return ids.map((id) => ({ id, depth: 0, hasChildren: false, collapsed: false, matched: true }));
     }

package/dist/core/canvas/db.js

@@ -1153,6 +1153,28 @@ ALTER TABLE crons ADD COLUMN held INTEGER NOT NULL DEFAULT 0;
 ALTER TABLE crons ADD COLUMN last_poke_at TEXT;
 `);
 }
+/** v33 — durable, daemon-owned attempts to deliver settled human completions. */
+function addHumanActionDeliveries(db) {
+    db.exec(`
+CREATE TABLE human_action_deliveries (
+  request_id           TEXT PRIMARY KEY,
+  state                TEXT NOT NULL,
+  attempt              INTEGER NOT NULL DEFAULT 0,
+  argv_json            TEXT NOT NULL,
+  cwd                  TEXT NOT NULL,
+  completion_json      TEXT NOT NULL,
+  next_attempt_at      INTEGER NOT NULL,
+  claimed_at           INTEGER,
+  claim_owner          TEXT,
+  accepted_at          INTEGER,
+  permanent_failed_at  INTEGER,
+  last_failure_json    TEXT,
+  created_at           INTEGER NOT NULL,
+  updated_at           INTEGER NOT NULL
+);
+CREATE INDEX idx_human_action_deliveries_due ON human_action_deliveries(state, next_attempt_at);
+`);
+}
 /** The journaled lane of the state-migration registry, adapted to this chain's
  *  step shape. Registry order is preserved, so these versions stay stable as
  *  long as the registry is append-only (same contract as the local list). */
@@ -1198,6 +1220,7 @@ export const MIGRATIONS = [
     /* v30 */ dropConsultOutbox,
     /* v31 */ addReviewSubmitRequested,
     /* v32 */ addCronHeldColumns,
+    /* v33 */ addHumanActionDeliveries,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not

package/dist/core/canvas/human-deliveries.d.ts

@@ -0,0 +1,53 @@
+export type ActionDeliveryState = 'pending' | 'running' | 'accepted' | 'permanent_failed';
+export interface ActionDeliveryFailure {
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    exitCode?: number;
+    signal?: string;
+    message?: string;
+    stderr?: string;
+}
+export interface ActionDeliveryRecord {
+    requestId: string;
+    state: ActionDeliveryState;
+    attempt: number;
+    argv: string[];
+    cwd: string;
+    completion: unknown;
+    nextAttemptAt: number;
+    claimedAt: number | null;
+    claimOwner: string | null;
+    acceptedAt: number | null;
+    permanentFailedAt: number | null;
+    lastFailure: ActionDeliveryFailure | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Insert the one delivery row for a settled action-bound request. Idempotent
+ *  on requestId: a replayed settlement must not create a second row. */
+export declare function enqueueActionDelivery(row: {
+    requestId: string;
+    argv: string[];
+    cwd: string;
+    /** Complete HumanCompletionV1 with delivery.attempt set to 0. */
+    completion: unknown;
+}): void;
+/** Delivery state for `GET /v1/human/requests/:id`; null when no row exists. */
+export declare function readActionDelivery(requestId: string): ActionDeliveryRecord | null;
+/** Due pending records in deterministic order for the daemon's serial tick. */
+export declare function dueActionDeliveries(now: number): ActionDeliveryRecord[];
+/** Atomically start one due delivery attempt. A null result lost the claim. */
+export declare function claimActionDelivery(requestId: string, now: number, claimOwner: string): ActionDeliveryRecord | null;
+export type ActionDeliverySettlement = {
+    state: 'accepted';
+} | {
+    state: 'permanent_failed';
+    failure: ActionDeliveryFailure;
+} | {
+    state: 'pending';
+    nextAttemptAt: number;
+    failure: ActionDeliveryFailure;
+};
+/** Settle only the still-owned running attempt, so a stale process cannot overwrite a newer claim. */
+export declare function settleActionDelivery(requestId: string, attempt: number, claimOwner: string, settlement: ActionDeliverySettlement, now: number): boolean;
+/** A new daemon deliberately redelivers interrupted completions at least once. */
+export declare function recoverRunningActionDeliveries(now: number): number;

package/dist/core/canvas/human-deliveries.js

@@ -0,0 +1,75 @@
+// Durable action-completion delivery state. The terminal ticket is composed
+// before this row exists; this module schedules its already-complete document.
+import { openDb, withCanvasWrite } from './db.js';
+function actionDeliveryFrom(row) {
+    return {
+        requestId: row.request_id,
+        state: row.state,
+        attempt: row.attempt,
+        argv: JSON.parse(row.argv_json),
+        cwd: row.cwd,
+        completion: JSON.parse(row.completion_json),
+        nextAttemptAt: row.next_attempt_at,
+        claimedAt: row.claimed_at,
+        claimOwner: row.claim_owner,
+        acceptedAt: row.accepted_at,
+        permanentFailedAt: row.permanent_failed_at,
+        lastFailure: row.last_failure_json === null ? null : JSON.parse(row.last_failure_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/** Insert the one delivery row for a settled action-bound request. Idempotent
+ *  on requestId: a replayed settlement must not create a second row. */
+export function enqueueActionDelivery(row) {
+    const now = Date.now();
+    withCanvasWrite((db) => {
+        db.prepare(`INSERT INTO human_action_deliveries
+        (request_id, state, attempt, argv_json, cwd, completion_json, next_attempt_at, created_at, updated_at)
+       VALUES (?, 'pending', 0, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(request_id) DO NOTHING`).run(row.requestId, JSON.stringify(row.argv), row.cwd, JSON.stringify(row.completion), now, now, now);
+    });
+}
+/** Delivery state for `GET /v1/human/requests/:id`; null when no row exists. */
+export function readActionDelivery(requestId) {
+    const row = openDb()
+        .prepare('SELECT * FROM human_action_deliveries WHERE request_id = ?')
+        .get(requestId);
+    return row === undefined ? null : actionDeliveryFrom(row);
+}
+/** Due pending records in deterministic order for the daemon's serial tick. */
+export function dueActionDeliveries(now) {
+    return openDb()
+        .prepare(`SELECT * FROM human_action_deliveries
+         WHERE state = 'pending' AND next_attempt_at <= ?
+         ORDER BY next_attempt_at, created_at, request_id`)
+        .all(now).map(actionDeliveryFrom);
+}
+/** Atomically start one due delivery attempt. A null result lost the claim. */
+export function claimActionDelivery(requestId, now, claimOwner) {
+    return withCanvasWrite((db) => {
+        const claimed = db.prepare(`UPDATE human_action_deliveries
+       SET state = 'running', attempt = attempt + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+       WHERE request_id = ? AND state = 'pending' AND next_attempt_at <= ?`).run(now, claimOwner, now, requestId, now);
+        if (Number(claimed.changes) === 0)
+            return null;
+        const row = db.prepare('SELECT * FROM human_action_deliveries WHERE request_id = ?').get(requestId);
+        return actionDeliveryFrom(row);
+    });
+}
+/** Settle only the still-owned running attempt, so a stale process cannot overwrite a newer claim. */
+export function settleActionDelivery(requestId, attempt, claimOwner, settlement, now) {
+    const failure = settlement.state === 'accepted' ? null : JSON.stringify(settlement.failure);
+    const result = withCanvasWrite((db) => db.prepare(`UPDATE human_action_deliveries
+     SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+         accepted_at = ?, permanent_failed_at = ?, last_failure_json = ?, updated_at = ?
+     WHERE request_id = ? AND state = 'running' AND attempt = ? AND claim_owner = ?`).run(settlement.state, settlement.state === 'pending' ? settlement.nextAttemptAt : now, settlement.state === 'accepted' ? now : null, settlement.state === 'permanent_failed' ? now : null, failure, now, requestId, attempt, claimOwner));
+    return Number(result.changes) === 1;
+}
+/** A new daemon deliberately redelivers interrupted completions at least once. */
+export function recoverRunningActionDeliveries(now) {
+    const result = withCanvasWrite((db) => db.prepare(`UPDATE human_action_deliveries
+     SET state = 'pending', next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL, updated_at = ?
+     WHERE state = 'running'`).run(now, now));
+    return Number(result.changes);
+}

package/dist/core/canvas/render-source.d.ts

@@ -16,7 +16,13 @@ export declare function renderTreeFromSource(source: CanvasSource, rootId: strin
 export declare function renderForestFromSource(source: CanvasSource): Promise<string>;
 export interface DashboardRow {
     node_id: string;
+    /** Full display label: explicit handle plus generated description. */
     name: string;
+    /** Explicit node handle, kept separate so search does not treat generated text
+     *  as part of the higher-weight name field. */
+    handle?: string;
+    /** Generated first-task description. Searchable below user-authored prompts. */
+    description?: string;
     status: NodeStatus;
     kind: string;
     mode: string;

package/dist/core/canvas/render-source.js

@@ -366,6 +366,7 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
     return {
         node_id: row.node_id,
         name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
+        handle: row.name,
         status: row.status,
         kind: row.kind,
         mode: row.mode,
@@ -399,6 +400,8 @@ export async function dashboardRowsFromSource(source, rootId) {
         rows.push({
             node_id: id,
             name: fullName(node),
+            handle: node.name,
+            description: node.description,
             status: node.status,
             kind: node.kind,
             mode: node.mode,
@@ -440,8 +443,11 @@ export async function enrichRowsFromSource(source, rows, asks) {
     // the client's cold-daemon path even though the daemon is still running.
     for (const row of todo) {
         const meta = await source.getNode(row.node_id);
-        if (meta !== null)
+        if (meta !== null) {
             row.name = fullName(meta);
+            row.handle = meta.name;
+            row.description = meta.description;
+        }
         row.ctx_tokens = remote ? 0 : (readNodeTelemetry(row.node_id).tokens_in ?? 0);
         row.asks = askMap[row.node_id] ?? 0;
         row.enriched = true;