@zq-silk/yui 1.1.2 → 2.1.0

package/dist/context/taskContext.js

@@ -3,16 +3,18 @@ import { isGitArtifactRefString, parseGitArtifactRef } from "../artifacts/gitArt
 import { taskNotFound, usageError } from "../errors/cliError.js";
 import { expandTaskMessageResult } from "../message/message.js";
 import { resolveManagedTaskReader } from "../runtime/managedCaller.js";
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
 import { providerRetryProjection } from "../runtime/providerRetry.js";
 import { projectTaskRemoteDeliveryFromStore } from "../task/remoteDeliveryService.js";
+import { retiredTaskRecordIds, TASK_RECORD_RETIRED_EVENT } from "../task/taskRecordRetirement.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
 import { contextContentDigest } from "./contextSnapshot.js";
 import { buildRunContextPack } from "./runContextPack.js";
 import { sourceRunContextValue } from "./sourceRunContext.js";
-const MAX_RECORDS = 256;
-const MAX_VALUE_BYTES = 4096;
-const MAX_PAGE_BYTES = 128 * 1024;
-const MAX_INSPECT_BYTES = 4 * 1024 * 1024;
+import { boundedDocument, recordPage } from "../output/boundedRead.js";
+const MAX_RECORDS = 64;
+const MAX_VALUE_BYTES = 2048;
+const MAX_PAGE_BYTES = 24 * 1024;
 const MAX_EVENTS = 100;
 const MAX_ATTENTION_REFS = 8;
 /** A current read model, not a second snapshot store or a delivery receipt.
@@ -21,7 +23,7 @@ const MAX_ATTENTION_REFS = 8;
 export function readTaskContext(store, taskId, environment = {}) {
     return store.readTransaction((reader) => {
         const scope = authorizeContext(reader, taskId, environment);
-        const sources = authorizedSources(reader, scope);
+        const sources = authorizedSources(reader, scope, true);
         const count = sources.reduce((total, source) => total + source.count, 0);
         const cursor = currentCursor(reader, taskId);
         // Reserve a small, classified view before ordinary history consumes the
@@ -34,10 +36,12 @@ export function readTaskContext(store, taskId, environment = {}) {
             for (const entry of source.read()) {
                 if (records.length >= MAX_RECORDS)
                     break page;
+                if (records.filter(record => record.ref.store === source.family).length >= 8)
+                    continue;
                 if (entry.ref.store === "run")
                     runtimeEvents ??= reader.listEventsByType(taskId, ["runtime.agent-error"]);
                 const valueBytes = Buffer.byteLength(JSON.stringify(entry.value));
-                const content = valueBytes > MAX_VALUE_BYTES
+                const content = valueBytes > MAX_VALUE_BYTES || ["task-message", "run", "work-item", "project-knowledge"].includes(entry.ref.store)
                     ? { ref: entry.ref, summary: summarize(entry.value), omitted: true }
                     : { ...entry, omitted: false };
                 const record = { ...content, ...(entry.ref.store === "run" ? {
@@ -53,11 +57,24 @@ export function readTaskContext(store, taskId, environment = {}) {
             }
         return {
             taskId, coreCursor: encode(cursor), throughCursor: encode(cursor),
+            view: "current",
+            collections: Object.entries(sources.reduce((counts, source) => {
+                counts[source.family] = (counts[source.family] ?? 0) + source.count;
+                return counts;
+            }, {})).map(([store, total]) => ({
+                store, total, returned: records.filter(record => record.ref.store === store).length
+            })),
+            discovery: `task context list ${taskId} --store <store>`,
+            commandDiscovery: {
+                help: "yui help", describe: "yui --json help",
+                note: "Help and completion share the current caller's offline command view. Follow that view for operation-specific discovery; execution always revalidates authority."
+            },
+            detail: `task context inspect ${taskId} --store <store> --ref <refId> --digest <digest>`,
             attention,
             records, count,
             omitted: { records: count - records.length, values: records.filter((r) => r.omitted).length },
             observations: [],
-            limits: { records: MAX_RECORDS, valueBytes: MAX_VALUE_BYTES, pageBytes: MAX_PAGE_BYTES,
+            limits: { records: MAX_RECORDS, valueBytes: MAX_VALUE_BYTES, pageBytes: 32 * 1024, recordBytes: MAX_PAGE_BYTES,
                 attentionRefsPerCategory: MAX_ATTENTION_REFS, attentionRefBytesPerCategory: MAX_VALUE_BYTES }
         };
     });
@@ -65,15 +82,16 @@ export function readTaskContext(store, taskId, environment = {}) {
 function summarizeAttention(store, taskId, allow) {
     const group = () => ({ count: 0, refs: [], omittedRefs: 0 });
     const attention = {
-        openInputs: group(), pendingOperations: group(), unknownOperations: group()
+        openInputs: group(), pendingOperations: group(), unknownOperations: group(), messages: group()
     };
     for (const [category, family, statuses] of [
         ["openInputs", "input-request", ["open"]],
         ["pendingOperations", "job", ["queued", "running"]],
-        ["unknownOperations", "job", ["unknown-needs-attention"]]
+        ["unknownOperations", "job", ["unknown-needs-attention"]],
+        ["messages", "task-message", undefined]
     ]) {
         const page = store.queryContextRecords(taskId, {
-            family, statuses, ids: allowedIds(allow, family), limit: MAX_ATTENTION_REFS
+            family, statuses, descending: category === "messages", ids: allowedIds(allow, family), limit: MAX_ATTENTION_REFS
         });
         const summary = attention[category];
         summary.count = page.count;
@@ -152,22 +170,58 @@ export function inspectTaskContext(store, taskId, selector, environment = {}) {
                 currentRef: entry.ref
             });
         }
-        if (Buffer.byteLength(JSON.stringify(entry.value)) > MAX_INSPECT_BYTES) {
-            throw usageError("Context value exceeds the bounded inspect limit.", undefined, { ref: entry.ref, maxBytes: MAX_INSPECT_BYTES });
-        }
         const expansion = selector.store === "task-message"
             ? expandTaskMessageResult(value, (task, run) => reader.getRun(task, run))
             : undefined;
         const response = { ...entry, ...(expansion !== undefined && "result" in expansion
                 ? { result: expansion.result } : {}),
             ...(selector.store === "run" ? { execution: runExecutionObservation(value, reader.getTaskRoleSessionSet(taskId, value.roleName)?.providerBinding, reader.listEventsByType(taskId, ["runtime.agent-error"])) } : {}),
-            coreCursor: encode(currentCursor(reader, taskId)) };
-        if (Buffer.byteLength(JSON.stringify(response)) > MAX_INSPECT_BYTES) {
-            throw usageError("Expanded Context exceeds the bounded inspect limit.", undefined, { ref: entry.ref, maxBytes: MAX_INSPECT_BYTES });
+        };
+        return boundedDocument(response, `task:${taskId}/${selector.store}/${selector.refId}`, selector.cursor);
+    });
+}
+/** Discover one authorized family without copying its bodies or unrelated Task
+ * state. Content-version cursors fail explicitly if the collection changes.
+ */
+export function listTaskContext(store, taskId, family, options = {}, environment = {}) {
+    return store.readTransaction(reader => {
+        const scope = authorizeContext(reader, taskId, environment);
+        const sources = authorizedSources(reader, scope, false, family);
+        if (!CONTEXT_FAMILIES.includes(family))
+            throw usageError(`Unknown Context store: ${family}.`);
+        if (options.after !== undefined && !Number.isFinite(Date.parse(options.after)))
+            throw usageError("Invalid --after timestamp.");
+        const retiredKind = family === "task-message" ? "message" : family === "run" ? "run" : undefined;
+        const retired = retiredKind === undefined ? undefined
+            : retiredTaskRecordIds(reader.listEventsByType(taskId, [TASK_RECORD_RETIRED_EVENT]), retiredKind);
+        const records = [];
+        for (const source of sources) {
+            for (let offset = 0; offset < source.count; offset += MAX_RECORDS) {
+                for (const entry of source.read(offset)) {
+                    const value = entry.value;
+                    if (options.status !== undefined && value.status !== options.status
+                        || options.workItemId !== undefined && value.workItemId !== options.workItemId
+                        || options.after !== undefined && Date.parse(String(value.createdAt)) <= Date.parse(options.after))
+                        continue;
+                    records.push({ ref: entry.ref, summary: summarize(value),
+                        ...(retired === undefined ? {} : { history: retired.has(entry.ref.refId) ? "retired" : "active" }),
+                        ...Object.fromEntries(["status", "kind", "type", "createdAt", "roleName", "assignee", "purpose", "workItemId", "reviewRoundId"]
+                            .filter(key => typeof value[key] === "string").map(key => [key, value[key]])) });
+                }
+            }
         }
-        return response;
+        return recordPage(records, `task:${taskId}/${family}/${JSON.stringify({
+            status: options.status, after: options.after, workItemId: options.workItemId
+        })}`, options);
     });
 }
+export const CONTEXT_FAMILIES = [
+    "task", "task-brief", "remote-delivery", "role", "role-profile",
+    "project-policy", "project-knowledge", "input-request", "work-item",
+    "accepted-work-item", "candidate", "environment-preparation", "managed-workspace",
+    "change-set", "task-message", "run", "source-run", "review-round", "mailbox",
+    "task-decision", "task-milestone", "job", "publication", "task-event"
+];
 export function listContextMessages(store, taskId, environment = {}) {
     return store.readTransaction((reader) => {
         const { allow } = authorizeContext(reader, taskId, environment);
@@ -220,8 +274,7 @@ export function resolveContextReader(store, environment) {
         throw usageError("Only Operator may read Task context from a global Session.");
     }
     if (caller === undefined && environment.YUI_SESSION_SCOPE === undefined
-        && (environment.YUI_ROLE !== undefined || environment.YUI_NATIVE_SESSION_ID !== undefined
-            || environment.YUI_TASK_ID !== undefined || environment.YUI_AGENT_ID !== undefined)) {
+        && hasManagedIdentity(environment)) {
         throw usageError("Incomplete managed Context caller identity.");
     }
     if (environment.YUI_SESSION_SCOPE !== undefined && !["task", "global"].includes(environment.YUI_SESSION_SCOPE)) {
@@ -241,7 +294,7 @@ function authorizeContext(store, taskId, environment) {
         if (caller.currentRunId === undefined)
             throw usageError("A managed Role needs a current AgentRun to read its scoped Context.");
         const pack = buildRunContextPack(store, taskId, caller.currentRunId);
-        allow = new Set(pack.authority.readableRefs.map((ref) => `${ref.store}:${ref.refId}`));
+        allow = new Set(pack.pointers.map((ref) => `${ref.store}:${ref.refId}`));
         allow.add(`role:${caller.roleName}`);
         allow.add(`turn:${caller.currentRunId}`);
         // Shared current user intent and this exact Assignment's live steers augment
@@ -389,31 +442,35 @@ function inspectValue(store, { task, allow, caller }, { store: family, refId })
         default: return null;
     }
 }
-function authorizedSources(store, { task, allow, caller }) {
+function authorizedSources(store, { task, allow, caller }, current = false, requestedFamily) {
     const taskId = task.id;
     const sources = [];
     const add = (family, id, value) => {
-        if (value !== null && isAllowed(allow, family, id)) {
-            sources.push({ count: 1, read: () => [materialize(family, id, value)] });
+        if ((requestedFamily === undefined || requestedFamily === family) && value !== null && isAllowed(allow, family, id)) {
+            sources.push({ family, count: 1, read: () => [materialize(family, id, value)] });
         }
     };
     const query = (family, options = {}) => {
+        if (requestedFamily !== undefined && requestedFamily !== family)
+            return;
         const selection = { ...options, family, ids: allowedIds(allow, family) };
         const { count } = store.queryContextRecords(taskId, { ...selection, limit: 0 });
-        sources.push({ count, *read() {
+        sources.push({ family, count, *read(offset = 0) {
                 for (const { id, value } of store.queryContextRecords(taskId, {
-                    ...selection, limit: MAX_RECORDS
+                    ...selection, offset, limit: current ? 8 : MAX_RECORDS
                 }).records)
                     yield materialize(family, id, value);
             } });
     };
     add("task", taskId, task);
     add("task-brief", taskId, store.getTaskBrief(taskId));
-    if (allow === undefined)
+    if (allow === undefined && (requestedFamily === undefined || requestedFamily === "remote-delivery")) {
         add("remote-delivery", taskId, projectTaskRemoteDeliveryFromStore(store, task));
+    }
     for (const role of store.listRoles(taskId)) {
         add("role", role.name, role);
-        add("role-profile", role.name, roleProfile(role));
+        if (!current)
+            add("role-profile", role.name, roleProfile(role));
     }
     for (const binding of task.projectBindings) {
         const project = store.getProject(binding.projectId);
@@ -427,42 +484,48 @@ function authorizedSources(store, { task, allow, caller }) {
     }
     // Current responsibilities and unanswered inputs precede historical bulk.
     query("input-request", { statuses: ["open"] });
-    query("work-item");
+    query("work-item", current ? { excludeStatuses: ["accepted", "retired"] } : {});
     for (const id of allowedIds(allow, "accepted-work-item") ?? []) {
         add("accepted-work-item", id, store.getWorkItem(taskId, id));
     }
-    query("candidate");
+    if (!current)
+        query("candidate");
     // File artifacts are not enumerated into the synchronous Context listing: the
     // core cursor does not cover file edits and an ambient directory index here
     // would be the forbidden update-time mirror (§3.7). Current artifacts are
     // listed on demand via the async `artifact.list` capability; frozen Candidate
     // artifacts remain reachable as commit-pinned pointers under their Candidate.
-    query("environment-preparation");
+    if (!current)
+        query("environment-preparation");
     query("managed-workspace");
     if (caller?.currentRunId !== undefined) {
         add("managed-workspace", `${taskId}/${caller.roleName}`, store.getRun(taskId, caller.currentRunId)?.workspace ?? null);
     }
-    query("change-set");
+    if (!current)
+        query("change-set");
     query("task-message", { descending: true });
-    query("run", { descending: true });
+    query("run", { descending: true, ...(current ? { statuses: ["active"] } : {}) });
     for (const id of allowedIds(allow, "source-turn") ?? []) {
         const run = store.getRun(taskId, id);
         if (run !== null)
             add("source-run", id, sourceRunContextValue(run));
     }
-    query("review-round", { descending: true });
-    query("input-request", { excludeStatuses: ["open"] });
-    if (allow === undefined) {
+    query("review-round", { descending: true, ...(current ? { statuses: ["pending", "running"] } : {}) });
+    if (!current)
+        query("input-request", { excludeStatuses: ["open"] });
+    if (!current && allow === undefined) {
         add("mailbox", "task", store.getWorkMailbox({ kind: "task", taskId }));
         for (const role of store.listRoles(taskId)) {
             add("mailbox", `role:${role.name}`, store.getWorkMailbox({ kind: "role", taskId, roleName: role.name }));
         }
     }
-    query("task-decision");
-    query("task-milestone");
-    query("job");
-    query("publication");
-    query("task-event", { descending: true });
+    query("task-decision", current ? { statuses: ["active"] } : {});
+    if (!current) {
+        query("task-milestone");
+        query("publication");
+        query("task-event", { descending: true });
+    }
+    query("job", current ? { statuses: ["queued", "running", "unknown-needs-attention"] } : {});
     return sources;
 }
 export function materialize(store, refId, value) {
@@ -512,7 +575,7 @@ function freeze(value) {
 }
 function summarize(value) {
     const record = value;
-    return ["title", "objective", "summary", "body", "status"]
+    return ["title", "objective", "question", "summary", "body", "status", "type"]
         .flatMap((key) => typeof record[key] === "string" ? [`${key}: ${record[key]}`] : [])
         .join("; ").slice(0, 400);
 }

package/dist/controller/clientRuntime.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { describeCliFailure } from "../errors/cliFailure.js";
 import { fileURLToPath } from "node:url";
 import { findLiveControllerProcessForHome, inspectLiveControllerProcess } from "../core/controllerProcessIdentity.js";
 import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
@@ -77,7 +78,7 @@ export async function ensureFileTaskController(home, options = {}) {
         ? findLiveControllerProcessForHome(readHomeFilesystemId(home))
         : undefined;
     const startupPid = existing?.pid
-        ?? spawnController(home, controllerSpawnEnvironment(home, options.environment ?? process.env));
+        ?? await spawnController(home, controllerSpawnEnvironment(home, options.environment ?? process.env));
     const deadline = Date.now() + timeoutMs;
     for (;;) {
         try {
@@ -129,15 +130,15 @@ function assertControllerRuntimeProcessIdentity(value, expected) {
         || actual.controllerProtocolVersion !== expected.controllerProtocolVersion
         || actual.storageVersion !== expected.storageVersion
         || actual.minimumStorageVersion !== expected.minimumStorageVersion) {
-        throw new Error("Authenticated Controller runtime identity does not match the captured executable, argv, package, protocol and storage versions; refusing readiness.");
+        throw new ControllerClientError("CONTROLLER_IDENTITY_MISMATCH", "Authenticated Controller runtime identity does not match the captured executable, argv, package, protocol and storage versions; refusing readiness.");
     }
 }
 function assertCompatibleControllerStatus(status, expectedIdentity) {
     const statusRecord = isJsonRecord(status) && status.running === true ? status : null;
     const actual = statusRecord?.protocolVersion;
     if (statusRecord === null || actual !== FILE_TASK_CONTROLLER_PROTOCOL_VERSION) {
-        throw new Error(`Controller protocol is incompatible (expected ${FILE_TASK_CONTROLLER_PROTOCOL_VERSION}, found ${typeof actual === "number" ? actual : "unknown"}). `
-            + "Run `yui controller restart` before writing new task records.");
+        throw new ControllerClientError("CONTROLLER_PROTOCOL_MISMATCH", `Controller protocol is incompatible (expected ${FILE_TASK_CONTROLLER_PROTOCOL_VERSION}, found ${typeof actual === "number" ? actual : "unknown"}). `
+            + "Verify Home, CLI and Controller identity before an authorized restart.");
     }
     const actualVersion = statusRecord.version;
     const current = yuiVersionIdentity();
@@ -146,14 +147,21 @@ function assertCompatibleControllerStatus(status, expectedIdentity) {
         version: typeof actualVersion === "string" ? actualVersion : current.version
     } : parseControllerIdentity(expectedIdentity));
 }
-function spawnDetachedFileTaskController(_home, environment) {
+async function spawnDetachedFileTaskController(_home, environment) {
     const child = spawn(process.execPath, [fileURLToPath(new URL("./controllerMain.js", import.meta.url))], {
         env: environment,
         detached: true,
         stdio: "ignore"
     });
-    child.unref();
-    return child.pid;
+    // Route asynchronous spawn failures back through the command's normal error
+    // boundary instead of Node's unhandled "error" event / raw stack output.
+    return await new Promise((resolve, reject) => {
+        child.once("error", error => reject(new Error("Controller process could not start.", { cause: error })));
+        child.once("spawn", () => {
+            child.unref();
+            resolve(child.pid);
+        });
+    });
 }
 /** Stops the per-home Controller and waits until its owned discovery is gone. */
 export async function stopFileTaskController(home, options = {}) {
@@ -398,7 +406,7 @@ function classifyRefreshFailure(error, options) {
     options.onError?.(error);
     return {
         status: "failed",
-        message: error instanceof Error ? error.message : String(error)
+        message: describeCliFailure(error).message
     };
 }
 /** Foreground command bridge. It never reads or writes Agent terminal bytes. */

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -6,6 +6,7 @@ import { settleGlobalRetryInput } from "../message/globalProviderRetry.js";
 import { interruptThenTerminalState, prepareMessageContinuations } from "../message/messageContinuation.js";
 import { assertExecutionEnvironmentCurrent } from "../runtime/executionEnvironment.js";
 import { deferProviderRetry, providerRetryPending, providerRetryProjection, recordProviderFailure } from "../runtime/providerRetry.js";
+import { createTaskMessage } from "../message/message.js";
 import { AgentHostObservationDeferred, recordAgentHostConnection, resolveAgentHostObservation } from "./agentHostObservation.js";
 import { admitOwnedProviderInput, ownedProviderInput } from "./providerRetryAdmission.js";
 import { RuntimeHookRunFenceError } from "./runtimeHookRunFence.js";
@@ -1243,6 +1244,29 @@ export class FileSchedulerStoreAdapter {
                 }
             }
             binding = admitOwnedProviderInput(store, binding, input);
+            // The Host's human console is a user ingress. Persist its original text
+            // before the Provider write; provider-visible userMessage items alone
+            // are NOT proof of human authorship (managed prompts use those too).
+            // This shares the exact writer/session admission and its transaction.
+            if (input.authorityOwner === "human" && input.roleName === "leader"
+                && input.runId === undefined && input.boundedText !== undefined) {
+                const prior = store.listEvents(input.taskId).find(event => event.type === "message.native-user-input" && event.payload.attemptId === input.attemptId);
+                if (prior !== undefined) {
+                    const message = store.listMessages(input.taskId).find(entry => entry.id === prior.payload.messageId);
+                    if (message?.body !== input.boundedText || prior.payload.nativeSessionId !== input.nativeSessionId) {
+                        throw new AgentHostProviderTurnFenceError("Native user input identity was reused with different content.");
+                    }
+                }
+                else {
+                    const message = createTaskMessage(store.nextMessageId(input.taskId), input.taskId, input.boundedText, "user", { type: "user" }, input.now, { intent: "record" });
+                    store.saveMessage(input.taskId, message);
+                    store.saveEvent(input.taskId, createTaskEvent(store.nextEventId(input.taskId), input.taskId, "message.native-user-input", {
+                        messageId: message.id, attemptId: input.attemptId, nativeSessionId: input.nativeSessionId,
+                        authorityEpoch: String(input.authorityEpoch), holderId: input.holderId
+                    }, input.now));
+                    // No mailbox enqueue: this very input is already being delivered.
+                }
+            }
             store.saveTaskRoleSessionSet(updateTaskRoleProviderRuntime(sessions, beginProviderTurn(binding, {
                 ...(input.runId === undefined ? {} : { runId: input.runId }),
                 attemptId: input.attemptId,

package/dist/controller/runtime.js

@@ -1,4 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
+import { archiveLeaderTask } from "../task/leaderArchive.js";
+import { TaskWorkspaceCoordinator } from "../repository/taskWorkspaceCoordinator.js";
 import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, NATIVE_AGENT_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES } from "../agent/launchEnvironment.js";
 import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { reconciliationIntervalMilliseconds, resolveAgentLaunchInactivityTimeoutSeconds, resolveControllerTaskConcurrency, resolveDeliveryTimeoutSeconds, resolveRuntimeHealth, resolveTmuxBin, resolveTmuxHistoryLimit } from "../config/yuiConfig.js";
@@ -359,6 +361,10 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         // the poll interval.
         const kernel = createKernelPorts(store, createLinuxProcessPort(), (taskId) => {
             runningRuntime?.signal(`task:${taskId}`);
+        }, [], async (taskId, environment, request) => {
+            if (!(workspacePreparer instanceof FileTaskWorkspacePreparer))
+                throw new Error("Archive workspace owner unavailable.");
+            return archiveLeaderTask(store, new TaskWorkspaceCoordinator(store, workspacePreparer, webWorkflow), taskId, environment, request);
         });
         closeKernel = () => kernel.close();
         const webWorkflow = new FileTaskWorkflowRuntime(home, store, schedulerStore, planner, tmux, workspacePreparer, {

package/dist/core/controllerClient.js

@@ -8,9 +8,11 @@ import { readHomeFilesystemId } from "./homeFilesystemIdentity.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;
-    constructor(code, message, cause) {
+    diagnostic;
+    constructor(code, message, cause, diagnostic) {
         super(message, { cause });
         this.code = code;
+        this.diagnostic = diagnostic;
         this.name = "ControllerClientError";
     }
 }
@@ -33,12 +35,14 @@ export async function readControllerDiscovery(home) {
     try {
         const metadata = await lstat(discoveryPath);
         const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
-        if (!metadata.isFile()
-            || (metadata.mode & 0o077) !== 0
-            || metadata.size > 4_096
-            || (uid !== undefined && metadata.uid !== uid)) {
-            throw invalidDiscovery();
-        }
+        if (!metadata.isFile())
+            throw invalidDiscovery(new Error("Discovery path is not a regular file."));
+        if ((metadata.mode & 0o077) !== 0)
+            throw invalidDiscovery(new Error("Discovery record permissions are not owner-only."));
+        if (metadata.size > 4_096)
+            throw invalidDiscovery(new Error("Discovery record exceeds the 4096-byte limit."));
+        if (uid !== undefined && metadata.uid !== uid)
+            throw invalidDiscovery(new Error("Discovery record belongs to a different user."));
         const value = JSON.parse(await readFile(discoveryPath, "utf8"));
         const socketPath = discoverySocketPath(value);
         return parseControllerDiscovery(value, {
@@ -50,7 +54,7 @@ export async function readControllerDiscovery(home) {
         if (error instanceof ControllerClientError)
             throw error;
         if (isNodeError(error) && error.code === "ENOENT") {
-            throw new ControllerClientError("CONTROLLER_NOT_RUNNING", withOriginalError("Controller is not running.", error), error);
+            throw new ControllerClientError("CONTROLLER_NOT_RUNNING", withOriginalError("Controller discovery record is missing; process state is unverified.", error), error, { delivery: "not-sent" });
         }
         if (isNodeError(error) && (error.code === "EPERM" || error.code === "EACCES")) {
             throw controllerAccessDenied(error, "discovery record");
@@ -72,12 +76,22 @@ function discoverySocketPath(value) {
     return socketPath;
 }
 export async function callController(home, method, params = {}, options = {}) {
-    const discovery = await readControllerDiscovery(home);
+    const id = options.id ?? randomUUID();
+    let discovery;
+    try {
+        discovery = await readControllerDiscovery(home);
+    }
+    catch (error) {
+        if (!(error instanceof ControllerClientError))
+            throw error;
+        throw new ControllerClientError(error.code, error.message, error.cause, {
+            delivery: "not-sent", method, requestId: id
+        });
+    }
     const timeoutMs = options.timeoutMs ?? 5_000;
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
         throw new TypeError("Controller timeout must be a positive integer.");
     }
-    const id = options.id ?? randomUUID();
     let requestLine;
     try {
         requestLine = encodeControllerRequest({
@@ -93,11 +107,13 @@ export async function callController(home, method, params = {}, options = {}) {
     }
     catch (error) {
         if (error instanceof ControllerProtocolError) {
-            throw new ControllerClientError(error.code, error.message, error);
+            throw new ControllerClientError(error.code, error.message, error, {
+                delivery: "not-sent", method, requestId: id
+            });
         }
-        throw new ControllerClientError("INVALID_REQUEST", withOriginalError("Invalid controller request.", error), error);
+        throw new ControllerClientError("INVALID_REQUEST", withOriginalError("Invalid controller request.", error), error, { delivery: "not-sent", method, requestId: id });
     }
-    return exchange(discovery.socketPath, requestLine, id, timeoutMs);
+    return exchange(discovery.socketPath, requestLine, id, timeoutMs, method);
 }
 /**
  * Explicit restart recovery for an exact Controller whose discovery record
@@ -151,7 +167,7 @@ export async function stopOrphanedFileTaskController(home, timeoutMs, options =
     }
     return Object.freeze({ pid: candidate.pid });
 }
-function exchange(socketPath, requestLine, expectedId, timeoutMs) {
+function exchange(socketPath, requestLine, expectedId, timeoutMs, method) {
     return new Promise((resolve, reject) => {
         const socket = createConnection(socketPath);
         let buffer = Buffer.alloc(0);
@@ -174,7 +190,12 @@ function exchange(socketPath, requestLine, expectedId, timeoutMs) {
             settled = true;
             clearTimeout(timer);
             socket.destroy();
-            reject(error);
+            reject(new ControllerClientError(error.code, error.message, error.cause, {
+                delivery: error.diagnostic?.delivery ?? (deliveryStarted ? "unconfirmed" : "not-sent"),
+                method,
+                requestId: expectedId,
+                socketPath
+            }));
         };
         socket.on("connect", () => {
             // Once write begins, a missing response cannot prove that the Controller
@@ -202,7 +223,9 @@ function exchange(socketPath, requestLine, expectedId, timeoutMs) {
                 if (response.ok)
                     finish(response.result);
                 else
-                    fail(new ControllerClientError(response.error.code, response.error.message));
+                    fail(new ControllerClientError(response.error.code, response.error.message, undefined, {
+                        delivery: "response-received"
+                    }));
             }
             catch (error) {
                 fail(invalidResponse(error));
@@ -219,22 +242,22 @@ function exchange(socketPath, requestLine, expectedId, timeoutMs) {
 }
 export function classifyControllerSocketError(error, deliveryStarted) {
     if (deliveryStarted) {
-        return new ControllerClientError("CONTROLLER_DELIVERY_UNKNOWN", withOriginalError("Controller request delivery is unknown.", error), error);
+        return new ControllerClientError("CONTROLLER_DELIVERY_UNKNOWN", withOriginalError("Controller request delivery is unknown.", error), error, { delivery: "unconfirmed" });
     }
     if (isNodeError(error) && (error.code === "EPERM" || error.code === "EACCES")) {
         return controllerAccessDenied(error, "socket");
     }
-    return new ControllerClientError("CONTROLLER_UNAVAILABLE", withOriginalError("Controller is unavailable.", error), error);
+    return new ControllerClientError("CONTROLLER_UNAVAILABLE", withOriginalError("Controller is unavailable.", error), error, { delivery: "not-sent" });
 }
 function controllerAccessDenied(error, target) {
     return new ControllerClientError("CONTROLLER_ACCESS_DENIED", `Controller ${target} access was denied (${error.code}) before any request was sent. `
         + "In Codex, request sandbox escalation to rerun the same Yui CLI command outside the sandbox "
-        + `if authorized. If escalation is denied, report that to the user.${originalErrorDetail(error)}`, error);
+        + `if authorized. If escalation is denied, report that to the user.${originalErrorDetail(error)}`, error, { delivery: "not-sent" });
 }
 function invalidDiscovery(error) {
     return new ControllerClientError("CONTROLLER_DISCOVERY_INVALID", error === undefined
         ? "Controller discovery is invalid."
-        : withOriginalError("Controller discovery is invalid.", error), error);
+        : withOriginalError("Controller discovery is invalid.", error), error, { delivery: "not-sent" });
 }
 function invalidResponse(error) {
     return new ControllerClientError("INVALID_RESPONSE", error === undefined
@@ -248,7 +271,9 @@ function originalErrorDetail(error) {
     const code = isNodeError(error) && typeof error.code === "string"
         ? ` (${error.code})`
         : "";
-    return ` Original error${code}: ${error instanceof Error ? error.message : String(error)}`;
+    return ` Original error${code}: ${error instanceof SyntaxError
+        ? "Input could not be parsed; raw input omitted."
+        : error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown cause."}`;
 }
 function isNodeError(error) {
     return error instanceof Error && "code" in error;

package/dist/core/protocol.js

@@ -129,11 +129,16 @@ export function parseControllerDiscovery(value, expected) {
             "processStartIdentity",
             "socketPath",
             "token"
-        ])
-        || value.schemaVersion !== 1
-        || value.protocolVersion !== FILE_TASK_CONTROLLER_PROTOCOL_VERSION
-        || !isHomeId(value.homeId)
-        || value.homeFilesystemId !== expected.homeFilesystemId
+        ])) {
+        throw new ControllerProtocolError("CONTROLLER_DISCOVERY_INVALID", "Controller discovery fields are invalid.");
+    }
+    if (value.schemaVersion !== 1 || value.protocolVersion !== FILE_TASK_CONTROLLER_PROTOCOL_VERSION) {
+        throw new ControllerProtocolError("CONTROLLER_DISCOVERY_INVALID", "Controller discovery schema/protocol version does not match this CLI; verify the matching installation.");
+    }
+    if (value.homeFilesystemId !== expected.homeFilesystemId || value.socketPath !== expected.socketPath) {
+        throw new ControllerProtocolError("CONTROLLER_DISCOVERY_INVALID", "Controller discovery Home/socket identity does not match this invocation.");
+    }
+    if (!isHomeId(value.homeId)
         || !isHomeFilesystemId(value.homeFilesystemId)
         || typeof value.controllerInstanceId !== "string"
         || !/^[a-f0-9]{32}$/u.test(value.controllerInstanceId)
@@ -141,10 +146,10 @@ export function parseControllerDiscovery(value, expected) {
         || value.pid < 1
         || typeof value.processStartIdentity !== "string"
         || !/^[0-9]{1,32}$/u.test(value.processStartIdentity)
-        || value.socketPath !== expected.socketPath
+        || typeof value.socketPath !== "string"
         || typeof value.token !== "string"
         || !/^[a-f0-9]{64}$/u.test(value.token)) {
-        throw new ControllerProtocolError("CONTROLLER_DISCOVERY_INVALID", "Controller discovery is invalid.");
+        throw new ControllerProtocolError("CONTROLLER_DISCOVERY_INVALID", "Controller discovery process, Home or authentication identity is invalid; raw record omitted.");
     }
     return Object.freeze({
         schemaVersion: 1,

package/dist/doctor/doctor.js

@@ -7,6 +7,7 @@ import { operationalAgentEnvironment } from "../agent/launchEnvironment.js";
 import { resolveTmuxBin } from "../config/yuiConfig.js";
 import { compileRoleSessionContext } from "../context/roleSessionContext.js";
 import { callController, ControllerClientError } from "../core/controllerClient.js";
+import { describeCliFailure } from "../errors/cliFailure.js";
 import { EPHEMERAL_DOMAIN_GRACE_MS, readEphemeralDomainIdentity, readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
 import { usageError } from "../errors/cliError.js";
 import { inspectAgentCapabilities, resolveAgentAdapter } from "../executor/agentAdapter.js";
@@ -162,19 +163,19 @@ export async function checkController(home, probe = callController) {
     }
     catch (error) {
         if (error instanceof ControllerClientError && error.code === "CONTROLLER_NOT_RUNNING") {
-            return { name: "controller", status: "missing", detail: `${error.message} Run yui start.` };
+            return { name: "controller", status: "missing", detail: describeCliFailure(error).message };
         }
         if (error instanceof ControllerClientError && error.code === "CONTROLLER_UNAVAILABLE") {
             return {
                 name: "controller",
                 status: "invalid",
-                detail: `Controller is not reachable: ${error.message} Run yui start. Its process state is unverified.`
+                detail: describeCliFailure(error).message
             };
         }
         return {
             name: "controller",
             status: "invalid",
-            detail: `Controller status could not be verified: ${error instanceof Error ? error.message : String(error)}. Inspect yui controller status --verbose.`
+            detail: describeCliFailure(error).message
         };
     }
 }