@north-light/crouter 0.3.198 → 0.3.199

package/dist/core/__tests__/session-cycles.test.js

@@ -105,3 +105,25 @@ test('cycleAwareMessages: a yielded cycle keeps terminal assistant content witho
     assert.equal(yieldedAssistant.errorMessage, undefined, 'the provider abort text is omitted with the yield boundary');
     assert.equal(out.filter((message) => message.customType === 'crtr-cycle-divider').length, 1);
 });
+// Observed shape: the yield's self-abort landed as the NEXT request was
+// starting, so the provider caught a bare AbortError instead of seeing its own
+// signal and stamped `stopReason: 'error'` on an empty turn. Pi's assistant
+// component reserves a red `Error: …` line for exactly that stopReason, so the
+// annotation must come off here too — a yield is not a failure.
+test('cycleAwareMessages: a yield abort recorded as a provider error is still not a failed turn', () => {
+    const m1 = userMsg('m1', null, 'yield after this turn');
+    const m2 = assistantMsg('m2', 'm1', [], 'error', 'This operation was aborted');
+    const cy1 = {
+        type: 'custom',
+        id: 'cy1',
+        parentId: null,
+        timestamp: new Date(1).toISOString(),
+        customType: CRTR_CYCLE_CUSTOM_TYPE,
+        data: { cycle: 2, fromLeaf: 'm2' },
+    };
+    const m3 = userMsg('m3', 'cy1', 'fresh cycle');
+    const out = cycleAwareMessages(cycleManager([m1, m2, cy1, m3], 'm3'));
+    const yieldedAssistant = out.find((message) => message.role === 'assistant');
+    assert.equal(yieldedAssistant.stopReason, undefined, 'yield is not presented as a failed assistant turn');
+    assert.equal(yieldedAssistant.errorMessage, undefined, 'the aborted-request text is omitted with the yield boundary');
+});

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

@@ -28,7 +28,7 @@ function node(id, over = {}) {
         ...over,
     };
 }
-const noSignals = { pushedFinal: false, askedHuman: false };
+const noSignals = { pushedFinal: false, requestedHumanReply: false };
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-stopguard-'));
     process.env['CRTR_HOME'] = home;
@@ -132,10 +132,10 @@ test('a TERMINAL node whose only worker is dead is stalled (no LIVE subscription
     assert.equal(d.action, 'reprompt');
     assert.equal(d.reason, 'stalled');
 });
-test('pushedFinal → finished; askedHuman → escalated (both short-circuit before lifecycle)', () => {
+test('pushedFinal → finished; requestedHumanReply → escalated (both short-circuit before lifecycle)', () => {
     createNode(node('t', { parent: 'mgr', lifecycle: 'terminal' }));
-    assert.deepEqual(evaluateStop('t', { pushedFinal: true, askedHuman: false }), { action: 'allow', reason: 'finished' });
-    assert.deepEqual(evaluateStop('t', { pushedFinal: false, askedHuman: true }), { action: 'allow', reason: 'escalated' });
+    assert.deepEqual(evaluateStop('t', { pushedFinal: true, requestedHumanReply: false }), { action: 'allow', reason: 'finished' });
+    assert.deepEqual(evaluateStop('t', { pushedFinal: false, requestedHumanReply: true }), { action: 'allow', reason: 'escalated' });
 });
 test('an active follow-up cycle with a canonical final is allowed without another final', () => {
     createNode(node('followUp', {

package/dist/core/__tests__/watchdog-abort-arms-retry.test.js

@@ -14,7 +14,7 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
 });
 test('only a watchdog-stamped aborted settlement records an automatic connection fault', () => {
-    const settleAbort = (nodeId, stagedWatchdogAbort) => {
+    const settleAbort = (nodeId, stagedWatchdogAbort, stagedRefreshAbort, stopReason = 'aborted') => {
         const session = {
             sessionManager: { getLeafId: () => 'leaf-entry' },
             model: undefined,
@@ -24,9 +24,14 @@ test('only a watchdog-stamped aborted settlement records an automatic connection
             session,
             fallback: { blocked: false },
             stagedProviderAgentEnd: {
-                messages: [{ role: 'assistant', stopReason: 'aborted', errorMessage: 'Request was aborted' }],
+                messages: [{
+                        role: 'assistant',
+                        stopReason,
+                        errorMessage: stopReason === 'error' ? 'This operation was aborted' : 'Request was aborted',
+                    }],
             },
             stagedWatchdogAbort,
+            stagedRefreshAbort,
             stagedOverflowFailure: null,
             executingTools: new Set(),
         };
@@ -38,15 +43,24 @@ test('only a watchdog-stamped aborted settlement records an automatic connection
         retry.publishSettledProviderFault(generation);
         return { retry, generation };
     };
-    const watchdog = settleAbort('watchdog-node', true);
+    const watchdog = settleAbort('watchdog-node', true, false);
     const fault = readFault('watchdog-node');
     assert.equal(fault?.link, 'pi→provider');
     assert.equal(fault?.kind, 'connection');
     assert.deepEqual(fault?.retry, { disposition: 'auto', by: 'daemon' });
     assert.equal(watchdog.retry.isActiveAutoFault(fault), true);
     assert.equal(watchdog.generation.stagedWatchdogAbort, false, 'settlement consumes the one-shot provenance');
-    settleAbort('human-node', false);
+    settleAbort('human-node', false, false);
     assert.equal(readFault('human-node'), null, 'an otherwise-identical human abort must not arm recovery');
+    // Pi 0.84 currently serializes a host abort from `node yield` as an `error`
+    // settlement. Only the refresh-abort provenance suppresses that provider-looking error.
+    const refresh = settleAbort('refresh-node', false, true, 'error');
+    assert.equal(readFault('refresh-node'), null, 'a refresh-aborted error settlement must not enter provider fault recovery');
+    assert.equal(refresh.generation.stagedRefreshAbort, false, 'settlement consumes the one-shot refresh provenance');
+    settleAbort('provider-node', false, false, 'error');
+    const providerFault = readFault('provider-node');
+    assert.equal(providerFault?.kind, 'other', 'the same provider error without refresh provenance still classifies');
+    assert.deepEqual(providerFault?.retry, { disposition: 'fatal' }, 'the same provider error without refresh provenance still records its fault');
 });
 test('a failed retry settlement carries the episode forward instead of restarting it', () => {
     // The episode marker a daemon retry records before re-prompting: original
@@ -68,6 +82,7 @@ test('a failed retry settlement carries the episode forward instead of restartin
             messages: [{ role: 'assistant', stopReason: 'error', errorMessage: 'fetch failed' }],
         },
         stagedWatchdogAbort: false,
+        stagedRefreshAbort: false,
         stagedOverflowFailure: null,
         executingTools: new Set(),
     };

package/dist/core/bash-jobs.d.ts

@@ -77,6 +77,12 @@ export declare function jobStartedAtMs(jobId: string): number | undefined;
  * notice, the `node bash background` result/toast, and the attach cockpit)
  * shows it: `<60s -> "12s"`; `60s-59m -> "3m 40s"`; `>=60m -> "1h 04m"`. */
 export declare function formatBashElapsed(ms: number): string;
+/** The command line worth SHOWING for a job. `cmd.sh` opens with the harness's
+ * injected environment preamble (`export CRTR_PREVIEW_RESULT_PATH=…`), so its
+ * literal first line names no command at all: skip leading assignment lines and
+ * return the first real one, whitespace-collapsed to a single line. A job whose
+ * command is nothing but assignments falls back to its first non-empty line. */
+export declare function bashJobCommandLine(command: string): string;
 export interface BashJobStatus {
     jobId: string;
     /** Full text of cmd.sh. */

package/dist/core/bash-jobs.js

@@ -189,6 +189,16 @@ export function formatBashElapsed(ms) {
     const minutes = totalMinutes % 60;
     return `${hours}h ${String(minutes).padStart(2, '0')}m`;
 }
+/** The command line worth SHOWING for a job. `cmd.sh` opens with the harness's
+ * injected environment preamble (`export CRTR_PREVIEW_RESULT_PATH=…`), so its
+ * literal first line names no command at all: skip leading assignment lines and
+ * return the first real one, whitespace-collapsed to a single line. A job whose
+ * command is nothing but assignments falls back to its first non-empty line. */
+export function bashJobCommandLine(command) {
+    const lines = command.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+    const real = lines.find((line) => !/^(export\s+)?[A-Za-z_][A-Za-z0-9_]*=/.test(line));
+    return (real ?? lines[0] ?? '').replace(/\s+/g, ' ');
+}
 /** Every live backgrounded bash job for this node — job.bg present, job.exit
  * absent — whether handed off by the menu, the valve deadline, or broker
  * termination. Read-only; never mutates. Skips malformed/partially-written

package/dist/core/canvas/__tests__/attention.test.js

@@ -4,7 +4,7 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { atomicWriteJson, pageManifestPath } from '../../human/convention.js';
+import { atomicWriteJson, bindTicketReplyRoute, pageManifestPath } from '../../human/convention.js';
 import { createNode } from '../canvas.js';
 import { closeDb } from '../db.js';
 import { nodeDir } from '../paths.js';
@@ -22,16 +22,19 @@ function meta(id, cwd, extra) {
         ...extra,
     };
 }
+// A ticket only counts as attention when it routes a reply back, so the fixture binds
+// the reply route the same way `human send` does before writing the page manifest.
 function seedPage(bridgeId) {
     const dir = nodeDir(bridgeId);
     mkdirSync(dir, { recursive: true });
+    bindTicketReplyRoute(dir, bridgeId);
     atomicWriteJson(pageManifestPath(dir), {
-        schema: 'crtr.page/v1',
-        dialect: 'html',
+        schema: 'crtr.page/v2',
+        dialect: 'jsx',
         title: bridgeId,
         subtitle: 'Acknowledge this ticket so the request can proceed.',
-        placement: 'inline',
-        document: 'page.html',
+        delivery: { placement: 'inline', inbox: true, reply: true },
+        document: 'page.tsx',
         steps: 1,
         slots: [],
     });

package/dist/core/canvas/__tests__/render-remote.test.js

@@ -8,7 +8,7 @@
 // This is adversarial, not merely a clean-machine assertion: BEFORE calling
 // the render functions, the test seeds real, CONFLICTING local state for the
 // same node id `a` (a local focus, an active fault, telemetry, a goal file, a
-// session transcript, and a pending human ask) — every historically-broken
+// session transcript, and a pending human reply) — every historically-broken
 // local read this suppression covers. If the production suppression ever
 // regressed back to consulting local disk/SQLite for a remote source, the
 // assertions below would observe the poisoned values instead of the safe
@@ -114,12 +114,12 @@ function seedPoisonedLocalState() {
     const askDir = nodeDir('poison-ask');
     mkdirSync(askDir, { recursive: true });
     atomicWriteJson(pageManifestPath(askDir), {
-        schema: 'crtr.page/v1',
-        dialect: 'html',
+        schema: 'crtr.page/v2',
+        dialect: 'jsx',
         title: 'poison',
         subtitle: 'This local ticket must not affect the remote rendering.',
-        placement: 'inline',
-        document: 'page.html',
+        delivery: { placement: 'inline', inbox: true, reply: true },
+        document: 'page.tsx',
         steps: 1,
         slots: [],
     });

package/dist/core/canvas/attention.js

@@ -1,15 +1,17 @@
 // attention.ts — pending human-ticket counters across the canvas.
 //
-// Every ticket is a direct child of the single registered `<canvas>/nodes` root,
-// named for its terminal human bridge node. The bridge's parent is the asking
-// node, so storage identity and attribution come from the canvas graph rather
-// than duplicated attribution fields in page/review data.
-import { basename } from 'node:path';
+// Reply-bearing tickets carry an explicit bridge route. The bridge's parent is
+// the asking node; standalone pages have no bridge and do not contribute to a
+// node's pending-reply count.
 import { scanInbox } from '../human/scan.js';
 import { filterTerminalReviewTickets } from '../review/ticket-filter.js';
+import { readTicketReplyRoute } from '../human/convention.js';
 import { getNode, listNodes, view } from './canvas.js';
 function askingNodeId(ticketDir) {
-    const bridge = getNode(basename(ticketDir));
+    const replyRoute = readTicketReplyRoute(ticketDir);
+    if (replyRoute === null)
+        return null;
+    const bridge = getNode(replyRoute.bridge_node_id);
     if (bridge === null)
         return null;
     return bridge.parent ?? bridge.node_id;

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

@@ -11,8 +11,14 @@ export type SortMode = 'tree' | 'attention' | 'relevance' | 'recency';
 export declare const SORTS: readonly SortMode[];
 /** Does a node belong to this tab's slice?
  *    All       — every node.
- *    Live      — active | idle.
- *    Dormant   — done | dead | canceled.
+ *    Live      — what you can pick up right now: active | idle, PLUS a resident
+ *                agent that stopped without finishing (its broker exited, but
+ *                Enter resumes the conversation in place — see `isFinishedWork`).
+ *                Finished work never appears here.
+ *    Dormant   — done | dead | canceled: literally "no engine running". A stopped
+ *                resident agent is deliberately on BOTH tabs — it is resumable
+ *                (Live) and it is not running (Dormant); both are true and each
+ *                tab is the one a different search starts from.
  *    Attention — needs a human: has pending asks OR is parked on a fault.
  *    Pinned    — user-starred (a local, view-only preference; `isPinned`). */
 export declare function tabPredicate(tab: Tab, row: DashboardRow, isPinned?: boolean): boolean;

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

@@ -4,19 +4,26 @@
 // it is exhaustively unit-testable. The app layer (app.ts) wires the canvas data
 // access (dashboardRowsAll / listNodes / subscriptionsOf) into buildTree, then
 // drives flatten() on each keystroke.
-import { statusRank } from '../node-order.js';
+import { isFinishedWork, isLiveStatus, statusRank } from '../node-order.js';
 export const TABS = ['All', 'Live', 'Dormant', 'Attention', 'Pinned'];
 export const SORTS = ['tree', 'attention', 'relevance', 'recency'];
 /** Does a node belong to this tab's slice?
  *    All       — every node.
- *    Live      — active | idle.
- *    Dormant   — done | dead | canceled.
+ *    Live      — what you can pick up right now: active | idle, PLUS a resident
+ *                agent that stopped without finishing (its broker exited, but
+ *                Enter resumes the conversation in place — see `isFinishedWork`).
+ *                Finished work never appears here.
+ *    Dormant   — done | dead | canceled: literally "no engine running". A stopped
+ *                resident agent is deliberately on BOTH tabs — it is resumable
+ *                (Live) and it is not running (Dormant); both are true and each
+ *                tab is the one a different search starts from.
  *    Attention — needs a human: has pending asks OR is parked on a fault.
  *    Pinned    — user-starred (a local, view-only preference; `isPinned`). */
 export function tabPredicate(tab, row, isPinned = false) {
     switch (tab) {
         case 'All': return true;
-        case 'Live': return row.status === 'active' || row.status === 'idle';
+        case 'Live': return isLiveStatus(row.status)
+            || !isFinishedWork({ lifecycle: row.lifecycle, finalized: row.finalized === true });
         case 'Dormant': return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
         case 'Attention': return row.asks > 0 || row.hanging != null;
         case 'Pinned': return isPinned;

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

@@ -90,6 +90,10 @@ export declare function clearPid(nodeId: string): void;
 export declare function migrateLegacyPidIdentities(captureIdentity?: (pid: number) => string | undefined): {
     migrated: string[];
 };
+/** Every hydrated node whose durable profile identity equals `profileId`.
+ *  Unlike `listNodes`, this includes unclaimed warm-pool spares: profile
+ *  deletion owns every matching row, whether or not it is user-visible. */
+export declare function listNodesByProfile(profileId: string): NodeMeta[];
 /** All rows, optionally filtered by status. Unclaimed warm spares are excluded. */
 export declare function listNodes(filter?: {
     status?: NodeStatus | NodeStatus[];
@@ -306,6 +310,9 @@ export interface DeleteNodeResult {
  *  state are removed in one canvas write boundary. Best-effort dir removal
  *  follows the commit. */
 export declare function deleteNode(nodeId: string): DeleteNodeResult;
+/** Hard-delete a validated set of nodes in one row transaction, then remove
+ *  their directories. The caller must tear down engines and viewers first. */
+export declare function deleteNodes(nodeIds: readonly string[]): string[];
 /** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. Open managed-worktree nodes are retained so their checkout

package/dist/core/canvas/canvas.js

@@ -336,6 +336,21 @@ export function migrateLegacyPidIdentities(captureIdentity = (pid) => capturePid
  *  yet — surfacing it would put a phantom empty conversation in the user's
  *  sidebar. Claiming deletes the marker, which is what makes the node visible. */
 const NOT_A_SPARE = 'node_id NOT IN (SELECT node_id FROM warm_pool)';
+/** Every hydrated node whose durable profile identity equals `profileId`.
+ *  Unlike `listNodes`, this includes unclaimed warm-pool spares: profile
+ *  deletion owns every matching row, whether or not it is user-visible. */
+export function listNodesByProfile(profileId) {
+    const ids = openDb()
+        .prepare('SELECT node_id FROM nodes WHERE profile_id = ? ORDER BY created')
+        .all(profileId);
+    return ids.map(({ node_id }) => {
+        const meta = getNode(node_id);
+        if (meta === null) {
+            throw new Error(`profile deletion cannot hydrate indexed node ${node_id}`);
+        }
+        return meta;
+    });
+}
 /** All rows, optionally filtered by status. Unclaimed warm spares are excluded. */
 export function listNodes(filter) {
     const db = openDb();
@@ -744,6 +759,28 @@ export function deleteNode(nodeId) {
     rmSync(nodeDir(nodeId), { recursive: true, force: true });
     return result;
 }
+/** Hard-delete a validated set of nodes in one row transaction, then remove
+ *  their directories. The caller must tear down engines and viewers first. */
+export function deleteNodes(nodeIds) {
+    const ids = [...new Set(nodeIds)];
+    if (ids.length === 0)
+        return [];
+    const blocked = ids.filter(hasOpenManagedWorktree);
+    if (blocked.length > 0) {
+        throw new Error(`refusing to delete nodes with open managed worktrees: ${blocked.join(', ')}`);
+    }
+    const placeholders = ids.map(() => '?').join(',');
+    const deleted = withCanvasWrite((db) => {
+        const existing = db
+            .prepare(`SELECT node_id FROM nodes WHERE node_id IN (${placeholders}) ORDER BY created`)
+            .all(...ids).map(({ node_id }) => node_id);
+        db.prepare(`DELETE FROM nodes WHERE node_id IN (${placeholders})`).run(...ids);
+        return existing;
+    });
+    for (const id of deleted)
+        rmSync(nodeDir(id), { recursive: true, force: true });
+    return deleted;
+}
 /** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. Open managed-worktree nodes are retained so their checkout

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

@@ -159,6 +159,15 @@ export declare function listCrons(scope: {
 export declare function cancelCron(cron_id: string, options?: {
     preserveRunningProcess?: boolean;
 }): boolean;
+/** Cron ids a hard profile deletion will remove: matching execution profile,
+ *  plus every row anchored to a node being deleted. */
+export declare function cronIdsForProfileDeletion(profileId: string, anchorNodeIds: readonly string[]): string[];
+/** Kill any leased matching/anchored runs, then delete their rows together. */
+export declare function deleteCronsForProfile(profileId: string, anchorNodeIds: readonly string[]): string[];
+/** Cron ids whose snapshotted profile will be detached. */
+export declare function cronIdsForProfileDetach(profileId: string): string[];
+/** Preserve matching crons while removing their deleted profile dependency. */
+export declare function globalizeCronsForProfile(profileId: string): string[];
 /** DELETE one cron by id — one-shot consumption after its run settles.
  *  Returns whether a live row was removed, so a consumer racing an explicit
  *  cancel can no-op instead of double-settling. */

package/dist/core/canvas/crons.js

@@ -191,6 +191,57 @@ export function cancelCron(cron_id, options) {
         return true;
     });
 }
+function profileCronWhere(profileId, anchorNodeIds) {
+    const anchors = [...new Set(anchorNodeIds)];
+    if (anchors.length === 0)
+        return { sql: 'profile = ?', params: [profileId] };
+    return {
+        sql: `profile = ? OR anchor_node IN (${anchors.map(() => '?').join(',')})`,
+        params: [profileId, ...anchors],
+    };
+}
+/** Cron ids a hard profile deletion will remove: matching execution profile,
+ *  plus every row anchored to a node being deleted. */
+export function cronIdsForProfileDeletion(profileId, anchorNodeIds) {
+    const where = profileCronWhere(profileId, anchorNodeIds);
+    return openDb()
+        .prepare(`SELECT cron_id FROM crons WHERE ${where.sql} ORDER BY created, cron_id`)
+        .all(...where.params).map(({ cron_id }) => cron_id);
+}
+/** Kill any leased matching/anchored runs, then delete their rows together. */
+export function deleteCronsForProfile(profileId, anchorNodeIds) {
+    return withCanvasWrite((db) => {
+        const where = profileCronWhere(profileId, anchorNodeIds);
+        const rows = db
+            .prepare(`SELECT * FROM crons WHERE ${where.sql} ORDER BY created, cron_id`)
+            .all(...where.params).map(cronFrom);
+        for (const cron of rows) {
+            if (cron.run_state === 'running')
+                killLeasedCronRun(cron);
+        }
+        db.prepare(`DELETE FROM crons WHERE ${where.sql}`).run(...where.params);
+        return rows.map(({ cron_id }) => cron_id);
+    });
+}
+/** Cron ids whose snapshotted profile will be detached. */
+export function cronIdsForProfileDetach(profileId) {
+    return openDb()
+        .prepare('SELECT cron_id FROM crons WHERE profile = ? ORDER BY created, cron_id')
+        .all(profileId).map(({ cron_id }) => cron_id);
+}
+/** Preserve matching crons while removing their deleted profile dependency. */
+export function globalizeCronsForProfile(profileId) {
+    return withCanvasWrite((db) => {
+        const ids = db
+            .prepare('SELECT cron_id FROM crons WHERE profile = ? ORDER BY created, cron_id')
+            .all(profileId).map(({ cron_id }) => cron_id);
+        if (ids.length > 0) {
+            db.prepare("UPDATE crons SET profile = NULL, scope = 'global', updated = ? WHERE profile = ?")
+                .run(new Date().toISOString(), profileId);
+        }
+        return ids;
+    });
+}
 /** DELETE one cron by id — one-shot consumption after its run settles.
  *  Returns whether a live row was removed, so a consumer racing an explicit
  *  cancel can no-op instead of double-settling. */

package/dist/core/canvas/node-order.d.ts

@@ -1,3 +1,24 @@
-import type { NodeStatus } from './types.js';
+import type { NodeStatus, Lifecycle } from './types.js';
 /** Sort live work before terminal work; unknown statuses sort last. */
 export declare function statusRank(status: NodeStatus | undefined): number;
+/** True when the node has a broker the daemon supervises — the statuses that
+ *  mean "a live engine is (or should be) running right now". */
+export declare function isLiveStatus(status: NodeStatus | undefined): boolean;
+/** True when a node's work is FINISHED — a terminal one-shot worker, or any node
+ *  that pushed a final report.
+ *
+ *  This is deliberately NOT "is it running": a non-live status alone conflates two
+ *  unrelated situations. Finished work is archive — opening it is inspection, and
+ *  relaunching it puts a completed worker back to work (the stop-guard reprompts a
+ *  terminal node that never pushed a final). A RESIDENT node with no final report
+ *  is the opposite: its `done` is only `markCleanExitDone` recording a clean broker
+ *  exit, which the stop-guard itself rules a legitimate stop (`reason: 'dormant'`),
+ *  so it never finished anything and resuming it is simply reopening a conversation.
+ *
+ *  `lifecycle` is optional because DashboardRow only carries it on the full browser
+ *  snapshot; absent, this answers `true` (treat as finished), keeping the caller on
+ *  the conservative inspect-don't-revive path. */
+export declare function isFinishedWork(node: {
+    lifecycle?: Lifecycle;
+    finalized: boolean;
+}): boolean;

package/dist/core/canvas/node-order.js

@@ -1,4 +1,7 @@
-// node-order.ts — canonical live-first ordering for canvas node statuses.
+// node-order.ts — canonical ordering and status/lifecycle classification for
+// canvas nodes. Pure (type-only imports) so every surface — the browser model,
+// command leaves, renderers — can share one answer to "is this node live?" and
+// "did this node finish?" without reaching the db.
 /** Sort live work before terminal work; unknown statuses sort last. */
 export function statusRank(status) {
     switch (status) {
@@ -10,3 +13,25 @@ export function statusRank(status) {
         default: return 5;
     }
 }
+/** True when the node has a broker the daemon supervises — the statuses that
+ *  mean "a live engine is (or should be) running right now". */
+export function isLiveStatus(status) {
+    return status === 'active' || status === 'idle';
+}
+/** True when a node's work is FINISHED — a terminal one-shot worker, or any node
+ *  that pushed a final report.
+ *
+ *  This is deliberately NOT "is it running": a non-live status alone conflates two
+ *  unrelated situations. Finished work is archive — opening it is inspection, and
+ *  relaunching it puts a completed worker back to work (the stop-guard reprompts a
+ *  terminal node that never pushed a final). A RESIDENT node with no final report
+ *  is the opposite: its `done` is only `markCleanExitDone` recording a clean broker
+ *  exit, which the stop-guard itself rules a legitimate stop (`reason: 'dormant'`),
+ *  so it never finished anything and resuming it is simply reopening a conversation.
+ *
+ *  `lifecycle` is optional because DashboardRow only carries it on the full browser
+ *  snapshot; absent, this answers `true` (treat as finished), keeping the caller on
+ *  the conservative inspect-don't-revive path. */
+export function isFinishedWork(node) {
+    return node.lifecycle !== 'resident' || node.finalized;
+}

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

@@ -34,6 +34,11 @@ export interface DashboardRow {
      *  agent you come back to. Drives the browser's resident-only lifecycle filter.
      *  Only populated by dashboardRowsAll (the browser snapshot). */
     lifecycle?: Lifecycle;
+    /** True when the node pushed a final report. With `lifecycle` this separates
+     *  work that FINISHED from a resident agent that merely stopped, which the
+     *  status alone cannot (see `isFinishedWork` in node-order.ts). Only populated
+     *  by dashboardRowsAll (the browser snapshot). */
+    finalized?: boolean;
     /** "Most recent activity" sort key — epoch ms. The cheap boot stats the node's
      *  job/telemetry.json (rewritten on every turn_end at a DETERMINISTIC path, so
      *  no meta read), falling back to `created`'s epoch when a node never ran a turn.

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

@@ -372,6 +372,7 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
         profile_id: row.profile_id,
         created: row.created,
         lifecycle: row.lifecycle,
+        finalized: row.final_report != null,
         mtimeMs: sessionMtime(row.node_id, row.created, remote),
         streaming: !remote && hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
         hanging,

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

@@ -49,6 +49,9 @@ export interface LaunchSpec {
 }
 export interface ManagedWorktree {
     state: 'open' | 'closed';
+    /** A closed worktree remains registered until its owner has exited, so Git
+     *  never deletes the caller's live checkout beneath it. */
+    cleanup?: 'pending' | 'complete';
     path: string;
     branch: string;
     repo_root: string;
@@ -57,10 +60,13 @@ export interface ManagedWorktree {
     created: string;
     closed?: string;
 }
-/** Immutable review-companion provenance. The origin session/leaf/model
- *  coordinates remain canonical in the review row rather than being duplicated
- *  into node metadata. */
+/** Immutable companion provenance. The origin session/leaf/model coordinates
+ *  remain canonical in the review row rather than being duplicated into node
+ *  metadata. `kind` names the surface the companion serves: absent or `review`
+ *  is a human document review; `page_feedback` binds a page ticket's feedback
+ *  conversation, with review_id = ticket id and target_file = the page source. */
 export interface ReviewBinding {
+    kind?: 'review' | 'page_feedback';
     review_id: string;
     origin_node_id: string;
     branch_file: string;

package/dist/core/command-plugins/bundle.d.ts

@@ -1,5 +1,5 @@
 import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
-import type { KindConfig } from '../../types.js';
+import type { KindConfig, PageComponentRegistration } from '../../types.js';
 export interface BundleIssue {
     code: string;
     path?: string;
@@ -15,6 +15,11 @@ export interface ValidatedBundle {
      *  manifest, where `readMergedLaunchConfig` layers it — see
      *  `PluginManifest.kinds`. */
     kinds?: Record<string, Partial<KindConfig>>;
+    /** Page-component contributions declared in `bundle.json` (optional). The
+     *  installer copies this validated block into the synthesized plugin
+     *  manifest, where `resolvePageComponents` reads it — see
+     *  `PluginManifest.page_components`. */
+    page_components?: PageComponentRegistration[];
     commands: ValidatedCommandManifest;
     commandsBytes: Uint8Array;
     directories: ReadonlyArray<{

package/dist/core/command-plugins/bundle.js

@@ -1,6 +1,7 @@
 import { Parser } from 'tar';
 import { validateCommandManifest } from '../command-manifests/manifest.js';
 import { invalidPluginKindsReasons } from '../config.js';
+import { invalidPageComponentsReasons, normalizePageComponents } from '../human/page-catalog.js';
 function issue(code, message, received, expected, next, path) {
     return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
 }
@@ -143,24 +144,35 @@ function parseBundleMetadata(bytes) {
         };
     }
     const record = raw;
-    const unknownKeys = Object.keys(record).filter((key) => key !== 'bundleVersion' && key !== 'kinds');
+    const unknownKeys = Object.keys(record).filter((key) => key !== 'bundleVersion' && key !== 'kinds' && key !== 'page_components');
     if (record['bundleVersion'] !== 1 || unknownKeys.length > 0) {
         return {
-            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most a kinds block', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds', 'Set bundle.json to {"bundleVersion":1} plus an optional kinds object.', 'bundle.json'),
+            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most kinds and page_components blocks', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds and page_components', 'Set bundle.json to {"bundleVersion":1} plus an optional kinds object and page_components array.', 'bundle.json'),
         };
     }
-    if (record['kinds'] === undefined)
-        return {};
-    // Install-time strictness: a bad kinds block fails the install loudly here,
-    // because the read side (`mergeKinds`) drops invalid entries silently and
-    // would otherwise ship a kind that never registers.
-    const reasons = invalidPluginKindsReasons(record['kinds']);
-    if (reasons.length > 0) {
-        return {
-            issue: bundleInvalid('bundle.json kinds block is invalid', reasons.join('; '), 'each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields', 'Fix the kinds entries in bundle.json.', 'bundle.json'),
-        };
+    // Install-time strictness: a bad block fails the install loudly here, because
+    // the read side (`mergeKinds`) drops invalid kind entries silently and would
+    // otherwise ship a kind that never registers.
+    if (record['kinds'] !== undefined) {
+        const reasons = invalidPluginKindsReasons(record['kinds']);
+        if (reasons.length > 0) {
+            return {
+                issue: bundleInvalid('bundle.json kinds block is invalid', reasons.join('; '), 'each entry a full KindConfig (whenToUse required) or a sparse patch of launch fields', 'Fix the kinds entries in bundle.json.', 'bundle.json'),
+            };
+        }
     }
-    return { kinds: record['kinds'] };
+    if (record['page_components'] !== undefined) {
+        const reasons = invalidPageComponentsReasons(record['page_components']);
+        if (reasons.length > 0) {
+            return {
+                issue: bundleInvalid('bundle.json page_components block is invalid', reasons.join('; '), 'an array of page component registrations, each a kind string or {kind, description?, useWhen?, doc?, display?}', 'Fix the page_components entries in bundle.json.', 'bundle.json'),
+            };
+        }
+    }
+    return {
+        ...(record['kinds'] !== undefined ? { kinds: record['kinds'] } : {}),
+        ...(record['page_components'] !== undefined ? { page_components: normalizePageComponents(record['page_components']) } : {}),
+    };
 }
 function parseCommands(bytes, reservedCoreNames, coreCommandPaths) {
     let raw;
@@ -206,6 +218,7 @@ export async function validatePluginBundle(archive, options) {
         bundle: {
             bundleVersion: 1,
             ...(metadata.kinds !== undefined ? { kinds: metadata.kinds } : {}),
+            ...(metadata.page_components !== undefined ? { page_components: metadata.page_components } : {}),
             commands: commandValidation.commands,
             commandsBytes: commands.bytes,
             directories: parsed.members