@zq-silk/yui 0.12.0 → 0.12.1

package/dist/commands/taskRoleRuntimeStatus.js

@@ -9,6 +9,7 @@ import { resolveRuntimeHealth } from "../config/yuiConfig.js";
 import { builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 import { operationalTaskRecords } from "../task/taskRecordRetirement.js";
 import { projectSessionTokenMetrics, resolveSessionTokenIdentity } from "../runtime/sessionTokenMetrics.js";
+import { freshConversationLaunchBlockers, projectConversationSwitch } from "../runtime/conversationSwitch.js";
 export function inspectTaskRoleRuntimeStatuses(taskId, roles, store, panes, now = new Date()) {
     const taskOpenInputRequestCount = store.listInputRequests(taskId)
         .filter((request) => request.status === "open").length;
@@ -93,10 +94,15 @@ export function renderTaskRoleRuntimeStatus(status) {
             ? `needs-attention (${status.stall.kind ?? "workflow-not-progressing"}; no workflow progress since ${status.stall.progressAt ?? "unknown"})`
             : "none"}`,
         `  Native session   ${nativeSession}`,
+        `  Session switch   ${status.conversationSwitch === null
+            ? "none"
+            : `${status.conversationSwitch.status} (${status.conversationSwitch.requestId}; ${status.conversationSwitch.reason})`}`,
         `  Agent runtime    ${runtime}`,
         `  Session tokens   ${sessionTokens}`,
         `  Runtime cleanup  ${status.runtimeCleanupPending ? "pending" : "none"}`,
-        `  Fresh launch     ${status.freshLaunchAllowed ? "allowed" : "blocked"}`,
+        `  Fresh launch     ${status.freshLaunchAllowed
+            ? "allowed"
+            : `blocked (${status.freshLaunchBlockers.join(", ")})`}`,
         `  tmux pane        ${tmux}`,
         `  Workspace        ${status.workspace.managed ? status.workspace.root : status.workspace.path}`,
         ...workspaceDetails
@@ -117,19 +123,30 @@ export function taskRoleLastRunLabel(status) {
 }
 export function taskRoleNativeSessionLabel(status) {
     if (status.runtimeCleanupPending && status.nativeSession === null)
-        return "reset (cleanup-pending)";
+        return "unbound (cleanup-pending)";
     return status.nativeSession?.status ?? "unbound";
 }
 export function inspectTaskRoleSessionRecovery(taskId, roleName, store) {
     const sessions = store.getTaskRoleSessionSet(taskId, roleName);
     const target = runtimeLifecycleTarget({ scope: "task", taskId, roleName });
     const runtimeMailbox = store.getWorkMailbox(target);
+    const roleMailbox = store.getWorkMailbox({ kind: "role", taskId, roleName });
+    const switchBlockers = freshConversationLaunchBlockers({
+        sessions,
+        events: store.listEvents(taskId),
+        mailbox: roleMailbox,
+        roleName
+    });
+    const freshLaunchBlockers = [
+        ...switchBlockers,
+        ...(hasRuntimeLifecycleWork(runtimeMailbox) ? ["runtime-lifecycle-busy"] : [])
+    ];
     return {
         taskId,
         roleName,
         runtimeCleanupPending: hasRuntimeCleanupObligation(runtimeMailbox),
-        freshLaunchAllowed: (sessions === null
-            || sessions.sessions[sessions.activeAgentId] === undefined) && !hasRuntimeLifecycleWork(runtimeMailbox)
+        freshLaunchAllowed: freshLaunchBlockers.length === 0,
+        freshLaunchBlockers
     };
 }
 export function taskRoleOpenInputLabel(status) {
@@ -186,6 +203,7 @@ function inspectTaskRoleRuntimeStatus(taskId, role, store, pane, openInputReques
         ? { managed: false, path: role.workspace }
         : { ...managedWorkspace, managed: true };
     const events = store.listEvents(taskId);
+    const conversationSwitch = projectConversationSwitch(events, role.name, sessions);
     const sessionTokens = projectSessionTokenMetrics(events, resolveSessionTokenIdentity(nativeSession === null
         ? null
         : { taskId, roleName: role.name, ...nativeSession }));
@@ -225,6 +243,7 @@ function inspectTaskRoleRuntimeStatus(taskId, role, store, pane, openInputReques
         tmux,
         workspace,
         sessionTokens,
+        conversationSwitch,
         runtime,
         stall
     };
@@ -243,7 +262,9 @@ function sessionCumulativeTokenLabel(metrics) {
 }
 function latestStallKind(events, runId) {
     const event = [...events]
-        .filter((candidate) => candidate.type === "run.stalled" && candidate.payload.runId === runId)
+        .filter((candidate) => candidate.type === "run.stalled"
+        && candidate.payload.runId === runId
+        && candidate.payload.status !== "diagnostic-only")
         .sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt))[0];
     return event?.payload.kind === "delivery-stalled" || event?.payload.kind === "workflow-not-progressing"
         ? event.payload.kind
@@ -253,7 +274,7 @@ function calculateHealth(role, activeRun, lastRun, nativeSession, runtimeCleanup
     if (runtimeCleanupPending && nativeSession === null) {
         return {
             health: "needs-attention",
-            healthReason: "the native Session was reset; verified runtime cleanup is pending"
+            healthReason: "the native Session is unbound; verified runtime cleanup is pending"
         };
     }
     if (role.status === "failed" || role.status === "exited") {
@@ -315,12 +336,15 @@ function calculateHealth(role, activeRun, lastRun, nativeSession, runtimeCleanup
                 case "broken":
                     return { health: "failed", healthReason: runtime.healthReason };
                 case "stopped":
-                case "diagnostic-needed":
                 case "ready":
                 case "awaiting-provider-acceptance":
                 case "runtime-unobservable":
                 case "starting":
                     return { health: "needs-attention", healthReason: runtime.healthReason };
+                case "diagnostic-needed":
+                    return runtime.observerStatus === "degraded" || runtime.observerStatus === "unavailable"
+                        ? { health: "needs-attention", healthReason: runtime.healthReason }
+                        : { health: "running", healthReason: runtime.healthReason };
                 case "waiting-user":
                     return { health: "blocked-input", healthReason: runtime.healthReason };
                 case "waiting-permission":

package/dist/config/configCatalog.js

@@ -13,7 +13,7 @@ export const CONFIG_DEFINITIONS = Object.freeze([
     { key: "time-zone", domain: "system", property: "timeZone", label: "Time zone", summary: "IANA timezone for human-facing timestamps (default: Asia/Shanghai).", takesEffect: "The next human-readable timestamp rendering; durable JSON remains UTC." },
     { key: "reconciliation-interval-seconds", domain: "runtime", property: "reconciliationIntervalSeconds", label: "Reconciliation interval", summary: "Recovery reconciliation interval, 5-300 seconds (default: 120).", takesEffect: "The running Controller is refreshed after the value is saved." },
     { key: "controller-task-concurrency", domain: "runtime", property: "controllerTaskConcurrency", label: "Controller Task concurrency", summary: "Maximum Tasks reconciled concurrently, 1-32 (default: 4).", takesEffect: "After the Controller restarts." },
-    { key: "runtime-health", domain: "runtime", property: "runtimeHealth", label: "Runtime health thresholds", summary: "Quiet, diagnostic, and semantic-stall thresholds in seconds; values must be strictly increasing (defaults: 300/600/1800).", takesEffect: "CLI and Web projections immediately; scheduler stall handling after the Controller restarts." },
+    { 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." },

package/dist/controller/clientRuntime.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { callController, readControllerDiscovery, stopOrphanedFileTaskController, stopPreviousFileTaskController } from "../core/controllerClient.js";
+import { callController, ControllerClientError, 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";
@@ -14,6 +14,7 @@ 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";
+import { isForeignHandoverLockHeld } from "../release/runtimeRelease.js";
 const STARTUP_TIMEOUT_MS = 5_000;
 const POLL_INTERVAL_MS = 50;
 const ENVIRONMENT_REFRESH_TIMEOUT_MS = 500;
@@ -54,6 +55,7 @@ export async function assertFileTaskControllerStorageCompatible(home, options =
 /** Starts the per-home FileTask Controller on demand and waits until callable. */
 export async function ensureFileTaskController(home, options = {}) {
     const call = options.call ?? callController;
+    await waitForForeignHandover(home, options);
     try {
         const status = await call(home, "controller.status", {});
         assertCompatibleControllerStatus(status, options.expectedVersion);
@@ -63,6 +65,10 @@ export async function ensureFileTaskController(home, options = {}) {
         if (!isUnavailable(error))
             throw error;
     }
+    // A handover may have started after the first lock check and before the
+    // failed discovery/socket call. Re-check before spawning so a managed
+    // Session can never resurrect the old Controller during an update.
+    await waitForForeignHandover(home, options);
     const timeoutMs = positive(options.startupTimeoutMs, STARTUP_TIMEOUT_MS, "startupTimeoutMs");
     const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
     const spawnController = options.spawnController ?? spawnDetachedFileTaskController;
@@ -322,15 +328,22 @@ export async function callFileTaskController(home, method, params = {}, options
                 : { stopped: false, alreadyStopped: true };
         }
     }
+    await waitForForeignHandover(home, options);
     try {
         return await call(home, method, params, {
             timeoutMs: options.requestTimeoutMs
         });
     }
     catch (error) {
-        if (!isUnavailable(error))
+        if (!isUnavailable(error)
+            && !(isControllerDraining(error)
+                && isForeignHandoverLockHeld(home, options.handoverOwnerPid ?? process.pid))) {
             throw error;
+        }
     }
+    // A pre-connect unavailable result is safe to retry. Ambiguous post-send
+    // failures are classified separately by the socket client and surface.
+    await waitForForeignHandover(home, options);
     await ensureFileTaskController(home, options);
     return call(home, method, params, {
         timeoutMs: options.requestTimeoutMs
@@ -631,6 +644,29 @@ function isUnavailable(error) {
     return code === "CONTROLLER_NOT_RUNNING"
         || code === "CONTROLLER_UNAVAILABLE";
 }
+function isControllerDraining(error) {
+    return typeof error === "object"
+        && error !== null
+        && "code" in error
+        && error.code === "CONTROLLER_DRAINING";
+}
+async function waitForForeignHandover(home, options) {
+    const allowedOwnerPid = options.handoverOwnerPid ?? process.pid;
+    if (!Number.isSafeInteger(allowedOwnerPid) || allowedOwnerPid < 1) {
+        throw new TypeError("handoverOwnerPid must be a positive integer");
+    }
+    if (!isForeignHandoverLockHeld(home, allowedOwnerPid))
+        return;
+    const timeoutMs = positive(options.handoverWaitTimeoutMs, LIFECYCLE_REQUEST_TIMEOUT_MS, "handoverWaitTimeoutMs");
+    const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
+    const deadline = Date.now() + timeoutMs;
+    do {
+        await delay(pollMs);
+        if (!isForeignHandoverLockHeld(home, allowedOwnerPid))
+            return;
+    } while (Date.now() < deadline);
+    throw new ControllerClientError("CONTROLLER_HANDOVER_TIMEOUT", `Controller handover did not finish within ${timeoutMs} ms.`);
+}
 function isDefinitelyNotRunning(error) {
     if (typeof error !== "object" || error === null || !("code" in error))
         return false;

package/dist/controller/controller.js

@@ -282,23 +282,27 @@ async function processSelectedRoleRuntimeCleanups(store, delivery, lifecycleHost
                     const reservedLaunchId = isRuntimeLaunchReservation(mailbox.processing)
                         ? mailbox.processing.batchId
                         : undefined;
-                    if (reservedLaunchId !== undefined
-                        && session?.launchId !== undefined
-                        && reservedLaunchId !== session.launchId) {
-                        throw new Error(`Task runtime cleanup launch identity is ambiguous: ${target.taskId}.`);
-                    }
-                    const launchId = reservedLaunchId ?? session?.launchId;
-                    if (launchId !== undefined
-                        && lifecycleHost.cleanupTaskLaunch !== undefined) {
+                    // A failed fresh-Conversation launch can leave two exact resource
+                    // generations: the detached Session's last committed launch and the
+                    // replacement reservation. They are not competing authorities. The
+                    // owner-wide stop has already proven physical zero, so clean both
+                    // exact launch roots idempotently before settling the mailbox.
+                    const launchIds = new Set([
+                        reservedLaunchId,
+                        session?.launchId
+                    ].filter((launchId) => launchId !== undefined));
+                    if (lifecycleHost.cleanupTaskLaunch !== undefined) {
                         const task = store.getTask(target.taskId);
                         const reason = task?.status === "completed"
                             ? "completion"
                             : "interruption";
-                        lifecycleHost.cleanupTaskLaunch({
-                            taskId: target.taskId,
-                            launchId,
-                            reason
-                        });
+                        for (const launchId of launchIds) {
+                            lifecycleHost.cleanupTaskLaunch({
+                                taskId: target.taskId,
+                                launchId,
+                                reason
+                            });
+                        }
                     }
                 }
                 if (store.completeRuntimeCleanup === undefined
@@ -1504,7 +1508,11 @@ export class FileTaskController {
         }
         for (const wakeup of result.wakeups) {
             const key = `role:${encodeURIComponent(wakeup.taskId)}/leader`;
-            if (wakeup.reason === "writer-attached") {
+            if (wakeup.terminalized === true) {
+                settled.add(key);
+                resignal.add(key);
+            }
+            else if (wakeup.reason === "writer-attached") {
                 writerBlocked.add(key);
             }
             else if (wakeup.reason === "not-ready") {
@@ -1690,7 +1698,7 @@ export async function startFileTaskController(home, store, delivery, dispatcher,
         dispatcherServiceTime.started();
         try {
             if (stopping) {
-                throw controllerApplicationError("METHOD_NOT_FOUND", "Controller is stopping.");
+                throw controllerApplicationError("CONTROLLER_DRAINING", "Controller is draining.");
             }
             if (method === "scheduler.signal") {
                 runtime.signal(signalMailboxKey(params));