@zq-silk/yui 1.1.2 → 2.1.0

package/dist/cli.js

@@ -12,6 +12,8 @@ import { nativeAgentEnvironmentNames } from "./agent/launchEnvironment.js";
 import { listArtifactsCapability, readArtifactCapability, saveArtifactCapability } from "./artifacts/artifactCapability.js";
 import { renderAgentConfigurationResolutionNotice } from "./cli/agentConfigurationPicker.js";
 import { describeCommandTree, findCommandNode } from "./cli/commandCatalog.js";
+import { discoveryCommandTree } from "./cli/commandDiscovery.js";
+import { contextRecordReader } from "./context/taskContext.js";
 import { renderCompletion } from "./cli/completion.js";
 import { runCompletionWizard } from "./cli/completionWizard.js";
 import { resolveCompletionCandidates } from "./cli/dynamicCompletion.js";
@@ -20,7 +22,8 @@ import { allowsInteractiveSelection, resolveInteractiveArguments } from "./cli/i
 import { routeInvocation } from "./cli/invocationRouter.js";
 import { operatorOfflineCommand, taskDiagnosticTarget } from "./cli/managedDiagnostics.js";
 import { assertConfigurationAuthority, assertTaskInvocationScope } from "./cli/invocationAuthority.js";
-import { requireManagedGlobalCaller } from "./runtime/managedCaller.js";
+import { requireManagedGlobalCaller, ManagedRuntimeDriftError } from "./runtime/managedCaller.js";
+import { hasManagedIdentity } from "./runtime/managedIdentity.js";
 import { resolveOperatorWizardArguments } from "./cli/operatorWizard.js";
 import { resolveGlobalRoleAgentConfigurationArguments, resolveRoleWizardArguments } from "./cli/roleWizard.js";
 import { runUpdateCommand } from "./cli/updateCommand.js";
@@ -41,7 +44,7 @@ import { runProjectCommand } from "./commands/projectCommands.js";
 import { renderReleaseActivateResult, renderReleaseInstallResult, renderReleaseList, resolveReleaseActivationDriver, runReleaseActivate, runReleaseInstall, runReleaseList } from "./commands/releaseCommands.js";
 import { runResourcesCommand } from "./commands/resourcesCommands.js";
 import { parseSessionReconcileOptions, parseSessionStopOptions, runSessionReconcileCommand, runSessionStopCommand } from "./commands/sessionCommands.js";
-import { assertTaskDeliveryAuthority, taskLocalActor } from "./task/taskAuthority.js";
+import { assertTaskDeliveryAuthority, taskLocalActor, resolveJobCaller } from "./task/taskAuthority.js";
 import { runTaskBaseStatusCommand } from "./commands/taskBaseCommands.js";
 import { runTaskChangeSetCommand } from "./commands/taskChangeSetCommands.js";
 import { assertWorkItemDependenciesCompletedForCommand, dispatchPreparedReviewRound, failPendingReviewRound, parseTaskArchiveArguments, parseTaskCompletionRequest, planReplicatedWorkItemLanes, preflightTaskCompletion, preserveReviewRoundWorkspace, previewTaskRoleAgentConfigurationMutation, requireWorkItemAssignee, runTaskCommand, validateTaskArchiveRequest } from "./commands/taskCommands.js";
@@ -58,7 +61,7 @@ import { runWorkflowCommandAsync } from "./commands/workflowCommands.js";
 import { FileCompletionManager } from "./completion/fileCompletionManager.js";
 import { CONFIG_DOMAINS } from "./config/configCatalog.js";
 import { resolveTmuxBin, resolveTmuxHistoryLimit } from "./config/yuiConfig.js";
-import { readSessionBootstrapManifest, refreshManagedSessionCliWrappers } from "./context/sessionBootstrapManifest.js";
+import { readSessionBootstrapManifest } from "./context/sessionBootstrapManifest.js";
 import { assertFileTaskControllerStorageCompatible, ensureFileTaskController, FileTaskWorkflowRuntime, refreshRunningFileTaskControllerConfiguration, refreshRunningFileTaskControllerEnvironment, restartFileTaskController, stopFileTaskController } from "./controller/clientRuntime.js";
 import { FileSchedulerStoreAdapter } from "./controller/fileSchedulerStoreAdapter.js";
 import { createControllerIntegrationJobPort } from "./controller/jobClient.js";
@@ -70,6 +73,7 @@ import { SessionOwnerReconciliation } from "./controller/sessionOwnerReconciliat
 import { callController, ControllerClientError } from "./core/controllerClient.js";
 import { buildDoctorReport, renderDoctor, runDoctorCommand } from "./doctor/doctor.js";
 import { agentNotFound, CliError, runtimeError, usageError } from "./errors/cliError.js";
+import { describeCliFailure, renderCliFailure, sanitizeFailureText, sanitizeFailureDetails } from "./errors/cliFailure.js";
 import { AgentConfigurationCatalogService, validateAgentLaunchConfiguration } from "./executor/agentConfigurationCatalog.js";
 import { FileRoleLaunchPlanner } from "./executor/fileRoleLaunchPlanner.js";
 import { createGitHubCliPublicationVerifier } from "./external/githubPublicationVerifier.js";
@@ -82,7 +86,7 @@ import { parseTaskAgentCapabilityQuery } from "./commands/taskAgentCapabilities.
 import { capabilityReaderIdentity } from "./controller/agentCapabilities.js";
 import { formatTimestamp } from "./output/timePresentation.js";
 import { resolveAgentProfileView } from "./profile/agentProfileRuntime.js";
-import { assertCliHomeReleaseFence, describeCliHomeInvocation } from "./release/cliHomeReleaseFence.js";
+import { assertCliHomeReleaseFence } from "./release/cliHomeReleaseFence.js";
 import { createReleaseWorkflowPorts } from "./release/releaseWorkflowPorts.js";
 import { acquireHandoverLock, readRuntimeIdentity } from "./release/runtimeRelease.js";
 import { NodeGitWorkspace } from "./repository/gitWorkspace.js";
@@ -102,7 +106,6 @@ import { requireManagedTaskCaller, resolveManagedTaskReader } from "./runtime/ma
 import { assertRuntimeCoherence } from "./runtime/runtimeCoherence.js";
 import { runSetupCommand, validateSetupInvocation } from "./setup/setupCommand.js";
 import { openCurrentTaskStore, validateCurrentTaskStore } from "./storage/currentTaskStore.js";
-import { SqliteSchemaError } from "./storage/sqliteSchema.js";
 import { inspectStorageSchema } from "./storage/storageSchema.js";
 import { resolveYuiHome } from "./storage/taskStore.js";
 import { renderArchiveDiagnostics, taskArchiveDiagnostics } from "./task/archiveDiagnostics.js";
@@ -123,51 +126,44 @@ const taskFinalReviewInvocation = extractTaskFinalReviewRequest(process.argv.sli
 const rawArgs = [...taskFinalReviewInvocation.args];
 const jsonOutput = rawArgs.includes("--json");
 const args = normalizeAliases(jsonOutput ? rawArgs.filter((argument) => argument !== "--json") : rawArgs);
+let invocationHome;
 void main().catch((error) => {
     if (error instanceof CleanupInspectionError) {
         error = cleanupCliError(error, error.checks[0]?.resource ?? "workspace");
     }
-    if (error instanceof CliError) {
-        const rendered = jsonOutput
-            ? JSON.stringify({ ok: false, code: error.code, message: error.message, details: error.details })
-            : `${error.code}: ${error.message}${error.helpText === undefined ? "" : `\n\n${error.helpText.trimEnd()}`}`;
-        process.stderr.write(`${rendered}\n`);
-        process.exitCode = error.exitCode;
-        return;
-    }
-    const message = runtimeFailureMessage(error);
-    process.stderr.write(`${jsonOutput
-        ? JSON.stringify({ ok: false, code: "RUNTIME_ERROR", message, details: {} })
-        : `RUNTIME_ERROR: ${message}`}\n`);
-    process.exitCode = 5;
+    const failure = describeCliFailure(error, failureContext());
+    process.stderr.write(`${renderCliFailure(failure, jsonOutput)}\n`);
+    process.exitCode = failure.exitCode;
 });
-function runtimeFailureMessage(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (error instanceof ControllerClientError
-        && ["CONTROLLER_NOT_RUNNING", "CONTROLLER_UNAVAILABLE", "CONTROLLER_DISCOVERY_INVALID"].includes(error.code)) {
-        return `${message} Run \`yui doctor\` with this Session's YUI_HOME and CLI; `
-            + "if the Controller is stopped, run `yui start`; if its process is present but unreachable, "
-            + "inspect it before `yui controller restart`. The Operator or user can perform recovery.";
-    }
-    if (!(error instanceof SqliteSchemaError))
-        return message;
-    try {
-        return `${message}\n${describeCliHomeInvocation({
-            home: resolveYuiHome(process.env),
-            packageRoot: fileURLToPath(new URL("../", import.meta.url)),
-            entryPath: fileURLToPath(import.meta.url)
-        })}`;
-    }
-    catch {
-        return message;
-    }
+function failureContext() {
+    const route = routeInvocation(args);
+    const node = "node" in route ? route.node : route.helpNode;
+    const operands = args.slice(node.path.length - 1);
+    const publicValues = new Set([
+        ...Object.values(node.argumentValues).flat(),
+        ...Object.values(node.optionValues).flat()
+    ]);
+    const recordId = /^(?:task|project|message|run|work|wake|operation|review|input|job|integration|publication)-\d+(?:\/(?:message|run|work|wake|review|input|job|integration|publication)-\d+)?$/;
+    return {
+        operation: node.path.join(" "),
+        targets: operands.filter(value => recordId.test(value)),
+        // Do not replay argv: operands include Message bodies, config values and credentials.
+        privateValues: operands.filter(value => !/^--[a-z][a-z-]*$/.test(value) && !recordId.test(value) && !publicValues.has(value)),
+        home: invocationHome ?? process.env.YUI_HOME ?? "(default Home unresolved)",
+        cli: fileURLToPath(import.meta.url),
+        environment: process.env
+    };
 }
 export async function main() {
     const home = resolveYuiHome(process.env);
+    const discovery = discoveryCommandTree(process.env);
+    invocationHome = home;
     const routedForFence = args.length === 0 ? undefined : routeInvocation(args);
     const managedInvocation = process.env.YUI_SESSION_SCOPE === "task"
         || process.env.YUI_SESSION_SCOPE === "global";
     const homeFreeInvocation = args.length === 0
+        || (args[0] === "config" && (args[1] === "describe"
+            || (args[1] === "completion" && args[2] === "candidates")))
         || (args[0] === "version" && args.length === 1)
         || routedForFence?.kind === "help"
         || routedForFence?.kind === "path-error"
@@ -188,7 +184,7 @@ export async function main() {
             stdio: "inherit"
         });
         if (delegated.error !== undefined) {
-            throw runtimeError(`Target release activation driver could not start: ${delegated.error.message}`);
+            throw runtimeError("Target release activation driver could not start.", { cause: delegated.error });
         }
         if (delegated.signal !== null) {
             throw runtimeError(`Target release activation driver stopped by signal ${delegated.signal}.`);
@@ -197,16 +193,16 @@ export async function main() {
         return;
     }
     if (args.length === 0) {
-        emit(renderCommandHelp((await import("./cli/commandCatalog.js")).ROOT_COMMAND, VERSION));
+        emit(renderCommandHelp(discovery, VERSION), false, jsonOutput ? describeCommandTree(discovery) : undefined);
         return;
     }
     if (args[0] === "version" && args.length === 1) {
         emit(VERSION, true, yuiVersionIdentity());
         return;
     }
-    const invocation = routeInvocation(args);
+    const invocation = routeInvocation(args, discovery);
     if (invocation.kind === "help") {
-        emit(renderCommandHelp(invocation.node, VERSION), true);
+        emit(renderCommandHelp(invocation.node, VERSION), true, jsonOutput ? describeCommandTree(invocation.node) : undefined);
         return;
     }
     if (invocation.kind === "path-error") {
@@ -217,11 +213,22 @@ export async function main() {
     }
     if (args[0] === "version")
         throw usageError("Version usage: yui version");
+    // Offline discovery is not an execution credential. Target selectors enter
+    // the original authenticated path lazily, only when stored data is needed.
+    if (args[0] === "config" && args[1] === "completion" && args[2] === "candidates") {
+        await completionCommand(home, invocation.node);
+        return;
+    }
+    if (args[0] === "config" && args[1] === "describe") {
+        const target = findCommandNode(args[2] === undefined ? ["config"] : ["config", args[2]], discovery);
+        if (args.length > 3 || !target)
+            throw usageError("Config describe usage: yui config describe [visible-domain].");
+        emit(renderCommandHelp(target, VERSION), false, describeCommandTree(target));
+        return;
+    }
     const { contract: taskFinalReviewContract, verifiedStore } = await preflightManagedTaskControlPlane();
     assertTaskInvocationScope(args, process.env);
-    if (["config", "resources"].includes(args[0] ?? "") && (managedInvocation
-        || process.env.YUI_ROLE !== undefined || process.env.YUI_AGENT_ID !== undefined
-        || process.env.YUI_NATIVE_SESSION_ID !== undefined)) {
+    if (["config", "resources"].includes(args[0] ?? "") && hasManagedIdentity(process.env)) {
         const ownedStore = verifiedStore === undefined ? openCurrentTaskStore(home) : undefined;
         try {
             assertConfigurationAuthority(args, verifiedStore ?? ownedStore, process.env);
@@ -240,7 +247,10 @@ export async function main() {
         const subcommand = args[1];
         if (subcommand === "install" && args.length === 3) {
             const result = runReleaseInstall(home, args[2]);
-            emit(renderReleaseInstallResult(result), false, result);
+            if (result.outcome === "aborted")
+                emitFailureResult(renderReleaseInstallResult(result), result);
+            else
+                emit(renderReleaseInstallResult(result), false, result);
             if (result.outcome === "aborted")
                 process.exitCode = 5;
             return;
@@ -259,7 +269,11 @@ export async function main() {
                     + "(or activate the active release when exactly one is installed).");
             }
             const result = await runReleaseActivate(home, releaseId);
-            emit(renderReleaseActivateResult(result), false, result);
+            if (result.outcome === "aborted" || result.outcome === "dual-owner") {
+                emitFailureResult(renderReleaseActivateResult(result), result);
+            }
+            else
+                emit(renderReleaseActivateResult(result), false, result);
             if (result.outcome === "aborted" || result.outcome === "dual-owner") {
                 process.exitCode = 5;
             }
@@ -271,21 +285,6 @@ export async function main() {
         await completionCommand(home, invocation.node);
         return;
     }
-    if (args[0] === "config" && args[1] === "describe") {
-        const describeNode = findCommandNode(["config", "describe"]);
-        if (describeNode === undefined)
-            throw new Error("Config describe command is missing from the catalog.");
-        const domain = args[2];
-        const domains = describeNode.argumentValues[0] ?? [];
-        if (args.length > 3 || (domain !== undefined && !domains.includes(domain))) {
-            throw usageError(`Config describe usage: ${describeNode.usage.join(" | ")}.`);
-        }
-        const target = findCommandNode(domain === undefined ? ["config"] : ["config", domain]);
-        if (target === undefined)
-            throw new Error(`Config domain is missing from the catalog: ${domain}.`);
-        emit(renderCommandHelp(target, VERSION), false, describeCommandTree(target));
-        return;
-    }
     if (args[0] === "capability") {
         const result = await runCapabilityCommand(args.slice(1), home, process.env);
         emit(JSON.stringify(result, null, 2), false, result);
@@ -356,7 +355,7 @@ export async function main() {
                 codex = await prepareLocalCodexStartup(startupStore, home, process.env);
             }
             catch (error) {
-                throw runtimeError(`Controller is ready, but Codex shared startup failed: ${error instanceof Error ? error.message : String(error)}`);
+                throw runtimeError("Controller is ready, but Codex shared startup failed.", { cause: error });
             }
             const lines = ["Yui Controller is ready."];
             if (codex.daemons.length === 0)
@@ -398,20 +397,13 @@ export async function main() {
     if (args[0] === "upgrade") {
         const result = await runUpgradeCommand(args.slice(1), home);
         process.exitCode = result.exitCode;
-        emit(result.output, false, result.data);
+        if (result.exitCode !== 0)
+            emitFailureResult(result.output, result.data);
+        else
+            emit(result.output, false, result.data);
         return;
     }
     if (args[0] === "internal") {
-        if (args[1] === "session-cli-refresh" && args.length === 2) {
-            if (process.env.YUI_SESSION_SCOPE === "task"
-                || (process.env.YUI_SESSION_SCOPE === "global" && process.env.YUI_ROLE !== "operator")) {
-                throw usageError("Managed Session CLI refresh may be run only by the user or global Operator.");
-            }
-            const result = refreshManagedSessionCliWrappers(home, currentInvocationEntryPoint());
-            emit(`Refreshed ${result.refreshed} managed Session CLI wrapper(s); `
-                + `${result.current} already current, ${result.skipped} skipped.`, false, result);
-            return;
-        }
         if (args[1] === "agent-host" && args.length === 3) {
             process.exitCode = await runAgentHost({
                 home,
@@ -483,17 +475,7 @@ export async function main() {
             catch (error) {
                 if (!(error instanceof ControllerClientError))
                     throw error;
-                if (jsonOutput) {
-                    process.stderr.write(`${JSON.stringify({
-                        ok: false,
-                        code: error.code,
-                        message: error.message,
-                        details: {}
-                    })}\n`);
-                }
-                else {
-                    process.stderr.write(`RUNTIME_ERROR: ${error.message}\n`);
-                }
+                process.stderr.write(`${renderCliFailure(describeCliFailure(error, failureContext()), jsonOutput, error.code)}\n`);
                 process.exitCode = 5;
             }
             return;
@@ -517,17 +499,7 @@ export async function main() {
                 // unknown-active block.
                 if (!(error instanceof ControllerClientError))
                     throw error;
-                if (jsonOutput) {
-                    process.stderr.write(`${JSON.stringify({
-                        ok: false,
-                        code: error.code,
-                        message: error.message,
-                        details: {}
-                    })}\n`);
-                }
-                else {
-                    process.stderr.write(`RUNTIME_ERROR: ${error.message}\n`);
-                }
+                process.stderr.write(`${renderCliFailure(describeCliFailure(error, failureContext()), jsonOutput, error.code)}\n`);
                 process.exitCode = 5;
             }
             return;
@@ -674,7 +646,7 @@ export async function main() {
         yuiHome: home,
         historyLimit: resolveTmuxHistoryLimit(store.getConfig().tmuxHistoryLimit),
         terminalInput: process.stdin,
-        onWarning: (message) => process.stderr.write(`Warning: ${message}\n`)
+        onWarning: (message) => writeCliWarning(message)
     });
     const telemetry = openSchedulerTelemetry(home, store.getConfig());
     try {
@@ -684,8 +656,11 @@ export async function main() {
         const runtime = new FileTaskWorkflowRuntime(home, store, schedulerStore, planner, tmux, workspacePreparer, {
             environment: process.env,
             onError: (error) => {
-                const message = error instanceof Error ? error.message : String(error);
-                process.stderr.write(`Controller runtime error: ${message}\n`);
+                // Advisory async failure: preserve the foreground command's exit status.
+                const failure = describeCliFailure(error, failureContext());
+                process.stderr.write(`${renderCliFailure({
+                    ...failure, details: { ...failure.details, advisory: true }
+                }, jsonOutput)}\n`);
             }
         });
         const workspaceCoordinator = new TaskWorkspaceCoordinator(store, workspacePreparer, runtime);
@@ -845,6 +820,10 @@ export async function main() {
                 ? [resolved[1], ...resolved.slice(2)]
                 : ["session", resolved[1] ?? "", ...resolved.slice(2)];
             const result = runGlobalRoleCommand(sessionArgs, store, roleOptions);
+            if (typeof result !== "string" && result.kind === "output") {
+                emit(result.output, false, result.data);
+                return;
+            }
             if (typeof result === "string") {
                 emit(result);
                 return;
@@ -893,6 +872,14 @@ export async function main() {
                 emit(result);
                 return;
             }
+            if (result.kind === "output") {
+                if (globalInputFailure !== undefined) {
+                    emitControlFailure(globalInputFailure.detail, globalInputFailure.code, globalInputFailure.data);
+                }
+                else
+                    emit(result.output, false, result.data);
+                return;
+            }
             if (result.kind === "input-steer") {
                 // Core already persisted the durable Global Message and proved target +
                 // capability + writer fence from the Global Role's own Session set. This
@@ -1101,8 +1088,7 @@ export async function main() {
                         finalizeStoppedTaskExecution(result.taskId, store);
                     }
                     catch (error) {
-                        const message = error instanceof Error ? error.message : String(error);
-                        throw runtimeError(`Task execution is stopped and durable progress is preserved, but physical runtime cleanup failed: ${message}`);
+                        throw runtimeError("Task execution is stopped and durable progress is preserved, but physical runtime cleanup failed.", { cause: error });
                     }
                     emit(result.output, false, result);
                     return;
@@ -1317,6 +1303,19 @@ export async function main() {
             let archiveRemoteDeliveryProof;
             let archiveTaskReviewCandidate;
             if (resolved[1] === "archive") {
+                const request = parseTaskArchiveArguments(resolved.slice(2));
+                if (request.sourceMessage !== undefined) {
+                    if (request.force || request.disposition !== "integrated") {
+                        throw usageError("Leader ordinary archive does not authorize --force or --abandon.");
+                    }
+                    const result = await callController(home, "capability.call", {
+                        taskId: request.taskId, caller: resolveJobCaller(process.env, request.taskId),
+                        request: { name: "task.archive", requestId: request.requestId,
+                            input: { taskId: request.taskId, sourceMessage: request.sourceMessage, purpose: request.purpose } }
+                    });
+                    emit("Controller archive result; inspect task events if this Session ends before the receipt.\n", false, result);
+                    return;
+                }
                 const { taskId, disposition, force } = validateTaskArchiveRequest(resolved.slice(2), store, {
                     runtime,
                     environment: process.env,
@@ -1497,7 +1496,7 @@ export async function main() {
                             })
                     });
                     for (const warning of completionWarnings) {
-                        process.stderr.write(`Warning: ${warning}\n`);
+                        writeCliWarning(warning);
                     }
                     // Refresh observes remote objects only. Choosing and executing an
                     // upstream Integration belongs to its explicit command, never completion.
@@ -1962,6 +1961,9 @@ async function preflightManagedTaskControlPlane() {
         if (process.env.YUI_SESSION_SCOPE === "global") {
             return await preflightManagedGlobalControlPlane();
         }
+        if (hasManagedIdentity(process.env)) {
+            throw usageError("Managed Agent identity is incomplete; refusing to infer user authority.");
+        }
         if (taskFinalReviewInvocation.request !== undefined) {
             throw new Error("Task final-review contract may only be established from the Task Leader's managed Session.");
         }
@@ -2035,7 +2037,7 @@ async function preflightManagedGlobalControlPlane() {
     const expectedRoleKind = process.env.YUI_ROLE === "operator" ? "operator" : "global";
     if (manifest.owner.scope !== "global"
         || manifest.roleKind !== expectedRoleKind) {
-        throw new Error("Managed global invocation does not match its Session Manifest.");
+        throw new ManagedRuntimeDriftError("Managed global invocation does not match its Session Manifest.");
     }
     if (expectedRoleKind === "operator" && ["doctor", "upgrade", "update"].includes(args[0] ?? "")) {
         // These commands inspect/adopt the storage contract themselves. Requiring
@@ -2059,28 +2061,24 @@ async function preflightManagedGlobalControlPlane() {
     }
     return { contract: undefined, verifiedStore };
 }
-/**
- * The entry point the current invocation resolves to. Only its executable and
- * CLI path are used, to retarget managed Session wrappers at this installation.
- */
-function currentInvocationEntryPoint() {
-    return {
-        executable: process.execPath,
-        cliEntry: fileURLToPath(import.meta.url)
-    };
-}
 function assertManagedSessionManifest(home, scope) {
     const manifestPath = process.env.YUI_SESSION_MANIFEST;
     if (manifestPath === undefined) {
-        throw new Error("Managed control-plane invocation requires its Session Manifest.");
+        throw new ManagedRuntimeDriftError("Managed control-plane invocation requires its Session Manifest.");
+    }
+    let manifest;
+    try {
+        manifest = readSessionBootstrapManifest(manifestPath);
+    }
+    catch (error) {
+        throw new ManagedRuntimeDriftError("Managed Session Manifest could not be verified.", { cause: error });
     }
-    const manifest = readSessionBootstrapManifest(manifestPath);
     if (manifest.owner.scope !== scope) {
-        throw new Error("Managed invocation scope does not match its Session Manifest.");
+        throw new ManagedRuntimeDriftError("Managed invocation scope does not match its Session Manifest.");
     }
     if (scope === "task" && (manifest.owner.scope !== "task"
         || manifest.owner.taskId !== process.env.YUI_TASK_ID)) {
-        throw new Error("Managed Task invocation does not match its Session Manifest owner.");
+        throw new ManagedRuntimeDriftError("Managed Task invocation does not match its Session Manifest owner.");
     }
     const expectedPath = resolve(home, "runtime", "session-manifests", `${manifest.digest}.json`);
     // YUI_HOME is canonicalized (its macOS /var -> /private/var prefix is a
@@ -2093,7 +2091,7 @@ function assertManagedSessionManifest(home, scope) {
         canonicalManifestPath = resolve(manifestPath);
     }
     if (canonicalManifestPath !== expectedPath) {
-        throw new Error("Managed Session Manifest path is outside this YUI_HOME.");
+        throw new ManagedRuntimeDriftError("Managed Session Manifest path is outside this YUI_HOME.");
     }
     return manifest;
 }
@@ -2104,7 +2102,7 @@ function cleanupCliError(error, fallbackResource) {
     if (error instanceof WorkspaceCleanupBlockedError) {
         return usageError(error.message, undefined, cleanupBlockedDetails(error.reason, error.resource, error.retryable));
     }
-    return new CliError("RUNTIME_ERROR", error instanceof Error ? error.message : String(error), undefined, cleanupBlockedDetails("cleanup-failed", fallbackResource, true));
+    return new CliError("RUNTIME_ERROR", error instanceof Error ? error.message : String(error), undefined, cleanupBlockedDetails("cleanup-failed", fallbackResource, true), { cause: error });
 }
 function cleanupBlockedDetails(reason, resource, retryable, checks) {
     return {
@@ -2540,7 +2538,7 @@ async function prepareCodexForCurrentRoles(store, home, targetAgentId) {
         }
     }
     catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
+        const detail = describeCliFailure(error, failureContext()).message;
         const permissionDenied = isCodexInspectionPermissionError(error);
         codexAppNotice(`${permissionDenied
             ? "Codex sharing could not be prepared or verified from this process"
@@ -2559,7 +2557,7 @@ function assertHomeStartupAuthority(store) {
     requireManagedGlobalCaller(store, process.env);
 }
 function codexAppNotice(message, notification) {
-    process.stderr.write(`\nYui: ${message}\n`);
+    writeCliWarning(message);
     if (process.platform !== "darwin")
         return;
     // The native TUI clears terminal output on attach, so keep the actionable
@@ -2569,6 +2567,12 @@ function codexAppNotice(message, notification) {
         `display notification "${notification}" with title "Yui"`
     ], { stdio: "ignore", timeout: 3_000 });
 }
+function writeCliWarning(message) {
+    const safe = sanitizeFailureText(message, failureContext());
+    process.stderr.write(`${jsonOutput
+        ? JSON.stringify({ ok: false, code: "RUNTIME_ERROR", message: safe, details: { advisory: true } })
+        : `Warning: ${safe}`}\n`);
+}
 function renderControllerResult(method, value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return JSON.stringify(value);
@@ -2595,10 +2599,23 @@ async function completionCommand(home, node) {
         if (prefix === undefined || separator !== 4) {
             throw usageError("Completion candidates usage: yui config completion candidates <prefix> -- <words...>");
         }
+        let selection;
         const candidates = await resolveCompletionCandidates({
             current: prefix,
             words: args.slice(separator + 1),
-            ports: completionSelectionPorts(home)
+            root: discoveryCommandTree(process.env),
+            ports: { call: async (method, params) => {
+                    if (!selection) {
+                        assertCliHomeReleaseFence({
+                            home, packageRoot: fileURLToPath(new URL("../", import.meta.url)),
+                            entryPath: fileURLToPath(import.meta.url), args
+                        });
+                        await preflightManagedTaskControlPlane();
+                        assertTaskInvocationScope(args.slice(separator + 1), process.env);
+                        selection = completionSelectionPorts(home);
+                    }
+                    return selection.call(method, params);
+                } }
         });
         process.stdout.write(candidates.length === 0 ? "" : `${candidates.join("\n")}\n`);
         return;
@@ -2771,13 +2788,12 @@ async function warmConfigurationMutationCatalog(commandArgs, store, catalogs) {
 async function liveHostObservationsForTaskCommand(args, store, home) {
     if (args[0] !== "task" || args[1] !== "role")
         return undefined;
-    const inspect = args[2] === "session" && args[3] === "inspect" && args.length === 6;
-    const status = args[2] === "status" && args.length === 5;
-    const list = args[2] === "list" && args.length === 4;
-    if (!inspect && !status && !list)
+    const inspect = args[2] === "session" && args[3] === "inspect" && args.length >= 6;
+    const status = args[2] === "status" && args.length >= 5;
+    if (!inspect && !status)
         return undefined;
     const taskId = args[inspect ? 4 : 3];
-    const roles = list ? store.listRoles(taskId).map(role => role.name) : [args[inspect ? 5 : 4]];
+    const roles = [args[inspect ? 5 : 4]];
     const entries = await Promise.all(roles.map(async (roleName) => [
         roleName, await readLiveHostObservation(store, home, taskId, roleName)
     ]));
@@ -2942,7 +2958,37 @@ function completionSelectionPorts(home) {
         return { call: () => [] };
     }
     const store = readableStore(home);
-    return selectionPorts(store, new AgentConfigurationCatalogService(home, { environment: process.env }));
+    const ports = selectionPorts(store, new AgentConfigurationCatalogService(home, { environment: process.env }));
+    if (process.env.YUI_SESSION_SCOPE !== "task")
+        return ports;
+    const taskId = process.env.YUI_TASK_ID;
+    const readable = contextRecordReader(store, taskId, process.env);
+    const families = {
+        "task.list": "task", "project.list": "project-policy", "task.role.list": "role",
+        "task.work.list": "work-item", "task.message.list": "task-message", "task.input.list": "input-request",
+        "task.turn.list": "run", "task.decision.list": "task-decision", "task.milestone.list": "task-milestone",
+        "task.event.list": "task-event", "task.change-set.list": "change-set",
+        "task.integration.list": "integration-attempt"
+    };
+    return { call: async (method, params) => {
+            if (params.taskId !== undefined && params.taskId !== taskId)
+                return [];
+            const family = families[method];
+            if (!family)
+                return []; // Completion never needs broader authority than Context.
+            const scopedParams = method === "task.input.list" ? { ...params, taskId } : params;
+            const values = await ports.call(method, scopedParams);
+            if (!Array.isArray(values))
+                return [];
+            return values.filter(value => {
+                const id = String(value.id ?? value.name ?? "");
+                if (method === "task.list" && id !== taskId)
+                    return false;
+                if (method === "project.list" && !store.getTask(taskId)?.projectBindings.some(binding => binding.projectId === id))
+                    return false;
+                return readable(family, id);
+            });
+        } };
 }
 function emit(output, literal = false, data) {
     const normalized = literal ? output.trimEnd() : output.trimEnd();
@@ -2954,9 +3000,17 @@ function emit(output, literal = false, data) {
 }
 function emitControlFailure(message, code, details) {
     process.exitCode = 2;
+    const context = failureContext();
+    const safeMessage = sanitizeFailureText(message.trim(), context);
+    const safeDetails = sanitizeFailureDetails({ value: details }, context).value;
     process.stdout.write(`${jsonOutput
-        ? JSON.stringify({ ok: false, code, message: message.trim(), details })
-        : message.trim()}\n`);
+        ? JSON.stringify({ ok: false, code, message: safeMessage, details: safeDetails })
+        : safeMessage}\n`);
+}
+/** Domain-owned failure reports retain their output envelope and effect receipts. */
+function emitFailureResult(output, data) {
+    const context = failureContext();
+    emit(sanitizeFailureText(output, context), false, sanitizeFailureDetails({ value: data }, context).value);
 }
 /**
  * The human line for a live steer, corrected to the *actual* live acceptance

package/dist/commands/capabilityCommands.js

@@ -3,7 +3,7 @@ import { resolveJobCaller } from "../task/taskAuthority.js";
 import { callFileTaskController } from "../controller/clientRuntime.js";
 export async function runCapabilityCommand(args, home, environment) {
     const [action, ...rest] = args;
-    const usage = "yui capability search [query] --task <id> | commands --task <id> | panels --task <id> | describe <name> --task <id> [--provider <id>] [--version <version>] | call <name> --task <id> --input <json> [--provider <id>] [--version <version>] [--request-id <id>]";
+    const usage = "yui capability search [query] --task <id> | commands --task <id> | panels --task <id> | describe <name> --task <id> [--input <json>] [--provider <id>] [--version <version>] | call <name> --task <id> --input <json> [--provider <id>] [--version <version>] [--request-id <id>]";
     if (!["search", "commands", "panels", "describe", "call"].includes(action))
         throw usageError(usage);
     const surfaceList = action === "commands" || action === "panels";
@@ -29,12 +29,12 @@ export async function runCapabilityCommand(args, home, environment) {
         throw usageError(usage);
     if ((action === "search" || surfaceList) && [...flags.keys()].some((key) => key !== "--task"))
         throw usageError(usage);
-    if (action === "describe" && (flags.has("--input") || flags.has("--request-id")))
+    if (action === "describe" && flags.has("--request-id"))
         throw usageError(usage);
     let input;
-    if (action === "call") {
-        if (!flags.has("--input"))
-            throw usageError("Capability call requires --input <json>.", usage);
+    if (action === "call" && !flags.has("--input"))
+        throw usageError("Capability call requires --input <json>.", usage);
+    if (flags.has("--input")) {
         try {
             input = JSON.parse(flags.get("--input"));
         }

package/dist/commands/controllerCommands.js

@@ -1,4 +1,5 @@
 import { usageError } from "../errors/cliError.js";
+import { describeCliFailure } from "../errors/cliFailure.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { DEFAULT_RECONCILIATION_INTERVAL_SECONDS } from "../config/yuiConfig.js";
 import { evaluateStorageHealth, UNSUPPORTED } from "../observability/runtimeIdentity.js";
@@ -280,7 +281,7 @@ export async function runInteractiveControllerCleanup(input) {
         catch (error) {
             failed.push({
                 id: resource.id,
-                message: error instanceof Error ? error.message : String(error)
+                message: describeCliFailure(error).message
             });
         }
     }