@zq-silk/yui 2.21.0 → 2.23.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,13 +1279,18 @@ 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"] },
             summary: "Install the latest or an exact published Yui version after storage preflight.",
-            usage: "yui update [--version <exact-version>]",
-            options: ["--version"]
+            usage: "yui update [--version <exact-version>] | --hosts-status",
+            options: ["--version", "--hosts-status"]
         },
         {
             name: "upgrade", 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/cli/updateCommand.js

@@ -14,9 +14,16 @@ import { usageError } from "../errors/cliError.js";
  * Returns a process exit code: 0 on success or already-current, 5 on abort.
  */
 export function runUpdateCommand(args = [], environment = process.env, spawn, write = (text) => process.stdout.write(text), ports) {
-    const version = parseUpdateVersion(args);
+    const statusOnly = args.length === 1 && args[0] === "--hosts-status";
+    const version = statusOnly ? undefined : parseUpdateVersion(args);
     const home = resolveYuiHome(environment);
     const resolvedPorts = ports ?? createUpdatePorts(environment, spawn);
+    if (statusOnly) {
+        if (!resolvedPorts.hostStatus)
+            throw usageError("Host status inspection is unavailable.");
+        write(`${renderHosts(resolvedPorts.hostStatus(home)).join("\n")}\n`);
+        return 0;
+    }
     const result = runUpdate(resolvedPorts, { home, version });
     write(`${renderUpdateResult(result)}\n`);
     if (result.outcome === "aborted")
@@ -29,7 +36,12 @@ function parseUpdateVersion(args) {
     if (args.length === 2 && args[0] === "--version" && isConcreteVersion(args[1])) {
         return args[1].trim();
     }
-    throw usageError("Update usage: yui update [--version <exact-version>]");
+    throw usageError("Update usage: yui update [--version <exact-version>] | --hosts-status");
+}
+function renderHosts(hosts) {
+    return hosts.length === 0 ? ["Hosts: no recorded active Sessions."] : hosts.map(host => `Host ${host.owner.scope === "task" ? `${host.owner.taskId}/` : "global/"}${host.owner.roleName} `
+        + `(${host.nativeSessionId}): ${host.status}; loaded Host=${host.hostImplementation?.generation ?? "unreported"}; `
+        + `loaded Endpoint=${host.endpointImplementation?.generation ?? "unreported"}${host.detail ? ` — ${host.detail}` : ""}`);
 }
 /** Render an {@link UpdateResult} as concise, CLI-style text. */
 export function renderUpdateResult(result) {
@@ -66,7 +78,12 @@ export function renderUpdateResult(result) {
     return [
         rendered,
         ...(result.outcome === "updated" ? [
-            "Runtime: existing Hosts are retained, not upgraded in place. Host control capabilities and event delivery are checked separately; accepted input is never replayed."
+            result.controllerStarted ? "Controller: target startup verified." : "Controller: not started by this update.",
+            "Hosts: graceful switching is separate from installation; accepted input is never replayed.",
+            ...(result.hosts === undefined ? ["Hosts: not confirmed; existing Hosts may still run older code."]
+                : renderHosts(result.hosts)),
+            "Inspect later without reinstalling: yui update --hosts-status",
+            ...(result.hostUpgradeError === undefined ? [] : [result.hostUpgradeError])
         ] : []),
         ...(result.controllerReconciliation === undefined ? [] : [
             `Controller reconciliation: ${JSON.stringify(result.controllerReconciliation)}`

package/dist/cli/updateOrchestrator.js

@@ -250,9 +250,22 @@ function activateAndVerify(ports, staged, home, lifecycle, preflight) {
                 : restoreControllerOrReport(ports, home, lifecycle, failure);
         }
     }
+    let hosts;
+    let hostUpgradeError;
+    if (lifecycle.ensureRunning && ports.upgradeHosts) {
+        try {
+            hosts = ports.upgradeHosts(home);
+        }
+        catch (error) {
+            hostUpgradeError = `Host upgrade request outcome is unknown: ${messageOf(error)}. Inspect existing requests; do not replay inputs.`;
+        }
+    }
     return {
         outcome: "updated",
         version: staged.version,
+        ...(lifecycle.ensureRunning ? { controllerStarted: true } : {}),
+        ...(hosts === undefined ? {} : { hosts }),
+        ...(hostUpgradeError === undefined ? {} : { hostUpgradeError }),
         ...(migration?.backupPath === undefined ? {} : { backupPath: migration.backupPath })
     };
 }

package/dist/cli/updatePorts.js

@@ -236,9 +236,36 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
         },
         restoreController(home, identity) {
             restoreControllerIdentity(home, identity, environment, spawn);
+        },
+        upgradeHosts(home) {
+            if (!verifiedActivatedBinary)
+                throw new Error("Host upgrade requires the verified activated binary.");
+            const root = dirname(dirname(activatedControllerEntrypoint(verifiedActivatedBinary)));
+            return requestHosts(root, home, "runtime.upgrade-hosts", environment, spawn);
+        },
+        hostStatus(home) {
+            return requestHosts(fileURLToPath(new URL("../", import.meta.url)), home, "runtime.host-upgrade-status", environment, spawn);
         }
     };
 }
+function requestHosts(root, home, method, environment, spawn) {
+    const helper = [
+        "const [root, home] = process.argv.slice(1);",
+        "(async () => {",
+        " const { pathToFileURL } = await import('node:url');",
+        " const { callController } = await import(pathToFileURL(root + '/core/controllerClient.js').href);",
+        " const { AGENT_HOST_IMPLEMENTATION } = await import(pathToFileURL(root + '/runtime/agentHostImplementation.js').href);",
+        ` const data = await callController(home, ${JSON.stringify(method)}, { generation: AGENT_HOST_IMPLEMENTATION.generation });`,
+        " process.stdout.write(JSON.stringify({ok: true, data}));",
+        "})().catch(error => { process.stderr.write(String(error)); process.exitCode = 5; });"
+    ].join(" ");
+    const result = spawn(process.execPath, ["-e", helper, root, home], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+    const data = parseSuccessEnvelopeData(result);
+    if (result.error || result.status !== 0 || !Array.isArray(data?.hosts)) {
+        throw new Error(`Host request was not confirmed: ${result.stderr.toString("utf8")}`);
+    }
+    return data.hosts;
+}
 const UPDATE_CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
 const UPDATE_CLIENT_RUNTIME_PATH = fileURLToPath(new URL("../controller/clientRuntime.js", import.meta.url));
 const UPDATE_INVENTORY_PATH = fileURLToPath(new URL("../controller/resourceInventoryLinux.js", import.meta.url));

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")