@north-light/crouter 0.3.281 → 0.3.282

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/exclusive-lock.d.ts

@@ -4,6 +4,18 @@
  *  work" apart from "my child is queued behind someone else's work" without
  *  any new bookkeeping. */
 export declare function exclusiveLockOwnerPid(path: string): number | null;
+/**
+ * Block until `path` is no longer held by a LIVE other process, or the wait
+ * runs out. Unlike `withExclusiveDirectoryLock*` this never CLAIMS the lock —
+ * it is for a reader that only needs the holder's transition to be over before
+ * it looks at the directory the holder is rewriting.
+ *
+ * Returns immediately when the lock is free, when its marker names this very
+ * process (a caller waiting on its own lock would otherwise deadlock), or when
+ * the named owner is gone — a dead holder's transition is already over, however
+ * it ended.
+ */
+export declare function awaitExclusiveLockRelease(path: string, timeoutMs: number): void;
 export interface ExclusiveLockOptions {
     /** Grace before a lock that names no owner at all is cleared. */
     staleMs?: number;

package/dist/core/exclusive-lock.js

@@ -103,6 +103,35 @@ export function exclusiveLockOwnerPid(path) {
     const pid = Number(token.split('.', 1)[0]);
     return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
 }
+/**
+ * Block until `path` is no longer held by a LIVE other process, or the wait
+ * runs out. Unlike `withExclusiveDirectoryLock*` this never CLAIMS the lock —
+ * it is for a reader that only needs the holder's transition to be over before
+ * it looks at the directory the holder is rewriting.
+ *
+ * Returns immediately when the lock is free, when its marker names this very
+ * process (a caller waiting on its own lock would otherwise deadlock), or when
+ * the named owner is gone — a dead holder's transition is already over, however
+ * it ended.
+ */
+export function awaitExclusiveLockRelease(path, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let pollMs = POLL_MS;
+    for (;;) {
+        const token = observedMarkerToken(path);
+        if (token === null)
+            return;
+        if (Number(token.split('.', 1)[0]) === process.pid)
+            return;
+        if (!ownerIsAlive(token))
+            return;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return;
+        pause(Math.min(pollMs, remaining));
+        pollMs = nextPollMs(pollMs);
+    }
+}
 function tryAcquire(path, staleMs) {
     const token = `${process.pid}.${randomUUID()}`;
     try {

package/dist/core/installed-plugins.js

@@ -11,15 +11,46 @@ import { join } from 'node:path';
 import { CONFIG_FILE } from '../types.js';
 import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
 import { readPluginManifest } from './manifest.js';
+import { awaitBundleSwap, bundleSwapInFlightElsewhere } from './plugin-swap-lock.js';
 function pluginConfigForRoot(root) {
     const cfg = readJsonIfExists(join(root, CONFIG_FILE));
     return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
 }
+/**
+ * A bundle-plugin swap replaces `<plugins>/<name>` with two renames, so there
+ * is a window in which the config names a plugin whose directory is not there.
+ * A list taken inside that window would drop a plugin that is installed and
+ * about to be present again — the caller would build a command tree missing it.
+ *
+ * That exact signal — named in config, absent on disk — is what we re-check,
+ * and only when another process's swap lock says a swap is actually running: a
+ * genuinely deleted directory holds no lock and is reported as gone at once.
+ * Every normal invocation, where each config-named plugin has its directory,
+ * pays one Set lookup per name and nothing else.
+ */
+function swapsToWaitOut(scopeRootPath, cfg, present) {
+    const names = Object.keys(cfg);
+    if (names.every((name) => present.has(name)))
+        return [];
+    return names.filter((name) => !present.has(name) && bundleSwapInFlightElsewhere(scopeRootPath, name));
+}
 export function listInstalledPluginsInRoot(scope, scopeRootPath) {
     const dir = join(scopeRootPath, 'plugins');
     if (!pathExists(dir))
         return [];
     const cfg = pluginConfigForRoot(scopeRootPath);
+    const first = collectInstalledPlugins(scope, dir, cfg);
+    const waiting = swapsToWaitOut(scopeRootPath, cfg, new Set(first.map((plugin) => plugin.name)));
+    if (waiting.length === 0)
+        return first;
+    for (const name of waiting)
+        awaitBundleSwap(scopeRootPath, name);
+    // One re-list, never a loop: the second read is taken after every swap we
+    // observed has finished. A swap that starts after it is a package this
+    // invocation was never going to see anyway.
+    return collectInstalledPlugins(scope, dir, cfg);
+}
+function collectInstalledPlugins(scope, dir, cfg) {
     const out = [];
     for (const name of listDirs(dir)) {
         const root = join(dir, name);

package/dist/core/manifest-recovery.d.ts

@@ -0,0 +1,15 @@
+import type { RootDef } from './command.js';
+/**
+ * Run `argv` against `root`, and if the backend answers `manifest_stale`,
+ * refetch that plugin's package and run the ORIGINAL argv again against a
+ * freshly resolved tree — exactly once.
+ *
+ * Re-parsing the original argv, rather than re-running the leaf that failed, is
+ * what makes a RENAMED verb recoverable: the old leaf no longer exists in the
+ * refreshed tree, and only the dispatcher can answer that against the fresh
+ * tree's own siblings.
+ *
+ * Never throws: every outcome is rendered through the dispatcher's own
+ * `handle`, so a caller can mark the end of dispatch unconditionally.
+ */
+export declare function dispatchWithStaleRecovery(root: RootDef, argv: string[]): Promise<void>;