@north-light/crouter 0.3.281 → 0.3.283

package/dist/commands/api-client.js

@@ -137,18 +137,8 @@ export function cliClient(opts) {
 // NodeSummaryDTO now carries every NodeRow field and NodeDetailDTO extends it,
 // so the viewer adapter returns the daemon's typed projections directly. It
 // performs no lossy legacy reconstruction or invented local-presence values.
-// The attach viewer's recurring subtree walk (chrome/canvas-panels.ts + overlays/graph.ts
-// computeActivity/visitActivity) calls subscriptionsOf/subscribersOf once per
-// visited node on every poll tick, and a `GET /v1/nodes/:id` per call just to
-// read the edge list off the detail DTO costs one round trip per visited node.
-// This short-TTL cache backs those two methods with the lean roster
-// (`GET /v1/canvas/roster`) instead — one shared fetch per TTL window covers
-// every topology walk in that window, comfortably under the attach viewer's 5s
-// poll cadence. Scoped to subscriptionsOf/subscribersOf only: listNodes/getRow
-// stay on the full per-id/list HTTP path because the roster does not carry the
-// runtime fields (intent/waiting_for/pi_pid/etc) those two already populate for
-// real from the full DTO — backing them with the roster would silently null out
-// live display fields, not just the already-lossy tmux-presence ones.
+// Index the short-lived lean roster once so repeated topology lookups stay O(1).
+// listNodes/getRow still use full DTO endpoints for fields the roster omits.
 const ROSTER_CACHE_TTL_MS = 2000;
 export class ApiCanvasSource {
     client;
@@ -160,15 +150,30 @@ export class ApiCanvasSource {
     async roster() {
         const now = Date.now();
         if (this.rosterCache !== null && now - this.rosterCache.at < ROSTER_CACHE_TTL_MS) {
-            return this.rosterCache.roster;
+            return this.rosterCache.index;
         }
         if (this.rosterInFlight !== null)
             return this.rosterInFlight;
         this.rosterInFlight = this.client
             .canvasRoster()
             .then((roster) => {
-            this.rosterCache = { at: Date.now(), roster };
-            return roster;
+            const index = { subscriptions: new Map(), subscribers: new Map() };
+            for (const edge of roster.edges) {
+                const subscription = { node_id: edge.to_id, active: edge.active, created: edge.created };
+                const subscriber = { node_id: edge.from_id, active: edge.active, created: edge.created };
+                const subscriptions = index.subscriptions.get(edge.from_id);
+                if (subscriptions === undefined)
+                    index.subscriptions.set(edge.from_id, [subscription]);
+                else
+                    subscriptions.push(subscription);
+                const subscribers = index.subscribers.get(edge.to_id);
+                if (subscribers === undefined)
+                    index.subscribers.set(edge.to_id, [subscriber]);
+                else
+                    subscribers.push(subscriber);
+            }
+            this.rosterCache = { at: Date.now(), index };
+            return index;
         })
             .finally(() => {
             this.rosterInFlight = null;
@@ -212,16 +217,10 @@ export class ApiCanvasSource {
         return rows;
     }
     async subscriptionsOf(subscriber) {
-        const roster = await this.roster();
-        return roster.edges
-            .filter((e) => e.from_id === subscriber)
-            .map((e) => ({ node_id: e.to_id, active: e.active, created: e.created }));
+        return this.roster().then((index) => index.subscriptions.get(subscriber) ?? []);
     }
     async subscribersOf(publisher) {
-        const roster = await this.roster();
-        return roster.edges
-            .filter((e) => e.to_id === publisher)
-            .map((e) => ({ node_id: e.from_id, active: e.active, created: e.created }));
+        return this.roster().then((index) => index.subscribers.get(publisher) ?? []);
     }
     /** BFS over the active `subscribes_to` edges from `root` (its transitive view),
      *  excluding `root` itself — the same traversal shape as

package/dist/commands/node/create.js

@@ -6,6 +6,7 @@ import { mark } from '../../core/timing.js';
 import { OUTPUT_SCHEMA_CONSTRAINTS, OUTPUT_SCHEMA_TRANSPORT, parseOutputSchemaValue } from '../../core/runtime/structured-output.js';
 import { MODEL_SPEC_FORMS, MODEL_SPEC_NEXT } from '../../core/runtime/model-selection.js';
 import { readMergedLaunchConfig } from '../../core/config.js';
+import { parseDurationMs } from '../../core/wake.js';
 import { profilesStateBlock } from '../../core/profiles/state-block.js';
 import { resolveProfileOperand } from '../../core/profiles/manifest.js';
 import { stateBlock } from '../../core/help.js';
@@ -14,7 +15,7 @@ import { inTmux } from '../../core/runtime/placement-tmux.js';
 import { openSpawnViewer } from '../surface/node/placement.js';
 import { resolve } from 'node:path';
 const YIELD_NUDGE_THRESHOLD = 100_000;
-const NODE_NEW_OUTPUT_SCHEMA_EFFECT = '--output-schema writes the accepted result to the node’s context/result.json and pushes it as the node’s final report.';
+const NODE_NEW_OUTPUT_SCHEMA_EFFECT = '--output-schema writes the accepted result to the node’s context/result.json and pushes it as the node’s final report; a node that cannot honestly satisfy the schema declines with `crtr push result --decline "<reason>" --code <token>`, which finishes it with a failure outcome (reason `declined`) whose `declined` field carries { reason, code, retryable } and no result. Name the code tokens you accept in the prompt; crouter carries the code verbatim and you validate it.';
 const STD_CHILD_FOLLOW_UP = "Do not wait, poll, or duplicate this child's assignment in your own context — there is no result to await, stopping will not strand you, and duplicated work wastes the delegated context. You're auto-subscribed, so its finish wakes you on its own. Two moves only: do other independent work right now, or stop and end your turn — the wake brings you back.";
 /** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
  *  but when the SPAWNER is an orchestrator whose context has already grown past
@@ -121,6 +122,9 @@ function nodeNewParams() {
         // this flag at exactly the moment it is needed. Advertising it would tax
         // every spawn with a capability almost no caller wants.
         { kind: 'flag', name: 'no-kickoff', type: 'bool', required: false, hidden: true, constraint: 'With --root, start the broker and session idle without a first message or model turn. Mutually exclusive with a prompt and --mode orchestrator.' },
+        { kind: 'flag', name: 'deadline', type: 'string', required: false, constraint: 'Positive, representable wall-clock duration from spawn. Grammar: one or more positive integer-unit parts; units: s, m, h, d; adjacent parts are summed. Omit for no deadline.' },
+        { kind: 'flag', name: 'outcome-action', type: 'string', required: false, constraint: 'Declared human-action name that receives the node outcome. Grammar: 1–128 ASCII letters, digits, dots, underscores, or hyphens; starts with a letter or digit. Omit when no external delivery target is needed.' },
+        { kind: 'flag', name: 'outcome-payload', type: 'string', required: false, constraint: 'JSON value, serialized at most 64 KiB, frozen and echoed to --outcome-action. Requires --outcome-action.' },
         {
             kind: 'flag',
             name: 'output-schema',
@@ -131,10 +135,10 @@ function nodeNewParams() {
                 whenToUse: 'Use only when the node’s consumer needs a machine-checkable final object with fixed fields. Omit it for ordinary delegation or when a prose report is enough; structured output replaces the completion protocol, and an over-constrained schema can force retries.',
                 value: `Pass the JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} ${OUTPUT_SCHEMA_CONSTRAINTS}`,
                 effects: [
-                    'The node receives a terminal submit tool and cannot finish until submit accepts a result; it must not call `crtr push final` itself.',
+                    'The node must answer with `crtr push result` and cannot finish until the result is accepted; a plain `crtr push final` is blocked while the request is pending.',
                     NODE_NEW_OUTPUT_SCHEMA_EFFECT,
                     'The managed parent wakes through its existing subscription when the final report arrives; an independent root has no subscriber to wake.',
-                    'Successful submit removes the request and terminates the node.',
+                    'An accepted result, or a decline, removes the request and terminates the node.',
                 ],
             },
         },
@@ -164,6 +168,8 @@ function nodeNewEffects() {
         'A managed child creates an active parent subscription; its pushes wake the parent. --root creates an independent node with spawned_by provenance and no parent subscription.',
         '--worktree creates a managed worktree at ~/.crouter/canvas/worktrees/<node-id>/ on a new crtr/<node-id> branch.',
         NODE_NEW_OUTPUT_SCHEMA_EFFECT,
+        '--deadline persists a wall-clock deadline from spawn; expiry cancels the node and records a failure outcome with reason deadline_exceeded.',
+        '--outcome-action registers one resolved local human-action target. When the node settles, crouter retries delivery of its outcome document until the target accepts it or permanently rejects it; --outcome-payload is frozen and echoed in that document.',
         ...(inTmux() ? ['--root opens a viewer for the new node in the current tmux session.'] : []),
     ];
 }
@@ -203,6 +209,28 @@ async function runNodeCreation(input) {
     const situationalContext = situationalContextRaw !== undefined && situationalContextRaw !== '' ? situationalContextRaw : undefined;
     const outputSchemaParsed = parseOutputSchemaValue(input['outputSchema']);
     const outputSchema = outputSchemaParsed !== null ? JSON.stringify(outputSchemaParsed) : null;
+    const deadline = input['deadline'];
+    if (deadline !== undefined) {
+        const durationMs = parseDurationMs(deadline);
+        const deadlineAt = durationMs === null ? Number.NaN : new Date(Date.now() + durationMs).getTime();
+        if (durationMs === null || !Number.isFinite(durationMs) || durationMs <= 0 || !Number.isFinite(deadlineAt)) {
+            throw new InputError({ error: 'invalid_deadline', message: '--deadline must be a positive representable duration', field: 'deadline', next: 'Pass positive integer-unit parts using s, m, h, or d.' });
+        }
+    }
+    const outcomeAction = input['outcomeAction'];
+    const outcomePayloadRaw = input['outcomePayload'];
+    if (outcomePayloadRaw !== undefined && outcomeAction === undefined) {
+        throw new InputError({ error: 'outcome_payload_requires_action', message: '--outcome-payload requires --outcome-action', field: 'outcome-payload', next: 'Pass the declared delivery action with --outcome-action.' });
+    }
+    let outcomePayload;
+    if (outcomePayloadRaw !== undefined) {
+        try {
+            outcomePayload = JSON.parse(outcomePayloadRaw);
+        }
+        catch {
+            throw new InputError({ error: 'invalid_outcome_payload', message: '--outcome-payload must be valid JSON', field: 'outcome-payload', next: 'Pass one valid JSON value.' });
+        }
+    }
     const nodeId = input['nodeId']?.trim();
     if (root && worktreeBase !== undefined) {
         throw new InputError({ error: 'worktree_root_conflict', message: '--worktree is mutually exclusive with --root', field: 'worktree', next: 'Drop either --root or --worktree.' });
@@ -236,6 +264,13 @@ async function runNodeCreation(input) {
         ...(situationalContext !== undefined ? { situational_context: situationalContext } : {}),
         ...(noKickoff ? { no_kickoff: true } : {}),
         ...(outputSchema !== null ? { output_schema: outputSchema } : {}),
+        ...(deadline !== undefined ? { deadline } : {}),
+        ...(outcomeAction !== undefined ? {
+            outcome_delivery: {
+                action: outcomeAction,
+                ...(outcomePayload === undefined ? {} : { payload: outcomePayload }),
+            },
+        } : {}),
         ...(nodeId !== undefined && nodeId !== '' ? { node_id: nodeId } : {}),
         // A bare `--root --no-kickoff` create is exactly what the warm pool holds
         // ready; every other shape is rejected server-side and cold-spawns.

package/dist/commands/node/inspect.js

@@ -82,13 +82,9 @@ const nodeList = defineLeaf({
                 return false;
             return true;
         });
-        const nodes = [];
-        for (const row of rows) {
-            const detail = await canvasSource.getNode(row.node_id).catch(rethrowAsCliError);
-            const named = { ...row, name: fullName(detail ?? row) };
-            if (name === undefined || name === '' || fuzzyMatch(name, named.name))
-                nodes.push(named);
-        }
+        const nodes = rows
+            .map((row) => ({ ...row, name: fullName(row) }))
+            .filter((row) => name === undefined || name === '' || fuzzyMatch(name, row.name));
         return { nodes };
     },
 });

package/dist/commands/node/message.js

@@ -57,7 +57,7 @@ function messageRequestParams() {
         { 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'], required: false, default: 'normal', constraint: 'Delivery urgency. Every accepted tier may revive a dormant target, because the request must be answered; deferred is rejected for that reason.' },
-        { kind: 'flag', name: 'output-schema', type: 'string', required: true, constraint: `JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} The target answers through a constrained submit tool, then keeps working. ${OUTPUT_SCHEMA_CONSTRAINTS}` },
+        { kind: 'flag', name: 'output-schema', type: 'string', required: true, constraint: `JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} The target answers with \`crtr push result\` (or declines with \`crtr push result --decline "<reason>" --code <token>\`), then keeps working. ${OUTPUT_SCHEMA_CONSTRAINTS}` },
         { 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, hidden: true, constraint: 'Clear a finalized target latch before delivery or fresh revive.' },
     ];
@@ -129,7 +129,7 @@ const nodeMessageRequest = defineLeaf({
         params: messageRequestParams(),
         output: messageOutput(),
         outputKind: 'object',
-        effects: ['Installs the one-off submit schema before appending the request.'],
+        effects: ['Installs the one-off output schema before appending the request.'],
     },
     run: (input) => {
         requireNonBlankDiscriminant(input, 'outputSchema');
@@ -144,7 +144,7 @@ export const nodeMessage = defineBranch({
     help: {
         name: 'node message',
         summary: 'deliver one immediate inbox entry to an existing node',
-        model: 'Both children append one inbox entry to a node that already exists, targeted by id or --self, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off submit schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target’s result file, and pushed as an update report to the TARGET’S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship — a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`.',
+        model: 'Both children append one inbox entry to a node that already exists, targeted by id or --self, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off output schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target’s result file, and pushed as an update report to the TARGET’S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship — a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`.',
     },
     children: [nodeMessageSend, nodeMessageRequest],
 });

package/dist/commands/node/outcome.d.ts

@@ -0,0 +1,2 @@
+export declare const nodeOutcomeDelivery: import("../../core/command.js").LeafDef;
+export declare const nodeOutcome: import("../../core/command.js").BranchDef;

package/dist/commands/node/outcome.js

@@ -0,0 +1,134 @@
+// `crtr node outcome` — read a durable terminal outcome through crtrd only.
+import { isSafeNodeId } from '../../api/index.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+function nodeId(input) {
+    const id = typeof input['node'] === 'string' ? input['node'].trim() : '';
+    if (!isSafeNodeId(id)) {
+        throw new InputError({
+            error: 'invalid_node',
+            message: `invalid node id: ${id === '' ? '(empty)' : id}`,
+            field: 'node',
+            next: 'Pass the exact node id returned when the node was created.',
+        });
+    }
+    return id;
+}
+function renderedJson(value) {
+    return value === null || value === undefined ? 'none' : JSON.stringify(value);
+}
+const nodeOutcomeRead = defineLeaf({
+    name: 'read',
+    description: 'read or briefly await a node’s durable terminal outcome',
+    whenToUse: 'an external caller needs the durable result or failure reason for one node, optionally blocking for its terminal outcome without consuming or claiming it',
+    help: {
+        name: 'node outcome read',
+        summary: 'read a node’s durable outcome, optionally awaiting it for up to 25 seconds',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id whose durable outcome to read.' },
+            { kind: 'flag', name: 'wait', type: 'int', required: false, default: 0, constraint: 'Whole seconds to await settlement: 0–25. Omit or use 0 to return the current pending/settled state immediately.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The requested node id.' },
+            { name: 'state', type: 'string', required: true, constraint: '`pending` while the node has no terminal outcome, otherwise `settled`.' },
+            { name: 'outcome', type: 'object', required: true, constraint: 'The durable result/failure record when settled — kind/reason, revision, settled time, report basename/path, structured result, failure detail, and `declined` ({ reason, code, retryable } for a failure with reason `declined`, else null) — otherwise null.' },
+            { name: 'node_status', type: 'string', required: true, constraint: 'The node status observed with the outcome.' },
+            { name: 'deadline_at', type: 'string', required: true, constraint: 'The absolute spawn deadline, or null when unbounded.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: calls the daemon’s replay-safe GET outcome route. With --wait, the daemon polls the durable row for no more than 25 seconds.'],
+    },
+    run: async (input) => {
+        const id = nodeId(input);
+        const wait = input['wait'];
+        if (typeof wait !== 'number' || !Number.isInteger(wait) || wait < 0 || wait > 25) {
+            throw new InputError({
+                error: 'invalid_wait',
+                message: '--wait must be an integer between 0 and 25 seconds',
+                field: 'wait',
+                received: wait,
+                next: 'Pass a whole number from 0 through 25, or omit --wait to poll immediately.',
+            });
+        }
+        return { ...await cliClient().getNodeOutcome(id, { waitSeconds: wait }).catch(rethrowAsCliError) };
+    },
+    render: (result) => {
+        const outcome = result['outcome'];
+        if (outcome === null) {
+            return [
+                `<outcome state="pending" node_id="${result['node_id']}">`,
+                `- node status: ${result['node_status']}`,
+                `- deadline: ${result['deadline_at'] ?? 'none'}`,
+                '</outcome>',
+            ].join('\n');
+        }
+        return [
+            `<outcome kind="${outcome['kind']}" reason="${outcome['reason']}" state="settled" node_id="${result['node_id']}" revision="${outcome['revision']}">`,
+            `- final report: ${outcome['final_report'] ?? 'none'}`,
+            `- report path: ${outcome['final_report_path'] ?? 'none'}`,
+            `- structured result: ${renderedJson(outcome['structured_result'])}`,
+            `- declined: ${renderedJson(outcome['declined'])}`,
+            `- failure detail: ${renderedJson(outcome['detail'])}`,
+            `- settled at: ${outcome['settled_at']}`,
+            `- node status: ${result['node_status']}`,
+            `- deadline: ${result['deadline_at'] ?? 'none'}`,
+            '</outcome>',
+        ].join('\n');
+    },
+});
+export const nodeOutcomeDelivery = defineLeaf({
+    name: 'delivery',
+    description: 'inspect a node outcome-delivery registration',
+    whenToUse: 'you need the durable state of the local action target registered to receive a node’s outcome',
+    help: {
+        name: 'node outcome delivery',
+        summary: 'inspect the registered outcome-delivery target for one node',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id whose outcome-delivery registration to inspect.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node whose outcome is delivered.' },
+            { name: 'state', type: 'string', required: true, constraint: '`armed`, `pending`, `running`, `accepted`, or `permanent_failed`.' },
+            { name: 'action', type: 'string', required: true, constraint: 'The resolved configured action name.' },
+            { name: 'attempt', type: 'number', required: true, constraint: 'How many delivery attempts have been claimed.' },
+            { name: 'next_attempt_at', type: 'string', required: true, constraint: 'ISO-8601 time of the next retry, or null before a retry is scheduled (including while armed).' },
+            { name: 'accepted_at', type: 'string', required: true, constraint: 'When the target accepted the document, or null.' },
+            { name: 'permanent_failed_at', type: 'string', required: true, constraint: 'When the target permanently rejected the document, or null.' },
+            { name: 'last_failure', type: 'object', required: true, constraint: 'The most recent retryable or permanent delivery failure, or null.' },
+            { name: 'created_at', type: 'string', required: true, constraint: 'When this delivery registration was created.' },
+            { name: 'updated_at', type: 'string', required: true, constraint: 'When this delivery registration was last updated.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: calls the daemon outcome-delivery inspection route.'],
+    },
+    run: async (input) => {
+        const id = nodeId(input);
+        return { ...await cliClient().getOutcomeDelivery(id).catch(rethrowAsCliError) };
+    },
+    render: (result) => {
+        return [
+            `<outcome-delivery state="${result['state']}" node_id="${result['node_id']}">`,
+            `- attempt: ${result['attempt']}`,
+            `- next retry: ${result['next_attempt_at'] ?? 'none'}`,
+            `- last failure: ${renderedJson(result['last_failure'])}`,
+            `- action: ${result['action']}`,
+            `- accepted at: ${result['accepted_at'] ?? 'none'}`,
+            `- permanently failed at: ${result['permanent_failed_at'] ?? 'none'}`,
+            `- registered at: ${result['created_at']}`,
+            `- updated at: ${result['updated_at']}`,
+            '</outcome-delivery>',
+        ].join('\n');
+    },
+});
+export const nodeOutcome = defineBranch({
+    name: 'outcome',
+    description: 'read a node’s terminal outcome or its delivery state',
+    whenToUse: 'you need the durable terminal result/failure of one node, or the state of its registered outcome-delivery target',
+    help: {
+        name: 'node outcome',
+        summary: 'read one node’s durable terminal outcome or its delivery registration',
+        model: 'Outcome reads never consume the terminal record. Read returns the durable result or failure and can wait briefly for settlement; delivery inspects the separate action-registration attempt state.',
+    },
+    children: [nodeOutcomeRead, nodeOutcomeDelivery],
+});

package/dist/commands/node.js

@@ -9,6 +9,7 @@ import { nodeSubscription } from './node/subscription.js';
 import { nodeBash } from './node/bash.js';
 import { pyramidSlash } from './node/pyramid.js';
 import { nodeWorktreeBranch } from './node-worktree.js';
+import { nodeOutcome } from './node/outcome.js';
 export function registerNode() {
     return defineBranch({
         name: 'node',
@@ -23,6 +24,6 @@ export function registerNode() {
             summary: 'create, inspect, message, and change canvas nodes',
             model: 'A node is one agent on the canvas. Immediate actions, durable waits, subscriptions, lifecycle changes, and scheduled crons are separate intent families; choose the family by when the effect happens and what persistent state it changes.',
         },
-        children: [nodeNew, nodeFork, nodeMessage, nodeWaitBranch, nodeSubscription, nodeInspect, nodeLifecycle, nodeWorktreeBranch, nodeConfig, nodePromote, nodeYield, nodeBash],
+        children: [nodeNew, nodeFork, nodeMessage, nodeWaitBranch, nodeSubscription, nodeOutcome, nodeInspect, nodeLifecycle, nodeWorktreeBranch, nodeConfig, nodePromote, nodeYield, nodeBash],
     });
 }

package/dist/commands/pkg/browse/catalog.js

@@ -337,7 +337,7 @@ function commandNode(node, parent = []) {
         children: [],
         params: node.params,
         output: node.output,
-        effects: node.effects,
+        effects: [...node.effects],
         ...("rest" in node ? { rest: { method: node.rest.method, path: node.rest.path, streaming: node.rest.streaming === true } } : {}),
     };
 }

package/dist/commands/pkg/plugin-manage.d.ts

@@ -1,5 +1,14 @@
+import { type CommandDiscoveryIssue } from '../../core/command-plugins/discovery.js';
 import { type HookPluginCandidate } from '../../core/command-hooks/discovery.js';
-import { type PluginManifest, type Scope } from '../../types.js';
+import { type HookReport } from '../../core/command-hooks/report.js';
+import { type PluginBundle, type PluginManifest, type Scope } from '../../types.js';
+/** Static command-manifest report attached to install/update results. Runs
+ *  the Phase-1 validator (no execution) so a caller sees exactly which
+ *  top-level commands the plugin now contributes and why any were rejected. */
+interface CommandReport {
+    mounts: string[];
+    issues: CommandDiscoveryIssue[];
+}
 interface MarketplaceRef {
     marketplace: string;
     plugin: string;
@@ -10,6 +19,21 @@ interface InstallResult {
     path: string;
     memory?: PluginMemoryReport;
 }
+interface BundleReplaceResult extends Record<string, unknown> {
+    name: string;
+    scope: Scope;
+    path: string;
+    transport: 'http';
+    version: string;
+    docs: number;
+    /** Count of kind-registry entries the bundle declared (0 when none). */
+    kinds: number;
+    /** Count of page-component registrations the bundle declared (0 when none). */
+    pageComponents: number;
+    commands: CommandReport;
+    hooks?: HookReport;
+    memory?: PluginMemoryReport;
+}
 /** Who owns the physical memory corpus a candidate gate converges. A `package`
  * corpus is bytes this command owns — staged, or installed under the scope's
  * plugins dir — so a failed activation still rolls the package back. A `linked`
@@ -27,6 +51,27 @@ interface PluginMemoryReport extends Record<string, unknown> {
 /** Validate a package candidate before it gains an active plugin path. The
  * candidate namespace shadows any installed declaration of the same name. */
 export declare function assertPluginCandidateValid(manifest: PluginManifest, root: string, scope: Scope, scopeRootPath: string, where: string, candidates?: readonly HookPluginCandidate[], ownership?: PluginMemoryOwnership): Promise<PluginMemoryReport | undefined>;
+/**
+ * Re-check an installed bundle plugin against its endpoint. A `conditional`
+ * check sends the validator stored for the package currently on disk, so an
+ * unchanged package is answered 304 and left untouched; an unconditional one
+ * asks for the archive outright, which is how recovery from a `manifest_stale`
+ * answer gets past a validator that is itself out of date.
+ *
+ * Returns the swap's report, or `undefined` when the package on disk is already
+ * the generation the server serves — whether the server said so with a 304 or
+ * we proved it by hashing bytes it re-sent.
+ *
+ * Every outcome, including a failure, records that the check happened, so an
+ * unreachable endpoint costs one timed-out probe per TTL rather than one per
+ * command. Failures throw; the caller decides whether a stale-but-present
+ * package is still good enough to run on.
+ */
+export declare function revalidateBundlePlugin(name: string, bundleSource: PluginBundle, scope: Scope, options: {
+    enable: boolean;
+    conditional: boolean;
+    timeoutMs?: number;
+}): Promise<BundleReplaceResult | undefined>;
 export declare function isMarketplaceRelativeSource(source: string): boolean;
 /** Install one marketplace plugin into a scope. Exported so `sys setup` can
  *  install the default plugin set through the same path `pkg plugin install`