@north-light/crouter 0.3.280 → 0.3.282

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`

package/dist/commands/pkg/plugin-manage.js

@@ -6,7 +6,9 @@ import { defineLeaf } from '../../core/command.js';
 import { notFound, usage, general, network } from '../../core/errors.js';
 import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
 import { NEUTRAL_PROJECT_MEMORY, pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
-import { updateConfig, updateState, ensureScopeInitialized, invalidPluginKindsReasons, invalidPluginBinReasons, invalidPluginRequiresReasons, normalizeRequires } from '../../core/config.js';
+import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized, invalidPluginKindsReasons, invalidPluginBinReasons, invalidPluginRequiresReasons, normalizeRequires } from '../../core/config.js';
+import { withExclusiveDirectoryLockAsync } from '../../core/exclusive-lock.js';
+import { bundleSwapLockPath } from '../../core/plugin-swap-lock.js';
 import { invalidPageComponentsReasons } from '../../core/human/page-catalog.js';
 import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, readSymlinkTarget, atomicWriteJson, readText, realpathOrSelf, walkFiles } from '../../core/fs-utils.js';
 import { clone, deriveNameFromUrl, currentSha, gitSync, isGitRepo } from '../../core/git.js';
@@ -317,26 +319,163 @@ function existingBundleRoot(name, scope, root) {
         rejectLegacyHttpPlugin(name);
     throw general(`plugin "${name}" already exists at ${root}; run \`crtr pkg plugin remove ${name}\` before installing the archive plugin.`);
 }
-async function replaceBundlePlugin(name, bundleSource, scope, options) {
+function resolveBundleTarget(name, bundleSource, scope, scopeRootPath) {
     const fetchTransport = validateHttpInstall(name, bundleSource.endpoint, bundleSource.authEnv);
     const bundle = { endpoint: fetchTransport.endpoint, ...(fetchTransport.authEnv !== undefined ? { authEnv: fetchTransport.authEnv } : {}) };
-    const transport = invocationTransport(bundle);
-    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
     const root = join(scopeRootPath, 'plugins', name);
     existingBundleRoot(name, scope, root);
-    const fetched = await fetchHttpPluginBundle({ name, endpoint: bundle.endpoint, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) });
-    if (fetched.status !== 200) {
-        const message = `HTTP plugin bundle fetch failed for "${name}": ${fetched.message}`;
-        if (fetched.status === 'auth_env_missing')
-            throw usage(message);
-        if (fetched.status === 'cli_unreachable')
-            throw network(message);
-        throw general(message);
-    }
-    const validated = await validatePluginBundle(fetched.raw, { reservedCoreNames: new Set(SUBTREE_NAMES), coreCommandPaths: await coreCommandPaths() });
+    return { bundle, transport: invocationTransport(bundle), scopeRootPath, root };
+}
+function fetchTarget(name, bundle) {
+    return { name, endpoint: bundle.endpoint, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) };
+}
+/** A user-initiated install or update waits out another process's swap; the
+ *  background pass waits a shorter time, because a wait that long there means
+ *  the holder is wedged rather than merely slow. */
+const INSTALL_SWAP_WAIT_MS = 60_000;
+const REVALIDATE_SWAP_WAIT_MS = 10_000;
+/**
+ * Serialize a plugin's package replacement against every other crtr process.
+ *
+ * The whole transition runs inside — re-reading the stored validator, the
+ * conditional fetch, the identity check, the directory swap, and both ledger
+ * writes. Holding it across the FETCH is the point: a process that queued
+ * behind another's swap re-reads the validator the winner just stored, so it
+ * sends the fresh ETag and is answered 304, instead of downloading the archive
+ * it waited for and swapping in a package identical to the one already there.
+ *
+ * The lock lives beside the staging and `.prev` directories the swap itself
+ * uses, and a holder that dies releases it immediately (its marker names a dead
+ * pid), so a crashed swap cannot wedge the next one.
+ */
+async function withBundleSwapLock(name, scope, timeoutMs, run) {
+    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
+    ensureDir(join(scopeRootPath, 'tmp'));
+    return withExclusiveDirectoryLockAsync(bundleSwapLockPath(scopeRootPath, name), () => run(scopeRootPath), {
+        timeoutMs,
+        timeoutError: () => general(`timed out waiting for another crtr process to finish replacing plugin "${name}"`, {
+            next: `Re-run once that process has finished, or check for a stalled crtr holding ${bundleSwapLockPath(scopeRootPath, name)}.`,
+        }),
+    });
+}
+async function replaceBundlePlugin(name, bundleSource, scope, options) {
+    return withBundleSwapLock(name, scope, INSTALL_SWAP_WAIT_MS, async (scopeRootPath) => {
+        const target = resolveBundleTarget(name, bundleSource, scope, scopeRootPath);
+        const fetched = await fetchHttpPluginBundle(fetchTarget(name, target.bundle));
+        if (fetched.status !== 200) {
+            const message = `HTTP plugin bundle fetch failed for "${name}": ${fetched.message}`;
+            if (fetched.status === 'auth_env_missing')
+                throw usage(message);
+            if (fetched.status === 'cli_unreachable')
+                throw network(message);
+            throw general(message);
+        }
+        return applyBundleArchive(name, scope, target, fetched.raw, fetched.etag, options);
+    });
+}
+/**
+ * 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 async function revalidateBundlePlugin(name, bundleSource, scope, options) {
+    return withBundleSwapLock(name, scope, REVALIDATE_SWAP_WAIT_MS, async (scopeRootPath) => {
+        try {
+            const target = resolveBundleTarget(name, bundleSource, scope, scopeRootPath);
+            // Read INSIDE the lock: a process that queued behind another's swap must
+            // send the validator that swap stored, not the one it read before waiting.
+            const etag = options.conditional ? readState(scope).plugins[name]?.etag : undefined;
+            const fetchOptions = {
+                ...(etag !== undefined ? { ifNoneMatch: etag } : {}),
+                ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+            };
+            const fetched = await fetchHttpPluginBundle(fetchTarget(name, target.bundle), fetchOptions);
+            if (fetched.status === 304)
+                return undefined;
+            if (fetched.status !== 200) {
+                throw general(`HTTP plugin bundle revalidation failed for "${name}": ${fetched.message}`);
+            }
+            // A server with no validator, or one whose validator moved without the
+            // archive changing, re-sends bytes we already have unpacked. Swapping
+            // them in would rewrite the package root and republish an identical
+            // command tree for nothing, so hash first: identical bytes are a 304 that
+            // cost a download, and get a 304's answer.
+            const version = bundleVersion(fetched.raw);
+            if (isInstalledGeneration(name, scope, target.root, version)) {
+                recordCheckedGeneration(scope, name, fetched.etag, { swapped: false });
+                return undefined;
+            }
+            return await applyBundleArchive(name, scope, target, fetched.raw, fetched.etag, options, version);
+        }
+        finally {
+            // Widened to cover `resolveBundleTarget` as well as the fetch: a plugin
+            // whose endpoint no longer validates throws on every invocation, and
+            // without a recorded check it would throw on every invocation forever.
+            recordPluginCheck(scope, name);
+        }
+    });
+}
+/** Mark that the revalidation pass reached this plugin, whatever came of it.
+ *  Separate from the etag write, which only a served archive earns. */
+function recordPluginCheck(scope, name) {
+    updateState(scope, (state) => {
+        if (state.plugins[name] === undefined)
+            state.plugins[name] = {};
+        state.plugins[name].checked_at = nowIso();
+    });
+}
+/** The ledger for a check that reached a served archive. `swapped` says whether
+ *  that archive replaced the package on disk; the validator and the check time
+ *  are recorded either way, because both describe the bytes now at the root. */
+function recordCheckedGeneration(scope, name, etag, options) {
+    updateState(scope, (state) => {
+        if (state.plugins[name] === undefined)
+            state.plugins[name] = {};
+        if (options.swapped)
+            state.plugins[name].last_updated = nowIso();
+        state.plugins[name].checked_at = nowIso();
+        // The validator names the bytes now unpacked at `root`. A response that
+        // carried none clears it, so the next check cannot claim to hold a
+        // validator for a package it never received one for.
+        if (etag === undefined)
+            delete state.plugins[name].etag;
+        else
+            state.plugins[name].etag = etag;
+    });
+}
+/** The hash recorded as a bundle package's `version`: the exact archive bytes
+ *  unpacked at its root. Same bytes, same version — which is what lets a
+ *  re-sent archive be recognized as the generation already installed. */
+function bundleVersion(raw) {
+    return createHash('sha256').update(raw).digest('hex').slice(0, 12);
+}
+/** Whether `version` is the generation already unpacked at `root`. Both halves
+ *  matter: the recorded version says the config agrees, and `commands.json`
+ *  says the tree that config describes is actually on disk. A swap that died
+ *  between the rename and the config write leaves the second false, and that is
+ *  exactly the case a no-op must not claim. */
+function isInstalledGeneration(name, scope, root, version) {
+    if (readConfig(scope).plugins[name]?.version !== version)
+        return false;
+    return pathExists(join(root, 'commands.json'));
+}
+async function applyBundleArchive(name, scope, target, raw, etag, options, knownVersion) {
+    const { bundle, transport, scopeRootPath, root } = target;
+    const validated = await validatePluginBundle(raw, { reservedCoreNames: new Set(SUBTREE_NAMES), coreCommandPaths: await coreCommandPaths() });
     if (validated.bundle === undefined)
         throw invalidBundleError(`HTTP plugin bundle for "${name}" is invalid`, validated.issues);
-    const version = createHash('sha256').update(fetched.raw).digest('hex').slice(0, 12);
+    const version = knownVersion ?? bundleVersion(raw);
     const manifest = {
         name,
         version,
@@ -388,15 +527,19 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     finally {
         removePath(staging);
     }
+    // Directory swap, then the config's version, then the state's validator — in
+    // that order, and never the reverse. A process killed mid-sequence leaves the
+    // ledger naming an OLDER generation than the disk, which the next check
+    // repairs: the server 200s against a stale-or-absent validator, the hash says
+    // the tree on disk is already that generation, and only the ledger is
+    // rewritten. The forbidden state — a validator for a generation the disk does
+    // not have, and so a permanent 304 against a package that was never unpacked
+    // — is unreachable from this order.
     ensureScopeInitialized(scope, scopeRootPath);
     updateConfig(scope, (cfg) => {
         cfg.plugins[name] = { enabled: options.enable ? true : (cfg.plugins[name]?.enabled ?? true), version };
     });
-    updateState(scope, (state) => {
-        if (state.plugins[name] === undefined)
-            state.plugins[name] = {};
-        state.plugins[name].last_updated = nowIso();
-    });
+    recordCheckedGeneration(scope, name, etag, { swapped: true });
     const commands = await commandReport(name, scope);
     if (commands === undefined)
         throw general(`bundle plugin "${name}" has no staged command report`);
@@ -838,6 +981,13 @@ export const pluginRemove = defineLeaf({
             updateConfig(scope, (cfg) => {
                 delete cfg.plugins[name];
             });
+            // The state record describes a package that no longer exists. Leaving it
+            // would hand a later reinstall of the same name a validator for bytes it
+            // never fetched, and keep the revalidation pass considering a plugin that
+            // is gone.
+            updateState(scope, (state) => {
+                delete state.plugins[name];
+            });
             removedFrom.push(scope);
         }
         if (removedFrom.length === 0) {

package/dist/core/__tests__/integration/plugin-revalidate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/integration/plugin-revalidate.test.js

@@ -0,0 +1,355 @@
+// Contract-seam tests for bundle-plugin revalidation against a stub endpoint.
+// Run with: npm run test:integration
+//
+// Two behaviors whose absence would be SILENT — the package on disk would still
+// be a complete, valid command tree, so nothing fails loudly while the client
+// dispatches against a description the server retired:
+//
+//  1. Round trip — an install stores the served validator; a later check sends
+//     it conditionally, leaves the package untouched on 304, and swaps it on a
+//     200 that carries different bytes.
+//  2. Refetch on miss — the forced refetch a `manifest_stale` answer triggers
+//     reports whether the package actually CHANGED. That boolean is the whole
+//     branch: false means the operation is genuinely gone and the server's own
+//     error stands, true means the retry has a fresher tree to parse against.
+//  3. Recovery from a RENAMED op, end to end and entirely off the wire: the
+//     stub answers the v1 op with a real 400 error envelope carrying
+//     `manifest_stale`, so the flag is parsed by the transport rather than
+//     hand-built. `runCli` renders every other failure itself, so recovery is
+//     unreachable unless this one class escapes it — and from the outside a
+//     rendered error looks identical to a recovered one. Its three legs: the
+//     escape, the refetch-and-replay, and exactly-once.
+//
+// All run against an isolated HOME and a startDir with no `.crouter` ancestor,
+// so no ambient plugin or scope of the developer's machine is reachable.
+import { test, describe, before, beforeEach, afterEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync, readFileSync, realpathSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as tar from 'tar';
+import { resetScopeCache, userScopeRoot } from '../../scope.js';
+import { readState, readConfig } from '../../config.js';
+import { revalidateBundlePlugins, forceRevalidateBundlePlugin } from '../../command-plugins/revalidate.js';
+import { pluginInstall } from '../../../commands/pkg/plugin-manage.js';
+import { runCli } from '../../command.js';
+import { buildRoot } from '../../../build-root.js';
+import { dispatchWithStaleRecovery } from '../../manifest-recovery.js';
+import { CrtrError } from '../../errors.js';
+const PLUGIN = 'revalidate-fixture';
+const ARGV = ['node', 'crtr', 'demo', 'show'];
+/** The positional the fixture leaf echoes back. */
+const FIXTURE_ID = 'fixture-1';
+let isolatedHome;
+let isolatedCwd;
+let prevHome;
+let prevTtl;
+let prevCwd;
+let server;
+let endpoint;
+/** What the stub serves right now, and what every BUNDLE request asked for. */
+let served;
+let requests;
+/** Which generations of the `demo show` op this backend has retired. A call
+ *  against a retired one gets the 400 + `manifest_stale` envelope that drives
+ *  client recovery; any other generation is served normally. */
+let retiredOps;
+/** Every generation the leaf was actually invoked at, in order — `['v1','v2']`
+ *  is one recovery: the stale call, then the replay against the fresh tree. */
+let opCalls;
+before(() => {
+    prevHome = process.env.HOME;
+    prevTtl = process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS;
+    prevCwd = process.cwd();
+});
+beforeEach(async () => {
+    isolatedHome = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-revalidate-home-')));
+    isolatedCwd = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-revalidate-cwd-')));
+    process.env.HOME = isolatedHome;
+    process.chdir(isolatedCwd);
+    resetScopeCache();
+    served = { archive: makeArchive('v1'), etag: '"sha256-v1"' };
+    requests = [];
+    retiredOps = new Set();
+    opCalls = [];
+    server = createServer((req, res) => {
+        const path = (req.url ?? '/').split('?')[0] ?? '/';
+        const op = /^\/(v\d+)\/demo\/(.+)$/.exec(path);
+        if (op !== null) {
+            serveOp(res, op[1], op[2]);
+            return;
+        }
+        if (path !== '/v1/cli/bundle') {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: { code: 'not_found', message: `no route for ${path}` } }));
+            return;
+        }
+        const ifNoneMatch = typeof req.headers['if-none-match'] === 'string' ? req.headers['if-none-match'] : undefined;
+        if (ifNoneMatch === served.etag) {
+            requests.push({ ifNoneMatch, status: 304 });
+            res.writeHead(304, { ETag: served.etag, 'Cache-Control': 'private, no-cache' });
+            res.end();
+            return;
+        }
+        requests.push({ ifNoneMatch, status: 200 });
+        res.writeHead(200, { 'Content-Type': 'application/x-tar', ETag: served.etag, 'Cache-Control': 'private, no-cache' });
+        res.end(Buffer.from(served.archive));
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (address === null || typeof address === 'string')
+        throw new Error('stub server has no TCP address');
+    endpoint = `http://127.0.0.1:${address.port}/v1/cli/bundle`;
+});
+afterEach(async () => {
+    await new Promise((resolve) => server.close(() => resolve()));
+    process.chdir(prevCwd);
+    rmSync(isolatedHome, { recursive: true, force: true });
+    rmSync(isolatedCwd, { recursive: true, force: true });
+});
+after(() => {
+    process.chdir(prevCwd);
+    process.env.HOME = prevHome;
+    if (prevTtl === undefined)
+        delete process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS;
+    else
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = prevTtl;
+    resetScopeCache();
+});
+/** The `demo show` leaf, answered at whichever generation the caller's tree
+ *  parsed the path from. A retired generation gets a real error envelope with
+ *  `manifest_stale` set, so the flag reaches the client through the transport's
+ *  own JSON parse rather than being constructed in the test. */
+function serveOp(res, generation, id) {
+    opCalls.push(generation);
+    if (retiredOps.has(generation)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            error: {
+                code: 'cli_op_unknown',
+                message: `this backend no longer serves "demo show" at ${generation}`,
+                manifest_stale: true,
+                next: 'Refetch the plugin package and re-run.',
+            },
+        }));
+        return;
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ id }));
+}
+/** One archive per generation. `marker` rides the leaf description AND the REST
+ *  path its leaf calls, so the tree unpacked on disk says which generation
+ *  produced it, the two generations are different bytes with different
+ *  validators, and a call made from the OLD tree is distinguishable on the wire
+ *  from the same call made after a swap — which is exactly what a renamed op
+ *  looks like to a backend. */
+function makeArchive(marker) {
+    const commands = {
+        schemaVersion: 1,
+        mounts: [
+            {
+                parent: [],
+                node: {
+                    kind: 'branch',
+                    name: 'demo',
+                    description: `demo commands (${marker})`,
+                    whenToUse: 'you are exercising the revalidation seam',
+                    rootEntry: {
+                        concept: 'a fixture command tree served by the stub endpoint',
+                        description: `demo commands (${marker})`,
+                        whenToUse: 'you are exercising the revalidation seam',
+                    },
+                    summary: `demo commands (${marker})`,
+                    model: 'A fixture tree with one read-only leaf.',
+                    children: [
+                        {
+                            kind: 'leaf',
+                            name: 'show',
+                            description: `show the fixture (${marker})`,
+                            whenToUse: 'inspect the fixture record',
+                            tier: 'important',
+                            summary: `show the fixture record (${marker})`,
+                            params: [{ kind: 'positional', name: 'id', required: true, constraint: 'the fixture id' }],
+                            output: [{ name: 'id', type: 'string', required: true, constraint: 'the echoed fixture id' }],
+                            effects: ['None. Read-only.'],
+                            rest: { method: 'GET', path: `/${marker}/demo/{id}`, params: { id: { in: 'path' } } },
+                        },
+                    ],
+                },
+            },
+        ],
+    };
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-revalidate-tar-'));
+    try {
+        writeFileSync(join(dir, 'bundle.json'), JSON.stringify({ bundleVersion: 1 }));
+        writeFileSync(join(dir, 'commands.json'), JSON.stringify(commands));
+        const pack = tar.create({ sync: true, cwd: dir, portable: true }, ['bundle.json', 'commands.json']);
+        const chunks = [];
+        let chunk;
+        while ((chunk = pack.read()) !== null)
+            chunks.push(chunk);
+        return new Uint8Array(Buffer.concat(chunks));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+async function install() {
+    await pluginInstall.run({ endpoint, name: PLUGIN, scope: 'user' });
+}
+/** The generation of the tree actually unpacked under the user scope. */
+function installedMarker() {
+    const path = join(userScopeRoot(), 'plugins', PLUGIN, 'commands.json');
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    const description = parsed.mounts[0].node.description;
+    return description.slice(description.indexOf('(') + 1, description.indexOf(')'));
+}
+function pluginState() {
+    return readState('user').plugins[PLUGIN] ?? {};
+}
+function installedVersion() {
+    return readConfig('user').plugins[PLUGIN]?.version;
+}
+/** Age out the TTL without waiting one out: the pass measures freshness from
+ *  `checked_at`, so a one-millisecond TTL plus a real pause is due. */
+async function makeDue() {
+    process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '1';
+    await new Promise((resolve) => setTimeout(resolve, 5));
+}
+/** Run a dispatch and collect what the caller would actually have observed:
+ *  what reached stdout (both rendered results and rendered errors go there) and
+ *  whether anything escaped the frame. `process.exitCode` is restored, since a
+ *  rendered error sets it and would otherwise fail the whole test process. */
+async function captured(run) {
+    const chunks = [];
+    const realWrite = process.stdout.write.bind(process.stdout);
+    const realExitCode = process.exitCode;
+    process.stdout.write = ((chunk) => {
+        chunks.push(String(chunk));
+        return true;
+    });
+    let thrown;
+    try {
+        await run();
+    }
+    catch (error) {
+        thrown = error;
+    }
+    finally {
+        process.stdout.write = realWrite;
+        process.exitCode = realExitCode;
+    }
+    return { stdout: chunks.join(''), thrown };
+}
+describe('bundle plugin revalidation', () => {
+    test('an install fills the cache; an unchanged bundle 304s and a changed one swaps the package', async () => {
+        await install();
+        // The install IS the first cache fill: unconditional, and it stores what
+        // the server named for the bytes it unpacked.
+        assert.deepEqual(requests, [{ ifNoneMatch: undefined, status: 200 }]);
+        assert.equal(pluginState().etag, '"sha256-v1"');
+        assert.ok(pluginState().checked_at !== undefined);
+        assert.equal(installedMarker(), 'v1');
+        const firstVersion = installedVersion();
+        // Inside the TTL there is nothing to do, and nothing is asked.
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        await revalidateBundlePlugins(ARGV);
+        assert.equal(requests.length, 1);
+        // Due, unchanged: the request carries the stored validator, the server
+        // answers 304, and the package on disk is left exactly as it was.
+        await makeDue();
+        const beforeCheck = pluginState().checked_at;
+        await revalidateBundlePlugins(ARGV);
+        assert.deepEqual(requests[1], { ifNoneMatch: '"sha256-v1"', status: 304 });
+        assert.equal(installedMarker(), 'v1');
+        assert.equal(installedVersion(), firstVersion);
+        assert.equal(pluginState().etag, '"sha256-v1"');
+        assert.notEqual(pluginState().checked_at, beforeCheck);
+        // Due, changed: the 200 swaps the package, and the new validator replaces
+        // the old one so the next check is conditional on what is now on disk.
+        served = { archive: makeArchive('v2'), etag: '"sha256-v2"' };
+        await makeDue();
+        await revalidateBundlePlugins(ARGV);
+        assert.deepEqual(requests[2], { ifNoneMatch: '"sha256-v1"', status: 200 });
+        assert.equal(installedMarker(), 'v2');
+        assert.notEqual(installedVersion(), firstVersion);
+        assert.equal(pluginState().etag, '"sha256-v2"');
+    });
+    test('a forced refetch reports whether the package changed, ignoring a fresh TTL', async () => {
+        await install();
+        // A TTL the ordinary pass would honor. The forced path must not.
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        // Nothing newer is served: the operation the caller invoked is genuinely
+        // gone, so the refetch reports no change and the server's error stands.
+        assert.equal(await forceRevalidateBundlePlugin(PLUGIN), false);
+        assert.deepEqual(requests[1], { ifNoneMatch: undefined, status: 200 });
+        assert.equal(installedMarker(), 'v1');
+        // A changed package: the retry has a fresher tree to re-parse against.
+        served = { archive: makeArchive('v2'), etag: '"sha256-v2"' };
+        assert.equal(await forceRevalidateBundlePlugin(PLUGIN), true);
+        assert.equal(installedMarker(), 'v2');
+        assert.equal(pluginState().etag, '"sha256-v2"');
+        // A plugin that is not installed is not a recovery path.
+        assert.equal(await forceRevalidateBundlePlugin('absent-plugin'), false);
+    });
+    test('the dispatcher lets a manifest_stale answer off the wire escape, and renders every other failure', async () => {
+        await install();
+        // The pass must not fire underneath these legs: every fetch below is one a
+        // test asked for.
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        retiredOps.add('v1');
+        const root = await buildRoot();
+        const stale = await captured(() => runCli(root, [...ARGV, FIXTURE_ID]));
+        // Rethrown, not rendered: nothing printed, and the frame above holds the
+        // error with the two details recovery needs.
+        assert.equal(stale.stdout, '');
+        const thrown = stale.thrown;
+        assert.ok(thrown instanceof CrtrError, String(thrown));
+        assert.equal(thrown.details?.['manifest_stale'], true);
+        assert.equal(thrown.details?.['plugin'], PLUGIN);
+        assert.deepEqual(opCalls, ['v1']);
+        // Every other failure stays the dispatcher's to report. The same leaf,
+        // missing its required positional, is rendered rather than thrown.
+        const usage = await captured(() => runCli(root, ARGV));
+        assert.equal(usage.thrown, undefined);
+        assert.ok(usage.stdout.includes('id'), usage.stdout);
+    });
+    test('a stale answer refetches the package and re-runs the ORIGINAL argv against the refreshed tree', async () => {
+        await install();
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        // The backend has moved the op on: it retired the generation this client
+        // installed, and now serves a package whose leaf calls the new path.
+        retiredOps.add('v1');
+        served = { archive: makeArchive('v2'), etag: '"sha256-v2"' };
+        const root = await buildRoot();
+        const run = await captured(() => dispatchWithStaleRecovery(root, [...ARGV, FIXTURE_ID]));
+        assert.equal(run.thrown, undefined);
+        // The stale call, one forced bundle fetch, then the replay at the NEW
+        // generation — which only the refreshed tree could have addressed.
+        assert.deepEqual(opCalls, ['v1', 'v2']);
+        assert.deepEqual(requests, [
+            { ifNoneMatch: undefined, status: 200 }, // the install
+            { ifNoneMatch: undefined, status: 200 }, // the forced refetch
+        ]);
+        assert.equal(installedMarker(), 'v2');
+        assert.ok(run.stdout.includes(FIXTURE_ID), run.stdout);
+    });
+    test('a second stale answer is rendered rather than refetched again', async () => {
+        await install();
+        process.env.CRTR_PLUGIN_REVALIDATE_TTL_MS = '600000';
+        // A backend that keeps answering `manifest_stale` however fresh the package
+        // is. The refetch genuinely changes the tree, so the retry does happen —
+        // and its own stale answer must end the cycle, not restart it.
+        retiredOps = new Set(['v1', 'v2']);
+        served = { archive: makeArchive('v2'), etag: '"sha256-v2"' };
+        const root = await buildRoot();
+        const run = await captured(() => dispatchWithStaleRecovery(root, [...ARGV, FIXTURE_ID]));
+        assert.equal(run.thrown, undefined);
+        assert.deepEqual(opCalls, ['v1', 'v2']);
+        assert.equal(requests.length, 2, 'the install plus exactly ONE forced refetch');
+        assert.equal(installedMarker(), 'v2');
+        // The backend's own second complaint is the answer the caller gets.
+        assert.ok(run.stdout.includes('no longer serves'), run.stdout);
+    });
+});