@zq-silk/yui 2.21.0 → 2.22.0

package/README.md

@@ -459,6 +459,11 @@ manage global installations; do not use the global `yui` to validate local chang
 Live-model, paid or shared-resource
 tests require an explicit request for those resources.
 
+For topic-specific evaluation and shared evidence tools, see
+[evaluation tooling](scripts/eval/README.md).
+`npm run eval:check` is fast and offline; `eval:context:wiring` is an explicit isolated
+fake-Provider check, outside the default core gate. It is not model validation.
+
 ## Community and support
 
 - Questions, bugs and feature requests: open a

package/dist/cli/commandCatalog.js

@@ -1,4 +1,5 @@
 import { supportedAgentAdapterIds } from "../agent/adapterCatalog.js";
+import { CONTEXT_FAMILIES } from "../context/contextFamilies.js";
 import { supportedAgentExecutionComponentIds } from "../agent/executionComponents.js";
 import { productConfigurationOptions } from "../nativeAgent/product/config.js";
 import { catalogCommands, catalogCommandOptions } from "../nativeAgent/product/catalog.js";
@@ -142,6 +143,7 @@ const roleProfileOptions = [
 ];
 const roleAgentOptions = [
     "--model", "--effort", "--permission-strategy", "--sandbox", "--approval", "--permission-mode",
+    "--exclude-tmpdir-env-var", "--exclude-slash-tmp",
     "--allowed-tool", "--disallowed-tool", "--search"
 ];
 const roleProfileClearOptions = [
@@ -151,7 +153,7 @@ const roleProfileClearOptions = [
 ];
 const roleAgentClearOptions = [
     "--clear-model", "--clear-effort", "--clear-allowed-tools", "--clear-disallowed-tools",
-    "--clear-search", "--clear-agent-config"
+    "--clear-search", "--clear-agent-config", "--clear-exclude-tmpdir-env-var", "--clear-exclude-slash-tmp"
 ];
 const agentProfileOptions = [
     "--description", "--instructions", "--skill",
@@ -164,6 +166,8 @@ const agentProfileClearOptions = [
 const roleAgentOptionValues = {
     "--sandbox": ["read-only", "workspace-write", "danger-full-access"],
     "--approval": ["untrusted", "on-request", "never"],
+    "--exclude-tmpdir-env-var": ["true", "false"],
+    "--exclude-slash-tmp": ["true", "false"],
     "--permission-strategy": ["default", "bypass", "configured"],
     "--search": ["true"]
 };
@@ -234,7 +238,8 @@ const globalSessionChildren = [
     {
         name: "retry", discovery: { surface: "public", audiences: ["public", "operator"] },
         summary: "Inspect or control bounded Provider recovery for this Global Session.",
-        usage: "yui session retry <role> [show|cancel|disable|enable]"
+        usage: "yui session retry <role> [show|cancel|disable|enable] [--cursor <cursor> (show only)]",
+        options: ["--cursor"]
     }
 ];
 const profileChildren = [
@@ -426,10 +431,41 @@ const taskChildren = [
     },
     {
         name: "context", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "unbound"] },
-        summary: "Read compact authorized facts, fixed-bound delta, or inspect a Context reference.",
-        usage: "yui task context [read|list|delta|inspect] <task> [--after <cursor>] [--continuation <cursor>] [--cursor <cursor>] [--limit <n>] [--store <store> --ref <id>] [--digest <digest>] [--view <current|all>]",
-        options: ["--after", "--continuation", "--cursor", "--limit", "--store", "--ref", "--digest", "--status", "--work-item", "--view"],
-        optionValues: { "--view": ["current", "all"] }
+        summary: "Read current authorized facts; discover references or inspect complete originals with a focused subcommand.",
+        executable: true,
+        usage: "yui task context <task>",
+        sections: [{ id: "read", title: "Context reads", entries: ["read", "list", "inspect", "delta"] }],
+        children: [
+            {
+                name: "read", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "unbound"] },
+                summary: "Read the current bounded Task index, equivalent to task context <task>.",
+                usage: "yui task context read <task>"
+            },
+            {
+                name: "list", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "unbound"] },
+                summary: "Discover one authorized family. --after filters creation time, not later edits; current excludes explicit ACK/retirement.",
+                usage: "yui task context list <task> --store <store> [--cursor <cursor>] [--limit <1..100>] [--view current|all] [--status <status>] [--after <timestamp>] [--work-item <id>]",
+                options: ["--store", "--cursor", "--limit", "--view", "--status", "--after", "--work-item"],
+                optionValues: { "--view": ["current", "all"], "--store": CONTEXT_FAMILIES }
+            },
+            {
+                name: "inspect", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "unbound"] },
+                summary: "Read complete originals. Choose one single-ref or 1–8-ref batch form; finish contentPage using the same selection and cursor.",
+                usage: [
+                    "yui task context inspect <task> --store <store> --ref <id> [--digest <digest>] [--cursor <cursor>]",
+                    "yui task context inspect <task> --context-ref <store/refId@digest> ... [--cursor <cursor>]",
+                    "yui task context inspect <task> --refs <JSON-array-of-store-refId-digest> [--cursor <cursor>]"
+                ],
+                options: ["--store", "--ref", "--digest", "--context-ref", "--refs", "--cursor"],
+                optionValues: { "--store": CONTEXT_FAMILIES }
+            },
+            {
+                name: "delta", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "unbound"] },
+                summary: "Read fixed-bound event history after coreCursor, not current record bodies. Use throughCursor for the next window.",
+                usage: "yui task context delta <task> --after <cursor> [--continuation <cursor>] [--limit <1..100>]",
+                options: ["--after", "--continuation", "--limit"]
+            }
+        ]
     },
     {
         name: "next-action", discovery: { surface: "managed", audiences: ["operator", "leader"] },
@@ -708,11 +744,11 @@ const taskChildren = [
             { name: "list", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Discover recorded Role health; Host is unchecked until role status.", usage: "yui task role list <task> [--limit <1..100>] [--cursor <cursor>]", options: ["--limit", "--cursor"] },
             {
                 name: "status", discovery: { surface: "managed", audiences: ["operator", "leader"] },
-                summary: "Show persisted and live runtime state for one Task Role.",
-                usage: "yui task role status <task> <role> [--cursor <cursor>]",
-                options: ["--cursor"]
+                summary: "Show current execution observations; full includes nested original records.",
+                usage: "yui task role status <task> <role> [--view current|full] [--cursor <cursor>]",
+                options: ["--view", "--cursor"], optionValues: { "--view": ["current", "full"] }
             },
-            { name: "show", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Show one Task Role.", usage: "yui task role show <task> <role> [--cursor <cursor>]", options: ["--cursor"] },
+            { name: "show", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Show current Role configuration; full adds Session and Run history.", usage: "yui task role show <task> <role> [--view current|full] [--cursor <cursor>]", options: ["--view", "--cursor"], optionValues: { "--view": ["current", "full"] } },
             { name: "enable", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Enable this Task Role; does not change Task execution authority.", usage: "yui task role enable <task> <role>" },
             { name: "disable", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Block new execution of this Task Role without stopping its current Run.", usage: "yui task role disable <task> <role>" },
             { name: "capabilities", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Read native options using this Role's desired or exact failed launch configuration.",
@@ -738,7 +774,8 @@ const taskChildren = [
                     {
                         name: "retry", discovery: { surface: "managed", audiences: ["operator", "leader"] },
                         summary: "Inspect or control Provider recovery without stopping an admitted Turn.",
-                        usage: "yui task role session retry <task> <role> [show|cancel|disable|enable]"
+                        usage: "yui task role session retry <task> <role> [show|cancel|disable|enable] [--cursor <cursor> (show only)]",
+                        options: ["--cursor"]
                     },
                     {
                         name: "inspect", discovery: { surface: "managed", audiences: ["operator", "leader"] },
@@ -912,9 +949,9 @@ const taskChildren = [
             { name: "list", discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] }, summary: "Discover AgentRuns for a Task or one WorkItem.", usage: "yui task run list <task|task/work> [--limit <1..100>] [--cursor <cursor>]", options: ["--limit", "--cursor"] },
             {
                 name: "show", discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] },
-                summary: "Show one AgentRun and its retained audit evidence.",
-                usage: "yui task run show <task>/<run> [--cursor <cursor>] [--json]",
-                options: ["--cursor", "--json"]
+                summary: "Read full audit evidence, current status, or the complete original result without input/configuration bodies.",
+                usage: "yui task run show <task>/<run> [--view full|status|result] [--cursor <cursor>] [--json]",
+                options: ["--view", "--cursor", "--json"]
             },
             {
                 name: "retry", discovery: { surface: "managed", audiences: ["operator", "leader"] },
@@ -937,9 +974,12 @@ const taskChildren = [
                 children: [
                     {
                         name: "expand", discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] },
-                        summary: "Expand one authorized AgentRun context reference.",
-                        usage: "yui task run context expand <task>/<run> <ref-id> --store <store> [--mode full] [--cursor <cursor>]",
-                        options: ["--store", "--mode", "--cursor"]
+                        summary: "Read one frozen original or 1–8 explicitly selected originals from the same authorized Run.",
+                        usage: [
+                            "yui task run context expand <task>/<run> <ref-id> --store <store> [--mode full] [--cursor <cursor>]",
+                            "yui task run context expand <task>/<run> --context-ref <store/refId[@digest]> ... [--cursor <cursor>]"
+                        ],
+                        options: ["--store", "--context-ref", "--mode", "--cursor"]
                     },
                     {
                         name: "delta", discovery: { surface: "managed", audiences: ["operator", "leader", "assignment"] },
@@ -1122,7 +1162,7 @@ const taskChildren = [
             { name: "show", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Show fixed wake inputs/results; expand diagnostics with --history.", usage: "yui task wake show <task> <wake> [--history] [--cursor <cursor>]", options: ["--history", "--cursor"] },
             { name: "retry", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Retry a rejected notification after correcting its cause; preserve original input.",
                 usage: "yui task wake retry <task> <wake> --reason <correction>", options: ["--reason"] },
-            { name: "resolve", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Release an unknown notification claim after explicit quiescence evidence, without replay.",
+            { name: "resolve", discovery: { surface: "managed", audiences: ["operator", "leader"] }, summary: "Release an unknown or rejected notification for explicit handling after quiescence evidence, without replay.",
                 usage: "yui task wake resolve <task> <wake> --reason <quiescence-evidence>", options: ["--reason"] }
         ]
     },
@@ -1239,7 +1279,12 @@ export const ROOT_COMMAND = buildNode({
                 }
             ]
         },
-        { name: "help", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global", "unbound"] }, summary: "Show root or scoped command help.", usage: "yui help [command ...]", commandPathArguments: true },
+        {
+            name: "help", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global", "unbound"] },
+            summary: "Show root or scoped command help; JSON defaults to immediate child summaries.",
+            usage: ["yui help [command ...]", "yui --json help [command ...] --recursive"],
+            options: ["--recursive"], commandPathArguments: true
+        },
         { name: "version", discovery: { surface: "public", audiences: ["public", "operator", "leader", "assignment", "global", "unbound"] }, summary: "Print the installed Yui version." },
         {
             name: "update", discovery: { surface: "public", audiences: ["public", "operator"] },
@@ -1811,8 +1856,7 @@ export function findCommandNode(path, root = ROOT_COMMAND) {
     return node;
 }
 export const findCommand = findCommandNode;
-/** Structured help projection consumed by `config describe --json` and Operator. */
-export function describeCommandTree(node) {
+function describeCommand(node) {
     return {
         path: node.path.slice(1).join(" "),
         summary: node.summary,
@@ -1821,8 +1865,25 @@ export function describeCommandTree(node) {
         options: node.options,
         optionValues: node.optionValues,
         argumentValues: node.argumentValues,
-        values: node.values,
-        children: visibleChildren(node).map(describeCommandTree)
+        values: node.values
+    };
+}
+/** Complete caller-filtered tree for explicit recursive help and offline tools. */
+export function describeCommandTree(node) {
+    return { ...describeCommand(node), children: visibleChildren(node).map(describeCommandTree) };
+}
+/** Complete current-command details; descendants require explicit navigation. */
+export function describeCommandHelp(node) {
+    return {
+        ...describeCommand(node),
+        children: visibleChildren(node).map(child => ({
+            path: child.path.slice(1).join(" "), summary: child.summary
+        })),
+        discovery: {
+            children: "complete-immediate-summaries",
+            details: "yui --json help <command ...>",
+            tree: "yui --json help [command ...] --recursive"
+        }
     };
 }
 export function validateCommandCatalog(root) {
@@ -1857,7 +1918,6 @@ export function validateCommandCatalog(root) {
                 || node.children.length > 0
                 || node.values.length > 0
                 || node.sections.length > 0
-                || node.options.length > 0
                 || node.hiddenOptions.length > 0
                 || Object.keys(node.optionValues).length > 0
                 || Object.keys(node.argumentValues).length > 0
@@ -1865,7 +1925,7 @@ export function validateCommandCatalog(root) {
                 || node.fileArguments.length > 0
                 || node.executableOptions.length > 0;
             if (ownsOtherCompletionMetadata) {
-                throw new Error(`Command-path provider must be a visible metadata-free leaf: ${node.path.join(" ")}`);
+                throw new Error(`Command-path provider must be a visible leaf with only flag options: ${node.path.join(" ")}`);
             }
         }
         const immediate = new Set();

package/dist/cli/dynamicCompletion.js

@@ -8,7 +8,10 @@ export async function resolveCompletionCandidates(input) {
     const root = input.root ?? ROOT_COMMAND;
     if (words[0] === "help") {
         const { node, consumed } = resolveCommand(words.slice(1), root);
-        return consumed === words.length - 1 ? prefix(visibleChildren(node).map(child => child.name), input.current) : [];
+        if (consumed !== words.length - 1)
+            return [];
+        return prefix(input.current.startsWith("-") ? findChild(root, "help")?.options ?? []
+            : visibleChildren(node).map(child => child.name), input.current);
     }
     const { node, consumed } = resolveCommand(words, root);
     if (node.kind === "group" && consumed < words.length)

package/dist/cli/helpRenderer.js

@@ -1,4 +1,14 @@
-import { visibleCommandSections } from "./commandCatalog.js";
+import { orderedImmediateTokens, visibleCommandSections } from "./commandCatalog.js";
+/** A path error needs nearby choices, not another complete help document.
+ * The caller supplies the already-filtered discovery node. */
+export function renderCommandPathHint(node) {
+    const choices = orderedImmediateTokens(node);
+    const path = node.path.slice(1).join(" ");
+    return [
+        ...(choices.length === 0 ? [] : [`Visible choices here: ${choices.join(", ")}`]),
+        `Full help: yui --json help${path ? ` ${path}` : ""}`
+    ].join("\n") + "\n";
+}
 export function renderCommandHelp(node, version) {
     const title = node.path.length === 1
         ? `Yui ${version}`
@@ -30,6 +40,7 @@ function describeOption(option) {
         "--detach": "Return after Controller starts Web; use --status / --stop. Operator and --json starts always return.",
         "--port": "Set the local listen port.",
         "--json": "Emit machine-readable JSON.",
+        "--recursive": "Expand the complete caller-filtered command tree (requires --json).",
         "--project": "Select a Project.",
         "--role": "Select a Task role.",
         "--summary": "Set summary text.",

package/dist/cli/interactionPolicy.js

@@ -88,6 +88,7 @@ export const INTERACTION_POLICIES = Object.freeze([
             "--responsibility": "value", "--constraint": "value", "--expected-output": "value",
             "--system-prompt": "value", "--skill": "value", "--model": "value",
             "--effort": "value", "--permission-strategy": "value", "--sandbox": "value", "--approval": "value",
+            "--exclude-tmpdir-env-var": "value", "--exclude-slash-tmp": "value",
             "--permission-mode": "value", "--allowed-tool": "value", "--disallowed-tool": "value",
             "--search": "value"
         }
@@ -374,6 +375,7 @@ export const INTERACTION_POLICIES = Object.freeze([
             "--constraint": "value", "--expected-output": "value", "--system-prompt": "value",
             "--skill": "value", "--model": "value", "--effort": "value",
             "--permission-strategy": "value", "--sandbox": "value", "--approval": "value", "--permission-mode": "value",
+            "--exclude-tmpdir-env-var": "value", "--exclude-slash-tmp": "value",
             "--allowed-tool": "value", "--disallowed-tool": "value", "--search": "value"
         }
     },

package/dist/cli/invocationRouter.js

@@ -18,20 +18,20 @@ export function routeInvocation(args, discoveryRoot = ROOT_COMMAND) {
     return { ...result, helpNode };
 }
 function resolveHelpPath(path, root) {
-    if (path.length === 0)
-        return { kind: "help", node: root };
+    const recursive = path.at(-1) === "--recursive";
+    const segments = recursive ? path.slice(0, -1) : path;
     let node = root;
     let nearestGroup = root;
-    for (const segment of path) {
+    for (const segment of segments) {
         const child = findChild(node, segment);
         if (child === undefined || child.hidden) {
-            return { kind: "path-error", typedPath: path.join(" "), helpNode: nearestGroup };
+            return { kind: "path-error", typedPath: path.join(" "), helpNode: nearestGroup, discoveryOnly: true };
         }
         node = child;
         if (node.kind !== "leaf")
             nearestGroup = node;
     }
-    return { kind: "help", node };
+    return { kind: "help", node, recursive };
 }
 function resolveExecutionPath(args) {
     let node = ROOT_COMMAND;

package/dist/cli/roleWizard.js

@@ -459,7 +459,11 @@ function agentFields(binding, catalog) {
         agentField("permission-strategy", "Permission strategy", permission.strategy, "--permission-strategy", ["--permission-strategy", "default"], catalogField(catalog, "permission.strategy")),
         ...(binding.adapterId === "codex" && permission.strategy === "configured" ? [
             agentField("sandbox", "Sandbox", permission.sandbox, "--sandbox", ["--permission-strategy", "default"], catalogField(catalog, "permission.sandbox")),
-            agentField("approval", "Approval", permission.approval, "--approval", ["--permission-strategy", "default"], catalogField(catalog, "permission.approval"))
+            agentField("approval", "Approval", permission.approval, "--approval", ["--permission-strategy", "default"], catalogField(catalog, "permission.approval")),
+            ...(permission.sandbox === "workspace-write" ? [
+                agentField("exclude-tmpdir-env-var", "Exclude TMPDIR write access", permission.excludeTmpdirEnvVar, "--exclude-tmpdir-env-var", ["--clear-exclude-tmpdir-env-var"], catalogField(catalog, "permission.excludeTmpdirEnvVar")),
+                agentField("exclude-slash-tmp", "Exclude /tmp write access", permission.excludeSlashTmp, "--exclude-slash-tmp", ["--clear-exclude-slash-tmp"], catalogField(catalog, "permission.excludeSlashTmp"))
+            ] : [])
         ] : []),
         ...(binding.adapterId === "codex" ? [
             agentField("search", "Web search", config.search, "--search", ["--clear-search"], catalogField(catalog, "search"))

package/dist/commands/globalRoleCommands.js

@@ -151,6 +151,21 @@ function roleContext(args, store, options) {
         historyRead: "yui inbox list --view history --json",
         note: "Historical absence of handling evidence is not new work or permission to replay effects."
     });
+    // Only the managed Turn's exact inputs, not the available queue or history.
+    // Keep pending's cursor lineage unchanged; oversized originals retain their
+    // existing exact detail read. No delivery/claim/ACK is performed here.
+    let originalBudget = 8 * 1024;
+    const visibleIds = new Set(pending.items.map(message => message.id));
+    const category = globalInboxCategory(name, sessions);
+    const currentOriginals = selfRead ? current.filter(message => {
+        if (!visibleIds.has(message.id) || category(message) !== "current")
+            return false;
+        const bytes = Buffer.byteLength(JSON.stringify(message));
+        if (bytes > 4 * 1024 || bytes > originalBudget)
+            return false;
+        originalBudget -= bytes;
+        return true;
+    }) : [];
     const observedAt = new Date();
     const { oldestAgeMs, messages: _backlogMessages, ...backlog } = globalInputBacklog(queued, sessions, observedAt, {
         attention: name === "operator" ? store.getWorkMailbox({ kind: "operator" }) : null,
@@ -191,6 +206,7 @@ function roleContext(args, store, options) {
         },
         // Reading pending input is neither delivery nor implementation.
         pending,
+        currentOriginals,
         backlog,
         reads: {
             ownInbox: "yui inbox list --view current --json",
@@ -233,13 +249,16 @@ function roleContext(args, store, options) {
             ""
         ].join("\n") };
 }
-function currentGlobalInboxMessages(messages, name, sessions) {
+function globalInboxCategory(name, sessions) {
     const actor = { scope: "global", roleName: name, agentId: sessions?.activeAgentId ?? "",
         nativeSessionId: sessions?.sessions[sessions.activeAgentId]?.nativeSessionId ?? "" };
     const binding = sessions?.providerBinding;
     const turn = binding?.conversations.find(c => c.epoch === binding.currentConversationEpoch)?.conversationId === actor.nativeSessionId
         ? binding?.run : undefined;
-    const category = (message) => inboxEntryCategory(message, actor, turn);
+    return (message) => inboxEntryCategory(message, actor, turn);
+}
+function currentGlobalInboxMessages(messages, name, sessions) {
+    const category = globalInboxCategory(name, sessions);
     return pendingGlobalInboxMessages(messages).filter(message => category(message) !== "history")
         .sort((a, b) => Number(category(b) === "current") - Number(category(a) === "current"));
 }
@@ -506,11 +525,14 @@ function roleSession(args, store, options) {
     const [command, rawName, ...tail] = args;
     if (command === "retry") {
         const name = roleName(rawName);
-        const [action = "show", ...extra] = tail;
+        const parsed = readOptions(tail, ["--cursor"]);
+        const [action = "show", ...extra] = parsed.positionals;
         if (extra.length > 0 || !["show", "cancel", "disable", "enable"].includes(action)) {
             throw usageError("Usage: yui session retry <role> [show|cancel|disable|enable]");
         }
-        return store.transaction(tx => {
+        if (action !== "show" && parsed.cursor !== undefined)
+            throw usageError("Only retry show accepts --cursor.");
+        return store[action === "show" ? "readTransaction" : "transaction"](tx => {
             const role = requireRole(name, tx);
             const sessions = tx.getGlobalRoleSessionSet(name);
             let binding = sessions?.providerBinding ?? null;
@@ -523,12 +545,15 @@ function roleSession(args, store, options) {
             }
             const health = globalSessionHealth(role, sessions);
             const historical = binding?.retry !== undefined && health.retry === null;
-            return options.jsonOutput ? JSON.stringify({
+            const detail = {
                 roleName: name, retry: providerRetryProjection(binding), disabled: binding?.retryDisabled ?? false,
                 selectedNativeSessionId: health.nativeSessionId,
                 retryScope: historical ? "historical-session" : "current-session"
-            }) + "\n" : (historical ? "Historical Session evidence (not the selected Session's current failure): " : "")
-                + renderProviderRetry(binding) + "\n";
+            };
+            return options.jsonOutput ? JSON.stringify(action === "show"
+                ? boundedDocument(detail, `global:${name}/retry`, parsed.cursor) : detail) + "\n"
+                : (historical ? "Historical Session evidence (not the selected Session's current failure): " : "")
+                    + renderProviderRetry(binding) + "\n";
         });
     }
     if (command !== "record" && command !== "replace") {
@@ -715,7 +740,7 @@ function globalRoleMessage(args, store, options) {
         ["--request-id", false],
         ...(action === "steer" ? [["--expected-target", false]] : [])
     ]));
-    const body = readCommandText(positionalBody, parsed.one("--body-file"), "--body", usage);
+    const body = readCommandText(positionalBody, parsed.one("--body-file"), "--body", usage, { preserveFileWhitespace: true });
     const requestId = required(parsed.one("--request-id"), "--request-id");
     const expectedTarget = action === "steer"
         ? required(parsed.one("--expected-target"), "--expected-target")

package/dist/commands/inboxCommands.js

@@ -9,6 +9,8 @@ import { nonReplayableMessageWake, isLeaderSteer, pinMessageRevisions, releasedN
 import { hasRuntimeCleanupObligation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { isTaskRecordRetired, retiredTaskRecordIds } from "../task/taskRecordRetirement.js";
 import { blocksInboxOrder, inboxEntryCategory, inboxSettled } from "../message/inboxTurn.js";
+import { recoveredMessageContinuation } from "../controller/taskRunRecovery.js";
+import { taskWakeInspectionCommand } from "./taskCommands.js";
 const target = (address) => ({ kind: "role", taskId: address.taskId, roleName: address.roleName });
 const source = (address) => `inbox:${address.scope}:${address.taskId ?? ""}:${address.roleName}`;
 const pendingId = (pending) => `pending-${readDigest(pending)}`;
@@ -38,6 +40,16 @@ function currentTurn(store, address) {
     return binding?.conversations.find(c => c.epoch === binding.currentConversationEpoch)?.conversationId === address.nativeSessionId
         ? binding?.run : undefined;
 }
+function isRecoveredMessage(store, address, entry) {
+    if (address.scope !== "task" || address.runId === undefined || isWake(entry))
+        return false;
+    const run = store.getRun(address.taskId, address.runId);
+    return run !== null && recoveredMessageContinuation(store, entry, run);
+}
+function entryCategory(store, address, entry) {
+    return isRecoveredMessage(store, address, entry) ? "current"
+        : inboxEntryCategory(entry, address, currentTurn(store, address));
+}
 function ownsMessage(store, address, message) {
     if (address.roleName === "leader" && message.taskId === address.taskId && isLeaderSteer(message))
         return true;
@@ -138,7 +150,8 @@ function blocker(store, address, entry) {
     }
     else {
         const message = entry;
-        if (message.continuation?.runId !== undefined && message.continuation.runId !== address.runId) {
+        if (message.continuation?.runId !== undefined && message.continuation.runId !== address.runId
+            && !isRecoveredMessage(store, address, message)) {
             return "continuation-already-dispatched";
         }
         if (!accepted && message.inputControl?.expectedSessionId !== undefined
@@ -163,7 +176,7 @@ function checkMutation(store, address) {
 }
 function summary(store, address, entry) {
     return { id: entry.id, kind: isWake(entry) ? "notification-window" : "message",
-        category: inboxEntryCategory(entry, address, currentTurn(store, address)),
+        category: entryCategory(store, address, entry),
         createdAt: entry.createdAt, summary: summaryText(isWake(entry) ? entry.reasons.join(", ") : entry.body),
         blocked: blocker(store, address, entry) ?? null, inbox: summaryMetadata(entry.inbox ?? null),
         handling: inboxHandlingState(entry.inbox),
@@ -178,9 +191,14 @@ function summary(store, address, entry) {
         read: `yui inbox show ${entry.id}`, ...(isWake(entry)
             ? { originals: `yui task wake show ${entry.taskId} ${entry.id} --json` } : {}) };
 }
-function receipt(entry) {
+function receipt(entry, requestedId) {
+    // Pending-window inspection has no fixed originals yet. An existing wake
+    // can already have been read completely through inbox show; offer refresh
+    // without implying that claim invalidated those bodies or proved a read.
+    const originalRead = isWake(entry)
+        ? { [requestedId.startsWith("pending-") ? "originals" : "refreshOriginals"]: `yui task wake show ${entry.taskId} ${entry.id} --json` } : {};
     return { id: entry.id, inbox: entry.inbox,
-        ...(isWake(entry) ? { originals: `yui task wake show ${entry.taskId} ${entry.id} --json` } : {}) };
+        ...originalRead };
 }
 /** Own-address command: there is deliberately no --role, --task or --session.
  * Reads do not claim. Exact claim precedes semantic handling; exact ack follows
@@ -198,8 +216,7 @@ export function runInboxCommand(args, store, env, now = new Date()) {
         const selected = address.scope === "global" ? pendingGlobalInboxMessages(store.listGlobalRoleMessages(address.roleName))
             : entries(store, address).filter(entry => (isWake(entry) || !retired.has(entry.id))
                 && !inboxSettled(entry.inbox));
-        const turn = currentTurn(store, address);
-        const categories = selected.map(entry => ({ entry, category: inboxEntryCategory(entry, address, turn) }));
+        const categories = selected.map(entry => ({ entry, category: entryCategory(store, address, entry) }));
         const rank = { current: 0, available: 1, history: 2 };
         categories.sort((a, b) => rank[a.category] - rank[b.category]);
         const items = categories.filter(item => view === "all"
@@ -230,7 +247,17 @@ export function runInboxCommand(args, store, env, now = new Date()) {
                 note: "Claim this exact window before processing; claim returns its durable wake and original-read command." }, `${source(address)}/${id}`, parsed.cursor);
         }
         const entry = getEntry(store, address, id);
-        const value = !isWake(entry) && address.scope === "task"
+        if (isWake(entry)) {
+            // Own-inbox authorization above remains the boundary. Reuse the existing
+            // bounded focused originals rather than reconstructing a second view or
+            // making a claim mutation depend on a subsequent read succeeding.
+            const focused = taskWakeInspectionCommand(["show", entry.taskId, entry.id], store);
+            if (focused.kind !== "output")
+                throw new Error("Wake inspection did not return a read result.");
+            const { wake: _wake, ...originalContext } = focused.data;
+            return boundedDocument({ ...entry, originalContext }, `${source(address)}/${id}`, parsed.cursor);
+        }
+        const value = address.scope === "task"
             ? expandTaskMessageResult(entry, (task, run) => store.getRun(task, run)) : entry;
         return boundedDocument(value, `${source(address)}/${id}`, parsed.cursor);
     }
@@ -262,7 +289,7 @@ export function runInboxCommand(args, store, env, now = new Date()) {
                 if (existing.inboxPendingId !== id) {
                     throw new Error("Inbox request id was reused for a different window.");
                 }
-                return receipt(existing);
+                return receipt(existing, id);
             }
             const mailbox = tx.getWorkMailbox(target(current));
             if (!mailbox?.pending || pendingId(mailbox.pending) !== id)
@@ -310,7 +337,7 @@ export function runInboxCommand(args, store, env, now = new Date()) {
                     if (saved.requestId !== requestId || saved.reason !== reason || !sameSession(saved.actor, current)) {
                         throw new Error("Conflicting retirement; original disposition retained.");
                     }
-                    return receipt(entry);
+                    return receipt(entry, id);
                 }
                 // A retained attempt in an older conversation is still evidence of
                 // submission; changing the active Session cannot erase that boundary.
@@ -336,7 +363,7 @@ export function runInboxCommand(args, store, env, now = new Date()) {
                         throw new Error("Claim belongs to a previous Session; read the original and prior effects, then explicitly acknowledge only after finishing its handling.");
                     if (entry.inbox.claim.requestId !== requestId)
                         throw new Error("Entry already claimed; retain the original request id.");
-                    return receipt(entry);
+                    return receipt(entry, id);
                 }
                 const blocked = blocker(tx, current, entry);
                 if (blocked !== undefined)
@@ -398,7 +425,7 @@ export function runInboxCommand(args, store, env, now = new Date()) {
                     if (entry.inbox.ack.requestId !== requestId || entry.inbox.ack.reason !== reason
                         || !sameSession(entry.inbox.ack.actor, current))
                         throw new Error("Conflicting acknowledgement; original disposition retained.");
-                    return receipt(entry);
+                    return receipt(entry, id);
                 }
                 const inbox = { ...entry.inbox,
                     ack: { requestId, actor: current, at: now.toISOString(), reason: reason } };
@@ -415,7 +442,7 @@ export function runInboxCommand(args, store, env, now = new Date()) {
             }
         }
         save(tx, current, entry);
-        return receipt(entry);
+        return receipt(entry, id);
     });
     if (ids.length === 1)
         return apply(ids[0]);

package/dist/commands/operatorCommands.js

@@ -136,11 +136,8 @@ function submit(rest, store, options) {
     if (requestId !== undefined && requestId.length === 0) {
         throw usageError("--request-id is required.", usage);
     }
-    const body = readCommandText(positionals[0], bodyFile, "--body", usage);
-    return {
-        kind: "output",
-        output: submitOperatorMessage(body, taskId, store, options, intent, requestId)
-    };
+    const body = readCommandText(positionals[0], bodyFile, "--body", usage, { preserveFileWhitespace: true });
+    return submitOperatorMessage(body, taskId, store, options, intent, requestId);
 }
 function listSessions(args, store, options) {
     if (args.length !== 0)

package/dist/commands/releaseCommands.js

@@ -5,6 +5,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, } from "node:fs";
 import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { callController, ControllerClientError } from "../core/controllerClient.js";
 import { processGenerationIsLive } from "../core/fileLockOwner.js";
 import { activateRelease, ControllerStartUnconfirmedError } from "../release/releaseHandover.js";
@@ -346,10 +347,23 @@ export function createReleaseActivatePorts(overrides = {}) {
                 }
             }),
         runPreflight: overrides.runPreflight ?? ((releaseDir, home) => {
-            const cli = join(releaseDir, "dist", "cli.js");
+            assertReleaseIsNotWorktreeOrLinked(releaseDir);
+            const manifest = verifyReleaseIntegrity(releaseDir);
+            if (resolve(releaseDir) !== resolve(releaseDirectoryFor(home, manifest))
+                || !hasMatchingSmokeReceipt(releaseDir, manifest)) {
+                throw new Error("Release preflight requires this Home's verified installed target and matching smoke receipt.");
+            }
             // The target owns current-record and database integrity validation.
             // Activation never migrates; a valid but older Home still blocks here.
-            const result = spawnSync(process.execPath, [cli, "--json", "upgrade", "--update-preflight"], {
+            // Invoke its read-only primitive, not an ordinary inactive CLI command:
+            // the Home's CLI fence must remain closed until handover completes.
+            const module = pathToFileURL(join(releaseDir, "dist", "storage", "upgrade", "upgradeOrchestrator.js")).href;
+            const result = spawnSync(process.execPath, ["--input-type=module", "-e", `
+        const { runStorageUpgrade } = await import(process.argv[1]);
+        const data = await runStorageUpgrade({ home: process.argv[2], mode: "update-preflight" });
+        process.stdout.write(JSON.stringify({ ok: true, data }));
+        process.exitCode = data.outcome === "update-preflight" ? 0 : 5;
+      `, module, home], {
                 env: { ...process.env, YUI_HOME: home, NO_COLOR: "1" },
                 encoding: "utf8",
                 timeout: 60_000