@zq-silk/yui 2.17.0 → 2.18.0

package/dist/cli/commandCatalog.js

@@ -1696,7 +1696,8 @@ export const ROOT_COMMAND = buildNode({
                                 : name === "run-delegation" ? "Read the exact execution Task/WorkItem and attention projection; never a grant."
                                     : `${name} a stable Job or exact Run.`,
                     usage: `yui job ${name} (--task <id>|--global)${name === "list" ? "" : " --job <id>"}`
-                        + (name === "define" || name === "update" ? " --title <text> --input <configuration-json>" : "")
+                        + (name === "define" ? " --title <text> (--input <json>|--input-file <file>|--command <shell>) [--script <path=local-file> ...]" : "")
+                        + (name === "update" ? " [--title <text>] [--input <json>|--input-file <file>|--command <shell>] [--script <path=local-file> ...]" : "")
                         + (name === "update" ? " --revision <current>" : "")
                         + (name === "run" ? " --request-id <key> [--retry-of <run-id>]" : "")
                         + (["run-get", "run-result", "run-evidence", "run-confirm", "run-delegation", "logs", "run-cancel", "run-acknowledge"].includes(name) ? " --run <run-id>" : "")

package/dist/commands/controllerCommands.js

@@ -161,10 +161,9 @@ export function parseControllerRuntimeSnapshot(result, droppedEvents) {
     const drain = runtime.drain;
     const commands = runtime.commands;
     const routes = commands?.routes;
-    const dispatcher = commands?.dispatcher;
     const eventLoopDelay = commands?.eventLoopDelay;
-    const queueDepth = (typeof routes?.inFlight === "number" ? routes.inFlight : 0)
-        + (typeof dispatcher?.inFlight === "number" ? dispatcher.inFlight : 0);
+    // Dispatcher work is a subset of authenticated routes, not another queue.
+    const queueDepth = typeof routes?.inFlight === "number" ? routes.inFlight : undefined;
     return {
         source: "controller.status",
         pid: typeof record.pid === "number" ? record.pid : undefined,
@@ -182,6 +181,16 @@ export function parseControllerRuntimeSnapshot(result, droppedEvents) {
             ? drain.progressEventsCoalesced
             : undefined,
         droppedEvents,
+        observations: {
+            commands: (runtime.commands ?? null),
+            phases: (runtime.phases ?? null),
+            reads: (runtime.reads ?? null),
+            persistence: (runtime.persistence ?? null),
+            diagnostics: (runtime.diagnostics ?? null),
+            scheduler: (runtime.scheduler ?? null),
+            preRoutingWait: "unmeasured; event-loop lag is sampled, not per-request queue time",
+            clock: "process-monotonic milliseconds; target/request labels are sha256 prefixes"
+        },
         queueDepth,
         oldestInFlightAgeMs: typeof routes?.oldestInFlightAgeMs === "number"
             ? routes.oldestInFlightAgeMs
@@ -210,7 +219,7 @@ export function renderRuntimeIdentitySection(input) {
     }
     lines.push(`  Health          ${health.status === "ok" ? "ok" : health.status === "degraded" ? "DEGRADED (needs-repair above)" : "FAIL (contradictions above)"}`, `  Controller      ${runtime.source === "controller.status" && runtime.pid !== undefined
         ? `PID ${runtime.pid}${runtime.uptimeMs === undefined ? "" : `, up ${formatDuration(runtime.uptimeMs)}`}${runtime.protocolVersion === undefined ? "" : `, protocol ${runtime.protocolVersion}`}`
-        : "not running (unsupported)"}`, `  Controller RSS  ${runtime.rssBytes !== undefined ? formatBytes(runtime.rssBytes) : UNSUPPORTED} (inventory ${formatBytes(inventoryRssBytes)})`, `  Command queue   depth ${runtime.queueDepth ?? UNSUPPORTED} · oldest ${runtime.oldestInFlightAgeMs === undefined
+        : "not running (unsupported)"}`, `  Controller RSS  ${runtime.rssBytes !== undefined ? formatBytes(runtime.rssBytes) : UNSUPPORTED} (inventory ${formatBytes(inventoryRssBytes)})`, `  Commands        in flight ${runtime.queueDepth ?? UNSUPPORTED} · oldest ${runtime.oldestInFlightAgeMs === undefined
         ? UNSUPPORTED
         : runtime.oldestInFlightAgeMs === null
             ? "—"

package/dist/commands/durableJobCommands.js

@@ -4,6 +4,7 @@ import { callFileTaskController } from "../controller/clientRuntime.js";
 import { acknowledgeDurableJob, cancelDurableJob, getDurableJob, startDurableJob } from "../controller/jobClient.js";
 import { resolveJobCaller, taskLocalActor } from "../task/taskAuthority.js";
 import { boundedJobArtifactPayload } from "../artifacts/jobArtifactTransport.js";
+import { readFileSync, statSync } from "node:fs";
 /**
  * The textual `--owner` forms accepted by `job start`. The public help text in
  * the command catalog must document exactly these forms.
@@ -38,9 +39,25 @@ export async function runDurableJobCommand(args, options) {
 }
 async function definitionCommand(command, args, options) {
     const flags = new Map();
+    const scripts = [];
+    const readText = (path) => {
+        if (!statSync(path).isFile() || statSync(path).size > 512 * 1024)
+            throw usageError("Job input files must be text files up to 512 KiB.");
+        return readFileSync(path, "utf8");
+    };
     for (let i = 0; i < args.length; i++) {
         const flag = args[i];
-        if (!["--global", "--task", "--job", "--title", "--input", "--revision", "--request-id", "--retry-of", "--run", "--artifact", "--reference", "--offset", "--result", "--expected-session", "--expected-attempt"].includes(flag)
+        if (flag === "--script") {
+            const value = args[++i] ?? "", separator = value.indexOf("=");
+            if (separator < 1 || separator === value.length - 1)
+                throw usageError("--script requires relative-path=local-file.");
+            const path = value.slice(0, separator);
+            if (scripts.some(file => file.path === path))
+                throw usageError("Repeated script path.");
+            scripts.push({ path, content: readText(value.slice(separator + 1)) });
+            continue;
+        }
+        if (!["--global", "--task", "--job", "--title", "--input", "--input-file", "--command", "--revision", "--request-id", "--retry-of", "--run", "--artifact", "--reference", "--offset", "--result", "--expected-session", "--expected-attempt"].includes(flag)
             || flags.has(flag))
             throw usageError(`Unknown or repeated Job flag: ${flag}.`);
         if (flag === "--global") {
@@ -61,14 +78,44 @@ async function definitionCommand(command, args, options) {
         ?? (executionRead ? options.environment?.YUI_TASK_ID : undefined) ?? "");
     const scope = taskId === undefined ? { kind: "global" } : { kind: "task", taskId };
     let configuration;
-    if (flags.has("--input")) {
+    if (flags.has("--input") && flags.has("--input-file"))
+        throw usageError("Choose --input or --input-file.");
+    if (flags.has("--input") || flags.has("--input-file")) {
         try {
-            configuration = JSON.parse(flags.get("--input"));
+            configuration = JSON.parse(flags.has("--input-file") ? readText(flags.get("--input-file")) : flags.get("--input"));
         }
         catch {
             throw usageError("--input must be a JSON Job configuration.");
         }
     }
+    if ((flags.has("--command") || scripts.length || flags.has("--input-file")) && !["define", "update"].includes(command)) {
+        throw usageError("Command and script edits require job define or update.");
+    }
+    if (flags.has("--command") || scripts.length) {
+        if (taskId !== undefined || configuration !== undefined)
+            throw usageError("--command/--script are global Shell shortcuts; use --input for a complete configuration.");
+        let shell = { kind: "shell", env: {}, steps: [], files: [] };
+        if (command === "update") {
+            const existing = await callFileTaskController(options.home, "job.definition", {
+                op: "show", scope, caller, id: flags.get("--job")
+            }, { environment: options.environment });
+            if (existing.revision !== Number(flags.get("--revision")))
+                throw usageError("Job revision changed; inspect before editing.");
+            if (existing.configuration.kind !== "shell")
+                throw usageError("Changing executor requires a new Job.");
+            shell = existing.configuration;
+            if (!flags.has("--title"))
+                flags.set("--title", existing.title);
+        }
+        if (flags.has("--command")) {
+            if (shell.steps.length > 1)
+                throw usageError("Use --input-file to edit a multi-step Job without discarding steps.");
+            shell = { ...shell, steps: [{ ...shell.steps[0], name: shell.steps[0]?.name ?? "run", command: flags.get("--command") }] };
+            // The command shortcut intentionally selects shell execution, not stale argv.
+            delete shell.steps[0].argv;
+        }
+        configuration = { ...shell, files: [...shell.files.filter(file => !scripts.some(next => next.path === file.path)), ...scripts] };
+    }
     const requestId = flags.get("--request-id");
     const parseObject = (flag) => {
         if (!flags.has(flag))

package/dist/commands/globalRoleCommands.js

@@ -2,7 +2,8 @@ import { roleNotFound, usageError } from "../errors/cliError.js";
 import { hasManagedIdentity } from "../runtime/managedIdentity.js";
 import { requireManagedGlobalCaller } from "../runtime/managedCaller.js";
 import { boundedDocument, recordPage, readOptions, readDigest, messageReceipt, summaryText, summaryMetadata } from "../output/boundedRead.js";
-import { controlProviderRetry, providerRetryProjection, providerRetrySummary, renderProviderRetry } from "../runtime/providerRetry.js";
+import { controlProviderRetry, providerRetryProjection, renderProviderRetry } from "../runtime/providerRetry.js";
+import { globalSessionHealth } from "../runtime/globalSessionHealth.js";
 import { pendingGlobalInboxMessages, inboxHandlingState, globalInboxDeliveryState } from "../message/inboxReceipt.js";
 import { settleGlobalRetryInput } from "../message/globalProviderRetry.js";
 import { globalInputBacklog } from "../message/globalInputBacklog.js";
@@ -134,6 +135,7 @@ function roleContext(args, store, options) {
     const effective = resolveEffectiveLaunch({ role, purpose: "execution" });
     const sessions = store.getGlobalRoleSessionSet(name);
     const session = sessions?.sessions[role.activeAgentId];
+    const health = globalSessionHealth(role, sessions);
     const currentSkills = checkCurrentSkills(options.yuiHome ?? environment.YUI_HOME, roleSkillIds(session?.effective.context ?? role, role.name === "operator" ? "operator" : "global"));
     // Native delivery and explicit Agent handling settle the same queued input
     // through distinct receipts; a context read does neither.
@@ -164,7 +166,9 @@ function roleContext(args, store, options) {
             agentId: binding.agentId,
             adapterId: binding.adapterId,
             workspace: role.workspace,
-            effectiveRevision: role.launchRevision,
+            desiredRevision: health.desiredRevision,
+            effectiveRevision: health.effectiveRevision,
+            configurationDrift: health.configurationDrift,
             ...(session?.nativeSessionId === undefined
                 ? {}
                 : { nativeSessionId: session.nativeSessionId })
@@ -180,7 +184,7 @@ function roleContext(args, store, options) {
         authority: {
             view: role.name === "operator" ? "operator" : "global",
             taskImplementation: false,
-            writableProjectIds: effective.writeProjectIds,
+            writableProjectIds: (session?.effective ?? effective).writeProjectIds,
             allowedActions: role.name === "operator"
                 ? ["route-request", "inspect-catalog", "answer-user-boundary"]
                 : ["perform-global-role-request"]
@@ -196,17 +200,14 @@ function roleContext(args, store, options) {
             diagnostics: `role message list ${name} --diagnostics`,
             retry: `session retry ${name} show`
         },
-        nativeTurn: sessions?.providerBinding?.run == null ? null : {
-            attemptId: sessions.providerBinding.run.attemptId,
-            nativeTurnId: sessions.providerBinding.run.nativeTurnId,
-            status: sessions.providerBinding.run.status
-        },
+        nativeTurn: health.nativeTurn,
+        health,
         ...(role.jobOwner === undefined ? {} : { job: {
                 owner: role.jobOwner,
                 read: `yui job show ${role.jobOwner.scope.kind === "global" ? "--global" : `--task ${role.jobOwner.scope.taskId}`} --job ${role.jobOwner.jobId} --json`,
                 boundary: "Job execution only. This Role is not Operator and owns no Task delivery authority. Read the exact Run from its original message."
             } }),
-        retry: providerRetrySummary(sessions?.providerBinding),
+        retry: health.retry,
         // Historical interrupt receipts are available through Session inspection;
         // only this Turn's exact identity is required at entry.
         sessionManifestPath: environment.YUI_SESSION_MANIFEST,
@@ -510,7 +511,7 @@ function roleSession(args, store, options) {
             throw usageError("Usage: yui session retry <role> [show|cancel|disable|enable]");
         }
         return store.transaction(tx => {
-            requireRole(name, tx);
+            const role = requireRole(name, tx);
             const sessions = tx.getGlobalRoleSessionSet(name);
             let binding = sessions?.providerBinding ?? null;
             if (action !== "show") {
@@ -520,9 +521,14 @@ function roleSession(args, store, options) {
                 tx.saveGlobalRoleSessionSet({ ...sessions, providerBinding: binding });
                 settleGlobalRetryInput(tx, name, binding, new Date());
             }
+            const health = globalSessionHealth(role, sessions);
+            const historical = binding?.retry !== undefined && health.retry === null;
             return options.jsonOutput ? JSON.stringify({
-                roleName: name, retry: providerRetryProjection(binding), disabled: binding?.retryDisabled ?? false
-            }) + "\n" : renderProviderRetry(binding) + "\n";
+                roleName: name, retry: providerRetryProjection(binding), disabled: binding?.retryDisabled ?? false,
+                selectedNativeSessionId: health.nativeSessionId,
+                retryScope: historical ? "historical-session" : "current-session"
+            }) + "\n" : (historical ? "Historical Session evidence (not the selected Session's current failure): " : "")
+                + renderProviderRetry(binding) + "\n";
         });
     }
     if (command !== "record" && command !== "replace") {

package/dist/commands/inboxCommands.js

@@ -322,6 +322,7 @@ export function runInboxCommand(args, store, env, now = new Date()) {
                 if (message.inbox?.ack || message.delivery !== undefined || message.interruptThen !== undefined
                     || message.control !== undefined && message.control.outcome !== "rejected"
                     || turn?.attemptId === `global-input:${current.roleName}/${message.id}`
+                        && turn.status !== "rejected"
                     || !foreignTarget && message.notDelivered === undefined) {
                     throw new Error("Retirement requires obsolete, proven-unsubmitted input; unknown/accepted/interrupt-owned input must retain its exact handling path.");
                 }

package/dist/commands/operatorCommands.js

@@ -1,5 +1,6 @@
 import { agentAdapterLabel as adapterLabel } from "../agent/adapterCatalog.js";
 import { assertRoleEnabled } from "../role/availability.js";
+import { globalSessionHealth } from "../runtime/globalSessionHealth.js";
 import { usageError } from "../errors/cliError.js";
 import { createRoleSessionSet } from "../executor/agentExecutor.js";
 import { TASK_SUBMISSION_INTENTS } from "../message/message.js";
@@ -32,7 +33,11 @@ function status(args, store, options) {
     if (activeBinding === undefined) {
         throw usageError(`Operator active Agent is not bound: ${role.activeAgentId}.`);
     }
-    const projection = projectOperatorStatus(store.getGlobalRoleSessionSet(role.name), role.activeAgentId, activeBinding.adapterId);
+    const sessions = store.getGlobalRoleSessionSet(role.name);
+    const projection = {
+        ...projectOperatorStatus(sessions, role.activeAgentId, activeBinding.adapterId),
+        health: globalSessionHealth(role, sessions)
+    };
     const writer = projection.writer;
     const writerLines = [
         "Operator status",
@@ -42,7 +47,10 @@ function status(args, store, options) {
         `  Adapter: ${adapterLabel(writer.adapterId)}`,
         `  Conversation: ${writer.sessionRef ?? "-"}`,
         `  Native session: ${writer.nativeSessionId ?? "-"}`,
-        `  Session state: ${writer.sessionStatus ?? "-"}`
+        `  Session state: ${writer.sessionStatus ?? "-"}`,
+        `  Configuration: desired r${projection.health.desiredRevision}, effective r${projection.health.effectiveRevision ?? "unknown"}`,
+        `  Host observation: ${projection.health.hostObservation}`,
+        `  ${projection.health.note}`
     ];
     const history = projection.historicalConversations;
     const historyOutput = history.length === 0

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/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) {