@zq-silk/yui 0.6.13 → 0.6.14

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -4,13 +4,17 @@ import { activeLiveRoleAgentSession, bindTaskRoleProviderRuntime, bindTaskRoleRu
 import { createProviderRuntimeBinding, endProviderActivation, startProviderActivation, updateProviderConversationRecoverability } from "../runtime/providerRuntimeIdentity.js";
 import { hasRecentTurnId } from "../executor/turnCompletion.js";
 import { createTaskEvent } from "../event/taskEvent.js";
+import { buildTaskWakeEnvelope } from "../context/wakeNotification.js";
+import { createTaskWake, fallbackWakeCursor, latestTaskWake } from "../scheduler/taskWake.js";
+import { rolloverTaskRoleSessionForContextBudget } from "../lifecycle/contextBudgetRollover.js";
+import { resolveContextBudget } from "../config/yuiConfig.js";
 import { answerInputRequest } from "../input/inputRequest.js";
 import { activeRoleAgentBinding, updateRoleStatus } from "../role/role.js";
 import { effectiveLaunchWithTaskMainWorkspace, effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain, resolveEffectiveLaunch, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 import { SYSTEM_OPERATOR_ROLE } from "../role/systemRoles.js";
 import { failAgentRun, markAgentRunDelivered, markAgentRunPushed, reopenRunForProviderRetry, withProviderRetry } from "../run/agentRun.js";
 import { classifyProviderError, isRetryableProviderErrorClass } from "../lifecycle/providerErrorClass.js";
-import { providerRetryIsDue, scheduleProviderRetry } from "../run/providerRetry.js";
+import { providerRetryBudgetExhausted, providerRetryIsDue, scheduleProviderRetry } from "../run/providerRetry.js";
 import { providerRetryConfig } from "../run/providerRetryConfig.js";
 import { terminalizeExactTaskRun } from "../lifecycle/exactRunTerminalization.js";
 import { createCanonicalLifecycleEvent, foldCanonicalLifecycleEvent } from "../lifecycle/canonicalLifecycleEvent.js";
@@ -18,6 +22,7 @@ import { recordLeaderFailure } from "../scheduler/leaderFailure.js";
 import { createLeaderRecoveryNotification, createLeaderStallNotification } from "../scheduler/operatorNotification.js";
 import { pendingWakeupsMatch } from "../scheduler/pendingWakeup.js";
 import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
+import { wakeReason } from "../scheduler/wakeReason.js";
 import { foldRunProgressFacts, latestRunDurableProgressAt, latestRunEventTime, latestStallEvidenceKey, clearMatchingLeaderStallAttention, RUN_PROGRESS_EVENT, RUN_RECOVERED_EVENT, RUN_STALLED_EVENT } from "../scheduler/roleRunStall.js";
 import { projectProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
 import { providerContinuationKey } from "../runtime/providerContinuation.js";
@@ -26,7 +31,7 @@ import { recordExecutionLaneResult } from "../execution/executionGroup.js";
 import { formatAgentRunReceiptId, formatTaskRecordReference } from "../task/taskRecordReference.js";
 import { bindExecution, claimPending, claimInputDelivery as claimMailboxInputDelivery, completeInputDelivery as completeMailboxInputDelivery, completeProcessing, mailboxHasPending, mailboxHasWork, pendingLane, markInputDeliveryPushed as markMailboxInputDeliveryPushed, markInputDeliveryUnknown as markMailboxInputDeliveryUnknown, releaseInputDelivery as releaseMailboxInputDelivery, resolveInputDeliveryNotAccepted as resolveMailboxInputDeliveryNotAccepted, releaseProcessing } from "../coordination/workMailbox.js";
 import { enqueueWork } from "../coordination/workMailboxQueue.js";
-import { RUNTIME_CLEANUP_REQUIRED_REASON, RUNTIME_LAUNCH_RESERVED_REASON, RUNTIME_LIFECYCLE_OWNER, hasRuntimeCleanupObligation, hasRuntimeLifecycleWork, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { RUNTIME_CLEANUP_REQUIRED_REASON, RUNTIME_LAUNCH_RESERVED_REASON, RUNTIME_LIFECYCLE_OWNER, RuntimeLifecycleBusyError, hasRuntimeCleanupObligation, hasRuntimeLifecycleWork, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation, runtimeObservationFenceMatches, runtimeObservationFromTaskEvent, runtimeObservationRunFenceMatches, runtimeObservationTaskEventPayload } from "../runtime/runtimeObservation.js";
@@ -138,6 +143,9 @@ export class FileSchedulerStoreAdapter {
                     launchId: input.fence.launchId,
                     nativeSessionId: input.fence.nativeSessionId,
                     runId: input.fence.runId,
+                    ...(failureEvidence.errorCode === undefined
+                        ? {}
+                        : { errorCode: failureEvidence.errorCode }),
                     error: failureEvidence.code,
                     ...(failureEvidence.details === undefined
                         ? {}
@@ -535,6 +543,35 @@ export class FileSchedulerStoreAdapter {
     getTaskBrief(taskId) { return this.store.getTaskBrief(taskId); }
     listDecisions(taskId) { return this.store.listDecisions(taskId); }
     listMilestones(taskId) { return this.store.listMilestones(taskId); }
+    getTaskWakeEnvelope(taskId) {
+        return this.store.transaction((reader) => {
+            const pending = reader.getPendingWakeup(taskId);
+            if (pending === null)
+                return null;
+            const task = reader.getTask(taskId);
+            if (task === null)
+                return null;
+            const latest = latestTaskWake(reader.listTaskWakes(taskId));
+            const fromCursor = latest?.toCursor ?? fallbackWakeCursor({
+                taskCreatedAt: task.createdAt,
+                leaderRunCreatedAt: reader.listAgentRuns(taskId)
+                    .filter((run) => run.roleName === "leader")
+                    .at(-1)?.createdAt
+            });
+            return buildTaskWakeEnvelope(reader, {
+                taskId,
+                wakeId: reader.peekNextTaskWakeId(taskId),
+                reasons: pending.reasons,
+                fromCursor
+            });
+        });
+    }
+    rolloverTaskRoleSessionForContextBudget(input) {
+        return this.store.transaction((reader) => rolloverTaskRoleSessionForContextBudget(reader, input.taskId, input.roleName, { peakTokens: input.peakTokens, hardTokens: input.hardTokens }, input.now));
+    }
+    getContextBudget() {
+        return resolveContextBudget(this.store.getConfig().contextBudget);
+    }
     listRoles(taskId) {
         return this.store.listRoles(taskId).map((role) => mapRole(this.store, role));
     }
@@ -583,7 +620,7 @@ export class FileSchedulerStoreAdapter {
                 const answered = answerInputRequest(request, { choiceKey }, "agent-timeout", now);
                 store.saveInputRequest(task.id, answered);
                 store.saveEvent(task.id, createTaskEvent(store.nextEventId(task.id), task.id, "input.auto-answered", { requestId: request.id, choiceKey }, now));
-                queueLeaderWakeup(store, task.id, `input-timeout:${request.id}`, now);
+                queueLeaderWakeup(store, task.id, wakeReason("input-timeout", request.id), now);
                 resolved.push({ inputRequestId: request.id, taskId: task.id, choiceKey });
             }
             return resolved;
@@ -684,7 +721,7 @@ export class FileSchedulerStoreAdapter {
                 ]);
             }
             else {
-                queueLeaderWakeup(store, task.id, "role-run-stalled", input.now);
+                queueLeaderWakeup(store, task.id, wakeReason("role-run-stalled"), input.now);
             }
             return "raised";
         });
@@ -809,6 +846,20 @@ export class FileSchedulerStoreAdapter {
     enqueueLeaderWakeup(taskId, reason, now) {
         return this.store.transaction((store) => (queueLeaderWakeup(store, taskId, reason, now)));
     }
+    /**
+     * Records that a Leader wake was suppressed by scheduler single-flight
+     * (the Role runtime lifecycle lane was busy). The wake stays durable and
+     * is retried after the lane settles; this event is the audit trail that
+     * separates scheduler backpressure from real Run failures.
+     */
+    recordWakeSuppression(taskId, reason, now) {
+        this.store.transaction((store) => {
+            const task = store.getTask(taskId);
+            if (task === null)
+                return;
+            store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, "wake.suppressed", { reason }, now));
+        });
+    }
     listActiveDurableJobs() {
         return this.store.listActiveDurableJobs();
     }
@@ -1135,6 +1186,24 @@ export class FileSchedulerStoreAdapter {
             store.saveRole(input.task.id, updateRoleStatus(role, "running", input.now));
             bindTaskRoleRunInFlight(store, role, input.run, input.now);
             store.saveEvent(input.task.id, createTaskEvent(store.nextEventId(input.task.id), input.task.id, "run.dispatched", runLaunchEventPayload(input.run), input.now));
+            if (input.wakeId !== undefined && input.wakeFromCursor !== undefined) {
+                if (store.peekNextTaskWakeId(input.task.id) !== input.wakeId) {
+                    return "state-changed";
+                }
+                const allocatedWakeId = store.nextTaskWakeId(input.task.id);
+                if (allocatedWakeId !== input.wakeId) {
+                    throw new Error(`Leader TaskWake allocation changed unexpectedly: ${input.task.id}.`);
+                }
+                store.saveTaskWake(input.task.id, createTaskWake({
+                    id: allocatedWakeId,
+                    taskId: input.task.id,
+                    reasons: input.wakeup.reasons,
+                    fromCursor: input.wakeFromCursor,
+                    toCursor: input.now.toISOString(),
+                    runId: input.run.id,
+                    now: input.now
+                }));
+            }
             if (input.session !== null && input.session.nativeSessionId !== undefined) {
                 saveTaskSession(store, role, {
                     ...input.session,
@@ -1405,7 +1474,7 @@ export class FileSchedulerStoreAdapter {
                 clearMatchingLeaderStallAttention(store, task.id, currentRun.id);
                 store.saveRole(task.id, updateRoleStatus(role, "exited", input.now));
                 stopTaskSessionIfPresent(store, task.id, role.name, currentRun.effective.agentId, input.now);
-                queueLeaderWakeup(store, task.id, "review-failed", input.now);
+                queueLeaderWakeup(store, task.id, wakeReason("review-failed"), input.now);
                 return "failed";
             }
             const target = { kind: "role", taskId: task.id, roleName: role.name };
@@ -1453,7 +1522,7 @@ export class FileSchedulerStoreAdapter {
             }
             store.saveRole(task.id, updateRoleStatus(role, "exited", input.now));
             stopTaskSessionIfPresent(store, task.id, role.name, currentRun.effective.agentId, input.now);
-            queueLeaderWakeup(store, task.id, role.name === "leader" ? "leader-run-failed" : "role-run-failed", input.now);
+            queueLeaderWakeup(store, task.id, wakeReason(role.name === "leader" ? "leader-run-failed" : "role-run-failed"), input.now);
             return "failed";
         });
     }
@@ -1486,7 +1555,7 @@ export class FileSchedulerStoreAdapter {
             }
             if (existing !== null
                 && (existing.processing !== null || existing.pending !== null)) {
-                throw new Error("Runtime lifecycle work is already pending.");
+                throw new RuntimeLifecycleBusyError("Runtime lifecycle work is already pending.");
             }
             enqueueWork(store, target, RUNTIME_LAUNCH_RESERVED_REASON, now, input.owner.scope === "task"
                 ? [{ type: "task", id: input.owner.taskId }]
@@ -1747,6 +1816,18 @@ export class FileSchedulerStoreAdapter {
                 sessions = rememberRoleAgentCompletedTurn(sessions, input.agentId, input.nativeSessionId, input.turnId, now);
                 store.saveTaskRoleSessionSet(sessions);
                 completeRuntimeHookReservation(store, owner, input.launchId);
+                // The in-flight fence was cleared by an in-place provider retry
+                // decision. If the active Run is still in its retry window and this
+                // completion belongs to it, the recovered CLI finished the original
+                // turn: clear the retry projection so the deadline does not re-push
+                // the prompt. The Run stays active for the normal completion path.
+                const activeRun = store.getActiveAgentRun(task.id, role.name);
+                if (activeRun !== null
+                    && activeRun.providerRetry !== undefined
+                    && input.runId === activeRun.id) {
+                    const { providerRetry: _removed, ...rest } = activeRun;
+                    store.saveAgentRun({ ...rest, updatedAt: now.toISOString() });
+                }
                 return { session: sessions.sessions[input.agentId], duplicate: false };
             }
             // A provider Turn is an activation boundary, not a Yui Run outcome.
@@ -1871,11 +1952,12 @@ export class FileSchedulerStoreAdapter {
      * the Run, or `null` to fall through to the existing terminalization path.
      */
     providerRetryDecision(store, input, summary, now) {
-        const config = providerRetryConfig();
+        const config = providerRetryConfig(this.store.getConfig());
         if (config.mode === "off")
             return null;
         const classification = classifyProviderError({
             adapterId: input.adapterId,
+            ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
             error: input.error,
             errorDetails: input.errorDetails,
             summary: input.lastAssistantMessage
@@ -1890,6 +1972,7 @@ export class FileSchedulerStoreAdapter {
             if (adapterEnabled) {
                 this.recordProviderRetryClassified(store, input, classification.errorClass, {
                     wouldRetry: String(retryable),
+                    basis: classification.basis,
                     shadow: String(shadow)
                 }, now);
             }
@@ -1903,6 +1986,20 @@ export class FileSchedulerStoreAdapter {
         const run = store.getAgentRun(input.taskId, input.runId);
         if (run === null || run.status !== "active")
             return null;
+        // A retry lineage that has used its total budget terminalizes with one
+        // structured failure instead of looping. The Run falls through to the
+        // normal terminalization path below.
+        if (run.providerRetry !== undefined
+            && providerRetryBudgetExhausted(run.providerRetry, now, config.maxWindowMs)) {
+            this.recordProviderRetryClassified(store, input, classification.errorClass, {
+                wouldRetry: "false",
+                shadow: "false",
+                basis: classification.basis,
+                note: "retry-budget-exhausted",
+                attempt: String(run.providerRetry.attempt)
+            }, now);
+            return null;
+        }
         const retry = scheduleProviderRetry(run.providerRetry, {
             errorClass: classification.errorClass,
             launchId: input.launchId,
@@ -1911,9 +2008,9 @@ export class FileSchedulerStoreAdapter {
         }, now);
         store.saveAgentRun(withProviderRetry(run, retry));
         // Clear the in-flight fence so the original Session can be re-bound and
-        // re-pushed by the delivery path; the Session itself stays alive.
         const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
-        if (sessions !== null) {
+        // re-pushed by the delivery path; the Session itself stays alive.
+        if (sessions !== null && sessions.inFlight !== null) {
             store.saveTaskRoleSessionSet(clearTaskRoleRun(sessions, {
                 agentId: input.agentId,
                 runId: input.runId,
@@ -1939,6 +2036,7 @@ export class FileSchedulerStoreAdapter {
         this.recordProviderRetryClassified(store, input, classification.errorClass, {
             wouldRetry: "true",
             shadow: "false",
+            basis: classification.basis,
             attempt: String(retry.attempt),
             nextAttemptAt: retry.nextAttemptAt
         }, now);
@@ -2001,6 +2099,7 @@ export class FileSchedulerStoreAdapter {
             : [...taskIds].sort((left, right) => (left.localeCompare(right, undefined, { numeric: true })));
         const due = this.listPendingProviderRetries(selectedTaskIds).filter((entry) => Date.parse(entry.nextAttemptAt) <= now.getTime());
         const reopened = [];
+        const config = providerRetryConfig(this.store.getConfig());
         for (const entry of due) {
             this.store.transaction((store) => {
                 const run = store.getAgentRun(entry.taskId, entry.runId);
@@ -2013,6 +2112,36 @@ export class FileSchedulerStoreAdapter {
                 }
                 const sessions = store.getTaskRoleSessionSet(entry.taskId, entry.roleName);
                 const session = sessions?.sessions[run.effective.agentId];
+                // Budget exhausted: one structured terminal failure, never a loop.
+                if (providerRetryBudgetExhausted(run.providerRetry, now, config.maxWindowMs)) {
+                    const summary = `Provider retry budget exhausted after ${run.providerRetry.attempt} attempt(s) `
+                        + `(run ${run.id}, error class ${run.providerRetry.errorClass}, `
+                        + `last error: ${run.providerRetry.lastErrorSummary}). `
+                        + `The original Session requires an explicit Leader recovery decision.`;
+                    const result = terminalizeExactTaskRun(store, {
+                        taskId: entry.taskId,
+                        roleName: entry.roleName,
+                        agentId: run.effective.agentId,
+                        runId: run.id,
+                        receiptId: formatAgentRunReceiptId(entry.taskId, run.id),
+                        ...(run.providerRetry.nativeSessionId === undefined
+                            ? {}
+                            : { nativeSessionId: run.providerRetry.nativeSessionId }),
+                        ...(run.providerRetry.launchId === undefined
+                            ? {}
+                            : { launchId: run.providerRetry.launchId }),
+                        outcome: { status: "failed", summary }
+                    }, now);
+                    if (result.disposition !== "applied")
+                        return;
+                    store.saveEvent(entry.taskId, createTaskEvent(store.nextEventId(entry.taskId), entry.taskId, "runtime.provider-retry-budget-exhausted", {
+                        runId: run.id,
+                        attempt: String(run.providerRetry.attempt),
+                        errorClass: run.providerRetry.errorClass
+                    }, now));
+                    enqueueWork(store, { kind: "role", taskId: entry.taskId, roleName: "leader" }, "role-run-failed", now, [{ type: "run", taskId: entry.taskId, id: run.id }]);
+                    return;
+                }
                 const identityMatches = session !== undefined
                     && session.adapterId === run.effective.adapterId
                     && (run.providerRetry.nativeSessionId === undefined
@@ -2022,10 +2151,41 @@ export class FileSchedulerStoreAdapter {
                 const sessionAlive = identityMatches
                     && session.status !== "stopped"
                     && session.status !== "broken";
-                if (!sessionAlive) {
-                    // Session-dead: stop in-place retry and raise a precise, actionable
-                    // replacement blocker for the Leader.
+                if (sessionAlive) {
+                    // The CLI process is still alive. Enter a grace period: let the
+                    // Provider reconnect and finish the turn itself instead of sending
+                    // a duplicate prompt. Reschedule with the next backoff; a late
+                    // completion is attributed to this Run by observeRuntimeTurnCompleted.
+                    const retry = scheduleProviderRetry(run.providerRetry, {
+                        errorClass: run.providerRetry.errorClass,
+                        ...(run.providerRetry.launchId === undefined
+                            ? {}
+                            : { launchId: run.providerRetry.launchId }),
+                        ...(run.providerRetry.nativeSessionId === undefined
+                            ? {}
+                            : { nativeSessionId: run.providerRetry.nativeSessionId }),
+                        lastErrorSummary: run.providerRetry.lastErrorSummary
+                    }, now);
+                    store.saveAgentRun(withProviderRetry(run, retry));
+                    store.saveEvent(entry.taskId, createTaskEvent(store.nextEventId(entry.taskId), entry.taskId, "runtime.provider-retry-waiting", {
+                        runId: run.id,
+                        attempt: String(retry.attempt),
+                        ...(retry.nextAttemptAt === undefined
+                            ? {}
+                            : { nextAttemptAt: retry.nextAttemptAt })
+                    }, now));
+                    return;
+                }
+                // The process is gone. If the adapter supports resume and the
+                // projection carries a native Session id, relaunch with resume: the
+                // conversation identity stays the same, only the launch generation
+                // changes. Otherwise terminalize with a precise replacement blocker.
+                const canResume = run.providerRetry.nativeSessionId !== undefined
+                    && this.drivers.requireByAdapterId(run.effective.adapterId)
+                        .capabilities.control.resume;
+                if (!canResume) {
                     const summary = `Provider retry stopped: the original Session is gone `
+                        + `and the adapter cannot resume it `
                         + `(run ${run.id}, attempt ${run.providerRetry.attempt}, `
                         + `last error: ${run.providerRetry.lastErrorSummary}). `
                         + `A replacement Session requires an explicit Leader recovery decision.`;
@@ -2049,10 +2209,17 @@ export class FileSchedulerStoreAdapter {
                     enqueueWork(store, { kind: "role", taskId: entry.taskId, roleName: "leader" }, "role-run-failed", now, [{ type: "run", taskId: entry.taskId, id: run.id }]);
                     return;
                 }
-                // Reopen the Run on its original Session: reset transport markers,
-                // switch to resume, and mark the projection in-flight. The delivery
-                // pass re-pushes the exact same input in this same pass.
+                // Resume relaunch: reopen the Run in resume mode on the same native
+                // Session. The delivery pass relaunches the process with resume and
+                // re-pushes the exact same input; only the launch generation changes.
                 store.saveAgentRun(reopenRunForProviderRetry(run, now));
+                store.saveEvent(entry.taskId, createTaskEvent(store.nextEventId(entry.taskId), entry.taskId, "runtime.provider-retry-resume", {
+                    runId: run.id,
+                    attempt: String(run.providerRetry.attempt),
+                    ...(run.providerRetry.nativeSessionId === undefined
+                        ? {}
+                        : { nativeSessionId: run.providerRetry.nativeSessionId })
+                }, now));
                 // The retry decision settled the original delivery claim; re-queue the
                 // Role mailbox so the delivery pass can claim and re-push the Run.
                 enqueueWork(store, { kind: "role", taskId: entry.taskId, roleName: entry.roleName }, "provider-retry-repush", now, [{ type: "run", taskId: entry.taskId, id: run.id }]);

package/dist/controller/jobSupervisor.js

@@ -18,6 +18,7 @@ import { fileURLToPath } from "node:url";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { cancelQueuedDurableJob, completeDurableJob, isDurableJobTerminal, markDurableJobUnknown, markDurableJobWakeupNotified, startDurableJob, touchDurableJobHeartbeat } from "../job/durableJob.js";
 import { readLinuxProcessStartIdentity } from "./domainIdentity.js";
+import { wakeReason } from "../scheduler/wakeReason.js";
 const DEFAULT_STEP_TIMEOUT_MS = 30 * 60_000;
 const HEARTBEAT_STALE_MS = 2 * 60_000;
 const SIGKILL_GRACE_MS = 30_000;
@@ -114,7 +115,7 @@ export class DurableJobSupervisor {
             // atomic (same transaction). Compose cancel + wakeupNotified and
             // pass the wakeup param so the adapter enqueues the Leader mailbox
             // entry in the same transaction.
-            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(cancelQueuedDurableJob(current, now), now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(cancelQueuedDurableJob(current, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
             this.#deliverTerminalEvent(terminal);
             return;
         }
@@ -290,7 +291,7 @@ export class DurableJobSupervisor {
         // the adapter enqueues the Leader mailbox entry in the same transaction.
         // A separate #notifyWakeup pass would lose the wakeup if the Controller
         // died between the terminal write and the flag flip.
-        const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, result, now), now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+        const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, result, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
         this.#deliverTerminalEvent(terminal);
         this.#sigkillAt.delete(this.#sigkillKey(job));
     }
@@ -303,12 +304,12 @@ export class DurableJobSupervisor {
             // The runner died without exit.json, but its step checkpoint covered
             // every planned step: the outcome is still provable from durable
             // evidence. No false pass — the checkpoint is the runner's own record.
-            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, { ...proven, evidenceSource: "checkpoint" }, now), now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, { ...proven, evidenceSource: "checkpoint" }, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
             this.#deliverTerminalEvent(terminal);
         }
         else {
             const completedSteps = checkpoint?.completedSteps ?? [];
-            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(markDurableJobUnknown(current, "runner process exited without writing exit.json", completedSteps, now), now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(markDurableJobUnknown(current, "runner process exited without writing exit.json", completedSteps, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
             this.#deliverTerminalEvent(terminal);
         }
         this.#sigkillAt.delete(this.#sigkillKey(job));

package/dist/controller/resourceCleanupLinux.js

@@ -14,7 +14,7 @@ export async function cleanControllerResource(resource, options = {}) {
     }
     assertEphemeralDomainFence(resource);
     const environment = options.environment ?? process.env;
-    const ports = options.ports ?? linuxCleanupPorts(environment);
+    const ports = options.ports ?? linuxCleanupPorts(environment, options.tmuxBin ?? "tmux");
     const cleanup = async () => {
         if (resource.artifact !== undefined) {
             cleanArtifact(resource, ports, environment);
@@ -151,7 +151,7 @@ async function waitForProcesses(resource, ports, graceMs, pollMs) {
         await ports.sleep(Math.min(pollMs, graceMs - elapsed));
     }
 }
-function linuxCleanupPorts(environment) {
+function linuxCleanupPorts(environment, tmuxBin) {
     return {
         processStartIdentity: readProcessStartIdentity,
         signal: (pid, signal) => process.kill(pid, signal),
@@ -169,7 +169,7 @@ function linuxCleanupPorts(environment) {
         socketActive: unixSocketIsActive,
         removeArtifact: (path) => unlinkSync(path),
         inspectTmuxServerPanes: async (resource) => {
-            const manager = tmuxManagerForResource(resource, environment);
+            const manager = tmuxManagerForResource(resource, environment, tmuxBin);
             return manager.inspectRolePaneInventory().map((pane) => (`${pane.taskId}/${pane.roleName}`));
         },
         killPane: async (resource) => {
@@ -177,7 +177,7 @@ function linuxCleanupPorts(environment) {
             if (target === undefined) {
                 throw new Error(`Role pane identity is unavailable: ${resource.id}.`);
             }
-            const manager = tmuxManagerForResource(resource, environment);
+            const manager = tmuxManagerForResource(resource, environment, tmuxBin);
             const pane = manager.inspectRolePaneInventory().find((candidate) => (candidate.target === target));
             if (pane === undefined)
                 return;
@@ -200,14 +200,14 @@ function linuxCleanupPorts(environment) {
         }
     };
 }
-function tmuxManagerForResource(resource, environment) {
+function tmuxManagerForResource(resource, environment, tmuxBin) {
     const home = resource.yuiHome;
     if (home === undefined) {
         throw new Error(`Tmux resource home is unavailable: ${resource.id}.`);
     }
     const executor = new NodeCommandExecutor();
     const commandEnvironment = tmuxSocketEnvironment(environment);
-    return new TmuxManager(environment.YUI_TMUX_BIN ?? "tmux", {
+    return new TmuxManager(tmuxBin, {
         run: (command, args, options) => executor.run(command, args, {
             ...options,
             environment: {

package/dist/controller/resourceInventoryLinux.js

@@ -53,7 +53,7 @@ export async function scanControllerResourceInventory(options) {
         const panes = options.panes !== undefined
             ? options.panes
             : tmuxArtifact?.active === true
-                ? inspectHomePanes(home, environment, warnings)
+                ? inspectHomePanes(home, environment, options.tmuxBin ?? "tmux", warnings)
                 : [];
         const discovery = await inspectDiscovery(home, matchingProcesses, activeSockets);
         if (discovery.status === "valid"
@@ -726,11 +726,11 @@ function loadHomeState(home, warnings, options) {
 function numericCompare(left, right) {
     return left.localeCompare(right, undefined, { numeric: true });
 }
-function inspectHomePanes(home, environment, warnings) {
+function inspectHomePanes(home, environment, tmuxBin, warnings) {
     try {
         const executor = new NodeCommandExecutor();
         const commandEnvironment = tmuxSocketEnvironment(environment);
-        return new TmuxManager(environment.YUI_TMUX_BIN ?? "tmux", {
+        return new TmuxManager(tmuxBin, {
             run: (command, args, options) => executor.run(command, args, {
                 ...options,
                 environment: {

package/dist/controller/runtime.js

@@ -1,4 +1,4 @@
-import { reconciliationIntervalMilliseconds } from "../config/yuiConfig.js";
+import { reconciliationIntervalMilliseconds, resolveTmuxBin } from "../config/yuiConfig.js";
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -7,7 +7,8 @@ import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, YUI_M
 import { hasRuntimeCleanupObligation, runtimeLifecycleSignalKey, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { agentProcessReadinessProbe, ExecutorRegistry } from "../executor/executorRegistry.js";
 import { activeLiveRoleAgentSession, roleAgentSessionResumeMode } from "../executor/agentExecutor.js";
-import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain, resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
+import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain, effectiveLaunchConfig, resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
+import { AgentConfigurationCatalogService, validateAgentLaunchConfiguration } from "../executor/agentConfigurationCatalog.js";
 import { isTaskOwnedWorkspace, managedWorkspaceIdentity, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { FileRoleLaunchPlanner } from "../executor/fileRoleLaunchPlanner.js";
 import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
@@ -100,13 +101,13 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         ? new ResourceInventoryClient()
         : undefined;
     const schedulerStore = options.schedulerStore
-        ?? new FileSchedulerStoreAdapter(store, openSchedulerTelemetry(home, options.environment ?? process.env));
+        ?? new FileSchedulerStoreAdapter(store, openSchedulerTelemetry(home, store.getConfig()));
     const domainIdentity = options.domainIdentity
         ?? ephemeralDomainFromEnvironment(options.environment ?? process.env);
     const planner = options.planner ?? new FileRoleLaunchPlanner(home, store, {
         environment: options.environment
     });
-    const tmux = options.tmux ?? new TmuxManager(options.environment?.YUI_TMUX_BIN ?? process.env.YUI_TMUX_BIN ?? "tmux", new NodeCommandExecutor(), {
+    const tmux = options.tmux ?? new TmuxManager(resolveTmuxBin(store.getConfig().tmuxBin), new NodeCommandExecutor(), {
         yuiHome: home,
         ...(domainIdentity === undefined
             ? {}
@@ -125,7 +126,57 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         tmux,
         onWarning: options.onError
     });
+    // The runtime inbox is also the low-latency discovery source during a
+    // scheduler-owned launch. Waiting only for the post-pass durable projection
+    // would deadlock behind the same pass that is currently starting the host.
+    const runtimeEventInbox = new FileRuntimeEventInbox(home);
+    const catalogs = options.catalogs
+        ?? new AgentConfigurationCatalogService(home, {
+            environment: options.environment ?? process.env
+        });
     const sessionHost = options.sessionHost ?? new TmuxSessionHost(planner, tmux, {
+        validateLaunch: async (request) => {
+            const agent = store.getConfiguredAgent(request.agentId);
+            if (agent === null)
+                return;
+            const resolved = await catalogs.resolve({
+                agent,
+                cwd: request.workspace,
+                config: effectiveLaunchConfig(request.effective)
+            });
+            validateAgentLaunchConfiguration(resolved.catalog, effectiveLaunchConfig(request.effective));
+        },
+        waitForNativeSession: async (request, signal) => {
+            const owner = request.owner;
+            if (owner.scope !== "task") {
+                throw new Error("Native session discovery requires a Task runtime owner.");
+            }
+            while (!signal.aborted) {
+                const session = schedulerStore.getRoleSession(owner.taskId, owner.roleName, request.agentId);
+                if (session !== null
+                    && session.launchId === request.launchId
+                    && typeof session.nativeSessionId === "string"
+                    && session.nativeSessionId.trim().length > 0) {
+                    return session.nativeSessionId;
+                }
+                for (const event of runtimeEventInbox.list()) {
+                    if (event.type === "runtime-observation"
+                        && event.observation.kind === "session.started"
+                        && event.observation.fence.taskId === owner.taskId
+                        && event.observation.fence.roleName === owner.roleName
+                        && event.observation.fence.agentId === request.agentId
+                        && event.observation.fence.launchId === request.launchId
+                        && typeof event.observation.fence.nativeSessionId === "string"
+                        && event.observation.fence.nativeSessionId.trim().length > 0) {
+                        return event.observation.fence.nativeSessionId;
+                    }
+                }
+                await abortableDelay(50, signal);
+            }
+            throw new Error("Native session discovery was aborted.");
+        },
+        inactivityTimeoutMs: positiveIntegerOption(options.environment?.YUI_LAUNCH_INACTIVITY_TIMEOUT_MS
+            ?? process.env.YUI_LAUNCH_INACTIVITY_TIMEOUT_MS, 300_000),
         onHostCreated: ({ binding, pane }) => {
             sessionOwners.recordHostOwner({
                 owner: binding.owner,
@@ -216,6 +267,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             currentHome: home,
             scope: "current",
             panes,
+            tmuxBin: resolveTmuxBin(store.getConfig().tmuxBin),
             ...(options.environment === undefined
                 ? {}
                 : { environment: options.environment })
@@ -304,6 +356,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
                 // explicit `controller cleanup --all` inventory operation.
                 scope: "current",
                 environment: options.environment,
+                tmuxBin: resolveTmuxBin(store.getConfig().tmuxBin),
                 // When the worker backend is active, the reaper's scan runs in the
                 // inventory worker too (same cadence, same inventory shape).
                 ...(inventoryClient === undefined
@@ -328,12 +381,11 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             environment: options.environment
         });
     const lifecycleDispatcher = createRuntimeLifecycleDispatcher(store, schedulerStore, sessionHost, options.dispatcher, signalRuntimeCleanup, launchCoordinator, planner);
-    // f7/rr5: Share one inbox between the supervisor's terminal channel and
-    // the runtime event processor. When a Job reaches a terminal state, the
-    // supervisor enqueues a durable-job-terminal event; the processor drains
-    // it on the next pass, waking the Controller immediately instead of
-    // waiting for the poll interval.
-    const runtimeEventInbox = new FileRuntimeEventInbox(home);
+    // f7/rr5: This same inbox feeds the supervisor's terminal channel and the
+    // runtime event processor. When a Job reaches a terminal state, the
+    // supervisor enqueues a durable-job-terminal event; the processor drains it
+    // on the next pass, waking the Controller immediately instead of waiting for
+    // the poll interval.
     const jobSupervisor = new DurableJobSupervisor({
         store: schedulerStore,
         process: createLinuxProcessPort(),
@@ -874,6 +926,32 @@ function requiredParam(value) {
     }
     return value;
 }
+function abortableDelay(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, milliseconds);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("Native session discovery was aborted."));
+        };
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function positiveIntegerOption(value, fallback) {
+    if (value === undefined || value.trim().length === 0)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new Error(`Invalid native session discovery timeout: ${value}`);
+    }
+    return parsed;
+}
 function applicationError(code, message) {
     const error = Object.assign(new Error(message), { code });
     error.name = "CoreApplicationError";