@zq-silk/yui 0.6.0 → 0.6.2

package/README.md

@@ -703,13 +703,13 @@ hiding the resources that remain. Use `--all` to include discovered Yui homes.
 
 `controller restart` replaces the Controller process and its scheduler/socket services with the currently installed Yui version. It does not stop or restart managed tmux/Agent sessions.
 
-Its recovery reconciliation runs every 120 seconds by default. Normal durable state changes enqueue a Task, Role, or Operator key and return immediately; keys received in the same fixed 100 ms window trigger one non-overlapping targeted pass. Operator presentation has an independent lane, so a blocked Task workspace operation cannot delay a user question. Periodic Git/worktree work is limited to Tasks with durable Task-mailbox work, while active Role liveness uses one tmux inventory. A Codex turn-complete Hook writes directly to storage without starting or waiting for the Controller, then gives a legal yield/input/completion two seconds to win before closing a forgotten Run. Durable mailboxes freeze the current batch while new signals merge into the next batch; failures release the current batch for recovery. Recommended InputRequest and pending Turn deadlines share one nearest-deadline selector and therefore do not wait for the recovery interval. Explicit `task reconcile` still requests an immediate recovery pass. The retained loop is:
+Its recovery reconciliation runs every 120 seconds by default. Normal durable state changes enqueue a Task, Role, or Operator key and return immediately; keys received in the same fixed 100 ms window trigger one non-overlapping targeted pass. Operator presentation has an independent lane, so a blocked Task workspace operation cannot delay a user question. Periodic Git/worktree work is limited to Tasks with durable Task-mailbox work, while active Role liveness uses one tmux inventory. A Codex turn-complete Hook writes directly to storage without starting or waiting for the Controller, then gives a legal yield/input/completion two seconds to win before closing a forgotten Run. Durable mailboxes freeze the current batch while new signals merge into the next batch. Task-orchestration failures retain the exact Controller-owned processing batch for two bounded fast retries and later periodic recovery; a successful retry completes that batch before newer pending work is claimed. Recommended InputRequest and pending Turn deadlines share one nearest-deadline selector and therefore do not wait for the recovery interval. Explicit `task reconcile` still requests an immediate recovery pass. The retained loop is:
 
-1. prepare active Project Task main worktrees;
-2. stop archived Task tmux sessions and clean only clean worktrees;
+1. dispatch pending Leader wakes whose Task workspaces are already ready;
+2. prepare active Project Task main worktrees with durable orchestration work;
 3. deliver queued Worker Runs;
-4. detect exited active Role processes;
-5. dispatch pending Leader wakes when the Leader is idle.
+4. resolve due Turn completions and reconcile Role liveness;
+5. dispatch Leader work created or unblocked by the later recovery phases.
 
 Automated input is sent only through tmux. Each pass performs one non-blocking process-state readiness check; a busy startup is retried through a small bounded mailbox timer, while later busy sessions are normally woken by Codex turn-complete events. A pane-local receipt prevents the same Run from being typed twice after a Controller retry.
 

package/dist/agent/managedRuntimeEnvironment.js

@@ -30,5 +30,6 @@ export const YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES = Object.freeze([
     "YUI_CONTEXT_PROJECT_IDS",
     "YUI_WORKSPACE_PROJECTS",
     "YUI_LEADER_ACTION_RUN_ID",
-    "YUI_LEADER_ACTION_RECEIPT_ID"
+    "YUI_LEADER_ACTION_RECEIPT_ID",
+    "YUI_JOB_CALLER_KEY"
 ]);

package/dist/cli/commandCatalog.js

@@ -219,6 +219,12 @@ const taskChildren = [
         summary: "Show consolidated working context for a Task.",
         usage: "yui task context <task>"
     },
+    {
+        name: "next-action",
+        summary: "Project the durable Task records into one protocol-level next action.",
+        usage: "yui task next-action <task> [--json]",
+        options: ["--json"]
+    },
     {
         name: "archive",
         summary: "Archive a Task after confirming the main worktree outcome.",
@@ -308,6 +314,75 @@ const taskChildren = [
             }
         ]
     },
+    {
+        name: "grant",
+        summary: "Manage capability grants for a Task. Issue and revoke require the authenticated global Operator session.",
+        sections: [{ id: "manage", title: "Commands", entries: ["issue", "show", "list", "revoke"] }],
+        children: [
+            {
+                name: "issue",
+                summary: "Issue a capability grant to a Task. Requires the authenticated global Operator session; the granter is bound to it.",
+                usage: "yui task grant issue <task> --action <name> (repeatable) [--scope-project <id>...] [--scope-repo <owner/name>...] [--scope-package <name>...] [--scope-home <path>] [--param <name=v1,v2>...] [--expires-at <iso-8601>] [--max-uses <int>] [--irreversibility-ceiling <none|reversible|irreversible>]",
+                options: ["--action", "--scope-project", "--scope-repo", "--scope-package", "--scope-home", "--param", "--expires-at", "--max-uses", "--irreversibility-ceiling"]
+            },
+            {
+                name: "show",
+                summary: "Show one capability grant.",
+                usage: "yui task grant show <task> <grant-id>"
+            },
+            {
+                name: "list",
+                summary: "List capability grants for a Task.",
+                usage: "yui task grant list <task>"
+            },
+            {
+                name: "revoke",
+                summary: "Revoke a capability grant. Requires the authenticated global Operator session; the revoker is bound to it.",
+                usage: "yui task grant revoke <task> <grant-id>",
+                options: []
+            }
+        ]
+    },
+    {
+        name: "workflow",
+        summary: "Manage release workflows for a Task.",
+        sections: [{ id: "manage", title: "Commands", entries: ["create", "show", "list", "run", "resume", "status"] }],
+        children: [
+            {
+                name: "create",
+                summary: "Create a release workflow for a Task.",
+                usage: "yui task workflow create <task> --grant <grant-id> --source-repo <owner/name> --source-commit <sha> [--source-artifact <name@integrity>] --step <id>:<kind> (repeatable) [--step-irreversibility <id>=<level> (repeatable)] [--step-param <id>:<key>=<value> (repeatable)]",
+                options: ["--grant", "--source-repo", "--source-commit", "--source-artifact", "--step", "--step-irreversibility", "--step-param"]
+            },
+            {
+                name: "show",
+                summary: "Show one release workflow.",
+                usage: "yui task workflow show <task> <workflow-id>"
+            },
+            {
+                name: "list",
+                summary: "List release workflows for a Task.",
+                usage: "yui task workflow list <task>"
+            },
+            {
+                name: "run",
+                summary: "Run a release workflow from its resume cursor.",
+                usage: "yui task workflow run <task> <workflow-id> [--grant <grant-id>] [--max-steps <int>]",
+                options: ["--grant", "--max-steps"]
+            },
+            {
+                name: "resume",
+                summary: "Resume a release workflow from its first unconfirmed step.",
+                usage: "yui task workflow resume <task> <workflow-id> [--grant <grant-id>] [--max-steps <int>]",
+                options: ["--grant", "--max-steps"]
+            },
+            {
+                name: "status",
+                summary: "Show a release workflow and its step states.",
+                usage: "yui task workflow status <task> <workflow-id>"
+            }
+        ]
+    },
     {
         name: "role",
         summary: "Manage Roles within a Task.",
@@ -508,7 +583,7 @@ const taskChildren = [
     {
         name: "review",
         summary: "Control Task-final ReviewRounds.",
-        sections: [{ id: "manage", title: "Commands", entries: ["request", "group", "retry"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["request", "group", "retry", "finding"] }],
         children: [
             {
                 name: "request",
@@ -533,13 +608,46 @@ const taskChildren = [
                 name: "retry",
                 summary: "Retry a failed Task-final ReviewRound without a Reviewer Run.",
                 usage: "yui task review retry <task>/<review-round>"
+            },
+            {
+                name: "finding",
+                summary: "Inspect and disposition the cross-Round Review finding ledger.",
+                executable: true,
+                sections: [{ id: "manage", title: "Commands", entries: ["list", "dispose", "repair-wave", "extract"] }],
+                children: [
+                    {
+                        name: "list",
+                        summary: "List the Task's review findings with disposition and repair lineage.",
+                        usage: "yui task review finding list <task>"
+                    },
+                    {
+                        name: "dispose",
+                        summary: "Record one Leader disposition for a review finding.",
+                        usage: "yui task review finding dispose <task>/<finding> --disposition <fixed-pending-review|verified-fixed|accepted-risk|not-actionable|superseded> [--work-item <id>] [--commit <sha>] [--verification <text>] [--note <text>] [--superseded-by <stable-key>]",
+                        options: ["--disposition", "--work-item", "--commit", "--verification", "--note", "--superseded-by"],
+                        optionValues: {
+                            "--disposition": ["fixed-pending-review", "verified-fixed", "accepted-risk", "not-actionable", "superseded"]
+                        }
+                    },
+                    {
+                        name: "repair-wave",
+                        summary: "Group open P1/P2 findings into parallel repair groups by overlap.",
+                        usage: "yui task review finding repair-wave <task> [--create]",
+                        options: ["--create"]
+                    },
+                    {
+                        name: "extract",
+                        summary: "Reconcile findings from one completed ReviewRound into the ledger.",
+                        usage: "yui task review finding extract <task>/<review-round>"
+                    }
+                ]
             }
         ]
     },
     {
         name: "integration",
         summary: "Safely integrate ChangeSets with Leader-owned conflict decisions.",
-        sections: [{ id: "manage", title: "Commands", entries: ["start", "continue", "resolve", "abort", "list", "show", "cleanup"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["start", "continue", "resolve", "abort", "supersede", "list", "show", "cleanup", "queue"] }],
         children: [
             {
                 name: "start",
@@ -565,9 +673,29 @@ const taskChildren = [
                 usage: "yui task integration abort <task>/<integration> --reason <text>",
                 options: ["--reason"]
             },
+            {
+                name: "supersede",
+                summary: "Mark a committed Integration as obsolete, retaining its evidence.",
+                usage: "yui task integration supersede <task>/<integration> --reason <text>",
+                options: ["--reason"]
+            },
             { name: "list", summary: "List Integration Attempts.", usage: "yui task integration list <task>" },
             { name: "show", summary: "Show one Integration Attempt.", usage: "yui task integration show <task>/<integration>" },
-            { name: "cleanup", summary: "Remove a terminal Integration worktree and branch.", usage: "yui task integration cleanup <task>/<integration>" }
+            { name: "cleanup", summary: "Remove a terminal Integration worktree and branch.", usage: "yui task integration cleanup <task>/<integration>" },
+            {
+                name: "queue",
+                summary: "Manage the serialized integration queue.",
+                sections: [{ id: "queue", title: "Commands", entries: ["enqueue", "list", "show", "process", "supersede", "requeue", "reconcile"] }],
+                children: [
+                    { name: "enqueue", summary: "Enqueue a ChangeSet for serialized integration.", usage: "yui task integration queue enqueue <task> --project <project> --change-set <id> [--target <ref>] [--check <command> ...]", options: ["--project", "--change-set", "--target", "--check"] },
+                    { name: "list", summary: "List integration queue entries.", usage: "yui task integration queue list <task> [--project <project>]", options: ["--project"] },
+                    { name: "show", summary: "Show one integration queue entry.", usage: "yui task integration queue show <task>/<entry>" },
+                    { name: "process", summary: "Process queued integration entries.", usage: "yui task integration queue process <task> [--project <project>] [--limit <n>]", options: ["--project", "--limit"] },
+                    { name: "supersede", summary: "Supersede a queued entry.", usage: "yui task integration queue supersede <task>/<entry> --reason <text>", options: ["--reason"] },
+                    { name: "requeue", summary: "Requeue a conflicted entry.", usage: "yui task integration queue requeue <task>/<entry>" },
+                    { name: "reconcile", summary: "Reconcile a blocked entry.", usage: "yui task integration queue reconcile <task>/<entry>" }
+                ]
+            }
         ]
     },
     {
@@ -635,6 +763,20 @@ const taskChildren = [
             { name: "show", summary: "Show one Task event.", usage: "yui task event show <task> <event>" }
         ]
     },
+    {
+        name: "overlap",
+        summary: "Show read-only cross-Task overlap diagnostics.",
+        usage: "yui task overlap [--project <project>] [--base <sha>] [--task <task> ...]",
+        options: ["--project", "--base", "--task"]
+    },
+    {
+        name: "change-set",
+        summary: "Inspect ChangeSets captured from WorkItem Candidates.",
+        sections: [{ id: "inspect", title: "Commands", entries: ["show"] }],
+        children: [
+            { name: "show", summary: "Show one ChangeSet.", usage: "yui task change-set show <task>/<change-set>" }
+        ]
+    },
     { name: "enter", summary: "Enter a Task Role, defaulting to Leader.", usage: "yui task enter <task> [role]" }
 ];
 export const ROOT_COMMAND = buildNode({
@@ -647,7 +789,8 @@ export const ROOT_COMMAND = buildNode({
             ] },
         { id: "workflow", title: "Workflow", entries: ["operator", "project", "task"] },
         { id: "configuration", title: "Configuration", entries: ["config", "agent", "profile", "role"] },
-        { id: "operations", title: "Operations", entries: ["web", "controller", "jobs"] },
+        { id: "operations", title: "Operations", entries: ["web", "controller", "execution", "job", "jobs", "telemetry", "release"] },
+        { id: "resources", title: "Resources", entries: ["resources"] },
         { id: "internal", title: "Internal", entries: ["internal"] }
     ],
     children: [
@@ -713,24 +856,80 @@ export const ROOT_COMMAND = buildNode({
                 },
                 {
                     name: "identity",
-                    summary: "Read the authenticated Controller launch identity.",
+                    summary: "Read the stable runtime identity receipt (build, backend, worker).",
                     hidden: true
                 },
                 { name: "stop", summary: "Stop the Controller." },
                 { name: "restart", summary: "Restart internal services without stopping tmux sessions." }
             ]
         },
+        {
+            name: "execution",
+            summary: "Read-only execution history audit.",
+            sections: [{
+                    id: "reports",
+                    title: "Commands",
+                    entries: ["audit"]
+                }],
+            children: [
+                {
+                    name: "audit",
+                    summary: "Report Runs, wakes, Sessions, Reviews, Integrations, and telemetry volume.",
+                    usage: "yui execution audit [--task <id>] [--since <iso>] [--until <iso>]",
+                    options: ["--task", "--since", "--until"]
+                }
+            ]
+        },
+        {
+            name: "release",
+            summary: "Install and activate immutable local runtime releases.",
+            sections: [{
+                    id: "commands",
+                    title: "Commands",
+                    entries: ["install", "list", "activate"]
+                }],
+            children: [
+                {
+                    name: "install",
+                    summary: "Install a runtime package as an immutable release.",
+                    usage: "yui release install <source-dir>"
+                },
+                { name: "list", summary: "List installed releases and the active pointer." },
+                {
+                    name: "activate",
+                    summary: "Activate a release via atomic Controller handover.",
+                    usage: "yui release activate [release-id]"
+                }
+            ]
+        },
+        {
+            name: "resources",
+            summary: "Inspect and garbage-collect managed worktrees, deployments, and runtime artifacts.",
+            sections: [{ id: "gc", title: "Commands", entries: ["gc"] }],
+            children: [
+                {
+                    name: "gc",
+                    summary: "Plan or apply resource garbage collection.",
+                    usage: "yui resources gc [--dry-run|--apply|--purge|--restore] [--quarantine-ttl-hours <hours>]",
+                    options: ["--dry-run", "--apply", "--purge", "--restore", "--quarantine-ttl-hours"]
+                }
+            ]
+        },
         {
             name: "config",
             summary: "Inspect or update Yui configuration.",
-            sections: [{ id: "manage", title: "Commands", entries: ["show", "set", "review"] }],
+            sections: [{ id: "manage", title: "Commands", entries: ["show", "set", "review", "leader-next-action"] }],
             children: [
                 { name: "show", summary: "Show effective Yui configuration." },
                 {
                     name: "set",
                     summary: "Update Yui configuration.",
-                    usage: "yui config set <--time-zone <IANA timezone> | --reconciliation-interval-seconds <5-300>>",
-                    options: ["--time-zone", "--reconciliation-interval-seconds"]
+                    usage: "yui config set <--time-zone <IANA timezone> | --reconciliation-interval-seconds <5-300> | --resources-gc-mode <report|quarantine> | --resources-gc-auto-quarantine <true|false>>",
+                    options: ["--time-zone", "--reconciliation-interval-seconds", "--resources-gc-mode", "--resources-gc-auto-quarantine"],
+                    optionValues: {
+                        "--resources-gc-mode": ["report", "quarantine"],
+                        "--resources-gc-auto-quarantine": ["true", "false"]
+                    }
                 },
                 {
                     name: "review",
@@ -741,12 +940,29 @@ export const ROOT_COMMAND = buildNode({
                         {
                             name: "set",
                             summary: "Enable review with a Global Role.",
-                            usage: "yui config review set --role <global-role> --trigger <always|leader|final>",
-                            options: ["--role", "--trigger"],
-                            optionValues: { "--trigger": ["always", "leader", "final"] }
+                            usage: "yui config review set --role <global-role> --trigger <always|leader|final> [--finding-ledger <shadow|enforce>]",
+                            options: ["--role", "--trigger", "--finding-ledger"],
+                            optionValues: {
+                                "--trigger": ["always", "leader", "final"],
+                                "--finding-ledger": ["shadow", "enforce"]
+                            }
                         },
                         { name: "clear", summary: "Disable global review." }
                     ]
+                },
+                {
+                    name: "leader-next-action",
+                    summary: "Configure the Leader next-action/duplicate-guard mode.",
+                    sections: [{ id: "manage", title: "Commands", entries: ["show", "set", "clear"] }],
+                    children: [
+                        { name: "show", summary: "Show the Leader next-action mode." },
+                        {
+                            name: "set",
+                            summary: "Set the Leader next-action mode (display|warn|enforce).",
+                            usage: "yui config leader-next-action set <display|warn|enforce>"
+                        },
+                        { name: "clear", summary: "Reset to the default display mode." }
+                    ]
                 }
             ]
         },
@@ -896,12 +1112,23 @@ export const ROOT_COMMAND = buildNode({
             name: "task",
             summary: "Manage Tasks, WorkItems, Agent Runs, and integration.",
             sections: [
-                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "update", "activate", "complete", "reopen", "retire", "list", "show", "context", "archive", "rebuild", "history", "replace", "reconcile"] },
-                { id: "collaboration", title: "Collaboration", entries: ["message", "input", "work", "run", "review", "integration", "role", "enter"] },
+                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "update", "activate", "complete", "reopen", "retire", "list", "show", "context", "next-action", "archive", "rebuild", "history", "replace", "reconcile"] },
+                { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "work", "run", "review", "integration", "role", "enter", "overlap", "change-set"] },
                 { id: "knowledge", title: "Task Knowledge", entries: ["brief", "decision", "milestone", "event"] }
             ],
             children: taskChildren
         },
+        {
+            name: "job",
+            summary: "Start, inspect, cancel, or acknowledge a Controller-managed DurableJob.",
+            sections: [{ id: "manage", title: "Commands", entries: ["start", "get", "cancel", "acknowledge"] }],
+            children: [
+                { name: "start", summary: "Start a DurableJob for build, test, package, or Integration checks.", usage: "yui job start --task <id> --project <project> --head <sha> --workspace <dir> --step <name>=<command> [--step ...] [--owner task|work-item:<id>|integration-attempt:<id>] [--env <k=v>...]" },
+                { name: "get", summary: "Show a DurableJob record and its terminal result.", usage: "yui job get --task <id> --job <job-id>" },
+                { name: "cancel", summary: "Request cancellation of a running or queued DurableJob.", usage: "yui job cancel --task <id> --job <job-id>" },
+                { name: "acknowledge", summary: "Acknowledge an unknown-needs-attention DurableJob so Task lifecycle gates can proceed.", usage: "yui job acknowledge --task <id> --job <job-id>" }
+            ]
+        },
         {
             name: "jobs",
             summary: "Inspect scheduler wake and recovery records.",
@@ -911,6 +1138,17 @@ export const ROOT_COMMAND = buildNode({
                 { name: "retry", summary: "Retry a failed Leader recovery.", usage: "yui jobs retry <id>" }
             ]
         },
+        {
+            name: "telemetry",
+            summary: "Inspect and compact the bounded provider-progress sidecar.",
+            sections: [{ id: "manage", title: "Commands", entries: ["status", "prune", "compact", "read"] }],
+            children: [
+                { name: "status", summary: "Show sidecar health, row counts, and retention settings.", usage: "yui telemetry status" },
+                { name: "prune", summary: "Apply terminal retention and active-Run caps.", usage: "yui telemetry prune [--task <id>] [--keep <n>] [--dry-run]" },
+                { name: "compact", summary: "Fold legacy semantic progress events into a staged Home's sidecar.", usage: "yui telemetry compact --from <home> --staged <dir> [--keep <n>] [--dry-run]" },
+                { name: "read", summary: "Page through retained progress rows or read a Run aggregate.", usage: "yui telemetry read --task <id> [--run <id>] [--aggregate] [--limit <n>] [--offset <n>]" }
+            ]
+        },
         {
             name: "internal",
             summary: "Internal Yui callbacks.",

package/dist/cli/updateOrchestrator.js

@@ -241,6 +241,14 @@ function activateAndVerify(ports, staged, home, storageBackupPath, lifecycle, pa
                         : postSwitchRecoveryAction(home, storageBackupPath),
                 recoverable: false,
                 version: staged.version,
+                // P1-1 (rr22): ANY failure to start or authenticate the replacement
+                // Controller leaves the lifecycle handoff unresolved — not just
+                // UPDATE_CONTROLLER_UNKNOWN_ACTIVE. Even when the old identity is
+                // restored below, the running Controller is not the replacement the
+                // step promised, so the adapter must persist the step as unknown
+                // rather than letting a controller-home query confirm it on binary
+                // health alone.
+                controllerOwnershipUnknown: true,
                 ...(storageBackupPath === undefined ? {} : { storageBackupPath })
             };
             // An ownership-unknown mismatch is a live-process blocker, not a

package/dist/cli/updatePorts.js

@@ -30,30 +30,89 @@
  * can resolve the true state.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { accessSync, constants, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runtimeError } from "../errors/cliError.js";
+import { isConcreteVersion } from "../domain/validation.js";
 import { STORAGE_DOCTOR_CHECK_NAMES } from "../doctor/doctor.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { correlateUpgradeReceipt } from "../storage/upgrade/upgradeOrchestrator.js";
 import { readSwitchProgress } from "../storage/upgrade/switchProgress.js";
 const PACKAGE_NAME = "@zq-silk/yui";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
+function resolveExecutable(command, environmentPath) {
+    if (isAbsolute(command))
+        return command;
+    for (const directory of (environmentPath ?? "").split(delimiter)) {
+        if (directory.length === 0)
+            continue;
+        const candidate = resolve(directory, command);
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Keep walking PATH; callers fail closed when no executable is found.
+        }
+    }
+    return undefined;
+}
+function failedSpawnResult(message) {
+    return {
+        pid: undefined,
+        output: [null, Buffer.alloc(0), Buffer.from(message)],
+        stdout: Buffer.alloc(0),
+        stderr: Buffer.from(message),
+        status: 127,
+        signal: null,
+        error: new Error(message)
+    };
+}
 /** Build the real ports. `spawn` is injectable so tests avoid real installs. */
 export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot = tmpdir()) {
+    // The production adapter must not let a later PATH change select a
+    // different npm during staging, activation, or recovery. Test doubles are
+    // intentionally left untouched so deterministic tests can dispatch on the
+    // stable command name `npm`.
+    const trustedNpm = spawn === spawnSync
+        ? resolveExecutable("npm", environment.PATH)
+        : "npm";
+    const run = (command, args, options) => {
+        if (command !== "npm")
+            return spawn(command, args, options);
+        if (trustedNpm === undefined) {
+            return failedSpawnResult("Unable to resolve trusted executable: npm");
+        }
+        return spawn(trustedNpm, args, options);
+    };
     // Keep the exact verified artifact in memory for this update attempt. This is
     // deliberately not persisted as a retry or recovery protocol.
     let verifiedActivatedBinary;
     let verifiedActivatedVersion;
-    const stopReplacementController = (home, pid) => (stopReplacementControllerForUpdate(home, pid, environment, spawn));
+    const stopReplacementController = (home, pid) => (stopReplacementControllerForUpdate(home, pid, environment, run));
     return {
-        stage() {
+        stage(version) {
+            // A caller that names a version (the release workflow, which freezes the
+            // exact version in its plan) installs THAT version — never a moving
+            // `latest` that could resolve to a different build than the one the
+            // plan authorized. A non-concrete value fails closed rather than being
+            // interpolated into an install spec. An omitted version keeps the
+            // interactive `yui update` behavior of staging latest.
+            const spec = version === undefined
+                ? PACKAGE_SPEC
+                : isConcreteVersion(version)
+                    ? `${PACKAGE_NAME}@${version.trim()}`
+                    : null;
+            if (spec === null) {
+                throw runtimeError(`Refusing to stage a non-concrete version (${String(version)}): only an exact `
+                    + "major.minor.patch version can be pinned for an update.");
+            }
             const stagingPath = mkdtempSync(join(stagingRoot, "yui-update-stage-"));
             let ownsStaging = true;
             try {
-                const result = spawn("npm", ["install", "--global", "--prefix", stagingPath, PACKAGE_SPEC], { cwd: process.cwd(), env: environment, shell: false, stdio: "inherit" });
+                const result = run("npm", ["install", "--global", "--prefix", stagingPath, spec], { cwd: process.cwd(), env: environment, shell: false, stdio: "inherit" });
                 assertSpawnOk(result, "stage the new package");
                 const binaryPath = join(stagingPath, "bin", "yui");
                 // Resolve the EXACT version that was staged (from the staged install's own
@@ -61,7 +120,7 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                 // version, FAIL the stage (R2-F1): we must never fall back to a bare
                 // `@latest`, which would let activation promote — and verify wave through —
                 // a different build than the one that passed preflight.
-                const version = resolveStagedVersion(stagingPath, binaryPath, environment, spawn);
+                const version = resolveStagedVersion(stagingPath, binaryPath, environment, run);
                 if (version === null) {
                     throw runtimeError("Failed to resolve the exact staged package version (neither the staged package.json "
                         + "nor `yui --json version` returned a concrete version). Refusing to proceed with a "
@@ -79,11 +138,11 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             }
         },
         preflight(staged, home) {
-            const result = spawn(staged.binaryPath, ["--json", "upgrade", "--update-preflight"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+            const result = run(staged.binaryPath, ["--json", "upgrade", "--update-preflight"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
             return interpretPreflight(result);
         },
         activateStorage(staged, home) {
-            const result = spawn(staged.binaryPath, ["--json", "upgrade"], {
+            const result = run(staged.binaryPath, ["--json", "upgrade"], {
                 cwd: process.cwd(),
                 // The parent update process captures/stops/drains the old Controller
                 // before invoking the staged child. Mark this internal call so the
@@ -105,12 +164,12 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             // `@latest` (R2-F1: `stage` guarantees `staged.version` is a concrete
             // version, so there is no `latest` sentinel to fall back to).
             const spec = `${PACKAGE_NAME}@${staged.version}`;
-            const result = spawn("npm", ["install", "--global", spec], { cwd: process.cwd(), env: environment, shell: false, stdio: "inherit" });
+            const result = run("npm", ["install", "--global", spec], { cwd: process.cwd(), env: environment, shell: false, stdio: "inherit" });
             assertSpawnOk(result, "activate the new binary");
         },
         verify(staged, home) {
             // Verify the ACTUALLY-ACTIVATED global binary, not the staging path (P1-3).
-            const activeBinary = resolveGlobalBinary(environment, spawn);
+            const activeBinary = resolveGlobalBinary(environment, run);
             if (activeBinary === null || !existsSync(activeBinary)) {
                 throw runtimeError("Post-update health check failed: could not locate the activated global `yui` binary.");
             }
@@ -122,7 +181,7 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             // "exited with status 5". We therefore parse+validate the structured storage
             // health first: only a valid success envelope with every expected storage
             // check present-and-ok, no blocking checks, AND exit 0 is healthy.
-            const doctor = spawn(activeBinary, ["--json", "doctor"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+            const doctor = run(activeBinary, ["--json", "doctor"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
             assertDoctorStorageHealthy(doctor);
             // 2) Confirm the activated binary's identity matches the staged artifact.
             // `staged.version` is always a concrete version (R2-F1), so we REQUIRE the
@@ -624,8 +683,12 @@ function assertActivatedControllerIdentity(identity, activatedBinary, activatedV
             + "runtime/entrypoint; refusing readiness.");
     }
 }
-/** Resolve the Controller entrypoint beside the activated package's CLI. */
-function activatedControllerEntrypoint(activatedBinary) {
+/**
+ * Resolve the Controller entrypoint beside the activated package's CLI.
+ * Exported so the release workflow's recovery query can apply the exact same
+ * entrypoint derivation as the production startup identity check (P1-1, rr23).
+ */
+export function activatedControllerEntrypoint(activatedBinary) {
     let resolvedBinary;
     try {
         resolvedBinary = realpathSync(activatedBinary);
@@ -934,15 +997,6 @@ function resolveStagedVersion(stagingPath, binaryPath, environment, spawn) {
     // with a successful, concrete version.
     return resolveBinaryVersion(binaryPath, environment, spawn);
 }
-/**
- * True for a concrete, pinnable package version — a semver-shaped `X.Y.Z` with an
- * optional pre-release/build suffix. Rejects dist-tag sentinels (`latest`, `next`,
- * …), empty/whitespace, and anything not anchored to a numeric `major.minor.patch`
- * so a sentinel can never be spliced into an activation spec (R3-F1).
- */
-function isConcreteVersion(value) {
-    return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value.trim());
-}
 /** Read a CONCRETE `version` from a package.json, or `null` when absent/non-concrete. */
 function readVersionFromPackageJson(path) {
     try {