@north-light/crouter 0.3.281 → 0.3.283

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

@@ -19,7 +19,7 @@ import { fullName } from './labels.js';
 import { jobDir, contextDir, reportsDir } from './paths.js';
 import { readNodeRecap } from './node-recap.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { isPidAlive } from './pid.js';
+import { isPidAlive, isPidPresent } from './pid.js';
 import { isFrozenRow, resolveNodeVisual, faultSummary } from './status-glyph.js';
 import { readFault } from '../runtime/fault.js';
 import { parseCard } from '../../shared/generated-context.js';
@@ -434,7 +434,7 @@ function assistantContentIsSubstantive(content) {
  *  (an active node is usually dormant between turns). Read directly off disk
  *  (mirrors telemetry) to avoid inverting the canvas→runtime dependency. */
 export function isStreaming(nodeId, piPid) {
-    if (!isPidAlive(piPid))
+    if (!isPidPresent(piPid))
         return false;
     try {
         return existsSync(join(jobDir(nodeId), 'busy'));

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

@@ -18,7 +18,34 @@ export type Lifecycle = 'terminal' | 'resident';
 export type Mode = 'base' | 'orchestrator';
 /** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
 export type ExitIntent = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
-export type TerminalReason = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded';
+export type TerminalReason = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined';
+export type NodeOutcomeKind = 'result' | 'failure';
+/** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
+export declare const OUTCOME_PAYLOAD_MAX_BYTES: number;
+export interface NodeOutcomeDetailV1 {
+    schema: 'crtr.node-outcome-detail/v1';
+    message?: string;
+    fault_kind?: import('../fault-classifier.js').FaultKind;
+    error_class?: import('../events/types.js').ErrorClassCode;
+    retry?: {
+        attempt: number;
+        max: number;
+    };
+    respawn_failures?: number;
+    deadline?: {
+        deadline_at: string;
+        elapsed_ms: number;
+    };
+    /** Present only for reason `declined`: what the node gave `crtr push result --decline`. */
+    declined?: DeclinedResult;
+    truncated?: true;
+}
+/** A declined structured result. `code` is opaque here — the requester validates it. */
+export interface DeclinedResult {
+    reason: string;
+    code: string;
+    retryable: boolean;
+}
 /** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
  *  org chart, views, completion routing). `spawned_by` is audit only. */
 export type EdgeType = 'subscribes_to' | 'spawned_by';
@@ -266,6 +293,14 @@ export interface NodeRuntime {
     final_report?: string | null;
     /** ISO timestamp carried by the committed canonical final report, or null. */
     finalized_at?: string | null;
+    /** Durable terminal outcome. `outcome_at` is its write-once latch. */
+    outcome_kind?: NodeOutcomeKind | null;
+    outcome_reason?: TerminalReason | null;
+    outcome_at?: string | null;
+    outcome_revision?: number;
+    outcome_detail_json?: string | null;
+    /** Absolute wall-clock spawn deadline, or null when unbounded. */
+    deadline_at?: string | null;
     /** OS pid of the live broker process, recorded on boot (stophook session_start).
      *  The daemon's authoritative liveness signal — every node is a detached broker,
      *  so `isPidAlive(pi_pid)` is the sole liveness check. Cleared to null by
@@ -342,6 +377,12 @@ export interface NodeRow {
     terminal_reason?: TerminalReason | null;
     final_report?: string | null;
     finalized_at?: string | null;
+    outcome_kind?: NodeOutcomeKind | null;
+    outcome_reason?: TerminalReason | null;
+    outcome_at?: string | null;
+    outcome_revision?: number;
+    outcome_detail_json?: string | null;
+    deadline_at?: string | null;
     pi_pid: number | null;
     /** See `NodeRuntime.pi_pid_identity`. */
     pi_pid_identity: string | null;

package/dist/core/canvas/types.js

@@ -5,4 +5,5 @@
 // `meta.json` is the source of truth for its own row; the db is a queryable
 // index over those metas, plus the authoritative store for the mutable
 // `subscribes_to` edges (which no single meta owns).
-export {};
+/** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
+export const OUTCOME_PAYLOAD_MAX_BYTES = 64 * 1024;

package/dist/core/command-manifests/registry.d.ts

@@ -24,7 +24,9 @@ export type LeafAdapter = (leaf: DeclLeafBase, commandPath: readonly string[]) =
  *  will produce its leaves' run implementations. */
 export interface CommandContribution {
     contributor: CommandContributorRef;
-    node: DeclBranch<DeclLeafBase>;
+    /** Every leaf below this branch carries its transport dialect — a validated
+     *  contribution is never a bare {@link DeclLeafBase}. */
+    node: DeclBranch;
     /** Root name from the manifest, before collision qualification. */
     manifestName: string;
     adaptLeaf: LeafAdapter;

package/dist/core/command-manifests/schema.d.ts

@@ -1,77 +1,5 @@
-import type { InputParam, Field } from '../help.js';
-export interface DeclRootEntry {
-    concept: string;
-    description: string;
-    whenToUse: string;
-}
-export interface DeclBranch<L = DeclLeafBase> {
-    kind: 'branch';
-    name: string;
-    description: string;
-    whenToUse: string;
-    tier?: 'normal' | 'common' | 'important';
-    /** Required on a top-level branch, forbidden on a nested one. */
-    rootEntry?: DeclRootEntry;
-    /** Allows the nearest repository fragment to contribute children below this top-level branch. */
-    extensible?: true;
-    summary: string;
-    model?: string;
-    /** Exec transport only: forward every argv token after this branch to an
-     *  external binary instead of parsing children. A passthrough branch is
-     *  childless by construction. HTTP manifests reject passthrough because an
-     *  HTTP transport must not name a local binary to execute. */
-    passthrough?: DeclPassthrough;
-    children: DeclNode<L>[];
-}
-export interface DeclPassthrough {
-    bin: string;
-    installHint: string;
-}
-export interface DeclLeafBase {
-    kind: 'leaf';
-    name: string;
-    description: string;
-    whenToUse: string;
-    tier?: 'normal' | 'common' | 'important';
-    summary: string;
-    params: InputParam[];
-    output: Field[];
-    effects: string[];
-}
-/** Exec-transport leaf: requires outputKind: 'object'. */
-export interface ExecDeclLeaf extends DeclLeafBase {
-    outputKind: 'object';
-}
-/** HTTP-transport plugin REST mapping (placeholder types; full spec in manifest.ts). */
-export type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-export type RestParamPlacement = 'path' | 'query' | 'body' | 'header';
-export interface RestParamMapping {
-    in: RestParamPlacement;
-    as?: string;
-}
-export interface RestMapping {
-    method: RestMethod;
-    path: string;
-    streaming?: boolean;
-    /** Constant literal body fields merged into the request body (top-level, alongside
-     *  any bodyRoot-nested param values). Forbidden on GET. */
-    body?: Record<string, string | number | boolean>;
-    /** When set, all in:"body" param values nest under this key instead of the body
-     *  top level (constants from `body` stay top-level regardless). Forbidden on GET. */
-    bodyRoot?: string;
-    params: Record<string, RestParamMapping>;
-}
-export interface ManifestTimeouts {
-    connectMs?: number;
-    requestMs?: number;
-    streamIdleMs?: number;
-}
-/** HTTP-transport leaf: requires rest (derives outputKind from streaming). */
-export interface HttpDeclLeaf extends DeclLeafBase {
-    rest: RestMapping;
-}
-export type DeclLeaf = ExecDeclLeaf | HttpDeclLeaf;
-export type DeclNode<L = DeclLeafBase> = DeclBranch<L> | (L extends DeclLeafBase ? DeclLeaf : never);
+import type { ManifestRootEntry as DeclRootEntry, ManifestPassthrough as DeclPassthrough, ManifestLeafBase as DeclLeafBase, ManifestExecLeaf as ExecDeclLeaf, ManifestHttpLeaf as HttpDeclLeaf, ManifestLeaf as DeclLeaf, ManifestBranch as DeclBranch, ManifestNode as DeclNode, RestMethod, RestParamPlacement, RestParamMapping, RestMapping, ManifestTimeouts } from '../../api/plugin-manifest-schema.js';
+export type { DeclRootEntry, DeclPassthrough, DeclLeafBase, ExecDeclLeaf, HttpDeclLeaf, DeclLeaf, DeclBranch, DeclNode, RestMethod, RestParamPlacement, RestParamMapping, RestMapping, ManifestTimeouts, };
 export interface CommandManifestIssue {
     code: CommandIssueCode;
     path?: string;
@@ -92,4 +20,3 @@ export interface CommandNodeValidationOptions {
     allowExtensible?: boolean;
 }
 export declare function validateCommandNode(raw: unknown, path: string[], topLevel: boolean, transport: TransportKind, issue: IssueFn, options?: CommandNodeValidationOptions): DeclBranch<DeclLeaf> | DeclLeaf | null;
-export {};

package/dist/core/command-manifests/schema.js

@@ -1,4 +1,9 @@
 // Unified command-manifest schema. Transport is the sole leaf-dialect discriminator.
+//
+// The SHAPE of a manifest is declared once, in `src/api/plugin-manifest-schema.ts`,
+// and published as `@north-light/crouter-api/plugin-manifest` so a server that
+// serves a plugin bundle compiles against the same types validated here. This
+// module owns the validators and re-exports those types under their in-tree names.
 import { isRecord } from '../../shared/predicates.js';
 // Validation helpers
 const TIERS = new Set(['normal', 'common', 'important']);

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

@@ -43,5 +43,5 @@ function buildBranch(contribution, node, path) {
 }
 function buildLeaf(contribution, node, path) {
     const adapted = contribution.adaptLeaf(node, path);
-    return defineLeaf({ name: node.name, description: node.description, whenToUse: node.whenToUse, ...(node.tier !== undefined ? { tier: node.tier } : {}), help: { name: path.join(' '), summary: node.summary, params: node.params, output: node.output, outputKind: adapted.outputKind, effects: node.effects }, run: adapted.run });
+    return defineLeaf({ name: node.name, description: node.description, whenToUse: node.whenToUse, ...(node.tier !== undefined ? { tier: node.tier } : {}), help: { name: path.join(' '), summary: node.summary, params: node.params, output: node.output, outputKind: adapted.outputKind, effects: [...node.effects] }, run: adapted.run });
 }

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

@@ -0,0 +1,18 @@
+/**
+ * Bring every installed bundle plugin whose last check has aged out back in
+ * step with its endpoint. Never throws: a plugin that cannot be revalidated
+ * keeps the package already unpacked on disk, which is a complete and valid
+ * command tree, and the failure is reported on stderr rather than replacing the
+ * caller's command with an error about a background check.
+ */
+export declare function revalidateBundlePlugins(argv: readonly string[]): Promise<void>;
+/**
+ * Force one plugin back in step with its endpoint, ignoring both the TTL and
+ * the stored validator. Recovery from a server that answered `manifest_stale`:
+ * the description the caller invoked from is out of date, so the check that
+ * would normally be skipped is exactly the one that has to run.
+ *
+ * Returns whether the package on disk actually changed, so a caller can tell a
+ * recoverable staleness from an operation that is genuinely gone.
+ */
+export declare function forceRevalidateBundlePlugin(name: string): Promise<boolean>;

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

@@ -0,0 +1,152 @@
+// TTL-gated revalidation of installed bundle plugins.
+//
+// A bundle plugin's package is fetched once, at install. Without this pass a
+// long-lived machine keeps invoking the command tree it installed on day one,
+// so a leaf the server renamed fails from the client side with no way back
+// except a human running `crtr pkg plugin update`.
+//
+// The pass runs before the command tree is built, so a replacement it performs
+// is what this very invocation dispatches against. Being on that path, it is
+// also bound by what it may DRAG there: this module reaches only the leaf-level
+// scope, config, and installed-plugin readers — never `discovery.js`, which
+// pulls the manifest validators, the registry, and the composer onto every
+// single crtr invocation, nor `plugin-manage.js`, which pulls the whole package
+// command graph. The machinery that fetches and swaps a package is imported
+// only once a plugin is found due.
+import { readState } from '../config.js';
+import { listInstalledPluginsInRoot } from '../installed-plugins.js';
+import { scopeRoot } from '../scope.js';
+import { GLOBAL_TOKENS } from '../command.js';
+const DEFAULT_TTL_MS = 15 * 60 * 1000;
+/** Project first, so a project-scoped package shadows a user-scoped one of the
+ *  same name exactly as the command tree resolves it. */
+const SCOPES = ['project', 'user'];
+/** How long a recorded check stands before the next invocation re-probes.
+ *  `CRTR_PLUGIN_REVALIDATE_TTL_MS=0` disables the pass outright — which is how
+ *  a test, or any process that must not reach the network, opts out. */
+function ttlMs() {
+    const raw = process.env['CRTR_PLUGIN_REVALIDATE_TTL_MS'];
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_TTL_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_TTL_MS;
+    return parsed;
+}
+/** A check is fresh for `ttl` after it happened. A `checked_at` in the FUTURE
+ *  did not happen: a clock that jumped back, or a file copied from another
+ *  machine, must not be able to suppress the pass until the clock catches up. */
+function isFresh(checkedAt, ttl, now) {
+    if (checkedAt === undefined)
+        return false;
+    const at = Date.parse(checkedAt);
+    if (Number.isNaN(at))
+        return false;
+    const age = now - at;
+    return age >= 0 && age < ttl;
+}
+/** A command that manages packages does its own fetching, with its own reporting
+ *  and its own exit codes. Revalidating underneath it would race that work and
+ *  make the leaf's result describe a package it did not install. `crtr --json
+ *  pkg …` is that same command: the global tokens the dispatcher strips are not
+ *  part of the command path here either. */
+function managesPackages(argv) {
+    return argv.slice(2).find((token) => !GLOBAL_TOKENS.has(token)) === 'pkg';
+}
+/** Every bundle plugin whose last check has aged out, resolved from the same
+ *  scope root whose state ledger records the check — so the plugin read and the
+ *  `checked_at` write can never describe different roots. */
+function duePlugins(ttl, now) {
+    const due = [];
+    const claimed = new Set();
+    for (const scope of SCOPES) {
+        const root = scopeRoot(scope);
+        if (root === null)
+            continue;
+        const state = readState(scope);
+        for (const plugin of listInstalledPluginsInRoot(scope, root)) {
+            if (claimed.has(plugin.name))
+                continue;
+            claimed.add(plugin.name);
+            const bundle = plugin.manifest.bundle;
+            if (!plugin.enabled || bundle === undefined)
+                continue;
+            if (isFresh(state.plugins[plugin.name]?.checked_at, ttl, now))
+                continue;
+            due.push({ name: plugin.name, scope, bundle, enabled: plugin.enabled });
+        }
+    }
+    return due;
+}
+/**
+ * Bring every installed bundle plugin whose last check has aged out back in
+ * step with its endpoint. Never throws: a plugin that cannot be revalidated
+ * keeps the package already unpacked on disk, which is a complete and valid
+ * command tree, and the failure is reported on stderr rather than replacing the
+ * caller's command with an error about a background check.
+ */
+export async function revalidateBundlePlugins(argv) {
+    const ttl = ttlMs();
+    if (ttl === 0 || managesPackages(argv))
+        return;
+    let due;
+    try {
+        due = duePlugins(ttl, Date.now());
+    }
+    catch {
+        // Enumeration reads config, state, and every installed plugin.json. A scope
+        // this process cannot read is a scope it also cannot revalidate, and the
+        // command it was invoked for may not need plugins at all.
+        return;
+    }
+    if (due.length === 0)
+        return;
+    const { revalidateBundlePlugin } = await import('../../commands/pkg/plugin-manage.js');
+    for (const plugin of due) {
+        try {
+            await revalidateBundlePlugin(plugin.name, plugin.bundle, plugin.scope, {
+                enable: plugin.enabled,
+                conditional: true,
+                timeoutMs: 2_000,
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`crtr: plugin "${plugin.name}" could not be revalidated (${detail}); using the installed package.\n`);
+        }
+    }
+}
+/**
+ * Force one plugin back in step with its endpoint, ignoring both the TTL and
+ * the stored validator. Recovery from a server that answered `manifest_stale`:
+ * the description the caller invoked from is out of date, so the check that
+ * would normally be skipped is exactly the one that has to run.
+ *
+ * Returns whether the package on disk actually changed, so a caller can tell a
+ * recoverable staleness from an operation that is genuinely gone.
+ */
+export async function forceRevalidateBundlePlugin(name) {
+    let plugin;
+    for (const scope of SCOPES) {
+        const root = scopeRoot(scope);
+        if (root === null)
+            continue;
+        plugin = listInstalledPluginsInRoot(scope, root).find((candidate) => candidate.name === name);
+        if (plugin !== undefined)
+            break;
+    }
+    const bundle = plugin?.manifest.bundle;
+    if (plugin === undefined || bundle === undefined)
+        return false;
+    const { revalidateBundlePlugin } = await import('../../commands/pkg/plugin-manage.js');
+    // An unconditional refetch either swaps the package or reports that the bytes
+    // the server served are byte-identical to the ones already unpacked. Both
+    // answers are the swap's own, so `undefined` here means "nothing changed" —
+    // the operation the caller invoked is genuinely gone, and the server's error
+    // stands.
+    const replaced = await revalidateBundlePlugin(name, bundle, plugin.scope, {
+        enable: plugin.enabled,
+        conditional: false,
+    });
+    return replaced !== undefined;
+}

package/dist/core/command-plugins/transport/http-fetch.d.ts

@@ -3,14 +3,39 @@ import type { HttpPluginFetchTarget } from '../endpoint.js';
 export interface FetchSuccess {
     status: 200;
     raw: Uint8Array;
+    /** The server's validator for these exact bytes, when it sent one. Storing it
+     *  is what lets the next fetch be conditional. */
+    etag?: string;
 }
-export type FetchResult = FetchSuccess | FetchFailure;
+/** The archive the caller already holds is still current. Only ever returned
+ *  when the caller supplied `ifNoneMatch`. */
+export interface FetchNotModified {
+    status: 304;
+}
+export type FetchResult = FetchSuccess | FetchNotModified | FetchFailure;
 export interface FetchFailure {
     status: 'auth_env_missing' | 'cli_unreachable' | 'cli_protocol_error';
     message: string;
 }
+export interface FetchOptions {
+    /** Send as `If-None-Match`, inviting the server to answer 304 instead of
+     *  resending an archive the caller already has unpacked. */
+    ifNoneMatch?: string;
+    /** Inactivity timeout. Defaults to ten seconds, which suits an install the
+     *  caller is waiting on; a revalidation on an ordinary command's latency path
+     *  passes something far shorter. */
+    timeoutMs?: number;
+}
 /**
- * One authenticated GET for a plugin directory archive. It has one ten-second
- * inactivity timeout and never retries or conditionally revalidates.
+ * One authenticated GET for a plugin directory archive, conditional when the
+ * caller supplies a validator. It never retries.
+ *
+ * A caller that sends no validator cannot be answered 304 — there is nothing
+ * for the server to compare against — and the overloads say so, so an
+ * unconditional caller handles the two outcomes it can actually get instead of
+ * carrying an unreachable branch for the third.
  */
-export declare function fetchHttpPluginBundle(registration: HttpPluginFetchTarget): Promise<FetchResult>;
+export declare function fetchHttpPluginBundle(registration: HttpPluginFetchTarget, options?: FetchOptions & {
+    ifNoneMatch?: never;
+}): Promise<FetchSuccess | FetchFailure>;
+export declare function fetchHttpPluginBundle(registration: HttpPluginFetchTarget, options: FetchOptions): Promise<FetchResult>;

package/dist/core/command-plugins/transport/http-fetch.js

@@ -1,11 +1,7 @@
 import { URL } from 'node:url';
 import { request as httpsRequest } from 'node:https';
 import { request as httpRequest } from 'node:http';
-/**
- * One authenticated GET for a plugin directory archive. It has one ten-second
- * inactivity timeout and never retries or conditionally revalidates.
- */
-export async function fetchHttpPluginBundle(registration) {
+export async function fetchHttpPluginBundle(registration, options = {}) {
     let token;
     if (registration.authEnv) {
         token = process.env[registration.authEnv];
@@ -26,20 +22,34 @@ export async function fetchHttpPluginBundle(registration) {
             message: `Invalid endpoint URL: ${registration.endpoint}`,
         };
     }
+    const timeoutMs = options.timeoutMs ?? 10_000;
     const headers = { Accept: 'application/x-tar' };
     if (token)
         headers['Authorization'] = `Bearer ${token}`;
+    if (options.ifNoneMatch !== undefined)
+        headers['If-None-Match'] = options.ifNoneMatch;
     return new Promise((resolve) => {
         const request = url.protocol === 'https:' ? httpsRequest : httpRequest;
-        const req = request(url, { method: 'GET', headers, timeout: 10_000 }, (res) => {
+        const req = request(url, { method: 'GET', headers, timeout: timeoutMs }, (res) => {
             let body = Buffer.alloc(0);
             res.on('data', (chunk) => { body = Buffer.concat([body, chunk]); });
             res.on('end', () => {
+                const etag = res.headers['etag'];
                 if (!res.statusCode) {
                     resolve({ status: 'cli_protocol_error', message: 'No HTTP status code received.' });
                 }
+                else if (res.statusCode === 304) {
+                    // Unsolicited: the caller has no archive this could be affirming, so
+                    // there is nothing on disk for a bare 304 to mean.
+                    if (options.ifNoneMatch === undefined) {
+                        resolve({ status: 'cli_protocol_error', message: `HTTP 304 from ${registration.endpoint} without a conditional request` });
+                    }
+                    else {
+                        resolve({ status: 304 });
+                    }
+                }
                 else if (res.statusCode >= 200 && res.statusCode < 300) {
-                    resolve({ status: 200, raw: new Uint8Array(body) });
+                    resolve({ status: 200, raw: new Uint8Array(body), ...(typeof etag === 'string' ? { etag } : {}) });
                 }
                 else {
                     resolve({ status: 'cli_protocol_error', message: `HTTP ${res.statusCode} from ${registration.endpoint}` });
@@ -48,7 +58,7 @@ export async function fetchHttpPluginBundle(registration) {
         });
         req.on('timeout', () => {
             req.destroy();
-            resolve({ status: 'cli_unreachable', message: `Request timeout (10s) fetching ${registration.endpoint}` });
+            resolve({ status: 'cli_unreachable', message: `Request timeout (${timeoutMs}ms) fetching ${registration.endpoint}` });
         });
         req.on('error', (error) => {
             resolve({ status: 'cli_unreachable', message: `Network error fetching ${registration.endpoint}: ${error.message}` });

package/dist/core/command-plugins/transport/http-invoke.js

@@ -17,6 +17,7 @@ import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { validateDeclaredResult } from './exec-invoke.js';
 import { CrtrError } from '../../errors.js';
+import { envelopeClaimsStale, staleErrorDetails } from '../../manifest-stale.js';
 import { diag, recordPreviewError, recordPreviewJsonLine, writeStdout } from '../../io.js';
 import { ExitCode } from '../../../types.js';
 import { isRecord } from '../../../shared/predicates.js';
@@ -479,9 +480,15 @@ function throwNon2xx(spec, status, body) {
             const field = typeof err['field'] === 'string' ? err['field'] : undefined;
             const next = typeof err['next'] === 'string' ? err['next'] : `Inspect the backend response, then retry if appropriate.`;
             const accepted = SNAKE.test(code) && !RESERVED_CODES.has(code);
+            // A generic recovery hint, not a backend-specific code: the server is
+            // saying the command description this call was parsed from is out of
+            // date. The dispatcher acts on it by refetching the plugin's package and
+            // re-running the original argv against the refreshed tree.
+            const manifestStale = envelopeClaimsStale(err);
             throw new CrtrError(accepted ? code : 'cli_protocol_error', message, exit, {
                 ...(err['received'] !== undefined ? { received: err['received'] } : {}),
                 ...(field !== undefined ? { field } : {}),
+                ...(manifestStale ? staleErrorDetails(spec.registration.name) : {}),
                 http_status: status,
                 next,
             });

package/dist/core/command.d.ts

@@ -173,5 +173,13 @@ export interface ParseArgvOptions {
  *  Returns a plain object whose keys are camelCase parameter names.
  *  Optionally tracks which parameters were explicitly provided via a callback. */
 export declare function parseArgv(params: InputParam[], tokens: string[], options?: ParseArgvOptions): Promise<Record<string, unknown>>;
+/**
+ * Tokens handled before dispatch and stripped from what the leaf schema parses
+ * (root `-h` renders them as the Globals footer). They belong to no command, so
+ * anything reasoning about which command an argv names — the plugin
+ * revalidation gate, for one — has to ignore them too. One declaration, so a
+ * new global cannot be added here and missed there.
+ */
+export declare const GLOBAL_TOKENS: ReadonlySet<string>;
 export declare function runCli(root: RootDef, argv: string[]): Promise<void>;
 export {};

package/dist/core/command.js

@@ -8,6 +8,7 @@ import { renderRoot, renderBranch, renderLeafArgv } from './help.js';
 import { beginPreview, publishPreviewResult, readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
 import { renderResult } from './render.js';
 import { CrtrError } from './errors.js';
+import { isManifestStaleError } from './manifest-stale.js';
 import { operationIdContext } from './events/operation-id.js';
 import { ExitCode } from '../types.js';
 import { readFileSync } from 'node:fs';
@@ -594,6 +595,14 @@ export async function parseArgv(params, tokens, options) {
     }
     return result;
 }
+/**
+ * Tokens handled before dispatch and stripped from what the leaf schema parses
+ * (root `-h` renders them as the Globals footer). They belong to no command, so
+ * anything reasoning about which command an argv names — the plugin
+ * revalidation gate, for one — has to ignore them too. One declaration, so a
+ * new global cannot be added here and missed there.
+ */
+export const GLOBAL_TOKENS = new Set(['--json', '--no-autostart']);
 export async function runCli(root, argv) {
     // argv is process.argv — strip node binary + script path. `--json` is a
     // global: pull it out anywhere it appears so the rest of argv parses against
@@ -607,10 +616,9 @@ export async function runCli(root, argv) {
     // to every API-backed verb, so strip it here rather than declaring it on each
     // leaf schema (an undeclared flag would otherwise be rejected as unknown).
     const rawTokens = argv.slice(2);
-    const jsonStripped = rawTokens.filter((t) => t !== '--json');
-    if (jsonStripped.length !== rawTokens.length)
+    if (rawTokens.includes('--json'))
         setJsonOutput(true);
-    const tokens = jsonStripped.filter((t) => t !== '--no-autostart');
+    const tokens = rawTokens.filter((token) => !GLOBAL_TOKENS.has(token));
     // Bare root invocation or -h at root
     if (tokens.length === 0 || (tokens.length === 1 && (tokens[0] === '-h' || tokens[0] === '--help'))) {
         process.stdout.write(renderRoot(root.help) + '\n');
@@ -686,6 +694,14 @@ export async function runCli(root, argv) {
         // JSONL leaves call emitLine themselves and return void
     }
     catch (e) {
+        // A backend that answered `manifest_stale` says this dispatch was parsed
+        // from an out-of-date command description. Only the caller above this one
+        // can act on that — refetching the package and re-walking the ORIGINAL argv
+        // against the refreshed tree — so it is the single error class this
+        // dispatcher reports by rethrowing instead of rendering. Whoever declines
+        // to recover renders it with the same `handle`.
+        if (isManifestStaleError(e))
+            throw e;
         handle(e);
     }
 }

package/dist/core/config.d.ts

@@ -1,4 +1,4 @@
-import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
+import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig, ProviderOptionsConfig } from '../types.js';
 import { type BindingId } from './keybindings/catalog.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
@@ -111,6 +111,9 @@ export declare function readRawScopeConfig(scope: Scope): Partial<ScopeConfig> |
 export interface MergedLaunchConfig {
     kinds: Record<string, KindConfig>;
     modelLadders: ModelLaddersConfig;
+    /** Per-provider behavior options keyed by runtime provider id, merged
+     *  per provider across scopes (project stack > profile > user). */
+    providerOptions: Record<string, ProviderOptionsConfig>;
     /** Complete declared routes. Every route here has all four strengths. */
     modelRoutes?: Record<string, ModelRouteConfig>;
     /** Read-only compatibility view for sparse routes written before complete