@zq-silk/yui 2.21.0 → 2.22.0

package/dist/controller/runtimeEventInbox.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { closeSync, constants, existsSync, fchmodSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { lstat, readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createRuntimeObservation, isRuntimeUsageEvidence } from "../runtime/runtimeObservation.js";
 import { boundedRunFailureDiagnostic, transportAgentResult } from "../domain/agentResultTransport.js";
@@ -19,6 +20,9 @@ export class FileRuntimeEventInbox {
     now;
     hooks;
     directory;
+    // Serialize this producer's async admissions, not the consumer/ACK path.
+    // No persistent index or cache: each scan retains the existing validation.
+    #asyncAdmission = Promise.resolve();
     constructor(home, now = () => new Date(), hooks = {}) {
         this.home = home;
         this.now = now;
@@ -26,6 +30,31 @@ export class FileRuntimeEventInbox {
         this.directory = join(home, RUNTIME_EVENT_DIRECTORY);
     }
     enqueueObservation(input, host) {
+        return this.publish(this.observationEvent(input, host));
+    }
+    /** Controller sampler ingress. The full usage dedup scan yields to control
+     * I/O; publication keeps the existing atomic fsync/link/conflict boundary.
+     * Callers must await before advancing cursor/state. Throughput remains O(U*E)
+     * and a scan still retains O(E) payload memory. */
+    enqueueObservationAsync(input, host) {
+        const event = this.observationEvent(input, host);
+        const admission = this.#asyncAdmission.then(async () => {
+            this.hooks.afterAdmission?.();
+            if (isRuntimeUsageEvidence(event.observation)) {
+                const existing = (await this.listAsync()).find(candidate => (candidate.type === "runtime-observation"
+                    && candidate.taskId === event.taskId
+                    && candidate.observation.eventId === event.observation.eventId));
+                if (existing !== undefined)
+                    return {
+                        event: existing, created: false
+                    };
+            }
+            return this.publishUnlocked(event);
+        });
+        this.#asyncAdmission = admission.catch(() => undefined);
+        return admission;
+    }
+    observationEvent(input, host) {
         const observation = createRuntimeObservation(input);
         const scope = observation.fence.taskId === undefined ? "global" : "task";
         const event = Object.freeze({
@@ -40,7 +69,7 @@ export class FileRuntimeEventInbox {
             observation,
             ...(host === undefined ? {} : { host: readAgentHostObservationSource(host) })
         });
-        return this.publish(event);
+        return event;
     }
     enqueueRunTerminal(input) {
         const normalized = normalizeNativeTurnTerminalInput(input);
@@ -89,6 +118,59 @@ export class FileRuntimeEventInbox {
         }
         return events.sort(compareRuntimeEvents);
     }
+    /** Controller consumers must not synchronously read an entire retained
+     * backlog before accepting control sockets. Keep the same validated,
+     * sorted snapshot; the fold/ACK batch and durable identities are unchanged. */
+    async listAsync() {
+        let names;
+        try {
+            names = await readdir(this.directory);
+        }
+        catch (error) {
+            if (isNodeError(error, "ENOENT"))
+                return [];
+            throw error;
+        }
+        const events = [];
+        for (const name of names.filter((entry) => entry.endsWith(".json"))) {
+            try {
+                const id = name.slice(0, -".json".length);
+                assertEventId(id);
+                const path = this.eventPath(id);
+                let metadata;
+                try {
+                    metadata = await lstat(path);
+                }
+                catch (error) {
+                    if (isNodeError(error, "ENOENT"))
+                        continue;
+                    throw error;
+                }
+                assertEventFile(metadata, id);
+                let content;
+                try {
+                    content = await readFile(path, "utf8");
+                }
+                catch {
+                    throw invalidEvent(`Runtime event JSON is invalid: ${id}`);
+                }
+                const event = parseEventFile(content, id);
+                events.push(event);
+            }
+            catch (error) {
+                if (!(error instanceof RuntimeEventInboxError)
+                    || error.code !== "RUNTIME_EVENT_INVALID")
+                    throw error;
+                try {
+                    this.quarantine(name);
+                }
+                catch {
+                    // Match list(): an invalid entry cannot block independent facts.
+                }
+            }
+        }
+        return events.sort(compareRuntimeEvents);
+    }
     read(id) {
         assertEventId(id);
         const path = this.eventPath(id);
@@ -101,23 +183,15 @@ export class FileRuntimeEventInbox {
                 return null;
             throw error;
         }
-        if (!metadata.isFile()
-            || (metadata.mode & 0o777) !== 0o600
-            || metadata.size > MAX_RUNTIME_EVENT_FILE_BYTES) {
-            throw invalidEvent(`Runtime event file is invalid: ${id}`);
-        }
-        let value;
+        assertEventFile(metadata, id);
+        let content;
         try {
-            value = JSON.parse(readFileSync(path, "utf8"));
+            content = readFileSync(path, "utf8");
         }
         catch {
             throw invalidEvent(`Runtime event JSON is invalid: ${id}`);
         }
-        const event = parseRuntimeEvent(decodeInboxV1(value));
-        if (event.id !== id || runtimeEventId(event.type, event) !== id) {
-            throw invalidEvent(`Runtime event identity is invalid: ${id}`);
-        }
-        return event;
+        return parseEventFile(content, id);
     }
     /** Producer-local delivery diagnostics need only existence, never a read of
      * another version's payload or permission to quarantine another producer. */
@@ -252,6 +326,26 @@ export class FileRuntimeEventInbox {
         }
     }
 }
+function assertEventFile(metadata, id) {
+    if (!metadata.isFile() || (metadata.mode & 0o777) !== 0o600
+        || metadata.size > MAX_RUNTIME_EVENT_FILE_BYTES) {
+        throw invalidEvent(`Runtime event file is invalid: ${id}`);
+    }
+}
+function parseEventFile(content, id) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        throw invalidEvent(`Runtime event JSON is invalid: ${id}`);
+    }
+    const event = parseRuntimeEvent(decodeInboxV1(value));
+    if (event.id !== id || runtimeEventId(event.type, event) !== id) {
+        throw invalidEvent(`Runtime event identity is invalid: ${id}`);
+    }
+    return event;
+}
 export class RuntimeEventInboxError extends Error {
     code;
     constructor(code, message) {

package/dist/controller/runtimeEventProcessor.js

@@ -530,8 +530,8 @@ export function createAsyncRuntimeObserver(invoke) {
 /**
  * The async counterpart to {@link FileRuntimeEventProcessor}: folds immutable
  * Hook facts one at a time (awaiting the worker-hosted observer) before
- * acknowledging them. The inbox itself is file-based and stays on the main
- * thread; only the db-touching folds are proxied to the worker.
+ * acknowledging them. File reads are asynchronous so a retained backlog
+ * cannot hold the control event loop before the worker's bounded fold.
  */
 export class AsyncRuntimeEventProcessor {
     inbox;
@@ -549,7 +549,7 @@ export class AsyncRuntimeEventProcessor {
         const failed = [];
         let events;
         try {
-            events = this.inbox.list();
+            events = this.inbox.listAsync === undefined ? this.inbox.list() : await this.inbox.listAsync();
         }
         catch (error) {
             return emptyDrainFailure(error);

package/dist/controller/taskRunRecovery.js

@@ -0,0 +1,153 @@
+import { isDeepStrictEqual } from "node:util";
+import { readRunContextSnapshot } from "../context/runContextPack.js";
+import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
+/**
+ * An explicit current-owner retry may follow an undelivered message
+ * continuation, rather than the retry's original business input. Recover the
+ * native anchor from durable evidence only; never schedule here or renew its
+ * budget. Native latest-failed-Turn and background checks still run at submit.
+ */
+export function taskRunRecovery(store, binding, current) {
+    if (!verifiedRecoveryChain(store, binding, current, false))
+        return undefined;
+    const { currentAttemptId: _attempt, successorRunId: _successor, successorReviewRoundId: _round, ...retained } = binding.retry;
+    return { ...retained, input: binding.run.input, status: "waiting", successorAutomatic: false,
+        previousRunId: current.id, failedAttemptId: binding.run.attemptId };
+}
+/** Read-only handling authority for the exact original Message. Its recipient,
+ * continuation, claim and delivery receipts are never rewritten or requeued. */
+export function recoveredMessageContinuation(store, message, current) {
+    const target = message.continuation?.runId;
+    if (target === undefined || message.id === undefined || message.taskId !== current.taskId
+        || message.recipient?.roleName !== current.roleName
+        || message.recipient.workItemId !== current.workItemId || message.recipient.reviewRoundId !== current.reviewRoundId)
+        return false;
+    const binding = store.getTaskRoleSessionSet(current.taskId, current.roleName)?.providerBinding;
+    if (binding == null || !verifiedRecoveryChain(store, binding, current, true))
+        return false;
+    const events = store.listEventsByType(current.taskId, ["run.retried"]);
+    const visited = new Set();
+    let id = current.id;
+    while (id !== target) {
+        if (visited.has(id))
+            return false;
+        visited.add(id);
+        const edge = events.find(e => e.payload.runId === id);
+        if (edge?.payload.previousRunId === undefined)
+            return false;
+        id = edge.payload.previousRunId;
+    }
+    const source = store.getRun(current.taskId, target);
+    if (source?.inputs[0]?.input.source.channel !== "message-continuation")
+        return false;
+    return readRunContextSnapshot(store, current).resources.some(entry => {
+        if (entry.ref.store !== "task-message" || entry.ref.refId !== message.id)
+            return false;
+        const frozen = entry.value;
+        return frozen.body === message.body && frozen.createdAt === message.createdAt
+            && isDeepStrictEqual(frozen.recipient, message.recipient);
+    });
+}
+function verifiedRecoveryChain(store, binding, current, admitted) {
+    const retry = binding.retry;
+    const turn = binding.run;
+    const conversation = binding.conversations.find(c => c.epoch === binding.currentConversationEpoch);
+    if (binding.providerNamespace !== "openai/codex"
+        || retry === undefined || retry.status === "recovered" || retry.failedNativeTurnId === undefined
+        || binding.authority.owner !== "controller" || retry.authorityEpoch !== binding.authority.epoch
+        || conversation?.conversationId !== retry.nativeSessionId
+        || turn?.runId !== current.id
+        || turn.authorityEpoch !== binding.authority.epoch || turn.retrySupported !== true
+        || turn.input?.kind !== "run" || turn.input.taskId !== current.taskId
+        || current.purpose !== "execution")
+        return false;
+    if (admitted
+        ? current.status !== "active" || turn.status !== "accepted"
+            || retry.currentAttemptId !== turn.attemptId || retry.successorRunId !== current.id
+            || retry.successorAutomatic !== false
+        : current.status !== "failed" || turn.status !== "rejected"
+            || turn.nativeTurnId !== undefined || turn.input.runId !== current.id)
+        return false;
+    const runs = store.listRuns(current.taskId).filter(r => r.roleName === current.roleName);
+    const start = runs.findIndex(r => r.result?.provider?.attemptId === retry.failureAttemptId
+        && r.result.provider.nativeTurnId === retry.failedNativeTurnId
+        && r.result.provider.conversationId === retry.nativeSessionId
+        && r.result.provider.status === "failed" && r.status === "failed");
+    const end = runs.findIndex(r => r.id === current.id);
+    if (start < 0 || end <= start || end !== runs.length - 1)
+        return false;
+    if (runs.slice(start, end + 1).some(run => run.purpose !== current.purpose
+        || run.workItemId !== current.workItemId || run.reviewRoundId !== current.reviewRoundId
+        || run.executionGroupId !== current.executionGroupId || run.executionLaneId !== current.executionLaneId
+        || run.sourceExecutionGroupId !== current.sourceExecutionGroupId
+        || !isDeepStrictEqual(run.effective, current.effective)
+        || !isDeepStrictEqual(run.workspace, current.workspace)))
+        return false;
+    const events = store.listEventsByType(current.taskId, ["runtime.agent-error", "runtime.observation", "run.retried", "message.continuation"]);
+    const anchor = events.findIndex(event => {
+        const observation = runtimeObservationFromTaskEvent(event);
+        return observation?.kind === "turn.failed"
+            && observation.fence.roleName === current.roleName
+            && observation.fence.runId === runs[start].id
+            && observation.fence.nativeSessionId === retry.nativeSessionId
+            && observation.fence.receiptId === retry.failureAttemptId
+            && observation.fence.nativeTurnId === retry.failedNativeTurnId
+            && observation.payload.failure?.error.inputDisposition === "accepted"
+            && observation.payload.failure.error.sessionDisposition === "recoverable";
+    });
+    if (anchor < 0)
+        return false;
+    // Reject any intervening accepted/unknown input, including an unowned native
+    // Turn. Timestamps or absence of a Run result are not non-submission proof.
+    for (const event of events.slice(anchor + 1)) {
+        if (event.payload.roleName !== current.roleName
+            || event.payload.nativeSessionId !== retry.nativeSessionId)
+            continue;
+        if (event.type === "runtime.agent-error" && event.payload.inputDisposition !== "not-accepted"
+            && !(event.payload.attemptId === retry.failureAttemptId
+                && event.payload.nativeTurnId === retry.failedNativeTurnId
+                && event.payload.phase === "turn-execute" && event.payload.inputDisposition === "accepted"))
+            return false;
+        if (event.type !== "runtime.observation")
+            continue;
+        const observation = runtimeObservationFromTaskEvent(event);
+        if (admitted && observation?.fence.receiptId === turn.attemptId
+            && observation.fence.runId === current.id && observation.fence.nativeTurnId === turn.nativeTurnId
+            && observation.kind !== "input.delivery-unknown")
+            continue;
+        if (observation === null || observation.kind === "input.accepted"
+            || observation.kind === "input.delivery-unknown"
+            || observation.kind.startsWith("turn.")
+                && observation.fence.nativeTurnId !== retry.failedNativeTurnId)
+            return false;
+    }
+    for (let i = start + 1; i <= end; i++) {
+        const prior = runs[i - 1];
+        const run = runs[i];
+        if (!(admitted && i === end)) {
+            if (run.status !== "failed" || run.result?.provider !== undefined
+                || run.result?.failureReason !== "runtime-failed")
+                return false;
+            const errors = events.filter(e => e.type === "runtime.agent-error" && e.payload.runId === run.id);
+            const proof = errors.find(({ payload: p }) => p.roleName === current.roleName
+                && p.agentId === run.effective.agentId && p.nativeSessionId === retry.nativeSessionId
+                && p.source === "host" && p.adapterId === "codex" && p.driverId === "openai/codex"
+                && p.phase === "turn-submit" && p.inputDisposition === "not-accepted"
+                && p.errorName === "CodexPreSubmissionError" && p.registrationDisposition === "committed"
+                && p.attemptId !== undefined);
+            if (proof === undefined || errors.some(e => e.payload.inputDisposition !== "not-accepted")
+                || i === end && proof.payload.attemptId !== turn.attemptId)
+                return false;
+        }
+        if (events.some(e => e.type === "run.retried"
+            && e.payload.runId === run.id && e.payload.previousRunId === prior.id))
+            continue;
+        if (run.inputs[0]?.input.source.channel !== "message-continuation"
+            || !events.some(e => e.type === "message.continuation" && e.payload.runId === run.id))
+            return false;
+        const snapshot = readRunContextSnapshot(store, run);
+        if (!snapshot.resources.some(r => r.ref.store === "source-run" && r.ref.refId === prior.id))
+            return false;
+    }
+    return true;
+}

package/dist/core/controllerClient.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { isControllerSocketPathForHome } from "./controllerEndpoint.js";
 import { findLiveControllerProcessForHome, inspectLiveControllerProcess } from "./controllerProcessIdentity.js";
 import { readHomeFilesystemId } from "./homeFilesystemIdentity.js";
+import { monotonicMilliseconds } from "./controllerTelemetry.js";
 import { CONTROLLER_DISCOVERY_PATH, ControllerProtocolError, encodeControllerRequest, FILE_TASK_CONTROLLER_PROTOCOL_VERSION, MAX_CONTROLLER_MESSAGE_BYTES, parseControllerDiscovery, parseControllerResponse } from "./protocol.js";
 export class ControllerClientError extends Error {
     code;
@@ -169,6 +170,10 @@ export async function stopOrphanedFileTaskController(home, timeoutMs, options =
 }
 function exchange(socketPath, requestLine, expectedId, timeoutMs, method) {
     return new Promise((resolve, reject) => {
+        const startedAtMs = monotonicMilliseconds();
+        let connectedAtMs = null;
+        let writeCompletedAtMs = null;
+        let responseAtMs = null;
         const socket = createConnection(socketPath);
         let buffer = Buffer.alloc(0);
         let settled = false;
@@ -194,19 +199,28 @@ function exchange(socketPath, requestLine, expectedId, timeoutMs, method) {
                 delivery: error.diagnostic?.delivery ?? (deliveryStarted ? "unconfirmed" : "not-sent"),
                 method,
                 requestId: expectedId,
-                socketPath
+                socketPath,
+                timing: { startedAtMs, connectedAtMs, writeCompletedAtMs, responseAtMs,
+                    endedAtMs: monotonicMilliseconds() }
             }));
         };
         socket.on("connect", () => {
+            if (settled)
+                return;
+            connectedAtMs = monotonicMilliseconds();
             // Once write begins, a missing response cannot prove that the Controller
             // did not commit the request. Callers must use their domain identity to
             // decide whether an explicit retry is safe.
             deliveryStarted = true;
-            socket.write(requestLine);
+            socket.write(requestLine, error => {
+                if (error == null)
+                    writeCompletedAtMs = monotonicMilliseconds();
+            });
         });
         socket.on("data", (chunk) => {
             if (settled)
                 return;
+            responseAtMs ??= monotonicMilliseconds();
             buffer = Buffer.concat([buffer, chunk]);
             const newline = buffer.indexOf(0x0a);
             if (newline < 0) {

package/dist/core/controllerServer.js

@@ -17,7 +17,7 @@ import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
 import { CommandExecutionError } from "../tmux/commandExecutor.js";
 import { redactAgentErrorText } from "../runtime/agentError.js";
 import { detectRunningRelease, readActiveReleasePointer, readHandoverFence, verifyReleaseIntegrity, writeHandoverFence, writeRuntimeIdentity } from "../release/runtimeRelease.js";
-import { isBuiltinControllerMethod, ControllerCommandObserver, ControllerEventLoopDelay } from "./controllerTelemetry.js";
+import { isBuiltinControllerMethod, ControllerCommandObserver, ControllerEventLoopDelay, monotonicMilliseconds } from "./controllerTelemetry.js";
 import { parseLinuxProcessStartIdentity, removeEphemeralDomainIdentity, readEphemeralDomainIdentity, writeEphemeralDomainIdentity } from "../controller/domainIdentity.js";
 /** Methods that stay available while a handover fence is active. */
 const HANDOVER_ALLOWED_METHODS = new Set([
@@ -54,7 +54,7 @@ async function startControllerServerLocked(home, dispatcher, beforeDiscoveryRemo
     await chmod(socketDirectory, 0o700);
     const token = randomBytes(32).toString("hex");
     let closeRunning = async () => undefined;
-    const commandObserver = new ControllerCommandObserver();
+    const commandObserver = new ControllerCommandObserver(undefined, options.onRequestDiagnostic);
     const eventLoopDelay = new ControllerEventLoopDelay();
     const telemetry = Object.freeze({
         commandObserver,
@@ -245,6 +245,7 @@ async function writeDiscoveryAtomically(discoveryPath, discovery) {
     }
 }
 function receiveRequest(socket, token, dispatcher, stop, status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, getPrimaryIdentity) {
+    const acceptedAtMs = monotonicMilliseconds();
     let buffer = Buffer.alloc(0);
     let complete = false;
     const fail = (code, message, id = "invalid") => {
@@ -273,7 +274,7 @@ function receiveRequest(socket, token, dispatcher, stop, status, telemetry, hand
             return;
         }
         complete = true;
-        void routeRequest(socket, buffer.subarray(0, newline).toString("utf8"), token, dispatcher, stop, status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, getPrimaryIdentity);
+        void routeRequest(socket, buffer.subarray(0, newline).toString("utf8"), token, dispatcher, stop, status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, getPrimaryIdentity, { acceptedAtMs, receivedAtMs: monotonicMilliseconds() });
     });
     socket.on("end", () => {
         if (!complete)
@@ -281,7 +282,7 @@ function receiveRequest(socket, token, dispatcher, stop, status, telemetry, hand
     });
     socket.on("error", () => undefined);
 }
-async function routeRequest(socket, line, token, dispatcher, stop, status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, getPrimaryIdentity) {
+async function routeRequest(socket, line, token, dispatcher, stop, status, telemetry, handover, home, homeId, homeFilesystemId, controllerInstanceId, getPrimaryIdentity, socketTiming) {
     let request;
     try {
         request = parseControllerRequest(line);
@@ -311,9 +312,17 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
     // observation completes when the response is handed to the socket, so a
     // later status snapshot sees prior built-in completions and the dispatcher
     // service-time metric stays a distinct observation.
-    const observation = telemetry.commandObserver.start(request.method, request.id);
+    const observation = telemetry.commandObserver.start(request.method, request.id, socketTiming);
+    // A queued response is not a local flush, and even a local flush is not a
+    // client receipt. Close before finish retains a failed transport observation.
+    socket.once("close", () => observation.flushed(true));
+    if (socket.destroyed)
+        observation.flushed(true);
     const send = (response, onFlushed) => {
         observation.complete(isBuiltinControllerMethod(request.method) ? "builtin" : "dispatched", response.ok ? "success" : "failure");
+        // Install only for our response: a peer FIN can auto-end an otherwise
+        // empty socket while its asynchronous handler is still running.
+        socket.once("finish", () => observation.flushed());
         sendResponse(socket, response, onFlushed);
     };
     // Issue 02: a fenced Controller is mid-handover. It stops accepting new

package/dist/core/controllerTelemetry.js

@@ -13,10 +13,10 @@ export class ControllerWorkObserver {
     constructor(clock = monotonicMilliseconds) {
         this.clock = clock;
     }
-    start(phase, target) {
+    start(phase, target, startedAtMs = this.clock()) {
         const token = {};
         const entry = { phase, target: target === undefined ? null
-                : createHash("sha256").update(target).digest("hex").slice(0, 16), startedAt: this.clock() };
+                : createHash("sha256").update(target).digest("hex").slice(0, 16), startedAt: startedAtMs };
         this.#active.set(token, entry);
         return (failed = false) => {
             if (!this.#active.delete(token))
@@ -76,6 +76,7 @@ const BUILTIN_METHODS = new Set([
     "controller.handover-state"
 ]);
 const OBSERVED_METHODS = new Set([...BUILTIN_METHODS,
+    "runtime.host-observation-apply", "runtime.observation-apply",
     "scheduler.signal", "scheduler.scan", "scheduler.configure",
     "runtime.ensure-role-session", "runtime.stop-role-session",
     "capability.search", "capability.describe", "capability.call",
@@ -104,6 +105,7 @@ export const productionTelemetryScheduler = {
  * for end-to-end latency and is never double-counted.
  */
 export class ControllerCommandObserver {
+    onRequestDiagnostic;
     #clock;
     #received = 0;
     #completed = 0;
@@ -116,22 +118,64 @@ export class ControllerCommandObserver {
     #dispatchedCompleted = 0;
     #dispatchedFailed = 0;
     #observations;
-    constructor(clock = monotonicMilliseconds) {
+    #transport;
+    constructor(clock = monotonicMilliseconds, onRequestDiagnostic) {
+        this.onRequestDiagnostic = onRequestDiagnostic;
         this.#clock = clock;
         this.#observations = new ControllerWorkObserver(clock);
+        this.#transport = new ControllerWorkObserver(clock);
     }
-    start(method = "unknown", requestId) {
+    start(method = "unknown", requestId, socketTiming) {
         this.#received += 1;
         this.#inFlight += 1;
         const token = {};
         this.#inFlightStarted.set(token, this.#clock());
         const finish = this.#observations.start(OBSERVED_METHODS.has(method) ? method : "other", requestId);
+        // Attach socket timestamps only after authentication, using the same hash
+        // as route accounting. No raw frames, params or tokens enter observations.
+        if (socketTiming !== undefined) {
+            this.#transport.start("socket.accept-to-route", requestId, socketTiming.acceptedAtMs)();
+            this.#transport.start("socket.receive-to-route", requestId, socketTiming.receivedAtMs)();
+        }
+        const finishFlush = socketTiming === undefined ? () => undefined
+            : this.#transport.start("socket.route-to-flush", requestId);
+        const routedAtMs = this.#clock();
+        let handlerCompletedAtMs, flushCompletedAtMs;
+        let handlerFailed = false, flushFailed = false;
+        const emit = () => {
+            if (socketTiming === undefined || handlerCompletedAtMs === undefined
+                || flushCompletedAtMs === undefined)
+                return;
+            const elapsedMs = Math.max(0, Math.max(handlerCompletedAtMs, flushCompletedAtMs) - socketTiming.acceptedAtMs);
+            if (!handlerFailed && !flushFailed && elapsedMs < 1000)
+                return;
+            try {
+                this.onRequestDiagnostic?.({
+                    target: requestId === undefined ? null
+                        : createHash("sha256").update(requestId).digest("hex").slice(0, 16),
+                    phase: OBSERVED_METHODS.has(method) ? method : "other",
+                    ...socketTiming, routedAtMs, handlerCompletedAtMs, flushCompletedAtMs,
+                    failed: handlerFailed || flushFailed, handlerFailed, flushFailed, elapsedMs
+                });
+            }
+            catch { /* Diagnostic sinks cannot change command effects. */ }
+        };
         let completed = false;
         return {
+            flushed: (failed = false) => {
+                if (flushCompletedAtMs !== undefined)
+                    return;
+                flushCompletedAtMs = this.#clock();
+                flushFailed = failed;
+                finishFlush(failed);
+                emit();
+            },
             complete: (kind, outcome) => {
                 if (completed)
                     return;
                 completed = true;
+                handlerCompletedAtMs = this.#clock();
+                handlerFailed = outcome === "failure";
                 this.#inFlight = Math.max(0, this.#inFlight - 1);
                 this.#inFlightStarted.delete(token);
                 finish(outcome === "failure");
@@ -150,6 +194,7 @@ export class ControllerCommandObserver {
                 else {
                     this.#dispatchedCompleted += 1;
                 }
+                emit();
             }
         };
     }
@@ -171,7 +216,8 @@ export class ControllerCommandObserver {
                 completed: this.#dispatchedCompleted,
                 failed: this.#dispatchedFailed
             },
-            observations: this.#observations.snapshot()
+            observations: this.#observations.snapshot(),
+            transport: this.#transport.snapshot()
         };
     }
 }

package/dist/errors/cliFailure.js

@@ -79,8 +79,17 @@ export function describeCliFailure(error, context = {}) {
                 ? "The Controller returned an error response; it does not prove rollback of earlier effects. " + RECONCILE
                 : RECONCILE;
     const help = error instanceof CliError && error.helpText !== undefined ? clean(error.helpText.trimEnd()) : undefined;
-    const message = [
-        ...chain.map((item, index) => `${index === 0 ? "" : "Caused by: "}${item.code === undefined ? "" : `[${item.code}] `}${item.message}`),
+    const causes = chain.map((item, index) => `${index === 0 ? "" : "Caused by: "}${item.code === undefined ? "" : `[${item.code}] `}${item.message}`);
+    const lines = (parts) => parts.filter((part) => part !== undefined && part.length > 0).join("\n");
+    const jsonMessage = lines([
+        causes[0],
+        effects,
+        guidance,
+        "Use the same Home and CLI in details.diagnostic; its causes retain the full error chain. Recovery commands are not run automatically.",
+        help
+    ]);
+    const message = lines([
+        ...causes,
         diagnostic.operation === undefined ? undefined : `Operation: ${diagnostic.operation}`,
         diagnostic.home === undefined ? undefined : `YUI_HOME: ${diagnostic.home}`,
         diagnostic.cli === undefined ? undefined : `CLI entry: ${diagnostic.cli}`,
@@ -92,9 +101,9 @@ export function describeCliFailure(error, context = {}) {
         guidance,
         "Recovery commands shown as `yui` must use the same Home and matching CLI entry above; they are not run automatically.",
         help
-    ].filter((part) => part !== undefined && part.length > 0).join("\n");
+    ]);
     return {
-        code, exitCode, message,
+        code, exitCode, message, jsonMessage,
         details: {
             ...(error instanceof CliError ? sanitizeFailureDetails(error.details, context) : {}),
             diagnostic
@@ -103,7 +112,7 @@ export function describeCliFailure(error, context = {}) {
 }
 export function renderCliFailure(failure, json, jsonCode = failure.code) {
     return json
-        ? JSON.stringify({ ok: false, code: jsonCode, message: failure.message, details: failure.details })
+        ? JSON.stringify({ ok: false, code: jsonCode, message: failure.jsonMessage, details: failure.details })
         : `${failure.code}: ${failure.message}`;
 }
 function errorCode(error) {