@north-light/crouter 0.3.280 → 0.3.282

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>;

package/dist/core/manifest-recovery.js

@@ -0,0 +1,72 @@
+// Dispatch with recovery from an out-of-date command description.
+//
+// Extracted from the cli entry so the whole behaviour — rethrow, refetch,
+// re-parse, exactly-once — can be driven by a test through `runCli` and a real
+// error off the wire, rather than only by launching the binary.
+import { resolveRoot } from '../build-root.js';
+import { runCli } from './command.js';
+import { forceRevalidateBundlePlugin } from './command-plugins/revalidate.js';
+import { handle } from './io.js';
+import { staleManifestPlugin } from './manifest-stale.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 async function dispatchWithStaleRecovery(root, argv) {
+    try {
+        // The dispatcher renders every other failure itself; a `manifest_stale`
+        // error is the one it rethrows, because recovery needs this frame.
+        await runCli(root, argv);
+        return;
+    }
+    catch (error) {
+        if (!(await refetchStalePlugin(error))) {
+            // Nothing newer to run against: report the backend's own complaint
+            // exactly as the dispatcher would have.
+            handle(error);
+            return;
+        }
+        try {
+            // The refreshed tree, re-resolved: the package this invocation dispatches
+            // against is not the one it was built from. Replaying the argv is only
+            // safe because a server that sets the flag has promised it — the two
+            // preconditions are recorded on `ManifestStaleEnvelope` in
+            // `src/api/plugin-manifest-schema.ts`, and crtr cannot check either one.
+            await runCli(await resolveRoot(argv[2]), argv);
+        }
+        catch (retryError) {
+            // Exactly once. A second `manifest_stale` against a package just
+            // refetched is the server's answer, not another refresh cycle.
+            handle(retryError);
+        }
+    }
+}
+/**
+ * A backend that answers `manifest_stale` is saying this client invoked from an
+ * out-of-date description of its commands. Refetch that plugin's package and
+ * report whether it actually changed. An unchanged package means the operation
+ * is genuinely gone, so the server's own error, which already names what it
+ * does serve, is the honest answer and stands.
+ */
+async function refetchStalePlugin(error) {
+    const plugin = staleManifestPlugin(error);
+    if (plugin === undefined)
+        return false;
+    try {
+        return await forceRevalidateBundlePlugin(plugin);
+    }
+    catch {
+        // The refetch is the recovery. If it fails there is nothing newer to retry
+        // against, and the server's original complaint is what the caller needs.
+        return false;
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { ManifestStaleEnvelope } from '../api/plugin-manifest-schema.js';
+/** What crtr attaches to the `CrtrError` it raises for a stale answer. */
+type StaleErrorDetails = Required<ManifestStaleEnvelope> & {
+    plugin: string;
+};
+/** Did the backend's own error envelope claim staleness? Reads the parsed JSON
+ *  body, before it becomes a `CrtrError`. */
+export declare function envelopeClaimsStale(envelope: Record<string, unknown>): boolean;
+/** The details a transport adds when it converts a stale envelope into the
+ *  error the dispatcher rethrows. */
+export declare function staleErrorDetails(plugin: string): StaleErrorDetails;
+/** Is this the one error class the dispatcher rethrows instead of rendering? */
+export declare function isManifestStaleError(error: unknown): boolean;
+/** The plugin to refetch, or `undefined` when this error is not a recoverable
+ *  stale answer. A stale flag with no plugin name is not actionable: nothing
+ *  identifies the package whose description went out of date. */
+export declare function staleManifestPlugin(error: unknown): string | undefined;
+export {};

package/dist/core/manifest-stale.js

@@ -0,0 +1,39 @@
+// The one place in crtr that names the `manifest_stale` wire field.
+//
+// The field itself is declared in the published format subpath
+// (`src/api/plugin-manifest-schema.ts`), which is what a plugin backend compiles
+// against. This module binds crtr's readers and writer to that declaration, so
+// renaming the field there fails the build here rather than silently splitting
+// the two sides: a backend that keeps setting a field nobody reads, and a client
+// that never recovers.
+import { CrtrError } from './errors.js';
+/** Bound to the published declaration: `keyof` is the field's literal type, so
+ *  a rename over there makes this assignment a type error. */
+const STALE_FIELD = 'manifest_stale';
+/** The plugin whose package produced the out-of-date description, carried
+ *  alongside the flag so the recovery frame knows what to refetch. The backend
+ *  does not send this — the transport that made the call names it. */
+const PLUGIN_FIELD = 'plugin';
+/** Did the backend's own error envelope claim staleness? Reads the parsed JSON
+ *  body, before it becomes a `CrtrError`. */
+export function envelopeClaimsStale(envelope) {
+    return envelope[STALE_FIELD] === true;
+}
+/** The details a transport adds when it converts a stale envelope into the
+ *  error the dispatcher rethrows. */
+export function staleErrorDetails(plugin) {
+    return { [STALE_FIELD]: true, [PLUGIN_FIELD]: plugin };
+}
+/** Is this the one error class the dispatcher rethrows instead of rendering? */
+export function isManifestStaleError(error) {
+    return error instanceof CrtrError && error.details?.[STALE_FIELD] === true;
+}
+/** The plugin to refetch, or `undefined` when this error is not a recoverable
+ *  stale answer. A stale flag with no plugin name is not actionable: nothing
+ *  identifies the package whose description went out of date. */
+export function staleManifestPlugin(error) {
+    if (!isManifestStaleError(error))
+        return undefined;
+    const plugin = error.details?.[PLUGIN_FIELD];
+    return typeof plugin === 'string' ? plugin : undefined;
+}

package/dist/core/plugin-swap-lock.d.ts

@@ -0,0 +1,9 @@
+/** Under the scope root's `tmp/`, alongside the staging and `.prev` dirs the
+ *  swap itself uses, so one directory holds the whole transition. */
+export declare function bundleSwapLockPath(scopeRootPath: string, name: string): string;
+/** Whether ANOTHER live process currently holds this plugin's swap lock. Our
+ *  own lock does not count: the swapper reads the plugin list from inside its
+ *  own critical section. */
+export declare function bundleSwapInFlightElsewhere(scopeRootPath: string, name: string): boolean;
+/** Wait out another process's swap of this plugin, bounded. */
+export declare function awaitBundleSwap(scopeRootPath: string, name: string): void;

package/dist/core/plugin-swap-lock.js

@@ -0,0 +1,31 @@
+// The one name for the lock a bundle-plugin package swap is held under, and the
+// two questions a reader asks about it.
+//
+// Two modules need it and neither may own it: the swapper lives in
+// `commands/pkg/plugin-manage.ts` (the whole command graph), the reader in
+// `core/installed-plugins.ts` (deliberately leaf-safe: types, fs-utils,
+// manifest). This module keeps both dependency-light — `node:path` plus the
+// generic lock primitive, which itself imports only `node:fs` and
+// `node:crypto`.
+import { join } from 'node:path';
+import { awaitExclusiveLockRelease, exclusiveLockOwnerPid } from './exclusive-lock.js';
+/** How long a reader waits for another process's swap to finish before it
+ *  reports what it can see. A swap is one rename of an already-staged, already-
+ *  validated tree, so a wait this long means the holder is wedged, not slow. */
+const READER_WAIT_MS = 2_000;
+/** Under the scope root's `tmp/`, alongside the staging and `.prev` dirs the
+ *  swap itself uses, so one directory holds the whole transition. */
+export function bundleSwapLockPath(scopeRootPath, name) {
+    return join(scopeRootPath, 'tmp', `${name}.swap.lock`);
+}
+/** Whether ANOTHER live process currently holds this plugin's swap lock. Our
+ *  own lock does not count: the swapper reads the plugin list from inside its
+ *  own critical section. */
+export function bundleSwapInFlightElsewhere(scopeRootPath, name) {
+    const pid = exclusiveLockOwnerPid(bundleSwapLockPath(scopeRootPath, name));
+    return pid !== null && pid !== process.pid;
+}
+/** Wait out another process's swap of this plugin, bounded. */
+export function awaitBundleSwap(scopeRootPath, name) {
+    awaitExclusiveLockRelease(bundleSwapLockPath(scopeRootPath, name), READER_WAIT_MS);
+}

package/dist/core/runtime/launch.d.ts

@@ -68,8 +68,13 @@ export interface LaunchBuildOptions {
     /** A newly supplied `--model` override. Resolve it through the target
      *  ladder and any quality floor once, then freeze the resulting concrete
      *  provider/id[:thinking] spec into the launch recipe so every launch,
-     *  revive, and retry consults exactly that model. Existing recipes instead
-     *  carry `modelExact`/`modelIntent` below verbatim. */
+     *  revive, and retry consults exactly that model — but ONLY when the raw
+     *  token names a concrete model. A PORTABLE ladder token (`medium`,
+     *  `anthropic/opus`) is a strength preference, not a model identity, so it
+     *  keeps its route intent and stays eligible for fallback; freezing it
+     *  would fail a node closed on a canvas whose only authenticated route is a
+     *  different provider. Existing recipes instead carry
+     *  `modelExact`/`modelIntent` below verbatim. */
     modelOverride?: boolean;
     /** The TARGET node's cwd — anchors the project-scope stack for kind/ladder
      *  resolution. Defaults to this process's own cwd, which is correct only

package/dist/core/runtime/launch.js

@@ -251,7 +251,8 @@ function buildLaunchSpecFromMerged(kind, mode, opts, merged) {
     const ladders = merged.modelLadders;
     const kindModel = mode === 'orchestrator' ? kindConfig?.orchestratorModel ?? kindConfig?.model : kindConfig?.model;
     const chosenModel = opts.modelExact === true ? opts.model : floorReviewModel(kind, opts.model, kindModel, ladders);
-    const exact = opts.modelExact === true || opts.modelOverride === true;
+    const exact = opts.modelExact === true
+        || (opts.modelOverride === true && opts.model !== undefined && !isPortableModelToken(opts.model));
     const resolvedModel = opts.modelExact === true
         ? chosenModel
         : (chosenModel !== undefined ? normalizeModel(chosenModel, ladders) : undefined);

package/dist/daemon/api/__tests__/node-model-validation.test.js

@@ -103,7 +103,12 @@ test('promote and yield reject unregistered model recipes before reshaping the n
         assert.equal(after?.mode, before?.mode, `${operation} did not reshape the node`);
     }
 });
-test('promote and yield reject an unregistered resolved portable override before reshaping the node', async () => {
+// A portable override names a strength, not a model identity, so it is a route
+// request: the registry cannot pre-judge it, and the broker resolves it against
+// whichever route is authenticated at launch. Gating it on the ladder cell being
+// registered is what killed every `--model medium` child on a canvas whose only
+// authenticated route belonged to another provider.
+test('promote and yield accept a portable override whose ladder cell is unregistered', async () => {
     const cwd = join(home, 'target-project');
     mkdirSync(join(cwd, '.crouter'), { recursive: true });
     writeFileSync(join(cwd, '.crouter', 'config.json'), JSON.stringify({
@@ -113,14 +118,15 @@ test('promote and yield reject an unregistered resolved portable override before
     for (const operation of ['promote', 'yield']) {
         const id = `${operation}-portable-model`;
         createNode(node(id, cwd));
-        const before = getNode(id);
         const request = ctx('POST', `/v1/nodes/${id}/${operation}`, id, { model: 'openai/strong' });
-        await assert.rejects(() => operation === 'promote'
-            ? handlePromote(request, { modelRegistry: registry })
-            : handleYield(request, { modelRegistry: registry }), (error) => error instanceof CrtrError && error.code === 'usage' && /target-openai\/missing-strong/.test(error.message));
+        if (operation === 'promote')
+            await handlePromote(request, { modelRegistry: registry });
+        else
+            await handleYield(request, { modelRegistry: registry });
         const after = getNode(id);
-        assert.deepEqual(after?.launch, before?.launch, `${operation} did not rewrite the launch recipe`);
-        assert.equal(after?.mode, before?.mode, `${operation} did not reshape the node`);
+        assert.equal(after?.launch?.model, 'target-openai/missing-strong', `${operation} resolves the tier against the target scope`);
+        assert.equal(after?.launch?.modelExact, undefined, `${operation} leaves the strength request routable`);
+        assert.deepEqual(after?.launch?.modelIntent, { family: 'openai', strength: 'strong' }, `${operation} keeps the route intent`);
     }
 });
 test('config normalizes portable models against the target node scope', async () => {
@@ -151,5 +157,7 @@ test('config normalizes portable models against the target node scope', async ()
     await handleConfig(ctx('PATCH', `/v1/nodes/${id}/config`, id, { model: 'openai/strong' }), { modelRegistry: registry });
     assert.equal(getNode(id)?.model_override, 'target-openai/o-strong');
     assert.equal(getNode(id)?.launch?.model, 'target-openai/o-strong');
+    // `config --model` records exactness in the model-swap path (updateModelRecipe),
+    // not in buildLaunchSpec, so a live user's pick freezes whatever its shape.
     assert.equal(getNode(id)?.launch?.modelExact, true, 'a config override cannot route away on revive');
 });

package/dist/types.d.ts

@@ -386,8 +386,15 @@ export interface ScopeState {
     marketplaces: Record<string, {
         last_updated?: string;
     }>;
+    /** Per-plugin cache bookkeeping for the bundle revalidation pass.
+     *  `etag` is the validator the server returned with the archive currently
+     *  unpacked on disk, replaced only on a 200. `checked_at` is written on every
+     *  revalidation attempt, success or failure, so an unreachable server costs
+     *  one timed-out probe per TTL rather than one per command. */
     plugins: Record<string, {
         last_updated?: string;
+        etag?: string;
+        checked_at?: string;
     }>;
     last_self_check?: string;
     /** The name of the remote canvas target `crtr canvas use` last selected

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.280",
+  "version": "0.3.282",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -76,6 +76,7 @@
     "typecheck:pi-packages": "npx tsc -p src/builtin-pi-packages/pi-crtr-extensions/tsconfig.json",
     "test:build-output": "node scripts/build-concurrency-test.mjs",
     "check:cli-no-canvas": "node scripts/check-cli-no-canvas.mjs",
+    "check:cli-cold-start": "node scripts/check-cli-cold-start.mjs",
     "check:daemon-no-barrel": "node scripts/check-daemon-no-barrel.mjs",
     "check:quote-style": "node scripts/check-quote-style.mjs",
     "postinstall": "node scripts/postinstall.mjs",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.280",
+  "version": "0.3.282",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.280",
+      "version": "0.3.282",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {