@north-light/crouter 0.3.281 → 0.3.283

package/dist/core/config.js

@@ -343,6 +343,25 @@ function mergeSpawnEnv(raw, base = []) {
     }
     return { allow: [...new Set([...base, ...extra])] };
 }
+/** Per-provider options, merged SHALLOWLY per provider id so a nearer scope
+ *  that sets one option does not erase a sibling option from a farther scope. */
+function mergeProviderOptions(raw, base = {}) {
+    const merged = {};
+    for (const [providerId, options] of Object.entries(base))
+        merged[providerId] = { ...options };
+    if (raw !== null && typeof raw === 'object') {
+        for (const [providerId, options] of Object.entries(raw)) {
+            if (options === null || typeof options !== 'object')
+                continue;
+            const next = { ...merged[providerId] };
+            const fastMode = options.fastMode;
+            if (typeof fastMode === 'boolean')
+                next.fastMode = fastMode;
+            merged[providerId] = next;
+        }
+    }
+    return merged;
+}
 /** The one bare-command-name rule, shared by the read path (`normalizeBin`)
  *  and the strict install gate (`invalidPluginBinReasons`): a name a shell can
  *  invoke verbatim and a filesystem can hold as a single symlink entry — no
@@ -761,6 +780,7 @@ function mergeConfig(partial) {
     const keybindings = normalizeKeybindings(partial.keybindings);
     const tmux_passthrough = normalizeTmuxPassthrough(partial.tmux_passthrough);
     const modelLadders = mergeModelLadders(partial.modelLadders);
+    const providerOptions = mergeProviderOptions(partial.providerOptions, defaults.providerOptions);
     const routes = resolveModelRoutes(mergeModelRoutePatches(partial.modelRoutes));
     const modelRoutes = routes.complete;
     const modelRouting = mergeModelRouting(partial.modelRouting, undefined);
@@ -769,7 +789,7 @@ function mergeConfig(partial) {
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
     const bin = normalizeBin(partial.bin);
     const humanActions = normalizeHumanActions(partial.humanActions);
-    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, providerOptions, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
@@ -858,12 +878,14 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
     // (ladders/routes/spawnEnv) have no plugin channel.
     let kinds = mergeKinds(userRaw?.kinds, layerPluginKinds('user', scopeRoot('user'), defaults.kinds));
     let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
+    let providerOptions = mergeProviderOptions(userRaw?.providerOptions, defaults.providerOptions);
     let modelRoutePatches = mergeModelRoutePatches(userRaw?.modelRoutes);
     let modelRouting = mergeModelRouting(userRaw?.modelRouting, undefined);
     let spawnEnv = mergeSpawnEnv(userRaw?.spawnEnv, defaults.spawnEnv?.allow);
     if (profileRaw !== null) {
         kinds = mergeKinds(profileRaw.kinds, kinds);
         modelLadders = mergeModelLadders(profileRaw.modelLadders, modelLadders);
+        providerOptions = mergeProviderOptions(profileRaw.providerOptions, providerOptions);
         modelRoutePatches = mergeModelRoutePatches(profileRaw.modelRoutes, modelRoutePatches);
         modelRouting = mergeModelRouting(profileRaw.modelRouting, modelRouting);
         spawnEnv = mergeSpawnEnv(profileRaw.spawnEnv, spawnEnv.allow);
@@ -873,6 +895,7 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
         if (raw === null)
             continue;
         modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
+        providerOptions = mergeProviderOptions(raw.providerOptions, providerOptions);
         modelRoutePatches = mergeModelRoutePatches(raw.modelRoutes, modelRoutePatches);
         modelRouting = mergeModelRouting(raw.modelRouting, modelRouting);
         spawnEnv = mergeSpawnEnv(raw.spawnEnv, spawnEnv.allow);
@@ -881,6 +904,7 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
     return {
         kinds,
         modelLadders,
+        providerOptions,
         ...(Object.keys(routes.complete).length > 0 ? { modelRoutes: routes.complete } : {}),
         ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}),
         ...(modelRouting !== undefined ? { modelRouting } : {}),

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

@@ -9,6 +9,14 @@ export interface PushOpts {
     from?: string;
     /** Attribution snapshotted by the human-ticket settlement paths; absent means an ordinary report. */
     disposition?: InboxDisposition;
+    /** Final only. The outcome the canonical final records; absent means `result`/`finalized`. */
+    outcome?: FinalOutcome;
+}
+/** A declined structured result: the node finishes, but its latch records a failure. */
+export interface FinalOutcome {
+    kind: 'failure';
+    reason: 'declined';
+    detailJson: string | null;
 }
 export interface PushResult {
     reportPath: string;

package/dist/core/feed/feed.js

@@ -2,7 +2,7 @@
 import { existsSync, linkSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { openDb, reportsDir, subscribersOf, cancelCronsOnWake, getNode } from '../canvas/index.js';
+import { openDb, reportsDir, subscribersOf, cancelCronsOnWake, composeOutcomeDeliveryDocument, getNode, readOutcomeDelivery, resetOutcomeDeliveryForSupersede } from '../canvas/index.js';
 import { appendInbox } from './inbox.js';
 import { appendPassive } from './passive.js';
 import { operationIdContext } from '../events/operation-id.js';
@@ -77,7 +77,7 @@ function deliver(subscribers, from, fromName, kind, requestedTier, reportRef, bo
     return { deliveredTo, failedTo };
 }
 /** Claim the one canonical final while holding SQLite's write lock. */
-function commitCanonicalFinal(nodeId, staged) {
+function commitCanonicalFinal(nodeId, staged, outcome) {
     const db = openDb();
     let installed = false;
     db.exec('BEGIN IMMEDIATE');
@@ -92,9 +92,28 @@ function commitCanonicalFinal(nodeId, staged) {
         if (row.status !== 'active' && row.status !== 'idle' && row.status !== 'done')
             throw new FinalizationError('finalization_forbidden');
         const subscribers = db.prepare(`SELECT from_id AS node_id, active, created FROM edges WHERE type = 'subscribes_to' AND to_id = ? ORDER BY created`).all(nodeId).map((row) => ({ node_id: row['node_id'], active: row['active'] === 1, created: row['created'] }));
+        const delivery = readOutcomeDelivery(nodeId);
+        const node = getNode(nodeId);
+        const recordsOutcome = node?.kind !== 'human';
+        const revision = (node?.outcome_revision ?? 0) + 1;
+        const outcomeKind = outcome?.kind ?? 'result';
+        const outcomeReason = outcome?.reason ?? 'finalized';
+        const outcomeDetailJson = outcome?.detailJson ?? null;
+        const documentJson = !recordsOutcome || delivery === null || node === null ? null : composeOutcomeDeliveryDocument({
+            nodeId,
+            outcome: { kind: outcomeKind, reason: outcomeReason, at: staged.ts, revision, detailJson: outcomeDetailJson },
+            action: { name: delivery.actionName, payload: delivery.payload },
+            finalReport: staged.basename,
+        });
         install(staged);
         installed = true;
-        db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = 'finalized', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(staged.basename, staged.ts, nodeId);
+        if (recordsOutcome) {
+            db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = ?, final_report = ?, finalized_at = ?, outcome_kind = ?, outcome_reason = ?, outcome_at = ?, outcome_revision = outcome_revision + 1, outcome_detail_json = ? WHERE node_id = ? AND final_report IS NULL").run(outcomeReason, staged.basename, staged.ts, outcomeKind, outcomeReason, staged.ts, outcomeDetailJson, nodeId);
+            resetOutcomeDeliveryForSupersede(nodeId, documentJson, Date.now());
+        }
+        else {
+            db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = 'finalized', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(staged.basename, staged.ts, nodeId);
+        }
         db.exec('COMMIT');
         return { subscribers };
     }
@@ -113,11 +132,13 @@ async function pushWithContext(nodeId, opts) {
         throw new Error(`push: empty nodeId (kind=${opts.kind}) — a report must belong to a node`);
     if (opts.kind === 'final' && opts.deliveryTier !== undefined)
         throw new Error('push final does not accept a delivery tier');
+    if (opts.kind !== 'final' && opts.outcome !== undefined)
+        throw new Error('push outcome is final-only');
     const staged = stageReport(nodeId, opts.kind, opts.body);
     const from = opts.from ?? nodeId;
     const fromName = getNode(from)?.name;
     if (opts.kind === 'final') {
-        const { subscribers } = commitCanonicalFinal(nodeId, staged);
+        const { subscribers } = commitCanonicalFinal(nodeId, staged, opts.outcome);
         // The finalization latch ends every wait this node was holding. It flips the
         // row to done DIRECTLY (not through lifecycle's `finish` event), so the
         // deadline cleanup must ride here too: an armed deadline outliving the final

package/dist/core/feed/inbox.d.ts

@@ -87,6 +87,11 @@ export declare function writeCursor(nodeId: string, entryId: string): void;
  *  (do not park, do not shut down, do not resume quietly), so report it and
  *  return that. */
 export declare function hasUnseenWakeMail(nodeId: string): boolean;
+/** Whether wake-capable mail arrived at or after a parking turn began. Unlike
+ * `hasUnseenWakeMail`, this deliberately includes mail the main engine already
+ * consumed: a shadow completion must not undo activity that occurred while it
+ * ran. A failed scan conservatively keeps the node live. */
+export declare function hasWakeMailSince(nodeId: string, sinceMs: number): boolean;
 /** Clip a body to a bounded preview, reporting whether anything was dropped. */
 export declare function clipBody(body: string): {
     text: string;

package/dist/core/feed/inbox.js

@@ -315,6 +315,19 @@ export function hasUnseenWakeMail(nodeId) {
         return true;
     }
 }
+/** Whether wake-capable mail arrived at or after a parking turn began. Unlike
+ * `hasUnseenWakeMail`, this deliberately includes mail the main engine already
+ * consumed: a shadow completion must not undo activity that occurred while it
+ * ran. A failed scan conservatively keeps the node live. */
+export function hasWakeMailSince(nodeId, sinceMs) {
+    try {
+        return readPhysicalInbox(nodeId).some((entry) => entry.tier !== 'deferred' && Date.parse(entry.ts) >= sinceMs);
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'inbox.wake_scan.failed', node_id: nodeId, error });
+        return true;
+    }
+}
 // Coalesce
 /** Bounds for inlining a message body's preview in the digest. */
 const BODY_MAX_LINES = 12;

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/keybindings/catalog.d.ts

@@ -1,6 +1,6 @@
 import type { BindingDefinition, SafetyRequirement } from './types.js';
 import type { AttachBindingId, AttachMenuBindingId } from './attach-control.js';
-type TmuxMenuAction = 'open' | 'attach' | 'show' | 'view-settings' | 'fold-tools' | 'metadata' | 'promote' | 'demote-mode' | 'resume' | 'fork' | 'demote' | 'make-resident' | 'detach' | 'close-subtree' | 'background-bash' | 'file-review' | 'pin' | 'reload-viewer' | 'recap' | 'context' | 'context-admin' | 'providers' | 'plugins' | 'graph' | 'focus-manager' | 'copy-id' | 'issues';
+type TmuxMenuAction = 'open' | 'attach' | 'show' | 'view-settings' | 'provider-options' | 'fold-tools' | 'metadata' | 'promote' | 'demote-mode' | 'resume' | 'fork' | 'demote' | 'make-resident' | 'detach' | 'close-subtree' | 'background-bash' | 'file-review' | 'pin' | 'reload-viewer' | 'recap' | 'context' | 'context-admin' | 'providers' | 'plugins' | 'graph' | 'focus-manager' | 'copy-id' | 'issues';
 type TmuxMenuEntryAction = Exclude<TmuxMenuAction, 'open' | 'attach'> | `issue.${'idea' | 'bug'}`;
 type GraphAction = 'down' | 'up' | 'first' | 'last' | 'collapse-or-manager' | 'expand-or-child' | 'focus' | 'revive' | 'focus-manager' | 'close-subtree' | 'dismiss';
 type BrowseAction = 'quit' | 'down' | 'up' | 'first' | 'last' | 'expand-or-child' | 'collapse-or-parent' | 'toggle-fold' | 'tab-next' | 'tab-previous' | `tab.${1 | 2 | 3 | 4 | 5}` | 'close-subtree' | 'confirm-close' | 'sort' | 'scope' | 'profile' | 'residents' | 'preview' | 'report' | 'pin' | 'search' | 'revive-now' | 'focus' | 'focus-background' | 'yank-id';

package/dist/core/keybindings/catalog.js

@@ -55,6 +55,9 @@ export const BINDING_CATALOG = Object.freeze([
     ...menuEntry('metadata', 'Show metadata', 'Show the focused node’s metadata dossier.', ['m'], ['tmux.menu.show']),
     ...menuEntry('context', 'Browse context', 'Browse the focused node context.', ['c'], ['tmux.menu.show']),
     ...menuEntry('providers', 'Open settings', 'Open the crouter settings panel.', [','], ['tmux.menu']),
+    // Next to the settings comma: the same page, opened on its provider-options
+    // destination.
+    ...menuEntry('provider-options', 'Provider options', 'Open provider options — how an authenticated provider serves your turns, including Codex fast mode.', ['.'], ['tmux.menu']),
     // j and k steer the menu cursor, so no selector may claim either.
     ...menuEntry('plugins', 'Browse plugins', 'Open the crouter plugin browser.', ['l'], ['tmux.menu']),
     // Lowercase c opens the create submenu, so the context surface takes the

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/profiles/manifest.d.ts

@@ -114,7 +114,9 @@ export declare function isProfilePaused(profileId: string | null | undefined): b
 export declare function assertProfileEntryActive(entry: ProfileEntry): void;
 export declare function assertProfileActive(profileId: string | null | undefined): ProfileEntry | null;
 export declare function pauseProfile(profileId: string): ProfileEntry;
-export declare function resumeProfile(profileId: string): ProfileEntry;
+export declare function resumeProfile(profileId: string): ProfileEntry & {
+    pausedAt: string | null;
+};
 export declare function setProfileDefaultKind(profileId: string, defaultKind: string): ProfileEntry;
 /** Merge `set` entries over the stored map and drop `unset` keys; the
  *  `metadata` field is omitted entirely when the result is empty. */

package/dist/core/profiles/manifest.js

@@ -592,7 +592,12 @@ export function pauseProfile(profileId) {
     return mutateManifest(profileId, (m) => ({ ...m, paused_at: m.paused_at ?? nowIso() }));
 }
 export function resumeProfile(profileId) {
-    return mutateManifest(profileId, (m) => ({ ...m, paused_at: null }));
+    let pausedAt = null;
+    const entry = mutateManifest(profileId, (m) => {
+        pausedAt = m.paused_at;
+        return { ...m, paused_at: null };
+    });
+    return { ...entry, pausedAt };
 }
 export function setProfileDefaultKind(profileId, defaultKind) {
     return mutateManifest(profileId, (m) => ({ ...m, default_kind: defaultKind }));

package/dist/core/runtime/broker/daemon-ops.d.ts

@@ -1,8 +1,10 @@
-import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from '../../../api/dto/broker-ops.js';
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerParkActivityResultDTO, BrokerParkCompleteRequest, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from '../../../api/dto/broker-ops.js';
 import type { RelaunchRootResultDTO } from '../../../api/dto/lifecycle.js';
 import type { PushReportRequest } from '../../../api/dto/reports.js';
 export declare function bindBrokerSession(nodeId: string, request: BrokerSessionBoundRequest): Promise<BrokerSessionBoundResultDTO>;
 export declare function settleBroker(nodeId: string, request: BrokerSettleRequest): Promise<BrokerSettleDirective>;
+export declare function completeBrokerPark(nodeId: string, request: BrokerParkCompleteRequest): Promise<BrokerSettleDirective>;
+export declare function recordBrokerParkActivity(nodeId: string): Promise<BrokerParkActivityResultDTO>;
 export declare function advanceBrokerInboxCursor(nodeId: string, request: BrokerInboxCursorRequest): Promise<BrokerInboxCursorDirective>;
 /** Fixed canvas projection for broker extension rendering. It deliberately
  * exposes no generic node/database facade. */

package/dist/core/runtime/broker/daemon-ops.js

@@ -12,6 +12,12 @@ export function bindBrokerSession(nodeId, request) {
 export function settleBroker(nodeId, request) {
     return daemonClient().settleBroker(nodeId, request);
 }
+export function completeBrokerPark(nodeId, request) {
+    return daemonClient().completeBrokerPark(nodeId, request);
+}
+export function recordBrokerParkActivity(nodeId) {
+    return daemonClient().recordBrokerParkActivity(nodeId);
+}
 export function advanceBrokerInboxCursor(nodeId, request) {
     return daemonClient().advanceBrokerInboxCursor(nodeId, request);
 }

package/dist/core/runtime/broker/engine-drive.d.ts

@@ -10,9 +10,7 @@ import type { RebindDriver } from './rebind.js';
 import type { ToolGroupTracker } from './tool-groups.js';
 import type { PromptDispatchTracker } from './turn-ignition.js';
 import type { TurnAdmissionGate } from './turn-admission.js';
-/** The frames that drive the live engine. A daemon delivery carries its
- *  provenance through admission because only the resolved route can decide
- *  whether the resulting run is internal. */
+/** The frames that drive the live engine. */
 type DeliveredInput = {
     delivery?: {
         origin?: MessageOrigin;
@@ -25,6 +23,7 @@ export type DriveFrame = (Extract<ClientToBroker, {
 }>;
 export type EngineDriver = (client: BrokerClient, frame: DriveFrame) => Promise<unknown> | undefined;
 export declare function createEngineDriver(deps: {
+    nodeId: string;
     registry: BrokerClientRegistry;
     replies: FrameReplies;
     session: () => BrokerSession;