@zq-silk/yui 0.13.7 → 0.13.9

package/dist/commands/taskCommands.js

@@ -19,7 +19,7 @@ import { renderRoleDetails } from "../output/rolePresentation.js";
 import { createTaskMessage, taskMessageAuthorLabel } from "../message/message.js";
 import { cancelInputRequest } from "../input/inputRequest.js";
 import { retireExactActiveAgentRun, terminalizeExactTaskRun, validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
-import { activeRoleAgentBinding, copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole, updateRoleStatus } from "../role/role.js";
+import { activeRoleAgentBinding, copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole } from "../role/role.js";
 import { agentRunDeliveryReceiptId, createAgentRun, failAgentRun, withAgentRunContextSnapshot, yieldAgentRun } from "../run/agentRun.js";
 import { matchYieldReceipt } from "../run/yieldReceipt.js";
 import { createRejectedYieldAttempt, rejectedYieldAttemptEventPayload, rejectedYieldAttemptFromTaskEvent, RUN_YIELD_REJECTED_EVENT } from "../run/rejectedYieldAttempt.js";
@@ -987,11 +987,6 @@ function retireTaskCommand(args, store, options) {
                 tx.saveInputRequest(task.id, cancelInputRequest(request, `Task retired: ${summary}`, now));
             }
         }
-        for (const role of tx.listRoles(task.id)) {
-            if (role.status !== "idle") {
-                tx.saveRole(task.id, updateRoleStatus(role, "idle", now));
-            }
-        }
         for (const mailbox of tx.listWorkMailboxes()) {
             if ((mailbox.target.kind === "task"
                 || mailbox.target.kind === "role")
@@ -1281,6 +1276,8 @@ function taskRoleCommand(args, store, options) {
         return output(bindTaskRole(rest, store, options));
     if (command === "unbind")
         return output(unbindTaskRole(rest, store, options));
+    if (command === "session")
+        return taskRoleSessionCommand(rest, store, options);
     if (command === "view")
         return viewTaskRole(rest, store);
     if (command === "takeover")
@@ -1291,6 +1288,87 @@ function taskRoleCommand(args, store, options) {
         ? "Task role command is required."
         : `Unknown command: task role ${command}`);
 }
+function taskRoleSessionCommand(args, store, options) {
+    const [command, ...rest] = args;
+    if (command === "inspect") {
+        exactPositionals(rest, 2, "Task Role Session inspect usage: yui task role session inspect <task> <role>.");
+        const task = requireTask(store, rest[0]);
+        const role = requireRole(store, task.id, rest[1]);
+        taskActor(store, options, task.id);
+        const sessions = store.getTaskRoleSessionSet(task.id, role.name);
+        const active = sessions?.sessions[sessions.activeAgentId] ?? null;
+        const binding = sessions?.providerBinding ?? null;
+        return output(active === null
+            ? `No Session exists for ${task.id}/${role.name}.\n`
+            : [
+                `Session ${task.id}/${role.name}`,
+                `Agent: ${active.agentId}/${active.adapterId}`,
+                `Native id: ${active.nativeSessionId}`,
+                `Host activation: ${active.launchId ?? "none"}`,
+                `Session: ${active.status}${active.endReason === undefined ? "" : `/${active.endReason}`}`,
+                `Turn: ${binding?.turn?.status ?? "none"}`
+            ].join("\n") + "\n", { task, role, session: active, providerBinding: binding });
+    }
+    if (command === "stop") {
+        const usage = "Task Role Session stop usage: yui task role session stop <task> <role> --reason <text>.";
+        const parsed = parseTail(rest, new Set(["--reason"]), usage);
+        exactPositionals(parsed.positionals, 2, usage);
+        const reason = requiredOption(parsed.options, "--reason");
+        const now = clock(options);
+        const request = store.transaction((tx) => {
+            const task = requireTask(tx, parsed.positionals[0]);
+            assertTaskOpen(task);
+            const actor = taskActor(tx, options, task.id);
+            const role = requireRole(tx, task.id, parsed.positionals[1]);
+            if (actor === "leader" && role.name === LEADER_ROLE) {
+                throw usageError("A Leader cannot stop the Session executing its own current command.", usage);
+            }
+            if (tx.getActiveAgentRun(task.id, role.name) !== null) {
+                throw usageError(`Task Role has an active Run; settle or retire it before stopping the Session: ${task.id}/${role.name}.`, usage);
+            }
+            const sessions = tx.getTaskRoleSessionSet(task.id, role.name);
+            const session = sessions?.sessions[sessions.activeAgentId];
+            if (session === undefined || session.status === "ended") {
+                throw usageError(`Task Role has no active Session: ${task.id}/${role.name}.`, usage);
+            }
+            const lifecycle = tx.getWorkMailbox(runtimeLifecycleTarget({
+                scope: "task",
+                taskId: task.id,
+                roleName: role.name
+            }));
+            if (lifecycle !== null && workMailboxHasWork(lifecycle)) {
+                throw usageError(`Task Role Session lifecycle is busy: ${task.id}/${role.name}.`, usage);
+            }
+            recordTaskEvent(tx, task.id, "runtime.session-stop-requested", {
+                roleName: role.name,
+                agentId: session.agentId,
+                adapterId: session.adapterId,
+                nativeSessionId: session.nativeSessionId,
+                launchId: session.launchId ?? "",
+                reason,
+                requestedBy: actor
+            }, now);
+            return {
+                taskId: task.id,
+                roleName: role.name,
+                agentId: session.agentId,
+                adapterId: session.adapterId,
+                nativeSessionId: session.nativeSessionId,
+                ...(session.launchId === undefined ? {} : { launchId: session.launchId }),
+                sessionUpdatedAt: session.updatedAt
+            };
+        });
+        return {
+            kind: "session-stop",
+            ...request,
+            reason,
+            output: `Stopped Session ${request.taskId}/${request.roleName}: ${reason}\n`
+        };
+    }
+    throw usageError(command === undefined
+        ? "Task Role Session command is required."
+        : `Unknown command: task role session ${command}`);
+}
 function addTaskRole(args, store, options) {
     const usage = "Task role add usage: yui task role add <task> <name> [Role and Agent settings].";
     const [taskId, roleName, ...tail] = args;
@@ -1488,7 +1566,7 @@ function removeTaskRole(args, store, options) {
             throw usageError(`Task Role has an active Run and cannot be removed: ${task.id}/${role.name}.`);
         }
         const sessions = tx.getTaskRoleSessionSet(task.id, role.name);
-        if (Object.values(sessions?.sessions ?? {}).some(({ status }) => status !== "stopped")) {
+        if (Object.values(sessions?.sessions ?? {}).some(({ status }) => status === "active")) {
             throw usageError(`Task Role has a running native Agent and cannot be removed: ${task.id}/${role.name}.`);
         }
         if (!tx.removeTaskRole(task.id, role.name))
@@ -1536,7 +1614,7 @@ function bindTaskRole(args, store, options) {
                 return switchActiveRoleAgent(bound, existing, agent.id, {
                     activeRun: tx.getActiveAgentRun(task.id, role.name) !== null,
                     nativeProcessRunning: currentSession !== undefined
-                        && currentSession.status !== "stopped"
+                        && currentSession.status === "active"
                 }, now);
             }
             catch (error) {
@@ -1590,7 +1668,7 @@ function viewTaskRole(args, store) {
     }
     const role = requireRole(store, task.id, args[1]);
     const session = store.getRoleSession(task.id, role.name);
-    if (session === null || session.status === "stopped" || session.status === "broken") {
+    if (session === null || session.status === "ended") {
         throw usageError(`Task Role has no live Provider view: ${task.id}/${role.name}.`);
     }
     return {
@@ -1619,7 +1697,7 @@ function transferTaskRoleAuthority(args, store, options, action) {
             if (sessions === null || sessions === undefined || session === undefined
                 || binding === null || binding === undefined
                 || session.launchId === undefined
-                || session.status === "stopped" || session.status === "broken") {
+                || session.status === "ended") {
                 throw new Error(`Task Role has no live managed Provider: ${task.id}/${role.name}.`);
             }
             const activation = currentProviderActivation(binding);
@@ -2374,7 +2452,6 @@ function dispatchWork(args, store, options) {
             const role = requireRole(tx, task.id, unboundRun.roleName);
             tx.saveAgentRun(runWithLineage);
             tx.saveActiveAgentRun(runWithLineage);
-            tx.saveRole(task.id, updateRoleStatus(role, "running", now));
             enqueueWork(tx, roleMailbox(task.id, role.name), "run-dispatched", now, [
                 runRef(task.id, runWithLineage.id),
                 workItemRef(task.id, item.id)
@@ -3065,7 +3142,7 @@ function rebindTaskFinalReviewContract(args, store, options) {
             if (leaderSessions.inFlight !== null) {
                 throw usageError("Task final-review contract cannot rebind while the Leader runtime has unsettled Run state.");
             }
-            const liveLeaderSession = Object.values(leaderSessions.sessions).find(({ status }) => status !== "stopped" && status !== "broken");
+            const liveLeaderSession = Object.values(leaderSessions.sessions).find(({ status }) => status === "active");
             if (liveLeaderSession !== undefined) {
                 throw usageError(`Task final-review contract cannot rebind while Leader Session ${liveLeaderSession.agentId} is ${liveLeaderSession.status}.`);
             }
@@ -4499,7 +4576,6 @@ function retryRun(args, store, options) {
         });
         tx.saveAgentRun(created);
         tx.saveActiveAgentRun(created);
-        tx.saveRole(task.id, updateRoleStatus(role, "running", now));
         if (previous.workItemId !== undefined && retriedItemWithGroup !== null) {
             const item = retriedItemWithGroup;
             const workspace = tx.getWorkItemWorkspace(task.id, item.id);
@@ -6072,7 +6148,6 @@ export function dispatchPreparedReviewRound(taskId, reviewRoundId, store, option
             const laneReviewer = requireRole(tx, taskId, unboundRun.roleName);
             tx.saveAgentRun(created);
             tx.saveActiveAgentRun(created);
-            tx.saveRole(taskId, updateRoleStatus(laneReviewer, "running", now));
             enqueueWork(tx, roleMailbox(taskId, laneReviewer.name), "review-requested", now, [
                 runRef(taskId, created.id),
                 ...(item === undefined ? [] : [workItemRef(taskId, item.id)])
@@ -7170,14 +7245,11 @@ function settleTaskExecutionForCompletion(store, taskId, roles, summary, now) {
                 sessions = terminalizeTaskRoleRunSession(sessions, sessions.inFlight, now);
             }
             const current = sessions.sessions[sessions.activeAgentId];
-            if (current !== undefined && current.status !== "stopped" && current.status !== "broken") {
-                sessions = updateRoleAgentSessionStatus(sessions, sessions.activeAgentId, "stopped", now);
+            if (current !== undefined && current.status === "active") {
+                sessions = updateRoleAgentSessionStatus(sessions, sessions.activeAgentId, "ended", now, "stopped");
             }
             store.saveTaskRoleSessionSet(sessions);
         }
-        if (role.status !== "idle") {
-            store.saveRole(taskId, updateRoleStatus(role, "idle", now));
-        }
         if (!cleanupRequired)
             continue;
         const target = runtimeLifecycleTarget({
@@ -7191,14 +7263,14 @@ function settleTaskExecutionForCompletion(store, taskId, roles, summary, now) {
     return targets;
 }
 function ownedRuntimeSessionRequiresCleanup(session) {
-    if (session === undefined || session.status === "stopped" || session.status === "broken") {
+    if (session === undefined || session.status === "ended") {
         return false;
     }
     // Older synthetic session fixtures can represent a ready native session
     // without a lifecycle generation. Do not manufacture a cleanup obligation
     // for those records; coordinated launches always carry launchId, while a
     // running session remains actionable even when an older record lacks it.
-    return session.status === "running" || session.launchId !== undefined;
+    return session.launchId !== undefined;
 }
 function roleMailbox(taskId, roleName) {
     return { kind: "role", taskId, roleName };

package/dist/commands/taskContextCommand.js

@@ -249,7 +249,7 @@ export function runTaskContextCommand(args, store, currentTaskReviewCandidate =
                 const effectiveSource = activeRun === undefined ? "Session" : "Run";
                 const creation = [...events].reverse().find((event) => (event.type === "role.added" && event.payload.role === role.name));
                 return [
-                    `  ${role.name} [${role.status}]: ${role.activeAgentId}/${binding.adapterId}`,
+                    `  ${role.name} [${activeRun === undefined ? "idle" : "running"}]: ${role.activeAgentId}/${binding.adapterId}`,
                     `    Desired: r${role.launchRevision}; Profile intent: ${role.defaultAccess}; Model: ${binding.config.model ?? "default"}; effort: ${binding.config.effort ?? "default"}; permission: ${binding.config.permission.strategy}`,
                     `    Effective: ${effective === undefined
                         ? "not started"

package/dist/commands/taskExecutionCommands.js

@@ -4,7 +4,6 @@ import { recordExecutionLaneResult } from "../execution/executionGroup.js";
 import { usageError } from "../errors/cliError.js";
 import { requestDurableJobCancel } from "../job/durableJob.js";
 import { finishReviewRound, updateReviewExecutionGroup } from "../review/reviewRound.js";
-import { updateRoleStatus } from "../role/role.js";
 import { failAgentRun } from "../run/agentRun.js";
 import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
 import { startTaskExecution, stopTaskExecution } from "../task/task.js";
@@ -83,10 +82,6 @@ export function stopTaskExecutionCommand(request, store, options = {}) {
             if (sessions !== null && sessions.inFlight !== null) {
                 tx.saveTaskRoleSessionSet(terminalizeCurrentRun(sessions, now));
             }
-            const role = tx.getRole(task.id, roleName);
-            if (role !== null && role.status !== "idle") {
-                tx.saveRole(task.id, updateRoleStatus(role, "idle", now));
-            }
         }
         // A stop is allowed to discard stale pointer projections even when their
         // historical Runs are already terminal.

package/dist/commands/taskOverviewCommand.js

@@ -78,7 +78,11 @@ function buildTaskOverviewEntry(task, store, now, runtimeHealthPolicy) {
     const legacyNext = deriveNextAction(task, brief, workItems, openInputRequests, blockers, pendingWakeup);
     const leader = {
         role: "leader",
-        roleStatus: leaderRole?.status ?? "missing",
+        roleStatus: leaderRole === null
+            ? "missing"
+            : agentRuns.some((run) => run.roleName === "leader" && run.status === "active")
+                ? "running"
+                : roleSessions.find((session) => session.roleName === "leader")?.status ?? "idle",
         summary: brief?.leaderSummary ?? null,
         currentFocus: brief?.currentFocus ?? null,
         updatedAt: brief?.updatedAt ?? null,

package/dist/commands/taskRoleRuntimeStatus.js

@@ -85,7 +85,6 @@ export function renderTaskRoleRuntimeStatus(status) {
             ? "-"
             : status.launchDrift ? "pending next launch" : "none"}`,
         `  Run/session      ${status.runSessionDrift ? "snapshot mismatch" : "snapshot consistent"}`,
-        `  Role state       ${status.role.status}`,
         `  Active work      ${activeWork}`,
         `  Active run       ${activeRun}`,
         ...(lastRun === undefined ? [] : [`  Last run         ${lastRun}`]),
@@ -254,10 +253,7 @@ function calculateHealth(role, activeRun, lastRun, nativeSession, runtimeCleanup
             healthReason: "the native Session is unbound; verified runtime cleanup is pending"
         };
     }
-    if (role.status === "failed" || role.status === "exited") {
-        return { health: "failed", healthReason: `persisted Role state is ${role.status}` };
-    }
-    if (nativeSession?.status === "broken") {
+    if (nativeSession?.status === "ended" && nativeSession.endReason === "failed") {
         // Issue 09: a broken Session only fails a live Run. When the last Run
         // already yielded, the Session death is a lifecycle event, not a Run
         // failure — surface it as attention with the persisted Run outcome.
@@ -287,12 +283,6 @@ function calculateHealth(role, activeRun, lastRun, nativeSession, runtimeCleanup
         };
     }
     if (activeRun !== null) {
-        if (role.status !== "running") {
-            return {
-                health: "needs-attention",
-                healthReason: `the active Run conflicts with persisted Role state ${role.status}`
-            };
-        }
         if (activeRun.deliveredAt !== undefined && tmux.state !== "running") {
             return { health: "needs-attention", healthReason: "the delivered active Run has no live tmux pane" };
         }
@@ -339,13 +329,10 @@ function calculateHealth(role, activeRun, lastRun, nativeSession, runtimeCleanup
             }
         }
     }
-    if (activeRun === null && role.status === "running") {
-        return { health: "needs-attention", healthReason: "the Role is running without an active Run" };
-    }
-    if (nativeSession?.status === "running" && tmux.state !== "running") {
+    if (nativeSession?.status === "active" && tmux.state !== "running") {
         return { health: "needs-attention", healthReason: "the native session is running without a live tmux pane" };
     }
-    if (nativeSession?.status === "stopped" && tmux.state === "running") {
+    if (nativeSession?.status === "ended" && tmux.state === "running") {
         return { health: "needs-attention", healthReason: "a stopped native session has a live tmux pane" };
     }
     if (role.name === "leader" && openInputRequestCount > 0) {

package/dist/config/configCatalog.js

@@ -1,6 +1,5 @@
-import { supportedAgentAdapterIds } from "../agent/adapterCatalog.js";
 import { MAX_RUN_CAP } from "../telemetry/telemetryConfig.js";
-import { MAX_CONTEXT_BUDGET_TOKENS, MAX_PROVIDER_RETRY_ATTEMPTS, MIN_CONTEXT_BUDGET_TOKENS } from "./yuiConfig.js";
+import { MAX_CONTEXT_BUDGET_TOKENS, MIN_CONTEXT_BUDGET_TOKENS } from "./yuiConfig.js";
 export const CONFIG_DOMAINS = ["system", "runtime", "workflow", "resources", "tools"];
 /**
  * Public durable configuration contract. CLI help, completion, config show,
@@ -16,10 +15,6 @@ export const CONFIG_DEFINITIONS = Object.freeze([
     { key: "runtime-health", domain: "runtime", property: "runtimeHealth", label: "Runtime health thresholds", summary: "Quiet, checkpoint-overdue, and read-only diagnostic thresholds in seconds; values must be strictly increasing (defaults: 300/900/1800).", takesEffect: "CLI and Web projections immediately; scheduler diagnostics after the Controller restarts." },
     { key: "agent-launch-inactivity-timeout-seconds", domain: "runtime", property: "agentLaunchInactivityTimeoutSeconds", label: "Agent launch inactivity timeout", summary: "Maximum launch silence before startup fails, 15-3600 seconds (default: 300).", takesEffect: "After the Controller restarts." },
     { key: "delivery-timeout-seconds", domain: "runtime", property: "deliveryTimeoutSeconds", label: "Delivery timeout", summary: "Total control-plane delivery retry budget, 5-600 seconds (default: 120).", takesEffect: "After the Controller restarts; internal retry cadence remains automatic." },
-    { key: "provider-retry-mode", domain: "runtime", property: "providerRetryMode", label: "Provider retry mode", summary: "Provider retry mode: off, shadow, or enforce (default: enforce).", takesEffect: "The next eligible provider-failure decision." },
-    { key: "provider-retry-adapters", domain: "runtime", property: "providerRetryAdapters", label: "Provider retry adapters", summary: `Adapters with in-place retry: all, off, or a comma-separated subset of ${supportedAgentAdapterIds().join(", ")} (default: all).`, takesEffect: "The next eligible provider-failure decision." },
-    { key: "provider-retry-delays-seconds", domain: "runtime", property: "providerRetryDelaysSeconds", label: "Provider retry delays", summary: `Ordered comma-separated retry delays of 1-600 seconds, with 1-${MAX_PROVIDER_RETRY_ATTEMPTS} attempts (default: 2,5,15).`, takesEffect: "The next eligible provider-failure decision; attempt count is the list length." },
-    { key: "provider-retry-max-window-seconds", domain: "runtime", property: "providerRetryMaxWindowSeconds", label: "Provider retry max window", summary: "Positive-integer total retry budget per Run lineage in seconds (default: 600).", takesEffect: "The next retry episode; an active episode keeps its existing deadline." },
     { key: "leader-next-action", domain: "workflow", property: "leaderNextActionMode", label: "Leader next-action mode", summary: "Leader next-action mode: display, warn, or enforce (default: display).", takesEffect: "The next Leader next-action projection or gate." },
     { key: "leader-semantic-budget-turns", domain: "workflow", property: "leaderSemanticBudgetTurns", label: "Leader semantic budget", summary: "Consecutive yielded Leader turns without durable delivery progress before warning, 1-20 (default: 3).", takesEffect: "The next Leader delivery guard evaluation." },
     { key: "context-budget", domain: "workflow", property: "contextBudget", label: "Legacy context budget (inactive)", summary: `Compatibility-only soft and hard values in ${MIN_CONTEXT_BUDGET_TOKENS}-${MAX_CONTEXT_BUDGET_TOKENS}; they are parsed but never control Session or workflow behavior.`, takesEffect: "No runtime effect; Session Token metrics are read-only observations." },

package/dist/config/yuiConfig.js

@@ -1,4 +1,3 @@
-import { supportedAgentAdapterIds } from "../agent/adapterCatalog.js";
 import { DEFAULT_RUN_CAP, DEFAULT_TERMINAL_KEEP, MAX_RUN_CAP } from "../telemetry/telemetryConfig.js";
 import { DEFAULT_RUNTIME_HEALTH_POLICY } from "../runtime/runtimeHealthPolicy.js";
 export const DEFAULT_RECONCILIATION_INTERVAL_SECONDS = 120;
@@ -75,84 +74,6 @@ export function resolveLeaderNextActionMode(value) {
     }
     return normalized;
 }
-// ── Issue 01: Provider retry ──────────────────────────────────────────────
-export const PROVIDER_RETRY_MODES = ["off", "shadow", "enforce"];
-export const DEFAULT_PROVIDER_RETRY_MODE = "enforce";
-export const DEFAULT_PROVIDER_RETRY_DELAYS_SECONDS = Object.freeze([2, 5, 15]);
-export const DEFAULT_PROVIDER_RETRY_MAX_WINDOW_SECONDS = 600;
-export const MAX_PROVIDER_RETRY_ATTEMPTS = 10;
-export function resolveProviderRetryMode(value) {
-    if (value === undefined || value === null)
-        return DEFAULT_PROVIDER_RETRY_MODE;
-    if (typeof value !== "string") {
-        throw new TypeError("providerRetryMode must be off, shadow, or enforce.");
-    }
-    const normalized = value.trim().toLowerCase();
-    if (normalized.length === 0)
-        return DEFAULT_PROVIDER_RETRY_MODE;
-    if (!PROVIDER_RETRY_MODES.includes(normalized)) {
-        throw new TypeError("providerRetryMode must be off, shadow, or enforce.");
-    }
-    return normalized;
-}
-/**
- * Resolves the adapter list. `["all"]` or undefined means every supported
- * adapter; an empty array disables in-place retry.
- */
-export function resolveProviderRetryAdapters(value) {
-    if (value === undefined || value === null) {
-        return [...supportedAgentAdapterIds()];
-    }
-    if (!Array.isArray(value)) {
-        throw new TypeError("providerRetryAdapters must be an array of adapter ids.");
-    }
-    const supported = new Set(supportedAgentAdapterIds());
-    const adapters = [];
-    for (const raw of value) {
-        if (typeof raw !== "string") {
-            throw new TypeError("providerRetryAdapters entries must be strings.");
-        }
-        const token = raw.trim().toLowerCase();
-        if (token === "all") {
-            for (const adapter of supportedAgentAdapterIds()) {
-                if (!adapters.includes(adapter))
-                    adapters.push(adapter);
-            }
-            continue;
-        }
-        if (!/^[a-z0-9][a-z0-9._-]*$/u.test(token)) {
-            throw new TypeError(`Invalid Provider retry adapter: ${token}.`);
-        }
-        if (!supported.has(token)) {
-            throw new TypeError(`Unknown Provider retry adapter: ${token}.`);
-        }
-        if (!adapters.includes(token))
-            adapters.push(token);
-    }
-    return adapters;
-}
-export function resolveProviderRetryDelaysSeconds(value) {
-    if (value === undefined || value === null)
-        return [...DEFAULT_PROVIDER_RETRY_DELAYS_SECONDS];
-    if (!Array.isArray(value) || value.length < 1 || value.length > MAX_PROVIDER_RETRY_ATTEMPTS) {
-        throw new TypeError(`providerRetryDelaysSeconds must contain 1-${MAX_PROVIDER_RETRY_ATTEMPTS} positive integers.`);
-    }
-    const delays = value.map((entry) => {
-        if (typeof entry !== "number" || !Number.isSafeInteger(entry) || entry < 1 || entry > 600) {
-            throw new TypeError("providerRetryDelaysSeconds entries must be integers from 1 to 600.");
-        }
-        return entry;
-    });
-    for (let index = 1; index < delays.length; index += 1) {
-        if (delays[index] < delays[index - 1]) {
-            throw new TypeError("providerRetryDelaysSeconds must be ordered from shortest to longest.");
-        }
-    }
-    return delays;
-}
-export function resolveProviderRetryMaxWindowSeconds(value) {
-    return resolveBoundedPositiveInteger(value, DEFAULT_PROVIDER_RETRY_MAX_WINDOW_SECONDS, 1, Number.MAX_SAFE_INTEGER, "providerRetryMaxWindowSeconds");
-}
 // ── Executable paths ──────────────────────────────────────────────────────
 export function resolveTmuxBin(value) {
     if (value === undefined || value === null)

package/dist/context/sessionBootstrapManifest.js

@@ -1,15 +1,18 @@
 import { createHash } from "node:crypto";
 import { chmodSync, existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { exactControlPlaneDigest, serializeExactDescriptor } from "../runtime/exactControlPlane.js";
+import { exactControlPlaneCommandPrefix, exactControlPlaneDigest, serializeExactDescriptor } from "../runtime/exactControlPlane.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 export { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
-const ORDINARY_SESSION_CLI = [
-    "#!/bin/sh",
-    "exec yui \"$@\"",
-    ""
-].join("\n");
+const ordinarySessionCli = ["#!/bin/sh", "exec yui \"$@\"", ""].join("\n");
+function renderSessionCli(controlPlane) {
+    return [
+        "#!/bin/sh",
+        `exec ${exactControlPlaneCommandPrefix(controlPlane)} \"$@\"`,
+        ""
+    ].join("\n");
+}
 /** Read back one immutable Session Manifest and verify its content digest. */
 export function readSessionBootstrapManifest(path) {
     const source = resolve(path);
@@ -84,10 +87,11 @@ export function materializeSessionBootstrap(input) {
     const controlDigest = exactControlPlaneDigest(input.controlPlane);
     const descriptorPath = resolve(join(home, "runtime", "control-plane", `${controlDigest}.json`));
     writeImmutableText(descriptorPath, `${serializeExactDescriptor(input.controlPlane)}\n`);
-    // Session identity is carried by the immutable Manifest and durable Role/
-    // Run fences. Resolve the ordinary CLI on every invocation so package or
-    // release upgrades do not invalidate a still-current native Session.
-    const sessionCliContent = ORDINARY_SESSION_CLI;
+    // Provider command runners may rebuild PATH independently of the managed
+    // process environment. Keep the Session entry point deterministic; the
+    // existing continuity preflight accepts compatible package replacement at
+    // this path without treating package version as Session identity.
+    const sessionCliContent = renderSessionCli(input.controlPlane);
     const sessionCliDigest = digest(sessionCliContent);
     const sessionCliPath = resolve(join(home, "runtime", "session-cli", `yui-${sessionCliDigest}.sh`));
     writeImmutableText(sessionCliPath, sessionCliContent);
@@ -126,11 +130,11 @@ export function materializeSessionBootstrap(input) {
         roleProfileRef: { digest: profileDigest, path: roleProfilePath },
         contextProtocol: input.owner.scope === "global"
             ? {
-                loadCommand: "yui session context \"$YUI_ROLE\" --json"
+                loadCommand: "\"$YUI_SESSION_CLI\" session context \"$YUI_ROLE\" --json"
             }
             : {
-                loadCommand: "yui task run context \"$YUI_TASK_ID/<run-id>\" --json",
-                expandCommand: "yui task run context expand \"$YUI_TASK_ID/<run-id>\" <ref-id> --store <store> --mode full --json"
+                loadCommand: "\"$YUI_SESSION_CLI\" task run context \"$YUI_TASK_ID/<run-id>\" --json",
+                expandCommand: "\"$YUI_SESSION_CLI\" task run context expand \"$YUI_TASK_ID/<run-id>\" <ref-id> --store <store> --mode full --json"
             }
     };
     const manifest = Object.freeze({ ...body, digest: digest(body) });
@@ -145,14 +149,13 @@ export function materializeSessionBootstrap(input) {
     });
 }
 /**
- * Converts wrappers produced before the protocol-compatible Session CLI to an
- * ordinary `yui` invocation. Only a valid Session Manifest may nominate a
- * wrapper, and only the exact legacy two-line wrapper shape is changed. The
- * Manifest and its frozen descriptor stay immutable and continue to
- * authenticate the Session; repeated refreshes are no-ops.
+ * Retargets known managed wrappers to the current resolved control plane after
+ * a compatible update. Only a valid Session Manifest may nominate a wrapper,
+ * and only Yui's ordinary or exact two-line wrapper shapes are changed.
  */
-export function refreshManagedSessionCliWrappers(homeInput) {
+export function refreshManagedSessionCliWrappers(homeInput, controlPlane) {
     const home = resolve(homeInput);
+    const currentSessionCli = renderSessionCli(controlPlane);
     const manifestDirectory = resolve(join(home, "runtime", "session-manifests"));
     const sessionCliDirectory = resolve(join(home, "runtime", "session-cli"));
     if (!existsSync(manifestDirectory)) {
@@ -189,21 +192,21 @@ export function refreshManagedSessionCliWrappers(homeInput) {
             continue;
         }
         const content = readFileSync(wrapperPath, "utf8");
-        if (content === ORDINARY_SESSION_CLI) {
+        if (content === currentSessionCli) {
             current += 1;
             continue;
         }
-        if (!isLegacyExactSessionCli(content)) {
+        if (content !== ordinarySessionCli && !isExactSessionCli(content)) {
             skipped += 1;
             continue;
         }
-        writeTextFileAtomically(wrapperPath, ORDINARY_SESSION_CLI);
+        writeTextFileAtomically(wrapperPath, currentSessionCli);
         chmodSync(wrapperPath, 0o700);
         refreshed += 1;
     }
     return Object.freeze({ refreshed, current, skipped });
 }
-function isLegacyExactSessionCli(content) {
+function isExactSessionCli(content) {
     return /^#!\/bin\/sh\nexec [^\n]+ '--yui-control' '[a-f0-9]{64}' "\$@"\n$/u.test(content);
 }
 function writeImmutableText(path, content) {

package/dist/controller/clientRuntime.js

@@ -466,11 +466,48 @@ export class FileTaskWorkflowRuntime {
                 throw new Error(`Role runtime did not stop: ${target.taskId}/${target.roleName}.`);
             }
             const session = this.store.getRoleSession(target.taskId, target.roleName);
-            if (session !== null && session.status !== "stopped") {
+            if (session !== null && session.status !== "ended") {
                 throw new Error(`Role runtime session is still active: ${target.taskId}/${target.roleName}.`);
             }
         }
     }
+    /** Stops only the exact idle Session observed by an Agent command. */
+    async stopExactTaskRoleSession(input) {
+        if (this.store.getActiveAgentRun(input.taskId, input.roleName) !== null) {
+            throw new Error(`Role has an active Run: ${input.taskId}/${input.roleName}.`);
+        }
+        const owner = {
+            scope: "task",
+            taskId: input.taskId,
+            roleName: input.roleName
+        };
+        const target = this.schedulerStore.enqueueRuntimeCleanup(owner, new Date(), {
+            owner,
+            agentId: input.agentId,
+            adapterId: input.adapterId,
+            nativeSessionId: input.nativeSessionId,
+            ...(input.launchId === undefined ? {} : { launchId: input.launchId }),
+            sessionUpdatedAt: input.sessionUpdatedAt
+        });
+        if (target === null) {
+            throw new Error(`Role Session changed before its exact stop was reserved: ${input.taskId}/${input.roleName}.`);
+        }
+        await callFileTaskController(this.home, "scheduler.scan", {}, {
+            ...this.clientOptions,
+            requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
+        });
+        if (hasRuntimeLifecycleWork(this.store.getWorkMailbox(target))) {
+            throw new Error(`Role runtime did not stop: ${input.taskId}/${input.roleName}.`);
+        }
+        const session = this.store.getRoleSession(input.taskId, input.roleName);
+        if (session !== null
+            && session.status !== "ended"
+            && session.agentId === input.agentId
+            && session.adapterId === input.adapterId
+            && session.nativeSessionId === input.nativeSessionId) {
+            throw new Error(`Role runtime session is still active: ${input.taskId}/${input.roleName}.`);
+        }
+    }
     /** Wait until every cancellation requested by Task execution stop is physically settled. */
     async stopTaskDurableJobs(taskId) {
         const deadline = Date.now() + LIFECYCLE_REQUEST_TIMEOUT_MS;
@@ -506,7 +543,7 @@ export class FileTaskWorkflowRuntime {
                 + activeJobs.map(({ id }) => id).join(", "));
         }
         const liveSessions = this.store.listRoleSessionSets(taskId).flatMap((sessions) => (Object.values(sessions.sessions)
-            .filter((session) => session.status !== "stopped" && session.status !== "broken")
+            .filter((session) => session.status === "active")
             .map((session) => `${sessions.owner.roleName}/${session.agentId}/${session.status}`)));
         if (liveSessions.length > 0) {
             throw new WorkspaceCleanupBlockedError("physical-resource-live", `task:${taskId}`, true, `Task physical resources are not released: current Role Session state is still live: `
@@ -556,7 +593,7 @@ export class FileTaskWorkflowRuntime {
         }
         const sessions = this.store.getGlobalRoleSessionSet(roleName);
         const active = sessions?.sessions[sessions.activeAgentId];
-        if (active !== undefined && active.status !== "stopped") {
+        if (active !== undefined && active.status !== "ended") {
             throw new Error(`Global Role runtime session is still active: ${roleName}.`);
         }
     }