@zq-silk/yui 0.8.6 → 0.8.8

package/README.md

@@ -633,6 +633,21 @@ and `task work retire <task>/<work> --summary "..."` to retire obsolete work,
 optionally naming a replacement. WorkItem and Integration
 worktrees and check logs remain available as evidence until explicit cleanup.
 
+Incorrect historical directives and execution attempts can be removed from
+operational projections without deleting their audit records:
+
+```sh
+yui task message retire <task>/<message> --reason "Superseded instruction"
+yui task run retire <task>/<agent-run> --reason "Invalid launch record"
+```
+
+These commands append a retirement fact. Lists and audit views retain the
+original Message, WorkItem, or AgentRun and mark it retired; managed Run context,
+actionability, recovery, review evidence, and scheduling ignore it. Retiring
+an active AgentRun first terminalizes that exact Run, and retirement is
+idempotent. Only the user or global Operator may retire Messages or AgentRuns;
+WorkItems may also be retired by their Task Leader.
+
 For long-running Tasks, the Leader keeps Yui—not a native transcript—as the
 recovery authority. The Task Brief owns the overall technical approach,
 including how coordinated Project changes fit together. WorkItems own the
@@ -766,9 +781,11 @@ running AgentRun and its native Session continue under their immutable
 effective snapshot even if the Role is edited or switched. Resume is allowed
 only when the complete effective snapshot and workspace remain compatible;
 otherwise Yui starts a new Session after the old process has stopped and keeps
-the terminal Session's immutable effective snapshot in history. Until that
-process terminates, exact control-plane wakes continue through its actual
-snapshot instead of applying desired drift as a hot change.
+the terminal Session's immutable effective snapshot in history. Managed
+Sessions invoke the ordinary `yui` command; their Manifest and durable
+Role/Run fences authenticate scope while protocol and storage compatibility
+allow a CLI package or Controller upgrade in place. Exact internal callbacks
+remain fenced to their originating runtime snapshot.
 
 Use `yui config role unbind <global-role> <agent-id>` or `yui task role unbind <task-id> <role> <agent-id>` to retire a dormant binding. The active binding and any non-stopped native session are rejected; a stopped session record is removed atomically with the binding.
 

package/dist/cli/commandCatalog.js

@@ -363,7 +363,7 @@ const taskChildren = [
     {
         name: "message",
         summary: "Manage durable Task messages.",
-        sections: [{ id: "manage", title: "Commands", entries: ["send", "list"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["send", "list", "retire"] }],
         children: [
             {
                 name: "send",
@@ -381,6 +381,12 @@ const taskChildren = [
                 summary: "List Task messages.",
                 usage: "yui task message list <id> [--after <timestamp>] [--limit <n>]",
                 options: ["--after", "--limit"]
+            },
+            {
+                name: "retire",
+                summary: "Retire an incorrect historical Task Message without deleting its audit record.",
+                usage: "yui task message retire <task>/<message> --reason <text>",
+                options: ["--reason"]
             }
         ]
     },
@@ -689,7 +695,7 @@ const taskChildren = [
     {
         name: "run",
         summary: "Inspect and control Task Role Agent Runs.",
-        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint", "retire"] }],
         children: [
             { name: "list", summary: "List Runs for a work item.", usage: "yui task run list <task>/<work>" },
             {
@@ -749,6 +755,12 @@ const taskChildren = [
                 options: ["--note", "--note-file"],
                 fileOptions: ["--note-file"],
                 hidden: true
+            },
+            {
+                name: "retire",
+                summary: "Retire an incorrect historical Agent Run without deleting its audit record.",
+                usage: "yui task run retire <task>/<run> --reason <text>",
+                options: ["--reason"]
             }
         ]
     },
@@ -1405,7 +1417,7 @@ export const ROOT_COMMAND = buildNode({
             sections: [{
                     id: "callbacks",
                     title: "Callbacks",
-                    entries: ["session-notify", "runtime-hook", "agent-host"]
+                    entries: ["session-notify", "runtime-hook", "agent-host", "session-cli-refresh"]
                 }],
             children: [
                 {
@@ -1422,6 +1434,11 @@ export const ROOT_COMMAND = buildNode({
                     name: "runtime-hook",
                     summary: "Record a managed Agent Driver observation from stdin.",
                     usage: "yui internal runtime-hook"
+                },
+                {
+                    name: "session-cli-refresh",
+                    summary: "Refresh legacy managed Session CLI wrappers after an update.",
+                    usage: "yui internal session-cli-refresh"
                 }
             ]
         }

package/dist/cli/updatePorts.js

@@ -199,6 +199,12 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                     + `but the staged/verified artifact was ${staged.version}. Refusing to trust a `
                     + "different build than the one that passed preflight.");
             }
+            // Existing managed Sessions may have been created by a release that
+            // embedded an exact CLI path/version in its wrapper. Convert those
+            // authenticated, Manifest-referenced wrappers before the replacement
+            // Controller starts so the update cannot strand a live Session.
+            const sessionCliRefresh = run(activeBinary, ["--json", "internal", "session-cli-refresh"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+            assertSpawnOk(sessionCliRefresh, "refresh managed Session CLI wrappers");
             // Retain the exact path used by both doctor and version verification. The
             // replacement start must not resolve UPDATE_CLI_PATH or npm again.
             verifiedActivatedBinary = activeBinary;

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -48,7 +49,7 @@ import { runWorkflowCommandAsync } from "./commands/workflowCommands.js";
 import { createUpdatePorts } from "./cli/updatePorts.js";
 import { createReleaseWorkflowPorts } from "./release/releaseWorkflowPorts.js";
 import { acquireHandoverLock, readRuntimeIdentity } from "./release/runtimeRelease.js";
-import { renderReleaseActivateResult, renderReleaseInstallResult, renderReleaseList, runReleaseActivate, runReleaseInstall, runReleaseList } from "./commands/releaseCommands.js";
+import { renderReleaseActivateResult, renderReleaseInstallResult, renderReleaseList, resolveReleaseActivationDriver, runReleaseActivate, runReleaseInstall, runReleaseList } from "./commands/releaseCommands.js";
 import { reconcileTaskRemoteBaselines, verifyTaskCompletionPublishedTree } from "./commands/taskCompletionGate.js";
 import { runTaskBaseStatusCommand } from "./commands/taskBaseCommands.js";
 import { assertTaskBaseFreshnessForCompletion, inspectTaskBaseFreshness } from "./repository/taskBaseFreshness.js";
@@ -81,8 +82,8 @@ import { AgentConfigurationCatalogService } from "./executor/agentConfigurationC
 import { TmuxWebTerminalService } from "./web/tmuxWebTerminal.js";
 import { listOperatorSessions, operatorSessionRef } from "./operator/operatorSessionHistory.js";
 import { YUI_VERSION, yuiVersionIdentity } from "./version.js";
-import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactControlPlanePreflight, assertExactTaskRuntimeEnvironment, assertExactTaskRuntimeState, exactControlPlaneDigest, extractExactControlArgument, parseExactControlPlaneDescriptor } from "./runtime/exactControlPlane.js";
-import { readSessionBootstrapManifest } from "./context/sessionBootstrapManifest.js";
+import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertCompatibleControlPlanePreflight, assertExactControlPlanePreflight, assertExactTaskRuntimeEnvironment, assertExactTaskRuntimeState, exactControlPlaneDigest, extractExactControlArgument, createExactControlPlaneDescriptor, parseExactControlPlaneDescriptor } from "./runtime/exactControlPlane.js";
+import { readSessionBootstrapManifest, refreshManagedSessionCliWrappers } from "./context/sessionBootstrapManifest.js";
 import { builtinAgentDriverRegistry } from "./runtime/builtinAgentDrivers.js";
 import { createTaskFinalReviewContract, extractTaskFinalReviewRequest } from "./review/taskFinalReviewContract.js";
 import { prepareTaskFinalReviewContractRebindProof, resolveRecordedTaskFinalReviewContract } from "./review/taskFinalReviewContractRebind.js";
@@ -112,6 +113,22 @@ void main().catch((error) => {
     process.exitCode = 5;
 });
 export async function main() {
+    const delegatedDriver = explicitReleaseActivationDriver();
+    if (delegatedDriver !== null) {
+        const delegated = spawnSync(process.execPath, [delegatedDriver, ...process.argv.slice(2)], {
+            cwd: process.cwd(),
+            env: process.env,
+            stdio: "inherit"
+        });
+        if (delegated.error !== undefined) {
+            throw runtimeError(`Target release activation driver could not start: ${delegated.error.message}`);
+        }
+        if (delegated.signal !== null) {
+            throw runtimeError(`Target release activation driver stopped by signal ${delegated.signal}.`);
+        }
+        process.exitCode = delegated.status ?? 5;
+        return;
+    }
     const { contract: taskFinalReviewContract, verifiedStore, controlPlane: exactCurrentControlPlane } = await preflightManagedTaskControlPlane();
     if (args.length === 0) {
         emit(renderCommandHelp((await import("./cli/commandCatalog.js")).ROOT_COMMAND, VERSION));
@@ -264,6 +281,16 @@ export async function main() {
         return;
     }
     if (args[0] === "internal") {
+        if (args[1] === "session-cli-refresh" && args.length === 2) {
+            if (process.env.YUI_SESSION_SCOPE === "task"
+                || (process.env.YUI_SESSION_SCOPE === "global" && process.env.YUI_ROLE !== "operator")) {
+                throw usageError("Managed Session CLI refresh may be run only by the user or global Operator.");
+            }
+            const result = refreshManagedSessionCliWrappers(home);
+            emit(`Refreshed ${result.refreshed} legacy Session CLI wrapper(s); `
+                + `${result.current} already current, ${result.skipped} skipped.`, false, result);
+            return;
+        }
         if (args[1] === "agent-host" && args.length === 4) {
             process.exitCode = await runAgentHost({
                 home,
@@ -1350,6 +1377,15 @@ export async function main() {
     }
     throw usageError(`Command is not connected to the restored FileTaskStore framework yet: ${resolved[0]}.`, renderCommandHelp(invocation.node, VERSION));
 }
+function explicitReleaseActivationDriver() {
+    if (args.length !== 3
+        || args[0] !== "release"
+        || args[1] !== "activate"
+        || args[2].startsWith("-")) {
+        return null;
+    }
+    return resolveReleaseActivationDriver(resolveYuiHome(process.env), args[2], fileURLToPath(import.meta.url));
+}
 async function preflightManagedTaskControlPlane() {
     if (exactControlInvocation.error !== undefined) {
         throw new Error(exactControlInvocation.error);
@@ -1364,7 +1400,8 @@ async function preflightManagedTaskControlPlane() {
         throw new Error("Exact control-plane invocation requires both frozen descriptors in a managed Task runtime.");
     }
     if (!exactRuntime) {
-        if (exactControlInvocation.digest !== undefined) {
+        if (exactControlInvocation.digest !== undefined
+            || process.env.YUI_SESSION_SCOPE === "global") {
             return await preflightManagedGlobalControlPlane(exactControlInvocation.digest);
         }
         if (taskFinalReviewInvocation.request !== undefined) {
@@ -1379,24 +1416,42 @@ async function preflightManagedTaskControlPlane() {
         throw new Error("Exact control-plane invocation is required for this managed Task runtime.");
     }
     const control = parseExactControlPlaneDescriptor(serializedControl);
-    const internalCallback = args[0] === "internal";
-    if (!internalCallback && exactControlInvocation.digest === undefined) {
-        throw new Error("Exact control-plane invocation is required; bare `yui` and PATH launchers are not valid in a managed Task runtime.");
-    }
-    const digest = exactControlInvocation.digest ?? exactControlPlaneDigest(control);
-    await assertExactControlPlanePreflight({
-        serializedDescriptor: serializedControl,
-        digest,
-        actualExecutable: process.execPath,
-        actualCliEntry: fileURLToPath(import.meta.url),
-        actualHome: resolveYuiHome(process.env)
-    }, {
-        // Provider callbacks must remain able to append their immutable inbox fact
-        // while the Controller is offline. They still validate executable, CLI,
-        // Home, build, schema, and the exact Task runtime envelope first.
-        checkController: !internalCallback
-    });
-    const runtime = assertExactTaskRuntimeEnvironment(serializedRuntime, process.env, digest, control.yuiHome);
+    const internalCallback = args[0] === "internal"
+        && ["agent-host", "session-notify", "runtime-hook"].includes(args[1] ?? "");
+    const home = resolveYuiHome(process.env);
+    assertManagedSessionManifest(home, "task");
+    if (resolve(control.yuiHome) !== resolve(home)) {
+        throw new Error("Managed Task control-plane descriptor belongs to another YUI_HOME.");
+    }
+    const frozenDigest = exactControlPlaneDigest(control);
+    const exactCommand = internalCallback || exactControlInvocation.digest !== undefined;
+    let commandControl;
+    let digest;
+    if (exactCommand) {
+        digest = exactControlInvocation.digest ?? frozenDigest;
+        await assertExactControlPlanePreflight({
+            serializedDescriptor: serializedControl,
+            digest,
+            actualExecutable: process.execPath,
+            actualCliEntry: fileURLToPath(import.meta.url),
+            actualHome: home
+        }, {
+            // Provider callbacks must remain able to append their immutable inbox fact
+            // while the Controller is offline. They still validate executable, CLI,
+            // Home, schema, and the exact Task runtime envelope first.
+            checkController: !internalCallback
+        });
+        commandControl = control;
+    }
+    else {
+        await assertCompatibleControlPlanePreflight({ actualHome: home });
+        // Package/build identity is deliberately not part of ordinary Session
+        // continuity. Keep contracts on the Session's frozen digest while the
+        // current CLI is proven protocol/storage compatible.
+        commandControl = control;
+        digest = frozenDigest;
+    }
+    const runtime = assertExactTaskRuntimeEnvironment(serializedRuntime, process.env, frozenDigest, control.yuiHome);
     const runtimeDriverCallback = args[0] === "internal"
         && args[1] === "runtime-hook"
         && process.env.YUI_DRIVER_ID !== undefined
@@ -1417,7 +1472,7 @@ async function preflightManagedTaskControlPlane() {
     if (request === undefined) {
         return {
             contract: undefined,
-            controlPlane: { digest, descriptor: control },
+            controlPlane: { digest, descriptor: commandControl },
             verifiedStore
         };
     }
@@ -1427,13 +1482,22 @@ async function preflightManagedTaskControlPlane() {
     if (request.taskId !== runtime.taskId) {
         throw new Error(`Task final-review contract Task id mismatch: expected ${runtime.taskId}, found ${request.taskId}.`);
     }
+    const recordedContract = resolveRecordedTaskFinalReviewContract(runtime.taskId, verifiedStore.listWorkItems(runtime.taskId), verifiedStore.listReviewRounds(runtime.taskId), verifiedStore.listEvents(runtime.taskId))?.effective;
+    if (recordedContract !== undefined
+        && recordedContract.reviewerRoleName !== request.reviewerRoleName) {
+        throw new Error(`Task final-review Reviewer mismatch: expected ${recordedContract.reviewerRoleName}, `
+            + `found ${request.reviewerRoleName}.`);
+    }
     return {
         contract: createTaskFinalReviewContract({
             taskId: runtime.taskId,
             reviewerRoleName: request.reviewerRoleName,
-            controlPlaneDigest: digest
+            // Once Task evidence establishes a contract, a compatible Session or
+            // CLI replacement presents that same capability. Package/build identity
+            // must not force a release rebind or invalidate delivery evidence.
+            controlPlaneDigest: recordedContract?.controlPlaneDigest ?? digest
         }),
-        controlPlane: { digest, descriptor: control },
+        controlPlane: { digest, descriptor: commandControl },
         verifiedStore
     };
 }
@@ -1445,38 +1509,77 @@ async function preflightManagedGlobalControlPlane(digest) {
         throw new Error("Task final-review contract establishment requires a verified exact Task control-plane invocation.");
     }
     const manifestPath = process.env.YUI_SESSION_MANIFEST;
-    const sessionCliPath = process.env.YUI_SESSION_CLI;
-    if (manifestPath === undefined || sessionCliPath === undefined) {
-        throw new Error("Exact global control-plane invocation requires its Session Manifest and CLI.");
+    if (manifestPath === undefined) {
+        throw new Error("Managed global control-plane invocation requires its Session Manifest.");
     }
-    const manifest = readSessionBootstrapManifest(manifestPath);
+    const home = resolveYuiHome(process.env);
+    const manifest = assertManagedSessionManifest(home, "global");
     const expectedRoleKind = process.env.YUI_ROLE === "operator" ? "operator" : "global";
     if (manifest.owner.scope !== "global"
-        || manifest.roleKind !== expectedRoleKind
-        || resolve(manifest.controlPlane.sessionCliPath) !== resolve(sessionCliPath)
-        || manifest.controlPlane.digest !== digest) {
-        throw new Error("Exact global control-plane invocation does not match its Session Manifest.");
+        || manifest.roleKind !== expectedRoleKind) {
+        throw new Error("Managed global invocation does not match its Session Manifest.");
     }
     const serializedDescriptor = readFileSync(manifest.controlPlane.descriptorPath, "utf8");
     const descriptor = parseExactControlPlaneDescriptor(serializedDescriptor);
-    if (exactControlPlaneDigest(descriptor) !== digest
-        || resolve(manifest.controlPlane.descriptorPath) !== resolve(join(descriptor.yuiHome, "runtime", "control-plane", `${digest}.json`))
+    if (resolve(descriptor.yuiHome) !== resolve(home)) {
+        throw new Error("Managed global control-plane descriptor belongs to another YUI_HOME.");
+    }
+    const frozenDigest = exactControlPlaneDigest(descriptor);
+    if (frozenDigest !== manifest.controlPlane.digest
+        || resolve(manifest.controlPlane.descriptorPath) !== resolve(join(descriptor.yuiHome, "runtime", "control-plane", `${frozenDigest}.json`))
         || resolve(manifestPath) !== resolve(join(descriptor.yuiHome, "runtime", "session-manifests", `${manifest.digest}.json`))) {
         throw new Error("Exact global Session Manifest does not match its control-plane descriptor.");
     }
-    await assertExactControlPlanePreflight({
-        serializedDescriptor,
-        digest,
-        actualExecutable: process.execPath,
-        actualCliEntry: fileURLToPath(import.meta.url),
-        actualHome: resolveYuiHome(process.env)
-    });
+    let commandControl;
+    let commandDigest;
+    if (digest !== undefined) {
+        await assertExactControlPlanePreflight({
+            serializedDescriptor,
+            digest,
+            actualExecutable: process.execPath,
+            actualCliEntry: fileURLToPath(import.meta.url),
+            actualHome: home
+        });
+        commandControl = descriptor;
+        commandDigest = digest;
+    }
+    else {
+        await assertCompatibleControlPlanePreflight({ actualHome: home });
+        commandControl = currentInvocationControlPlane(home);
+        commandDigest = exactControlPlaneDigest(commandControl);
+    }
     return {
         contract: undefined,
-        controlPlane: { digest, descriptor },
-        verifiedStore: openCompatibleFileTaskStore(descriptor.yuiHome)
+        controlPlane: { digest: commandDigest, descriptor: commandControl },
+        verifiedStore: openCompatibleFileTaskStore(home)
     };
 }
+function currentInvocationControlPlane(home) {
+    return createExactControlPlaneDescriptor({
+        executable: process.execPath,
+        cliEntry: fileURLToPath(import.meta.url),
+        yuiHome: home
+    });
+}
+function assertManagedSessionManifest(home, scope) {
+    const manifestPath = process.env.YUI_SESSION_MANIFEST;
+    if (manifestPath === undefined) {
+        throw new Error("Managed control-plane invocation requires its Session Manifest.");
+    }
+    const manifest = readSessionBootstrapManifest(manifestPath);
+    if (manifest.owner.scope !== scope) {
+        throw new Error("Managed invocation scope does not match its Session Manifest.");
+    }
+    if (scope === "task" && (manifest.owner.scope !== "task"
+        || manifest.owner.taskId !== process.env.YUI_TASK_ID)) {
+        throw new Error("Managed Task invocation does not match its Session Manifest owner.");
+    }
+    const expectedPath = resolve(home, "runtime", "session-manifests", `${manifest.digest}.json`);
+    if (resolve(manifestPath) !== expectedPath) {
+        throw new Error("Managed Session Manifest path is outside this YUI_HOME.");
+    }
+    return manifest;
+}
 function cleanupCliError(error, fallbackResource) {
     if (error instanceof WorkspaceCleanupBlockedError) {
         return usageError(error.message, undefined, cleanupBlockedDetails(error.reason, error.resource, error.retryable));

package/dist/commands/globalRoleCommands.js

@@ -36,9 +36,8 @@ function roleContext(args, store, options) {
         if (environment.YUI_SESSION_SCOPE !== "global" || environment.YUI_ROLE !== name) {
             throw usageError("Managed GlobalRole context is outside the exact Session authority.");
         }
-        if (environment.YUI_SESSION_MANIFEST === undefined
-            || environment.YUI_SESSION_CLI === undefined) {
-            throw usageError("Managed GlobalRole context requires the exact Session Manifest and CLI.");
+        if (environment.YUI_SESSION_MANIFEST === undefined) {
+            throw usageError("Managed GlobalRole context requires its Session Manifest.");
         }
     }
     const role = requireRole(name, store);
@@ -81,7 +80,12 @@ function roleContext(args, store, options) {
                 : ["perform-global-role-request"]
         },
         sessionManifestPath: environment.YUI_SESSION_MANIFEST,
-        sessionCliPath: environment.YUI_SESSION_CLI
+        cliCommand: "yui",
+        // Compatibility hint for already-running Sessions. New instructions use
+        // the stable command name and do not bind behavior to this wrapper path.
+        ...(environment.YUI_SESSION_CLI === undefined
+            ? {}
+            : { legacySessionCliPath: environment.YUI_SESSION_CLI })
     });
     if (options.jsonOutput === true)
         return `${JSON.stringify(context)}\n`;

package/dist/commands/releaseCommands.js

@@ -8,7 +8,7 @@ import { join, resolve } from "node:path";
 import { callController, ControllerClientError } from "../core/controllerClient.js";
 import { readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
 import { activateRelease } from "../release/releaseHandover.js";
-import { assertReleaseIsNotWorktreeOrLinked, readActiveReleasePointer, readReleaseManifest, releasesDirectory, releaseDirectoryFor, verifyReleaseIntegrity, writeSmokeReceipt } from "../release/runtimeRelease.js";
+import { assertReleaseIsNotWorktreeOrLinked, detectRunningRelease, readActiveReleasePointer, readReleaseManifest, readSmokeReceipt, releasesDirectory, releaseDirectoryFor, verifyReleaseIntegrity, writeSmokeReceipt } from "../release/runtimeRelease.js";
 /**
  * Installs a runtime package directory into the Home's immutable release
  * tree. The source must carry a release manifest, must not be a Git worktree
@@ -123,7 +123,7 @@ export function runReleaseList(home) {
                     version: manifest.version,
                     buildId: manifest.buildId,
                     packageDigest: manifest.packageDigest,
-                    smoke: existsSync(join(releaseDir, "smoke-receipt.json"))
+                    smoke: hasMatchingSmokeReceipt(releaseDir, manifest)
                 };
             }
             catch {
@@ -142,6 +142,8 @@ export function runReleaseList(home) {
 /** Resolves an installed release by directory name or build ID. */
 export function resolveInstalledRelease(home, releaseId) {
     const directory = releasesDirectory(home);
+    if (!existsSync(directory))
+        return null;
     for (const entry of readdirSync(directory, { withFileTypes: true })) {
         if (!entry.isDirectory())
             continue;
@@ -156,18 +158,45 @@ export function resolveInstalledRelease(home, releaseId) {
                     + "Reinstall it with `yui release install <source-dir>` before activating.", { cause: error });
             }
         }
+        const releaseDir = join(directory, entry.name);
+        let manifest;
         try {
-            const manifest = readReleaseManifest(join(directory, entry.name));
-            if (manifest.buildId === releaseId) {
-                return { releaseDir: join(directory, entry.name), manifest };
-            }
+            manifest = readReleaseManifest(releaseDir);
         }
         catch {
             continue;
         }
+        if (manifest.buildId !== releaseId)
+            continue;
+        try {
+            return { releaseDir, manifest: verifyReleaseIntegrity(releaseDir) };
+        }
+        catch (error) {
+            throw new Error(`Release ${releaseId} failed integrity verification and may have drifted: `
+                + `${error instanceof Error ? error.message : String(error)}. `
+                + "Reinstall it with `yui release install <source-dir>` before activating.", { cause: error });
+        }
     }
     return null;
 }
+/**
+ * Selects the verified target release CLI as the activation driver. Ordinary
+ * commands remain on the globally installed CLI; only an explicit target
+ * activation crosses into the target package so its handover deadlines and
+ * protocol own the complete operation.
+ */
+export function resolveReleaseActivationDriver(home, releaseId, currentCliPath) {
+    const resolved = resolveInstalledRelease(home, releaseId);
+    if (resolved === null)
+        return null;
+    if (!hasMatchingSmokeReceipt(resolved.releaseDir, resolved.manifest))
+        return null;
+    const running = detectRunningRelease(currentCliPath);
+    if (running !== null && resolve(running.releaseDir) === resolve(resolved.releaseDir)) {
+        return null;
+    }
+    return join(resolved.releaseDir, "dist", "cli.js");
+}
 /** Runs the atomic Controller handover for one installed release. */
 export async function runReleaseActivate(home, releaseId, options = {}) {
     let resolved;
@@ -192,11 +221,11 @@ export async function runReleaseActivate(home, releaseId, options = {}) {
             recoverable: true
         };
     }
-    if (!existsSync(join(resolved.releaseDir, "smoke-receipt.json"))) {
+    if (!hasMatchingSmokeReceipt(resolved.releaseDir, resolved.manifest)) {
         return {
             outcome: "aborted",
             phase: "resolve",
-            message: `Release has no smoke receipt: ${releaseId}.`,
+            message: `Release has no matching smoke receipt: ${releaseId}.`,
             action: "Reinstall the release; the smoke receipt is written at install time.",
             recoverable: true
         };
@@ -217,6 +246,13 @@ export async function runReleaseActivate(home, releaseId, options = {}) {
             : { dualOwnerGraceMs: options.dualOwnerGraceMs })
     });
 }
+function hasMatchingSmokeReceipt(releaseDir, manifest) {
+    const receipt = readSmokeReceipt(releaseDir);
+    return receipt !== null
+        && receipt.version === manifest.version
+        && receipt.buildId === manifest.buildId
+        && receipt.packageDigest === manifest.packageDigest;
+}
 /** Renders the install result as concise CLI text. */
 export function renderReleaseInstallResult(result) {
     switch (result.outcome) {