@zq-silk/yui 0.9.0 → 0.10.0

package/ARCHITECTURE.md

@@ -98,9 +98,9 @@ leaves every candidate for the Leader to accept directly or review explicitly.
 `final` keeps WorkItem acceptance and Integration independent and supplies the
 default Reviewer Role when the Leader decides the frozen Task result warrants
 an independent final Review. An immutable Task-final contract can require that
-Review. Once a Task-final Round exists, it remains an obligation; a changed
-Task head requires a new Round and the previous report remains evidence. This
-final Reviewer evaluates the whole
+Review. A Leader-requested Round remains evidence without becoming policy: a
+later Task head does not require another Round unless the Leader requests one
+or an explicit Task contract requires it. This final Reviewer evaluates the whole
 Task, so normal delivery does not pay for a complete review of every WorkItem.
 Review Runs complete only their exact ReviewRound, leave the WorkItem awaiting
 acceptance, and never trigger another review or append a Candidate. Successful

package/README.md

@@ -144,6 +144,21 @@ Input by itself do not block. A blocker reports the total and exact available
 Task/Role/Run/native-session/launch identities and reason, leaves the scene
 unchanged, and tells the user to re-run `yui update` after the listed work clears;
 it never kills, resets, rebinds, retries, or drains on the user's behalf.
+After every listed Turn or Run finishes, the user can stop all idle managed
+Sessions from a normal shell and retry the update:
+
+```sh
+yui session stop --all
+yui update
+```
+
+`session stop --all` first checks every current Session and refuses without
+stopping anything while any Session still has a running Turn/Run or pending
+lifecycle work. Once clear, it fences new Leader dispatch, stops and drains the
+Controller, rechecks the runtime facts, then stops every exact idle Session. The
+Controller remains stopped so `yui update` can enter its offline window. When the
+installed version predates this command, exit every listed managed Session
+manually instead; a staged new CLI cannot write the older migration-required Home.
 
 Only that user re-run may enter the existing full migration. Once its preflight
 is clear, the update parent captures and stops the exact old Controller PID. The
@@ -266,9 +281,11 @@ feature before creating WorkItems. The Leader decides whether a feature is
 small enough to deliver on Task main or large enough for independently owned WorkItems. A WorkItem is
 one substantial requirement for one Worker, not a development step, test run,
 review finding, or local fix. Multiple WorkItems are useful only when distinct
-Workers can advance meaningful requirements independently. Once WorkItems
-produce Git results, their ChangeSets must be integrated into the Leader's
-Task main before Task-final Review or completion.
+Workers can advance meaningful requirements independently. A WorkItem's
+governing Candidate defines its delivery obligation: its current ChangeSets
+must reach committed Integration or an explicit superseded queue disposition
+before Task-final Review or completion. Older Candidate and ChangeSet records
+remain audit evidence without keeping the Task open.
 
 `project refresh` is the explicit network operation for a stable Project checkout. It fetches the
 configured stable branch directly from the Project remote URL and advances only through a clean,
@@ -402,7 +419,9 @@ yui task base status <task-id> --refresh
 The default check is offline and uses local remote-tracking refs. `--refresh`
 is the explicit authorization to query the configured remote; Yui never
 fetches, rebases, merges, or force-pushes as a hidden side effect of Task
-completion.
+completion. Behind, diverged, or unavailable remote state is reported as
+delivery-risk evidence for the Leader; it does not replace the Leader's choice
+of delivery base. A dirty Task workspace remains a completion blocker.
 
 Implementation WorkItems declare the Projects they may modify. Their workspace
 keeps the same relative layout, creates isolated worktrees only for that write
@@ -704,7 +723,7 @@ yui task complete <task-id> --summary-file delivery.txt \
   --accept-published-tree <publication-id>
 ```
 
-This does not weaken normal freshness checks. Yui requires the current,
+This is an independent exact-tree authorization. Yui requires the current,
 unsuperseded Publication to be merged and verified, its local commit to equal
 the physical Task head, its remote commit to be ancestry-divergent, and both
 commits to resolve to the same exact tree. When a Task-final Review obligation
@@ -712,10 +731,10 @@ exists, completion also requires the latest semantic Round to attest the
 accepted Task head; otherwise completion does not invent a ReviewRound.
 `--refresh-remote` fetches
 the remote object graph before resolving that Publication commit. For a Task
-governed by a durable exact final-review contract, the user/Operator command
-persists the exact authorization tuple and wakes the Task Leader; only that
-contract-capable Leader may consume it and complete the Task. Tasks without
-that contract retain the one-step explicit completion path. The Task event
+governed by a durable final-review contract, the stored contract continues to
+require its Reviewer policy, but compatible CLI and Controller updates do not
+need to reproduce its historical control-plane digest. Tasks without that
+contract retain the one-step explicit completion path. The Task event
 audit records the authorization and, on completion, the accepted Project,
 Publication, optional ReviewRound, both commits, and tree.
 
@@ -764,14 +783,22 @@ Global Operator and global Role sessions remain native interactive CLIs:
 yui session enter <global-role>
 ```
 
+An offline Home migration requires a short maintenance window with no managed
+Agent Session running. Once current Turns and Runs have finished, use
+`yui session stop --all` from a normal shell. The command stops Task and global
+Role Sessions only after every one is idle, and leaves all Sessions untouched
+when any Role is still busy. On success it also leaves the Controller stopped;
+run `yui update` next rather than resuming ordinary Task work.
+
 tmux fixes a pane's history capacity when that pane is created. Existing panes
 retain their configured capacity; managed runtime output remains observable in
 the Agent Host pane without becoming lifecycle or acknowledgement evidence.
 
-Each Role, including a Task-bound Worker instance, can bind multiple configured Agents, has one active Agent, and keeps
-a separate native session per Agent binding. Operator narrows this to at most
-one Agent per adapter—for example, one Codex and one Claude—so its bindings are
-ready-to-switch configurations rather than parallel identities. Operator can
+Each Role, including Operator and a Task-bound Worker instance, can bind multiple
+configured Agents, has one active Agent, and keeps a separate native session per
+Agent binding. Multiple bindings may use the same adapter for different accounts,
+models, profiles, or environment sources. They are ready-to-switch configurations,
+not parallel writers: the active binding remains the unique authority. Operator can
 keep multiple conversations for each binding. `operator new` and
 `operator resume` reuse the single Operator tmux pane: when a process is
 running, Yui asks before stopping it and switching the conversation. On a
@@ -813,7 +840,7 @@ movement cannot conceal a workflow that is not advancing.
 
 Stable Role context is also launch metadata, never a bootstrap turn. Yui passes Role policy and `systemPrompt` through the Agent's native system/developer-instruction channel. Task execution Runs receive the generic Leader or Worker Skill, while review Runs receive the generic Reviewer Skill based on durable Run purpose rather than a configured Role name. These Yui-owned Role Skills define portable orchestration only. Project Skills remain ordinary versioned files in the Project and are discovered, selected, and loaded by the Agent through its native project mechanism; Yui does not scan, parse, copy, or inject them.
 
-Native Codex developer instructions carry compact absolute references only for Yui-owned Role Skills, which Codex reads on demand. Because `developer_instructions` is one scalar setting, Yui inspects every supported Linux Codex layer—`/etc/codex/config.toml`, the user config, the selected `$CODEX_HOME/<name>.config.toml`, project configs, and `/etc/codex/managed_config.toml`—and refuses to replace a value found in any of them. Codex sessions opened without a managed Run use Yui's structured `notify` callback for session presentation and therefore require exclusive ownership of that setting. Managed Runs instead use invocation-local Agent Driver Hooks as their sole lifecycle authority. `skills.config` is not misused because it only enables or disables already-discovered Skills. Claude receives the same Yui-owned Role Skill content from a private `0600` managed context file rather than a large or sensitive argv value; retries and resumes reuse the purpose-specific Role path. Non-Operator global Roles stay neutral and receive no Task orchestration Skill. Operator therefore opens at an empty native composer, so the user's text remains its first user message. Leader wakeups and Worker or Reviewer Run assignments remain real mailbox-delivered work messages. An adapter without a native instruction channel must reject this context rather than silently converting it into a first user prompt.
+Native Codex developer instructions carry compact absolute references only for Yui-owned Role Skills, which Codex reads on demand. Yui applies this scalar as an invocation-local override, so existing user, profile, project, and system values do not make the Session unusable and the underlying config file is never mutated. A higher-precedence managed `developer_instructions` value remains a bounded launch blocker because Codex will not let invocation flags replace it. Interactive Codex Sessions apply the same rule to Yui's structured `notify` callback; Doctor reports ordinary overridden sources as context and rejects an effective managed conflict. Managed Runs instead use invocation-local Agent Driver Hooks as their sole lifecycle authority and do not claim `notify`. `skills.config` is not misused because it only enables or disables already-discovered Skills. Claude receives the same Yui-owned Role Skill content from a private `0600` managed context file rather than a large or sensitive argv value; retries and resumes reuse the purpose-specific Role path. Non-Operator global Roles stay neutral and receive no Task orchestration Skill. Operator therefore opens at an empty native composer, so the user's text remains its first user message. Leader wakeups and Worker or Reviewer Run assignments remain real mailbox-delivered work messages. An adapter without a native instruction channel must reject this context rather than silently converting it into a first user prompt.
 
 ## Controller and failure handling
 
@@ -929,6 +956,7 @@ yui config role add|list|show|update|remove|bind|unbind
 yui config profile add|list|show|update|remove|reset
 yui config completion [bash|zsh|fish]
 yui session enter|record|replace|reconcile
+yui session stop --all
 yui project add|clone|refresh|update|discover|list|show|knowledge
 ```
 

package/dist/cli/commandCatalog.js

@@ -199,6 +199,12 @@ const globalSessionChildren = [
         usage: "yui session replace <role> --native-id <id> --reason <text>",
         options: ["--native-id", "--reason"]
     },
+    {
+        name: "stop",
+        summary: "Stop all idle managed Sessions and the Controller before an offline update.",
+        usage: "yui session stop --all",
+        options: ["--all"]
+    },
     {
         name: "reconcile",
         summary: "Reconcile durable Session owners with native sessions.",
@@ -1357,14 +1363,16 @@ export const ROOT_COMMAND = buildNode({
         },
         {
             name: "session",
-            summary: "Load and enter global Role sessions, and reconcile their durable identities.",
+            summary: "Enter, stop, and reconcile managed Role sessions.",
             examples: [
                 "yui session context operator --json",
                 "yui session enter operator",
+                "yui session stop --all",
                 "yui session reconcile --report"
             ],
             sections: [
                 { id: "global", title: "Global Role sessions", entries: ["context", "enter", "record", "replace"] },
+                { id: "maintenance", title: "Maintenance", entries: ["stop"] },
                 { id: "recovery", title: "Recovery", entries: ["reconcile"] }
             ],
             children: globalSessionChildren

package/dist/cli.js

@@ -28,7 +28,7 @@ import { CONFIG_DOMAINS } from "./config/configCatalog.js";
 import { runConfigOverview } from "./commands/configOverview.js";
 import { parseControllerCleanupOptions, parseControllerStatusOptions, parseControllerRuntimeSnapshot, renderControllerResourceStatus, renderRuntimeIdentitySection, summarizeDurablePhysicalMismatch, runInteractiveControllerCleanup } from "./commands/controllerCommands.js";
 import { parseExecutionAuditOptions, runExecutionAuditCommand } from "./commands/executionAuditCommands.js";
-import { parseSessionReconcileOptions, runSessionReconcileCommand } from "./commands/sessionCommands.js";
+import { parseSessionReconcileOptions, parseSessionStopOptions, runSessionReconcileCommand, runSessionStopCommand } from "./commands/sessionCommands.js";
 import { SessionOwnerReconciliation } from "./controller/sessionOwnerReconciliation.js";
 import { runJobCommand } from "./commands/jobCommands.js";
 import { runDurableJobCommand } from "./commands/durableJobCommands.js";
@@ -667,6 +667,31 @@ export async function main() {
         return;
     }
     if (resolved[0] === "session") {
+        if (resolved[1] === "stop") {
+            const options = parseSessionStopOptions(resolved.slice(2));
+            const result = await runSessionStopCommand({
+                options,
+                runtime: {
+                    beginMaintenance: () => acquireHandoverLock(home),
+                    snapshot: () => ({
+                        candidates: schedulerStore.listRuntimeSessionCandidates(),
+                        dormant: schedulerStore.listDormantRuntimeOwners()
+                    }),
+                    drainController: () => runtime.drainController(),
+                    stopController: () => stopFileTaskController(home, {
+                        environment: process.env
+                    }),
+                    startController: async () => {
+                        await ensureFileTaskController(home, { environment: process.env });
+                    },
+                    stopDormantSession: (candidate) => runtime.stopDormantSession(candidate)
+                },
+                environment: process.env
+            });
+            process.exitCode = result.exitCode;
+            emit(result.output, false, result.data);
+            return;
+        }
         const roleOptions = {
             yuiHome: home,
             env: process.env,

package/dist/commands/globalRoleCommands.js

@@ -198,7 +198,6 @@ function updateRole(args, store, options) {
         if (changesAgentConfig) {
             const agentId = parsed.one("--agent")?.trim() || role.activeAgentId;
             const agent = requireAgent(agentId, tx);
-            assertOperatorAdapterAvailable(role, agent);
             const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
             bindings = { ...role.agentBindings, [agentId]: patchRoleAgentBinding(binding, parsed) };
         }
@@ -231,7 +230,6 @@ function bindRole(args, store) {
             roleName: role.name
         }, "desired Agent binding update");
         const agent = requireAgent(agentId, tx);
-        assertOperatorAdapterAvailable(role, agent);
         const binding = role.agentBindings[agentId] ?? createRoleAgentBinding(definition(agent));
         const withBinding = updateGlobalRole(role, {
             agentBindings: { ...role.agentBindings, [agentId]: binding }
@@ -260,16 +258,6 @@ function bindRole(args, store) {
     });
     return presentRole(result.message, result.role, store);
 }
-function assertOperatorAdapterAvailable(role, agent) {
-    if (role.name !== "operator" || Object.hasOwn(role.agentBindings, agent.id))
-        return;
-    const existing = Object.values(role.agentBindings).find((binding) => binding.adapterId === agent.adapterId);
-    if (existing !== undefined) {
-        throw usageError(`Operator already has a ${agent.adapterId} Agent: ${existing.agentId}. `
-            + "Update that Agent's configuration, or activate another adapter and "
-            + "unbind it before binding this Agent.");
-    }
-}
 function removeRole(args, store) {
     const [rawName, ...rest] = args;
     const name = roleName(rawName);

package/dist/commands/sessionCommands.js

@@ -1,5 +1,121 @@
 import { usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
+export function parseSessionStopOptions(args) {
+    if (args.length !== 1 || args[0] !== "--all") {
+        throw usageError("Session stop usage: yui session stop --all.");
+    }
+    return { all: true };
+}
+/**
+ * Stop every current managed Session only when all of them are idle. The
+ * all-or-nothing preflight prevents a maintenance command from silently
+ * stopping half the topology while another Role is still working.
+ */
+export async function runSessionStopCommand(input) {
+    void input.options;
+    if (input.environment?.YUI_SESSION_SCOPE !== undefined) {
+        throw usageError("Session stop must be run by the user from a normal shell, outside a managed Yui Session.");
+    }
+    const maintenance = input.runtime.beginMaintenance();
+    let completed = false;
+    try {
+        const initial = input.runtime.snapshot();
+        const initiallyBlocked = blockedSessions(initial);
+        if (initiallyBlocked.length > 0)
+            return blockedStopResult(initiallyBlocked);
+        // Stop and drain the Controller while the handover fence prevents a new
+        // Leader dispatch. The explicit full pass settles pending runtime inbox and
+        // lifecycle work that may exist without a current Session candidate.
+        await input.runtime.drainController();
+        await input.runtime.stopController();
+        // Re-read the authoritative facts after the drain because a Run that was
+        // already inside a pass may have changed state meanwhile.
+        const settled = input.runtime.snapshot();
+        const blockedAfterDrain = blockedSessions(settled);
+        if (blockedAfterDrain.length > 0) {
+            await input.runtime.startController();
+            return blockedStopResult(blockedAfterDrain);
+        }
+        for (const session of settled.candidates) {
+            const candidate = settled.dormant.find((entry) => sameStopCandidate(session, entry));
+            if (candidate === undefined) {
+                throw new Error(`Dormant Session changed during maintenance: ${renderSessionOwner(session)}.`);
+            }
+            await input.runtime.stopDormantSession(candidate);
+        }
+        const count = settled.candidates.length;
+        completed = true;
+        return {
+            output: count === 0
+                ? "No managed Sessions were running. The Controller remains stopped; run `yui update` now.\n"
+                : `Stopped ${count} managed Sessions. The Controller remains stopped; run \`yui update\` now.\n`,
+            data: { stopped: settled.candidates, blocked: [] },
+            exitCode: 0
+        };
+    }
+    catch (error) {
+        if (!completed) {
+            try {
+                await input.runtime.startController();
+            }
+            catch (restartError) {
+                throw new AggregateError([error, restartError], "Session maintenance failed and the Controller could not be restarted.");
+            }
+        }
+        throw error;
+    }
+    finally {
+        maintenance.release();
+    }
+}
+function blockedSessions(input) {
+    return input.candidates.flatMap((session) => {
+        const idle = input.dormant.some((candidate) => sameStopCandidate(session, candidate));
+        if (idle)
+            return [];
+        return [{
+                session,
+                reason: session.status === "running"
+                    ? "running"
+                    : "runtime-work-pending"
+            }];
+    });
+}
+function blockedStopResult(blocked) {
+    const details = blocked.map(({ session, reason }) => (`- ${renderSessionOwner(session)} (${reason === "running"
+        ? "a Turn or Run is still running"
+        : "an active Run or lifecycle operation is still pending"})`));
+    return {
+        output: [
+            `Cannot stop managed Sessions: ${blocked.length} Session(s) are still busy.`,
+            ...details,
+            "No Session was stopped. Let the listed work finish, then run `yui session stop --all` again."
+        ].join("\n") + "\n",
+        data: { stopped: [], blocked },
+        exitCode: 5
+    };
+}
+function sameStopCandidate(session, candidate) {
+    if (session.owner.scope !== candidate.owner.scope)
+        return false;
+    if (session.owner.roleName !== candidate.owner.roleName)
+        return false;
+    if (session.owner.scope === "task"
+        && candidate.owner.scope === "task"
+        && session.owner.taskId !== candidate.owner.taskId) {
+        return false;
+    }
+    return session.agentId === candidate.agentId
+        && session.adapterId === candidate.adapterId
+        && session.nativeSessionId === candidate.nativeSessionId
+        && session.launchId === candidate.launchId
+        && session.sessionUpdatedAt === candidate.sessionUpdatedAt;
+}
+function renderSessionOwner(session) {
+    return session.owner.scope === "task"
+        ? `${session.owner.taskId}/${session.owner.roleName}`
+        : `global/${session.owner.roleName}`;
+}
 export function parseSessionReconcileOptions(args) {
     const allowed = new Set(["--report", "--cleanup"]);
     if (args.some((argument) => !allowed.has(argument))) {

package/dist/commands/taskBaseCommands.js

@@ -1,5 +1,5 @@
 import { usageError } from "../errors/cliError.js";
-import { assertTaskBaseFreshnessForCompletion, inspectTaskBaseFreshness, renderTaskBaseFreshnessReport } from "../repository/taskBaseFreshness.js";
+import { inspectTaskBaseFreshness, renderTaskBaseFreshnessReport } from "../repository/taskBaseFreshness.js";
 export async function runTaskBaseStatusCommand(args, store, options = {}) {
     const usage = "Task base status usage: yui task base status <task> [--refresh].";
     const refresh = args.includes("--refresh");
@@ -11,19 +11,9 @@ export async function runTaskBaseStatusCommand(args, store, options = {}) {
         git: options.git,
         refresh
     });
-    assertReportIsDeliverySafe(report);
     return {
         kind: "output",
         output: renderTaskBaseFreshnessReport(report),
         data: report
     };
 }
-function assertReportIsDeliverySafe(report) {
-    try {
-        assertTaskBaseFreshnessForCompletion(report);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw usageError(`${renderTaskBaseFreshnessReport(report)}${message}`);
-    }
-}

package/dist/commands/taskCommands.js

@@ -102,7 +102,7 @@ function storedTaskFinalReviewContractResolution(store, taskId) {
  * acceptance, and completion mutation must present the same verified
  * capability; shared review-config drift is intentionally irrelevant.
  */
-function taskFinalReviewContractForMutation(store, taskId, options, authorization = {}) {
+function taskFinalReviewContractForMutation(store, taskId, options) {
     const supplied = options.taskFinalReviewContract;
     if (supplied !== undefined) {
         validateTaskFinalReviewContract(supplied);
@@ -117,11 +117,12 @@ function taskFinalReviewContractForMutation(store, taskId, options, authorizatio
     }
     if (stored === undefined)
         return supplied;
-    if (supplied === undefined) {
-        if (authorization.allowStoredWithoutSupplied === true)
-            return stored;
-        throw usageError(`Task final-review contract is missing for ${taskId}.`);
-    }
+    // Historical exact contracts now express only a durable Reviewer policy.
+    // The persisted contract remains the audit authority, but ordinary
+    // protocol/storage-compatible CLIs may continue the Task without presenting
+    // a release-bound capability on every mutation.
+    if (supplied === undefined)
+        return stored;
     if (!sameTaskFinalReviewContract(stored, supplied)) {
         throw usageError(`Task final-review contract control-plane digest mismatch for ${taskId}.`);
     }
@@ -168,18 +169,10 @@ export function preflightTaskCompletion(taskId, store, options = {}, request = {
         throw usageError(`Task is archived: ${task.id}.`);
     if (task.status !== "active")
         throw usageError(`Task is not active: ${task.id}.`);
-    // Resolve and authenticate the durable Task-local gate before any remote
-    // fetch or Integration write.  All checks below mirror the transactional
-    // completion path, which remains the final CAS fence after reconciliation.
-    // A human/global Operator cannot present the exact managed Leader contract.
-    // For the explicit published-tree path only, let that caller authenticate
-    // the stored contract far enough to persist an exact authorization fact.
-    // The same command must return before any contract-governed completion
-    // mutation; the exact Leader later consumes the authorization with the real
-    // contract capability.
-    const authorizingPublishedTree = request.acceptedPublishedTreePublicationId !== undefined
-        && actor !== "leader";
-    const taskFinalReviewContract = taskFinalReviewContractForMutation(store, task.id, options, { allowStoredWithoutSupplied: authorizingPublishedTree });
+    // Resolve the durable Task-local Reviewer policy before any remote fetch or
+    // Integration write. Historical control-plane identity is audit evidence,
+    // not a capability that every compatible CLI must reproduce.
+    const taskFinalReviewContract = taskFinalReviewContractForMutation(store, task.id, options);
     const activeTaskReview = store.listReviewRounds(task.id).some((round) => ((round.scope ?? "work-item") === "task"
         && (round.status === "pending" || round.status === "running")));
     // Issue 06: one shared readiness projection enumerates every blocker.
@@ -4375,30 +4368,17 @@ function queueTaskReviewRound(store, task, config, taskCandidate, options, now,
  * (or a failed round is surfaced as a blocker).
  */
 function prepareFinalTaskReview(store, task, now, taskFinalContract, options) {
-    // Any Task-final ReviewRound is durable completion evidence/obligation.
-    // Once one exists, later changes to the mutable global review config cannot
-    // weaken the requirement or change its reviewer. Before the first such
-    // Round, the current global `final` config remains an available Reviewer
-    // default but does not establish an obligation by itself.
+    // A Leader-requested ReviewRound is evidence, not policy. Only an explicit
+    // immutable Task contract creates a durable completion obligation; optional
+    // historical Rounds never cause completion to manufacture another Round for
+    // a later head.
+    if (taskFinalContract === undefined || task.projectBindings.length === 0)
+        return null;
     const taskRounds = reviewRoundsByIdentity(store.listReviewRounds(task.id))
         .filter((round) => ((round.scope ?? "work-item") === "task"
-        && (taskFinalContract === undefined || sameTaskFinalReviewContract(round.taskFinalReviewContract, taskFinalContract))));
+        && sameTaskFinalReviewContract(round.taskFinalReviewContract, taskFinalContract)));
     const establishedRound = taskRounds.at(-1);
-    let config;
-    if (taskFinalContract !== undefined) {
-        config = taskFinalReviewConfig(taskFinalContract);
-    }
-    else if (establishedRound === undefined) {
-        // The configured Reviewer is available to the Leader, but does not choose
-        // the Task topology. A managed final Review becomes an obligation only
-        // after the Leader requests one (or an immutable Task contract requires it).
-        config = null;
-    }
-    else {
-        config = { roleName: establishedRound.reviewerRoleName, trigger: "final" };
-    }
-    if (config === null || task.projectBindings.length === 0)
-        return null;
+    const config = taskFinalReviewConfig(taskFinalContract);
     const taskCandidate = taskReviewProvenance(store, task, options).candidate;
     const latest = establishedRound;
     if (latest?.status === "running") {

package/dist/controller/clientRuntime.js

@@ -1,9 +1,11 @@
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { callController, readControllerDiscovery, stopOrphanedFileTaskController, stopPreviousFileTaskController } from "../core/controllerClient.js";
+import { controllerSocketPath } from "../core/controllerEndpoint.js";
 import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "../core/protocol.js";
 import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, operationalAgentEnvironment, selectEnvironment, YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES } from "../agent/launchEnvironment.js";
 import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
+import { yuiTmuxServerName } from "../tmux/tmuxManager.js";
 import { hasRuntimeLifecycleWork } from "../runtime/lifecycleReservation.js";
 import { assertControllerStatusIdentity } from "../runtime/exactControlPlane.js";
 import { EPHEMERAL_DOMAIN_ENVIRONMENT_NAMES } from "./domainIdentity.js";
@@ -11,6 +13,7 @@ import { yuiVersionIdentity } from "../version.js";
 import { SessionOwnerReconciliation } from "./sessionOwnerReconciliation.js";
 import { WorkspaceCleanupBlockedError } from "../repository/taskWorkspacePreparer.js";
 import { CONTROLLER_SHUTDOWN_TIMEOUT_MS, LIFECYCLE_REQUEST_TIMEOUT_MS } from "../runtime/runtimeDeadlines.js";
+import { FileTaskRuntimeIsolation } from "../runtime/taskRuntimeIsolation.js";
 const STARTUP_TIMEOUT_MS = 5_000;
 const POLL_INTERVAL_MS = 50;
 const ENVIRONMENT_REFRESH_TIMEOUT_MS = 500;
@@ -502,6 +505,63 @@ export class FileTaskWorkflowRuntime {
             throw new Error(`Global Role runtime session is still active: ${roleName}.`);
         }
     }
+    /** Drain pending runtime facts while an external maintenance fence is held. */
+    async drainController() {
+        await ensureFileTaskController(this.home, {
+            environment: this.clientOptions.environment
+        });
+        await callFileTaskController(this.home, "scheduler.scan", {}, {
+            ...this.clientOptions,
+            requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
+        });
+    }
+    /**
+     * Maintenance-only exact stop used after the Controller has fully exited.
+     * The dormant candidate fences the durable cleanup request; physical owner
+     * records and Task runtime isolation are cleared through the same primitives
+     * as the Controller lifecycle path before the Session becomes stopped.
+     */
+    async stopDormantSession(candidate) {
+        const queuedAt = new Date();
+        const target = this.schedulerStore.enqueueRuntimeCleanup(candidate.owner, queuedAt, candidate);
+        if (target === null) {
+            throw new Error(`Dormant Session changed before maintenance cleanup: ${runtimeOwnerLabel(candidate.owner)}.`);
+        }
+        const reconciliation = new SessionOwnerReconciliation({
+            home: this.home,
+            store: this.store,
+            environment: this.clientOptions.environment,
+            tmux: this.tmux
+        });
+        const termination = await reconciliation.terminateOwner(candidate.owner);
+        if (termination.outcome !== "stop-confirmed") {
+            throw new Error(`Role runtime cleanup could not prove physical exit: ${runtimeOwnerLabel(candidate.owner)}; `
+                + termination.remaining
+                    .map(({ record, detail }) => `${record.launchId}: ${detail}`)
+                    .join("; "));
+        }
+        if (candidate.owner.scope === "task" && candidate.launchId !== undefined) {
+            const isolation = new FileTaskRuntimeIsolation({
+                runtimeRoot: `${this.home}.task-runtimes`,
+                controlPlane: {
+                    yuiHome: this.home,
+                    controllerSocketPath: controllerSocketPath(this.store.getHomeIdentity().homeId),
+                    tmuxNamespace: yuiTmuxServerName(this.home),
+                    globalInstallPaths: [process.execPath]
+                }
+            });
+            isolation.cleanupTaskLaunch({
+                taskId: candidate.owner.taskId,
+                launchId: candidate.launchId,
+                reason: this.store.getTask(candidate.owner.taskId)?.status === "completed"
+                    ? "completion"
+                    : "interruption"
+            });
+        }
+        if (!this.schedulerStore.completeRuntimeCleanup(target, new Date())) {
+            throw new Error(`Role runtime cleanup state changed before completion: ${runtimeOwnerLabel(candidate.owner)}.`);
+        }
+    }
     inspectTaskRolePanes(taskId) {
         return this.tmux.inspectTaskRolePanes(taskId);
     }
@@ -532,6 +592,11 @@ export class FileTaskWorkflowRuntime {
         });
     }
 }
+function runtimeOwnerLabel(owner) {
+    return owner.scope === "task"
+        ? `${owner.taskId}/${owner.roleName}`
+        : `global/${owner.roleName}`;
+}
 const MANAGED_RUNTIME_ENVIRONMENT = new Set(YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES);
 function foregroundGlobalRoleEnvironment(store, roleName, source) {
     const role = store.getGlobalRole?.(roleName);