@zq-silk/yui 2.16.0 → 2.18.0

package/dist/commands/roleConfiguration.js

@@ -1,4 +1,5 @@
 import { usageError } from "../errors/cliError.js";
+import { parseEnabled } from "../role/availability.js";
 import { defaultRoleAgentConfig, resolveAgentAdapter } from "../executor/agentAdapter.js";
 const PROFILE_OPTIONS = [
     ["--description", "value"],
@@ -64,6 +65,7 @@ export function roleOptionSpecs(input) {
         ...(input.includeAgent === true ? [["--agent", "value"]] : []),
         ...(input.includeWorkspace === true ? [["--workspace", "value"]] : []),
         ...(input.update ? [["--yes", "flag"]] : []),
+        ...(input.update ? [["--enabled", "value"]] : []),
         ...PROFILE_OPTIONS,
         ...agentValueOptions,
         ...agentRepeatableOptions,
@@ -123,6 +125,7 @@ export function roleProfilePatch(parsed) {
         ["--skill", "--clear-skills"]
     ]);
     return {
+        ...(parsed.has("--enabled") ? { enabled: parseEnabled(parsed.one("--enabled")) } : {}),
         ...(parsed.has("--description") ? { description: requiredText(parsed.one("--description")) } : {}),
         ...(parsed.has("--clear-description") ? { description: undefined } : {}),
         ...(parsed.has("--responsibility")

package/dist/commands/taskCommands.js

@@ -3,6 +3,7 @@ import { isDeepStrictEqual } from "node:util";
 import { taskMessageInboxReceipt } from "../message/taskInboxOwnership.js";
 import { agentExecutionComponentLabel } from "../agent/executionComponents.js";
 import { assertLeaderArchiveAdmission } from "../task/leaderArchiveAuthority.js";
+import { assertRoleEnabled, isEnabled } from "../role/availability.js";
 import { createRun, runExecutionObservation, runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { isGitArtifactRefString, parseGitArtifactRef } from "../artifacts/gitArtifactRef.js";
 import { contextContentDigest, contextSnapshotRef } from "../context/contextSnapshot.js";
@@ -2251,6 +2252,11 @@ function taskRoleCommand(args, store, options) {
         return showTaskRole(rest, store);
     if (command === "update")
         return updateTaskRole(rest, store, options);
+    if (command === "enable" || command === "disable") {
+        if (rest.length !== 2)
+            throw usageError(`Usage: yui task role ${command} <task> <role>`);
+        return updateTaskRole([...rest, "--enabled", String(command === "enable")], store, options);
+    }
     if (command === "remove")
         return output(removeTaskRole(rest, store, options));
     if (command === "bind")
@@ -2751,6 +2757,7 @@ function listTaskRoles(args, store, options) {
     const statuses = inspectTaskRoleRuntimeStatuses(task.id, roles, store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? [], options.now?.() ?? new Date());
     const data = recordPage(statuses.map(status => ({
         roleName: status.roleName, agentId: status.agentId, recordedHealth: status.health,
+        enabled: isEnabled(status.role),
         hostObservation: "not-requested",
         openInput: taskRoleOpenInputLabel(status), activeWork: taskRoleActiveWorkLabel(status),
         lastRun: taskRoleLastRunLabel(status), nativeSession: taskRoleNativeSessionLabel(status),
@@ -2810,6 +2817,9 @@ function updateTaskRole(args, store, options) {
         taskActor(tx, options, task.id);
         const role = requireRole(tx, task.id, roleName);
         const changesEnvironment = parsed.has("--environment") || parsed.has("--managed-environment");
+        if (parsed.seen.size === 1 && parsed.has("--enabled")
+            && isEnabled(role) === roleProfilePatch(parsed).enabled)
+            return role;
         const changesLaunchContext = hasRoleLaunchContextOptions(parsed) || parsed.has("--profile")
             || changesEnvironment;
         const changesAgentConfig = hasAgentConfigOptions(parsed);
@@ -3562,6 +3572,7 @@ function dispatchWork(args, store, options) {
         }
         const roles = lanePlan.roles.map((name) => requireRole(tx, task.id, name));
         for (const role of roles) {
+            assertRoleEnabled(role);
             if (tx.getActiveRun(task.id, role.name) !== null) {
                 throw usageError(`${task.id}/${role.name} already has an active run.`);
             }
@@ -3570,6 +3581,7 @@ function dispatchWork(args, store, options) {
         let workItemForDispatch = prepareWorkItemDispatch(item, now);
         if (lanePlan.roles.length === 0) {
             const role = requireRole(tx, task.id, assignee);
+            assertRoleEnabled(role);
             if (tx.getActiveRun(task.id, role.name) !== null) {
                 throw usageError(`${task.id}/${role.name} already has an active run.`);
             }
@@ -4383,6 +4395,9 @@ function assertTaskReviewRequestLane(store, taskId, reviewerRoleName, reusableRo
     assertReviewerAvailable(store, taskId, reviewerRoleName, reusableRound);
 }
 function assertReviewerAvailable(store, taskId, reviewerRoleName, reusableRound) {
+    const role = store.getRole(taskId, reviewerRoleName);
+    if (role !== null)
+        assertRoleEnabled(role);
     const availability = projectReviewerAvailability(store, taskId, reviewerRoleName);
     if (availability.kind === "available")
         return;
@@ -5001,6 +5016,7 @@ function retryRunOperation(args, store, options) {
             throw usageError(`Task does not admit ${previous.purpose} retry: ${task.id}/${task.status}.`);
         }
         const role = requireRole(tx, task.id, previous.roleName);
+        assertRoleEnabled(role);
         if (tx.getActiveRun(task.id, role.name) !== null) {
             throw usageError(`${task.id}/${role.name} already has an active run.`);
         }

package/dist/commands/taskRoleRuntimeStatus.js

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { runExecutionObservation } from "../agentRun/agentRun.js";
+import { isEnabled, roleDisabledReason } from "../role/availability.js";
 import { hasRuntimeCleanupObligation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { currentProviderConversation, managedProviderTurnId } from "../runtime/providerRuntimeIdentity.js";
 import { isRoleRunStalled, latestStallProgressAt } from "../scheduler/roleRunStall.js";
@@ -118,6 +119,8 @@ export function renderTaskRoleRuntimeStatus(status) {
         `Task Role status: ${status.taskId}/${status.roleName}`,
         "",
         `  Health           ${status.health}`,
+        `  Enabled          ${isEnabled(status.role)}`,
+        ...(!isEnabled(status.role) ? [`  Availability     ${roleDisabledReason(status.role)}`] : []),
         `  Reason           ${status.healthReason}`,
         `  Open inputs      ${status.openInputRequestCount}`,
         `  Agent            ${status.agentId}`,

package/dist/controlPlaneCli.js

@@ -532,8 +532,9 @@ export async function main() {
                 const result = await callController(home, "controller.status", {}, { timeoutMs: 2_000 });
                 runtime = parseControllerRuntimeSnapshot(result, droppedEvents);
             }
-            catch {
-                runtime = { source: "unsupported", droppedEvents };
+            catch (error) {
+                runtime = { source: "unsupported", droppedEvents,
+                    error: describeCliFailure(error, failureContext()).message.slice(0, 1000) };
             }
             const mismatch = summarizeDurablePhysicalMismatch(snapshot);
             const identitySection = renderRuntimeIdentitySection({
@@ -2611,6 +2612,7 @@ async function executeOperatorSessionControl(control, home, store, runtime, tmux
     }
     await prepareInteractiveCodexApp(control.targetAgentId, store, home);
     await ensureFileTaskController(home, { environment: process.env });
+    let stopDisposition = "not-required";
     if (paneRunning
         || (active !== undefined
             && active.status === "active")
@@ -2618,9 +2620,24 @@ async function executeOperatorSessionControl(control, home, store, runtime, tmux
             && ["submitting", "accepted", "delivery-unknown"].includes(sessionSet.providerBinding.run.status))
         || (sessionSet?.providerBinding?.goal != null && sessionSet.providerBinding.goal.status !== "complete")) {
         await runtime.stopGlobalRoleSession(role.name);
+        stopDisposition = "completed";
+    }
+    try {
+        applyOperatorSessionControl(control, store);
+    }
+    catch (error) {
+        throw new Error(`Operator replacement selection failed; prior stop=${stopDisposition}; `
+            + "new Session startup has not begun. Inspect the retained Session state.", { cause: error });
+    }
+    try {
+        await runtime.prepareGlobalRoleEnter(role.name);
+    }
+    catch (error) {
+        throw new Error(`Operator replacement selection committed; prior stop=${stopDisposition}; its startup phase failed `
+            + "without readiness confirmation. Whether native startup began is unconfirmed. "
+            + "Inspect the exact current Session/Host before retrying; "
+            + "do not infer that startup had no effect.", { cause: error });
     }
-    applyOperatorSessionControl(control, store);
-    await runtime.prepareGlobalRoleEnter(role.name);
     tmux.attachRole("operator", role.name, "auto");
 }
 async function prepareInteractiveCodexApp(agentId, store, home) {

package/dist/controller/agentJobControl.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { assertRoleEnabled } from "../role/availability.js";
 import { mkdirSync } from "node:fs";
 import { isDeepStrictEqual } from "node:util";
 import { join } from "node:path";
@@ -63,7 +64,8 @@ function requireTaskTarget(store, target, runnable = true) {
     const task = store.getTask(target.taskId);
     if (!task || runnable && (task.status !== "active" || task.executionGate.state !== "enabled"))
         throw new Error("Task Agent requires an active, execution-enabled Task.");
-    if (!store.getRole(target.taskId, target.roleName))
+    const role = store.getRole(target.taskId, target.roleName);
+    if (!role)
         throw new Error("Task Agent Role is unavailable.");
     const recipient = taskRecipient(store, target);
     if (recipient.ownerRunId) {
@@ -117,6 +119,7 @@ function ownedRole(store, home, job, runId, now) {
     const jobOwner = { scope: job.scope, jobId: job.id, ...(isolated ? { runId } : {}) };
     const existing = store.getGlobalRole(name);
     if (existing) {
+        assertRoleEnabled(existing);
         if (!isDeepStrictEqual(existing.jobOwner, jobOwner) || existing.activeAgentId !== job.configuration.target.agentId) {
             throw new Error("Job Role binding changed; inspect its Session/configuration before dispatch.");
         }
@@ -155,6 +158,9 @@ function queueAttempt(store, home, job, runId, index, now) {
     const inputControl = { action: "queue", requestId: `job-agent:${runId}:${index}` };
     let messageId;
     if (recipient.scope === "global") {
+        const role = store.getGlobalRole(recipient.roleName);
+        if (role !== null)
+            assertRoleEnabled(role);
         messageId = store.nextGlobalRoleMessageId();
         let message = createGlobalRoleMessage(messageId, recipient.roleName, body, "system", { type: "system" }, now, { inputControl });
         const set = store.getGlobalRoleSessionSet(recipient.roleName);
@@ -165,6 +171,7 @@ function queueAttempt(store, home, job, runId, index, now) {
     }
     else {
         requireTaskTarget(store, { ...recipient });
+        assertRoleEnabled(store.getRole(recipient.taskId, recipient.roleName));
         const resolved = taskRecipient(store, recipient);
         messageId = store.nextMessageId(recipient.taskId);
         store.saveMessage(recipient.taskId, createTaskMessage(messageId, recipient.taskId, body, "system", { type: "system" }, now, { ...(resolved.ownerRunId ? { recipient: resolved } : {}), inputControl }));
@@ -256,6 +263,7 @@ export function controlAgentJob(store, home, job, input, now) {
         if (op === "session-new") {
             if (!role)
                 throw new Error("Create the Job Role first.");
+            assertRoleEnabled(role);
             assertRoleRuntimeMutationAllowed(store, { scope: "global", roleName }, "Job Session replacement");
             const set = store.getGlobalRoleSessionSet(roleName);
             const old = set?.sessions[set.activeAgentId];

package/dist/controller/clientRuntime.js

@@ -456,10 +456,7 @@ export class FileTaskWorkflowRuntime {
         }
         if (targets.length === 0)
             return;
-        await callFileTaskController(this.home, "scheduler.scan", {}, {
-            ...this.clientOptions,
-            requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
-        });
+        await Promise.all(targets.map(target => this.#waitForRuntimeCleanup(target)));
         for (const target of targets) {
             if (hasRuntimeLifecycleWork(this.store.getWorkMailbox(target))) {
                 throw new Error(`Role runtime did not stop: ${target.taskId}/${target.roleName}.`);
@@ -487,10 +484,7 @@ export class FileTaskWorkflowRuntime {
         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
-        });
+        await this.#waitForRuntimeCleanup(target);
         if (hasRuntimeLifecycleWork(this.store.getWorkMailbox(target))) {
             throw new Error(`Role runtime did not stop: ${input.taskId}/${input.roleName}.`);
         }
@@ -506,7 +500,7 @@ export class FileTaskWorkflowRuntime {
                 .filter((job) => job.taskId === taskId);
             if (active.length === 0)
                 return;
-            await callFileTaskController(this.home, "scheduler.scan", {}, {
+            await callFileTaskController(this.home, "scheduler.signal", { key: `task:${encodeURIComponent(taskId)}` }, {
                 ...this.clientOptions,
                 requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
             });
@@ -585,10 +579,7 @@ export class FileTaskWorkflowRuntime {
         if (target?.kind !== "global-role-runtime") {
             throw new Error(`Global Role runtime cleanup target is invalid: ${roleName}.`);
         }
-        await callFileTaskController(this.home, "scheduler.scan", {}, {
-            ...this.clientOptions,
-            requestTimeoutMs: LIFECYCLE_REQUEST_TIMEOUT_MS
-        });
+        await this.#waitForRuntimeCleanup(target);
         if (hasRuntimeLifecycleWork(this.store.getWorkMailbox(target))) {
             throw new Error(`Global Role runtime did not stop: ${roleName}.`);
         }
@@ -598,6 +589,36 @@ export class FileTaskWorkflowRuntime {
             throw new Error(`Global Role runtime session is still active: ${roleName}.`);
         }
     }
+    /**
+     * The durable cleanup mailbox is completed only after stopOwner proves
+     * quiescence and commits the existing cleanup transaction. A scheduler hint
+     * is not that proof; nor is exhaustion of the Home-wide coalescing loop.
+     */
+    async #waitForRuntimeCleanup(target) {
+        const timeoutMs = this.clientOptions.requestTimeoutMs ?? LIFECYCLE_REQUEST_TIMEOUT_MS;
+        const deadline = Date.now() + timeoutMs;
+        const label = controllerMailboxKey(target);
+        try {
+            await callFileTaskController(this.home, "scheduler.signal", { key: label }, {
+                ...this.clientOptions, requestTimeoutMs: timeoutMs
+            });
+            while (hasRuntimeLifecycleWork(this.store.getWorkMailbox(target))) {
+                if (Date.now() >= deadline) {
+                    throw new Error("Timed out awaiting the target's durable cleanup transaction.");
+                }
+                await new Promise(resolve => setTimeout(resolve, Math.min(this.clientOptions.pollIntervalMs ?? POLL_INTERVAL_MS, Math.max(1, deadline - Date.now()))));
+            }
+        }
+        catch (error) {
+            // A lost hint response must not hide cleanup that actually committed.
+            // No hint or native input is replayed here.
+            if (!hasRuntimeLifecycleWork(this.store.getWorkMailbox(target)))
+                return;
+            throw new Error(`Runtime stop remains unconfirmed for ${label}; cleanup obligation retained. `
+                + "No replacement was started by this stop operation. Inspect the exact Session/Host "
+                + "and cleanup failure before retrying; no physical exit is inferred.", { cause: error });
+        }
+    }
     /** Drain pending runtime facts while an external maintenance fence is held. */
     async drainController() {
         await ensureFileTaskController(this.home, {

package/dist/controller/controller.js

@@ -7,7 +7,7 @@ import { reconcileExitedRoleRuns } from "../scheduler/roleRunLiveness.js";
 import { DEFAULT_STALL_WINDOW_MS, DEFAULT_WORKFLOW_STALL_CANDIDATE_AGE_MS, reconcileStalledRoleRuns } from "../scheduler/roleRunStall.js";
 import { processOperatorInputNotifications } from "../scheduler/operatorInputNotificationProcessor.js";
 import { startControllerServer } from "../core/controllerServer.js";
-import { monotonicMilliseconds } from "../core/controllerTelemetry.js";
+import { ControllerWorkObserver, monotonicMilliseconds } from "../core/controllerTelemetry.js";
 import { isProjectMaintenanceFenced } from "../repository/projectMaintenanceLock.js";
 import { isHandoverLockHeld } from "../release/runtimeRelease.js";
 import { KeyedWorkQueue } from "../coordination/keyedWorkQueue.js";
@@ -44,7 +44,9 @@ const ZERO_DRAIN_METRICS = Object.freeze({
  * Runs one lean scheduler pass. Due native Turn completions are folded before
  * liveness, so a valid Hook boundary fences destructive process reconciliation.
  */
-export async function runControllerSchedulerPass(store, delivery, now, workspacePreparer, scope = { kind: "full" }, includeOperator = true, runtimeCleanupOutcomes = [], lifecycleHost, stallWindowMs = DEFAULT_STALL_WINDOW_MS, maintenanceFence, onMaintenanceFenceDefer, blockedTaskIds = new Set(), diagnosticAfterMs = DEFAULT_WORKFLOW_STALL_CANDIDATE_AGE_MS, leaderWakeFence, onError) {
+export async function runControllerSchedulerPass(store, delivery, now, workspacePreparer, scope = { kind: "full" }, includeOperator = true, runtimeCleanupOutcomes = [], lifecycleHost, stallWindowMs = DEFAULT_STALL_WINDOW_MS, maintenanceFence, onMaintenanceFenceDefer, blockedTaskIds = new Set(), diagnosticAfterMs = DEFAULT_WORKFLOW_STALL_CANDIDATE_AGE_MS, leaderWakeFence, onError, observer) {
+    const target = scope.kind === "full" ? "home" : scope.keys.slice(0, 16).join(",");
+    const observe = (phase, action) => observer === undefined ? Promise.resolve().then(action) : observer.observe(phase, target, action);
     const compiledSelection = compileReconcileSelection(scope);
     const selection = includeOperator
         ? { ...compiledSelection, blockedTaskIds }
@@ -54,7 +56,7 @@ export async function runControllerSchedulerPass(store, delivery, now, workspace
     // event-loop turn. Give already-written requests a poll boundary before the
     // next durable phase; later phases retain their existing CAS fences.
     await controlEventLoopRun();
-    const failedCleanupRoles = await processSelectedRoleRuntimeCleanups(store, delivery, lifecycleHost, scope, now, runtimeCleanupOutcomes, blockedTaskIds);
+    const failedCleanupRoles = await observe("runtime-cleanup", () => processSelectedRoleRuntimeCleanups(store, delivery, lifecycleHost, scope, now, runtimeCleanupOutcomes, blockedTaskIds));
     const roleSelection = selectionWithoutFailedCleanupRoles(store, selection, failedCleanupRoles);
     const availableWakeupSelection = () => (leaderWakeFence?.() === true
         ? exactTaskSelection(new Set())
@@ -64,19 +66,19 @@ export async function runControllerSchedulerPass(store, delivery, now, workspace
         // Durable Leader work that already has a ready Task workspace belongs to
         // the control path. Dispatch it before any unrelated Task workspace I/O;
         // the processor itself retains the fail-closed workspace-ready guard.
-        const initialWakeups = selectedPendingWakeups(store, availableWakeupSelection());
-        const initialWakeupResults = await processLeaderWakeups(store, delivery, now, exactTaskSelection(new Set(initialWakeups.keys())));
+        const initialWakeups = await observe("wakeup-projection", () => selectedPendingWakeups(store, availableWakeupSelection()));
+        const initialWakeupResults = await observe("leader-delivery", () => processLeaderWakeups(store, delivery, now, exactTaskSelection(new Set(initialWakeups.keys()))));
         // Preserve ready-Leader-first ordering, then bound the repeated state
         // projections that follow it in this pass.
         await controlEventLoopRun();
         // A Task whose deferred activation was just released must become active
         // before the workspace phase, so its first workspace preparation happens in
         // this same pass rather than waiting for the next one.
-        await adoptReleasedTaskActivations(store, workspacePreparer, selection, onError);
+        await observe("activation", () => adoptReleasedTaskActivations(store, workspacePreparer, selection, onError));
         await controlEventLoopRun();
-        const workspacePreparation = await prepareActiveWorkspaces(store, workspacePreparer, selection, maintenanceFence, onMaintenanceFenceDefer);
+        const workspacePreparation = await observe("workspace-preparation", () => prepareActiveWorkspaces(store, workspacePreparer, selection, maintenanceFence, onMaintenanceFenceDefer));
         await controlEventLoopRun();
-        const activeRunDeliveries = await processActiveRoleRunDeliveries(store, delivery, now, roleSelection);
+        const activeRunDeliveries = await observe("run-delivery", () => processActiveRoleRunDeliveries(store, delivery, now, roleSelection));
         await controlEventLoopRun();
         const unsettledRunRefs = new Set(activeRunDeliveries.flatMap((result) => (result.reason === "delivery-uncertain"
             ? [formatTaskRecordReference(result.taskId, result.runId, "run")]
@@ -108,16 +110,16 @@ export async function runControllerSchedulerPass(store, delivery, now, workspace
         await controlEventLoopRun();
         const liveStatuses = new Map();
         const resourceEvidence = new Map();
-        const failedRunRefs = await reconcileExitedRoleRuns(store, delivery, now, roleSelection, unsettledRunRefs, liveStatuses, resourceEvidence, scope.kind === "dirty");
+        const failedRunRefs = await observe("run-liveness", () => reconcileExitedRoleRuns(store, delivery, now, roleSelection, unsettledRunRefs, liveStatuses, resourceEvidence, scope.kind === "dirty"));
         await controlEventLoopRun();
         await reconcileStalledRoleRuns(store, delivery, now, roleSelection, stallWindowMs, liveStatuses, resourceEvidence, diagnosticAfterMs);
         await controlEventLoopRun();
         const selectedInputTaskIds = selectedTaskIdsForBoundedPass(store, selection);
         const autoResolvedInputs = selectedInputTaskIds === undefined
-            ? store.resolveExpiredInputRecommendations(now)
+            ? await store.resolveExpiredInputRecommendations(now)
             : selectedInputTaskIds.size === 0
                 ? []
-                : store.resolveExpiredInputRecommendations(now, selectedInputTaskIds);
+                : await store.resolveExpiredInputRecommendations(now, selectedInputTaskIds);
         // Liveness and auto-resolution can durably queue new Leader work. Process
         // only Tasks that were not part of phase one, except when a same-pass due
         // completion made an initially busy Leader idle. Result order remains
@@ -694,7 +696,10 @@ export class FileTaskController {
     #providerRetry;
     #continuationReconciler;
     #hostTerminalRecovery;
+    #persistenceMetrics;
+    #diagnosticMetrics;
     #current;
+    #phases = new ControllerWorkObserver();
     #operatorCurrent;
     #runtimeObserverCurrent;
     #pendingFull = false;
@@ -712,6 +717,8 @@ export class FileTaskController {
     constructor(store, delivery, options = {}) {
         this.store = store;
         this.delivery = delivery;
+        this.#persistenceMetrics = options.persistenceMetrics;
+        this.#diagnosticMetrics = options.diagnosticMetrics;
         this.#intervalMs = positiveInteger(options.intervalMs, DEFAULT_RECONCILIATION_INTERVAL_MS, "Controller reconciliation interval");
         this.#now = options.now ?? (() => new Date());
         this.#onError = options.onError ?? (() => { });
@@ -782,6 +789,12 @@ export class FileTaskController {
     runtimeMetrics() {
         const metrics = this.#lastRuntimeDrain?.metrics ?? ZERO_DRAIN_METRICS;
         return {
+            diagnostics: this.#diagnosticMetrics?.() ?? null,
+            phases: this.#phases.snapshot(),
+            persistence: this.#persistenceMetrics?.() ?? null,
+            reads: this.store.readObservationMetrics?.() ?? null,
+            scheduler: { running: this.#current !== undefined, pendingFull: this.#pendingFull,
+                pendingKeys: this.#pendingKeys.size },
             // Status is intentionally O(1): scanning the inbox while serving the
             // control socket would recreate the starvation this metric diagnoses.
             inbox: {
@@ -956,7 +969,7 @@ export class FileTaskController {
      * without bypassing the scheduler's own ownership and delivery fences. */
     async #observeMaintenance(phase, action) {
         try {
-            return await action();
+            return await this.#phases.observe(phase, "home", action);
         }
         catch (error) {
             this.#onError(new Error(`${phase} failed: ${error instanceof Error ? error.message : String(error)}. `
@@ -998,12 +1011,12 @@ export class FileTaskController {
                             }
                         }
                     }
-                    const firstRuntimeDrain = await this.#drainRuntimeEvents();
+                    const firstRuntimeDrain = await this.#phases.observe("runtime-drain", "home", () => this.#drainRuntimeEvents());
                     if (scope.kind === "full" && this.#hostTerminalRecovery !== undefined) {
                         await this.#observeMaintenance("Host terminal recovery", this.#hostTerminalRecovery);
                     }
-                    await this.#providerRetry?.reconcile();
-                    await this.#globalInputDelivery?.({ reconcile: scope.kind === "full", now: this.#now() });
+                    await this.#phases.observe("provider-retry", "home", () => this.#providerRetry?.reconcile());
+                    await this.#phases.observe("global-input", "home", () => this.#globalInputDelivery?.({ reconcile: scope.kind === "full", now: this.#now() }));
                     for (const taskId of runtimeTaskFailureIds(firstRuntimeDrain)) {
                         runtimeFailedTaskIds.add(taskId);
                     }
@@ -1016,17 +1029,17 @@ export class FileTaskController {
                     // DurableJob reconciliation runs before the scheduler pass so a
                     // terminal job's Leader wakeup is enqueued in the same pass that
                     // processes Leader wakeups.
-                    this.#schedules?.reconcile(this.#now());
+                    await this.#schedules?.reconcile(this.#now());
                     this.#jobSupervisor?.reconcile(this.#now());
                     if (scope.kind === "full") {
-                        result = await runControllerSchedulerPass(this.store, this.delivery, this.#now(), this.#workspacePreparer, scope, false, runtimeCleanupOutcomes, this.#lifecycleHost, this.#stallWindowMs, this.#maintenanceFence, this.#onMaintenanceFenceDefer, runtimeFailedTaskIds, this.#diagnosticAfterMs, this.#leaderWakeFence, this.#onError);
+                        result = await this.#phases.observe("scheduler-full", "home", () => runControllerSchedulerPass(this.store, this.delivery, this.#now(), this.#workspacePreparer, scope, false, runtimeCleanupOutcomes, this.#lifecycleHost, this.#stallWindowMs, this.#maintenanceFence, this.#onMaintenanceFenceDefer, runtimeFailedTaskIds, this.#diagnosticAfterMs, this.#leaderWakeFence, this.#onError, this.#phases));
                     }
                     else {
-                        const dirtyPass = await this.#runDirtySchedulerPass(scope, runtimeCleanupOutcomes, runtimeFailedTaskIds);
+                        const dirtyPass = await this.#phases.observe("scheduler-dirty", scope.keys.slice(0, 16).join(","), () => this.#runDirtySchedulerPass(scope, runtimeCleanupOutcomes, runtimeFailedTaskIds));
                         result = dirtyPass.result;
                         failedTaskScopes = dirtyPass.failedTaskScopes;
                     }
-                    const secondRuntimeDrain = await this.#drainRuntimeEvents();
+                    const secondRuntimeDrain = await this.#phases.observe("runtime-drain", "home", () => this.#drainRuntimeEvents());
                     for (const taskId of runtimeTaskFailureIds(secondRuntimeDrain)) {
                         runtimeFailedTaskIds.add(taskId);
                     }
@@ -1040,7 +1053,7 @@ export class FileTaskController {
                     // scheduler.
                     if (scope.kind === "full" && this.#resourceAutoGc !== undefined) {
                         try {
-                            const gc = await this.#resourceAutoGc();
+                            const gc = await this.#phases.observe("resource-gc", "home", this.#resourceAutoGc);
                             if (!gc.skipped && gc.failed > 0) {
                                 this.#onError(new Error(`Resource auto-GC failed to quarantine ${gc.failed} `
                                     + "resource(s); they stay in place and retry next pass."));
@@ -1120,7 +1133,7 @@ export class FileTaskController {
         const taskScopes = partition.taskScopes.filter((taskScope) => (!blockedTaskIds.has(taskScope.taskId)));
         const orderedResults = [];
         if (partition.globalKeys.length > 0) {
-            orderedResults.push(await runControllerSchedulerPass(this.store, this.delivery, this.#now(), this.#workspacePreparer, { kind: "dirty", keys: partition.globalKeys }, false, runtimeCleanupOutcomes, this.#lifecycleHost, this.#stallWindowMs, this.#maintenanceFence, this.#onMaintenanceFenceDefer, blockedTaskIds, this.#diagnosticAfterMs, this.#leaderWakeFence, this.#onError));
+            orderedResults.push(await runControllerSchedulerPass(this.store, this.delivery, this.#now(), this.#workspacePreparer, { kind: "dirty", keys: partition.globalKeys }, false, runtimeCleanupOutcomes, this.#lifecycleHost, this.#stallWindowMs, this.#maintenanceFence, this.#onMaintenanceFenceDefer, blockedTaskIds, this.#diagnosticAfterMs, this.#leaderWakeFence, this.#onError, this.#phases));
         }
         if (taskScopes.length === 0
             || this.#stopped
@@ -1153,7 +1166,7 @@ export class FileTaskController {
                     if (this.#stopped || this.#pendingFull)
                         continue;
                     try {
-                        taskResults[selected.index] = await runControllerSchedulerPass(this.store, this.delivery, this.#now(), this.#workspacePreparer, { kind: "dirty", keys: selected.taskScope.keys }, false, taskCleanupOutcomes[selected.index], this.#lifecycleHost, this.#stallWindowMs, this.#maintenanceFence, this.#onMaintenanceFenceDefer, blockedTaskIds, this.#diagnosticAfterMs, this.#leaderWakeFence, this.#onError);
+                        taskResults[selected.index] = await runControllerSchedulerPass(this.store, this.delivery, this.#now(), this.#workspacePreparer, { kind: "dirty", keys: selected.taskScope.keys }, false, taskCleanupOutcomes[selected.index], this.#lifecycleHost, this.#stallWindowMs, this.#maintenanceFence, this.#onMaintenanceFenceDefer, blockedTaskIds, this.#diagnosticAfterMs, this.#leaderWakeFence, this.#onError, this.#phases);
                         this.#clearTaskPassRetry(selected.taskScope.taskId);
                     }
                     catch (error) {