@zq-silk/yui 0.16.0 → 0.99.0

package/ARCHITECTURE.md

@@ -67,6 +67,18 @@ AgentHost serializes submission through AgentEndpoint. The Provider binding
 records actual acceptance and native correlation. A notification can settle
 on acceptance without requiring a final execution report.
 
+Operator attention has a separate, local handoff boundary: one transaction
+saves the exact batch as a Global system Message and consumes only that mailbox
+claim. `queued` (with the Message id) means durable queue ownership, not Provider
+acceptance or Agent processing. Later events form a new batch without repeating
+the handed-off refs. Global Messages alone own subsequent native delivery,
+including rejection, unknown acceptance and Session-target mismatch; none causes
+automatic reissuance under a different key. A pass can mark multiple definitively
+unsent stale-target entries undelivered before reaching successor input, but never
+bypass an uncertain attempt or an interrupt-then reservation. Original Messages
+and source Task/Input/Event records remain inspectable. Notifications ask Agents
+to reread facts; they do not authorize replaying prior operations.
+
 Busy with proven non-acceptance preserves the input for a subsequent attempt.
 Transport submission alone does not prove acceptance. Unknown effects remain
 visible and fenced: no blind resend or inferred success. Explicit replacement

package/ARCHITECTURE.zh-CN.md

@@ -53,6 +53,14 @@ AgentRun 记录一次明确请求的执行，带有冻结的 Context 和生效
 mailbox 批次；AgentHost 通过 AgentEndpoint 串行化提交。Provider 绑定记录实际接受和原生
 关联。一条通知可以在接受时结算，而不要求最终执行报告。
 
+Operator attention 有独立的本地交接边界：同一事务把精确批次保存为 Global 系统 Message，
+并且只消费该 mailbox claim。`queued`（带 Message id）表示持久队列已接管，不代表 Provider
+接受或 Agent 已处理。后到事件形成新批次，不重复已经交出的 refs。后续原生投递仅由
+Global Message 负责，包括拒绝、接受结果未知和 Session 目标失效；这些结果都不会自动换键
+重发。一轮可将多个已明确未提交且目标失效的条目标为未投递，再处理后继输入，但不能越过
+不确定尝试或 interrupt-then 预约。原始 Message 和来源 Task/Input/Event 仍可查阅。通知
+只要求 Agent 重读事实，不授予重放先前操作的权限。
+
 忙碌且已证明未接受会为后续尝试保留输入。仅有传输提交不证明接受。未知效果保持可见且被
 围栏隔离：不盲目重发，也不推断成功。显式替换先解决实际的原生执行，再丢弃其工程占用。
 在一个已认领批次期间到达的输入，留待下一个批次。读取 Context 不消费投递。

package/README.md

@@ -140,6 +140,9 @@ For a visual overview, run `yui web` in another terminal. The local Web view
 shows the same tasks and pending questions and lets you send messages, answer
 questions and explicitly queue, steer or interrupt Task input. These authenticated
 Task controls use the same operations as the CLI; Web is not a separate task system.
+The detail prioritizes user input, native Session activity, Task progress and key
+conclusions; fixed file results and delivery evidence open on demand. See
+[attention and progress](docs/observability/README.md#web-attention-and-progress).
 See [Web permissions](docs/architecture/capabilities-and-resources.md#cli-and-web)
 and [input timing](docs/managed-turn-and-session-runtime.md#input-timing-queue-steer-and-interrupt).
 

package/dist/agent/managedRuntimeEnvironment.js

@@ -19,10 +19,6 @@ export const YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES = Object.freeze([
     "YUI_RUN_ID",
     "YUI_NATIVE_SESSION_ROOT",
     "YUI_NATIVE_SESSION_ID",
-    // Retired: Yui no longer publishes a frozen control-plane descriptor into a
-    // managed process. Sessions launched by an earlier release still carry it, so
-    // it stays in this sanitize list.
-    "YUI_CONTROL_PLANE_DESCRIPTOR",
     "YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR",
     "YUI_TASK_RUNTIME_SERVICE_NAMESPACE",
     "YUI_SESSION_TITLE",

package/dist/agentRun/agentRun.js

@@ -1,7 +1,7 @@
 import { validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
-import { createRunInput, createRunInputEnvelope, validateRunInput } from "../context/runInputContract.js";
+import { createRunInputEnvelope, requireRunContextSnapshotRef, validateRunInput } from "../context/runInputContract.js";
 import { providerRetryProjection } from "../runtime/providerRetry.js";
 import { boundedRunFailureDiagnostic, MAX_RUN_FAILURE_DIAGNOSTIC_BYTES, MAX_RUN_RESULT_OUTPUT_BYTES } from "../domain/agentResultTransport.js";
 export { boundedRunFailureDiagnostic, MAX_RUN_FAILURE_DIAGNOSTIC_BYTES, MAX_RUN_RESULT_OUTPUT_BYTES, transportAgentResult } from "../domain/agentResultTransport.js";
@@ -32,6 +32,9 @@ export function createRun(id, taskId, roleName, mode, input, now, context) {
     }
     const timestamp = now.toISOString();
     const normalizedInput = validateRunInput(input);
+    const snapshot = requireRunContextSnapshotRef(normalizedInput);
+    if (snapshot.taskId !== taskId)
+        throw new Error("AgentRun Context Snapshot belongs to another Task.");
     return {
         schemaVersion: 5,
         id: requireSafeIdentity(id, "AgentRun id"),
@@ -85,22 +88,6 @@ export function runPurposeAdmitsTaskState(purpose, task) {
         ? task.status === "draft" || task.status === "active"
         : task.status === "active";
 }
-/** Binds a freshly created, not-yet-persisted Turn to its frozen Context. */
-export function withRunContextSnapshot(run, snapshot, deltaRefIds = []) {
-    const initial = run.inputs[0];
-    if (run.status !== "active" || initial.input.contextSnapshotRef !== undefined) {
-        throw new Error(`Cannot replace the AgentRun Context Snapshot: ${run.id}.`);
-    }
-    const input = createRunInput({
-        ...initial.input,
-        contextSnapshotRef: snapshot,
-        deltaRefIds
-    });
-    return validateRun(Object.freeze({
-        ...run,
-        inputs: [runInputRecord(input, 1, initial.submittedAt), ...run.inputs.slice(1)]
-    }));
-}
 export function appendRunInput(run, input, now) {
     validateRun(run);
     if (run.status !== "active")
@@ -118,6 +105,7 @@ export function appendRunInput(run, input, now) {
 /** Derives Provider-visible identity from the AgentRun, the sole semantic owner. */
 export function runInputEnvelope(run, sequence = 1) {
     validateRun(run);
+    requireRunContextSnapshotRef(run.inputs[0].input);
     const record = run.inputs[sequence - 1];
     if (record === undefined)
         throw new Error(`AgentRun input does not exist: ${run.id}/${sequence}.`);
@@ -295,6 +283,8 @@ export function validateRun(run) {
         throw new Error("Execution AgentRun cannot carry Review effective provenance.");
     }
     for (const record of run.inputs) {
+        // Structural validation keeps historical records and observed subsequent
+        // inputs readable. Creation/submission require the initial frozen Snapshot.
         createRunInputEnvelope(runEnvelopeContext(run), record.input);
     }
     if (!["active", "completed", "failed"].includes(run.status)) {

package/dist/cli/agentConfigurationPicker.js

@@ -30,12 +30,11 @@ export async function selectAgentEffort(resolved, io, input) {
 }
 /** Select provider-native permission settings in the adapter's canonical shape. */
 export async function selectAgentPermission(resolved, io, current) {
+    renderResolutionNotice(resolved, io);
     const strategyField = configurationField(resolved.catalog, "permission.strategy");
-    const strategyChoices = uniqueChoices(strategyField?.choices ?? [
-        { value: "default", label: "default" },
-        { value: "bypass", label: "bypass" },
-        { value: "configured", label: "configured" }
-    ], current.strategy);
+    if (strategyField?.reason !== undefined)
+        io.write(`${strategyField.reason}\n`);
+    const strategyChoices = uniqueChoices(strategyField?.available === false ? [] : strategyField?.choices ?? [], current.strategy);
     const strategy = await choose("Select permission strategy", strategyChoices.map(({ value, label, description }) => ({
         value,
         label,
@@ -67,6 +66,10 @@ export async function selectAgentPermission(resolved, io, current) {
             delete permission.approval;
         else
             permission.approval = approval.value;
+        if (permission.sandbox === undefined && permission.approval === undefined) {
+            io.write("Configured permission requires an explicit native option; configuration unchanged.\n");
+            return { kind: "cancelled" };
+        }
         return {
             kind: "selected",
             permission: permission
@@ -98,6 +101,11 @@ export async function selectAgentPermission(resolved, io, current) {
         delete permission.mode;
     else
         permission.mode = mode.value;
+    if (permission.mode === undefined && permission.allowedTools === undefined
+        && permission.disallowedTools === undefined) {
+        io.write("Configured permission requires an explicit native option; configuration unchanged.\n");
+        return { kind: "cancelled" };
+    }
     return {
         kind: "selected",
         permission: permission
@@ -107,12 +115,13 @@ export function renderAgentConfigurationResolutionNotice(resolved) {
     const lines = [];
     if (resolved.source === "cache") {
         lines.push((resolved.failure === undefined ? "" : `! Runtime capability request failed (${resolved.failure.message}). `)
-            + `Showing cached options from ${resolved.fetchedAt ?? "an earlier request"}; they may be stale.`);
+            + `Showing identity-matched cached options from ${resolved.fetchedAt ?? "an earlier request"}; they may be stale.`);
     }
     else if (resolved.source === "fallback") {
         lines.push(`! Runtime capability request failed (${resolved.failure?.message ?? "unknown failure"}). `
-            + "No matching cache is available; only fallback and custom values can be offered.");
+            + "No matching cache is available; only declared static adapter contracts and explicit custom values can be offered.");
     }
+    lines.push(`Metadata source: ${resolved.source}; last probe attempted ${resolved.attemptedAt}${resolved.fetchedAt === undefined ? "" : `; fetched ${resolved.fetchedAt}`}. Source describes the query, not native confirmation of every field.`);
     lines.push(...resolved.catalog.warnings.map((warning) => `! Agent catalog warning: ${warning}`));
     return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
 }
@@ -215,29 +224,23 @@ function observedEfforts(models) {
 }
 async function selectPermissionField(resolved, io, key, current, defaultValue) {
     const field = configurationField(resolved.catalog, key);
-    const fallback = key === "permission.sandbox"
-        ? ["read-only", "workspace-write", "danger-full-access"]
-        : key === "permission.approval"
-            ? ["untrusted", "on-request", "never"]
-            : ["acceptEdits", "auto", "bypassPermissions", "manual", "dontAsk", "plan"];
-    const choices = uniqueChoices(field === undefined
-        ? fallback.map((value) => ({ value, label: value }))
-        : field.choices, current);
-    const includeOmit = defaultValue === OMIT || current !== undefined;
+    if (field?.reason !== undefined)
+        io.write(`${key}: ${field.reason}\n`);
+    if (field === undefined)
+        io.write(`${key}: no catalog field was reported; no choices inferred.\n`);
+    const choices = uniqueChoices(field?.available === false ? [] : field?.choices ?? [], current);
     const pickerChoices = [
-        ...(includeOmit
-            ? [{ value: OMIT, label: "Omit", detail: "Do not pass this provider option" }]
-            : []),
+        { value: OMIT, label: "Omit", detail: "Do not pass this provider option" },
         ...choices.map(({ value, label, description }) => ({
             value,
             label,
             detail: description ?? value
         })),
         ...(field?.allowCustom === true
-            ? [{ value: CUSTOM, label: "Custom…", detail: "Enter another provider value" }]
+            ? [{ value: CUSTOM, label: "Custom…", detail: "Explicit value; native acceptance unverified" }]
             : [])
     ];
-    const selected = await choose(`Select ${key}`, pickerChoices, io, current ?? defaultValue ?? pickerChoices[0]?.value ?? OMIT, key);
+    const selected = await choose(`Select ${key}`, pickerChoices, io, current ?? (choices.some(choice => choice.value === defaultValue) ? defaultValue : OMIT), key);
     if (selected === undefined)
         return { kind: "cancelled" };
     if (selected === OMIT)

package/dist/cli/commandCatalog.js

@@ -344,7 +344,7 @@ const taskChildren = [
     },
     {
         name: "complete",
-        summary: "Complete an active Task and stop automatic wakeups.",
+        summary: "Complete locally, or prepare/dispatch the configured final Review and remain active. --refresh-remote only fetches freshness observations; it never rebases, changes HEAD or starts Integration checks.",
         usage: "yui task complete <id> (--summary <text>|--summary-file <path|->) [--artifact-ref <artifact-id|turn:id|url> ...] [--refresh-remote] [--accept-published-tree <publication-id>]",
         options: ["--summary", "--summary-file", "--artifact-ref", "--refresh-remote", "--accept-published-tree"],
         fileOptions: ["--summary-file"]
@@ -356,7 +356,7 @@ const taskChildren = [
         children: [
             {
                 name: "status",
-                summary: "Classify Task Project bases against local or refreshed remote refs.",
+                summary: "Observe Task Project bases against local refs; --refresh fetches remote objects without changing HEAD, starting checks or creating Integration/Review.",
                 usage: "yui task base status <task> [--refresh]",
                 options: ["--refresh"]
             }
@@ -402,7 +402,7 @@ const taskChildren = [
     },
     {
         name: "next-action",
-        summary: "Project the durable Task records into one protocol-level next action.",
+        summary: "Read Task facts, mechanical prerequisites and legal alternatives; semantic choices remain with the Leader.",
         usage: "yui task next-action <task> [--json]",
         options: ["--json"]
     },
@@ -432,7 +432,7 @@ const taskChildren = [
         children: [
             {
                 name: "integrate",
-                summary: "Rebase Task changes onto the remote development head through Integration.",
+                summary: "Explicitly rebase Task changes onto the remote development head, run configured/additional checks (possibly as Jobs), then advance HEAD through Integration CAS. Returns exact attempts and partial results; does not request Review or complete the Task.",
                 usage: "yui task upstream integrate <task> (--latest|--project <project>) [--check <command> ...] [--rerun-checks]",
                 options: ["--latest", "--project", "--check", "--rerun-checks"]
             }
@@ -893,7 +893,7 @@ const taskChildren = [
                     {
                         name: "expand",
                         summary: "Expand one authorized AgentRun context reference.",
-                        usage: "yui task run context expand <task>/<run> <ref-id> [--store <store>] [--mode full]",
+                        usage: "yui task run context expand <task>/<run> <ref-id> --store <store> [--mode full]",
                         options: ["--store", "--mode"]
                     },
                     {
@@ -916,7 +916,7 @@ const taskChildren = [
                 name: "retire",
                 summary: "Retire an incorrect historical AgentRun without deleting its audit record.",
                 usage: "yui task run retire <task>/<run> --reason <text> [--expected-progress-at <timestamp>] [--agent-id <id>] [--adapter-id <id>] [--native-session-id <id>]",
-                options: ["--reason", "--expected-progress-at", "--progress-at", "--agent-id", "--adapter-id", "--native-session-id"]
+                options: ["--reason", "--expected-progress-at", "--agent-id", "--adapter-id", "--native-session-id"]
             }
         ]
     },
@@ -1142,7 +1142,12 @@ export const ROOT_COMMAND = buildNode({
         },
         { name: "help", summary: "Show root or scoped command help.", usage: "yui help [command ...]", commandPathArguments: true },
         { name: "version", summary: "Print the installed Yui version." },
-        { name: "update", summary: "Install the latest published Yui package globally." },
+        {
+            name: "update",
+            summary: "Install the latest or an exact published Yui version after storage preflight.",
+            usage: "yui update [--version <exact-version>]",
+            options: ["--version"]
+        },
         {
             name: "upgrade",
             summary: "Plan or apply supported storage migrations for this Home.",
@@ -1379,8 +1384,8 @@ export const ROOT_COMMAND = buildNode({
                 {
                     name: "clone",
                     summary: "Clone and bind a Project after user confirmation.",
-                    usage: "yui project clone <name> <remote> [--alias <name> ...] [--stable <ref>] [--development <ref>]",
-                    options: ["--alias", "--stable", "--development"]
+                    usage: "yui project clone <name> <remote> [--alias <name> ...] [--stable <ref>] [--development <ref>] [--external]",
+                    options: ["--alias", "--stable", "--development", "--external"]
                 },
                 {
                     name: "refresh",
@@ -1722,8 +1727,11 @@ export function validateCommandCatalog(root) {
         }
         const options = new Set();
         for (const option of [...node.options, ...node.hiddenOptions]) {
-            if (reservedAliases.has(option))
+            // --version is an alias only as the entire root invocation. Scoped
+            // commands may own a version selector; help aliases remain reserved.
+            if (reservedAliases.has(option) && option !== "--version") {
                 throw new Error(`Reserved alias token is not allowed: ${[...node.path, option].join(" ")}`);
+            }
             if (options.has(option) || immediate.has(option))
                 throw new Error(`Duplicate command token: ${[...node.path, option].join(" ")}`);
             options.add(option);

package/dist/cli/roleWizard.js

@@ -2,7 +2,7 @@ import { renderTable } from "../output/table.js";
 import { displayExecutionComponent } from "../agent/executionComponents.js";
 import { isAgentAdapterId } from "../agent/adapterCatalog.js";
 import { defaultRoleAgentConfig } from "../executor/agentAdapter.js";
-import { selectAgentEffort, selectAgentModelAndEffort } from "./agentConfigurationPicker.js";
+import { selectAgentEffort, selectAgentModelAndEffort, renderAgentConfigurationResolutionNotice } from "./agentConfigurationPicker.js";
 const TEXT_COLUMN = { header: "Selection", minWidth: 12, maxWidth: 34 };
 export async function resolveRoleWizardArguments(commandArgs, ports, io) {
     const args = [...commandArgs];
@@ -231,6 +231,8 @@ async function configureNewAgentField(args, agent, ports, io) {
                 args: selection.effort === undefined ? args : [...args, "--effort", selection.effort]
             };
     }
+    if (resolved !== undefined)
+        io.write(renderAgentConfigurationResolutionNotice(resolved));
     if (selected.value === "permission-strategy") {
         const strategy = await promptAgentFieldValue(selected, io);
         if (strategy === undefined || strategy.length === 0)
@@ -407,6 +409,8 @@ async function updateAgentBindingSettings(args, role, binding, ports, io) {
             ]
         };
     }
+    if (resolved !== undefined)
+        io.write(renderAgentConfigurationResolutionNotice(resolved));
     if (selectedField.value === "permission-strategy") {
         const strategy = await promptAgentFieldValue(selectedField, io);
         if (strategy === undefined || strategy.length === 0)
@@ -446,23 +450,17 @@ function agentFields(binding, catalog) {
     return [
         agentField("model", "Model", config.model, "--model", ["--clear-model"]),
         agentField("effort", "Effort", config.effort, "--effort", ["--clear-effort"]),
-        agentField("permission-strategy", "Permission strategy", permission.strategy, "--permission-strategy", ["--permission-strategy", "default"], catalogChoices(catalog, "permission.strategy", ["default", "bypass", "configured"])),
+        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"], catalogChoices(catalog, "permission.sandbox", [
-                "read-only", "workspace-write", "danger-full-access"
-            ])),
-            agentField("approval", "Approval", permission.approval, "--approval", ["--permission-strategy", "default"], catalogChoices(catalog, "permission.approval", [
-                "untrusted", "on-request", "never"
-            ]))
+            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"))
         ] : []),
         ...(binding.adapterId === "codex" ? [
-            agentField("search", "Web search", config.search, "--search", ["--clear-search"], [
-                ...catalogChoices(catalog, "search", ["true"])
-            ])
+            agentField("search", "Web search", config.search, "--search", ["--clear-search"], catalogField(catalog, "search"))
         ] : []),
         ...((binding.adapterId === "claude" || binding.adapterId === "acp")
             && permission.strategy === "configured" ? [
-            agentField("permission-mode", "Permission mode", permission.mode, "--permission-mode", ["--permission-strategy", "default"], catalogChoices(catalog, "permission.mode"))
+            agentField("permission-mode", "Permission mode", permission.mode, "--permission-mode", ["--permission-strategy", "default"], catalogField(catalog, "permission.mode"))
         ] : [])
     ];
 }
@@ -479,9 +477,8 @@ async function loadAgentCatalog(ports, binding, cwd) {
         ? value
         : undefined;
 }
-function catalogChoices(catalog, key, fallback = []) {
-    const field = catalog?.fields.find((candidate) => candidate.key === key);
-    return field === undefined ? [...fallback] : field.choices.map(({ value }) => value);
+function catalogField(catalog, key) {
+    return catalog?.fields.find((candidate) => candidate.key === key);
 }
 function appendModelEffortPatch(args, selection, update) {
     return [
@@ -494,8 +491,19 @@ function appendModelEffortPatch(args, selection, update) {
             : ["--effort", selection.effort])
     ];
 }
-function agentField(value, label, current, set, clear, choices) {
-    return { value, label, current: display(current), set, clear, ...(choices === undefined ? {} : { choices }) };
+function agentField(value, label, current, set, clear, capability) {
+    const reported = capability?.available === false ? [] : capability?.choices.map(choice => choice.value) ?? [];
+    const retained = (typeof current === "string" || typeof current === "boolean")
+        && !reported.includes(String(current)) ? [String(current)] : [];
+    return {
+        value, label, current: display(current), set, clear,
+        choices: [...reported, ...retained], allowCustom: capability?.allowCustom === true,
+        reason: [
+            capability?.reason ?? (capability === undefined
+                ? "No catalog field was reported; no choices inferred." : ""),
+            ...(retained.length === 0 ? [] : ["Current value is retained but not reported by this catalog."])
+        ].filter(Boolean).join(" ")
+    };
 }
 async function configuredPermissionArgs(binding, catalog, strategy, io) {
     if (strategy !== "configured")
@@ -509,12 +517,8 @@ async function configuredPermissionArgs(binding, catalog, strategy, io) {
             return undefined;
         const option = field === "sandbox" ? "--sandbox" : "--approval";
         const value = await promptAgentFieldValue(agentField(field, field === "sandbox" ? "Sandbox" : "Approval", undefined, option, ["--permission-strategy", "default"], field === "sandbox"
-            ? catalogChoices(catalog, "permission.sandbox", [
-                "read-only", "workspace-write", "danger-full-access"
-            ])
-            : catalogChoices(catalog, "permission.approval", [
-                "untrusted", "on-request", "never"
-            ])), io);
+            ? catalogField(catalog, "permission.sandbox")
+            : catalogField(catalog, "permission.approval")), io);
         return value === undefined
             ? undefined
             : ["--permission-strategy", "configured", option, value];
@@ -523,9 +527,9 @@ async function configuredPermissionArgs(binding, catalog, strategy, io) {
         // An ACP Session's configured permission is one mode the Agent enumerated,
         // so there is nothing to choose between: ask for the mode directly rather
         // than offering tool rules the protocol has no place for. The choices come
-        // from the capability catalog, so a Session that offers no modes presents
-        // none instead of inviting a value the Agent would reject.
-        const value = await promptAgentFieldValue(agentField("permission-mode", "Permission mode", undefined, "--permission-mode", ["--permission-strategy", "default"], catalogChoices(catalog, "permission.mode")), io);
+        // from the catalog. An explicitly open field permits a custom mode before
+        // Session creation; it is checked against the native Session at launch.
+        const value = await promptAgentFieldValue(agentField("permission-mode", "Permission mode", undefined, "--permission-mode", ["--permission-strategy", "default"], catalogField(catalog, "permission.mode")), io);
         return value === undefined || value.length === 0
             ? undefined
             : ["--permission-strategy", "configured", "--permission-mode", value];
@@ -541,16 +545,23 @@ async function configuredPermissionArgs(binding, catalog, strategy, io) {
         ? "--permission-mode"
         : field === "allowed" ? "--allowed-tool" : "--disallowed-tool";
     const value = field === "mode"
-        ? await promptAgentFieldValue(agentField("permission-mode", "Permission mode", undefined, option, ["--permission-strategy", "default"], catalogChoices(catalog, "permission.mode")), io)
+        ? await promptAgentFieldValue(agentField("permission-mode", "Permission mode", undefined, option, ["--permission-strategy", "default"], catalogField(catalog, "permission.mode")), io)
         : (await io.question(`${field === "allowed" ? "Allowed" : "Disallowed"} tool: `))?.trim();
     return value === undefined || value.length === 0
         ? undefined
         : ["--permission-strategy", "configured", option, value];
 }
 async function promptAgentFieldValue(field, io) {
-    return field.choices === undefined
-        ? (await io.question(`${field.label}: `))?.trim()
-        : choose(`Set ${field.label}`, field.choices.map((choice) => ({ value: choice, cells: [choice] })), [TEXT_COLUMN], io, field.choices[0], "value");
+    if (field.reason)
+        io.write(`${field.label}: ${field.reason}\n`);
+    if (field.choices === undefined)
+        return (await io.question(`${field.label}: `))?.trim();
+    const custom = "\0yui:custom";
+    const selected = await choose(`Set ${field.label}`, [
+        ...field.choices.map(choice => ({ value: choice, cells: [choice] })),
+        ...(field.allowCustom ? [{ value: custom, cells: ["Custom value (native acceptance unverified)"] }] : [])
+    ], [TEXT_COLUMN], io, field.choices.includes(field.current) ? field.current : field.choices[0], "value");
+    return selected === custom ? (await io.question(`Custom ${field.label}: `))?.trim() : selected;
 }
 async function selectActiveAgent(role, ports, io) {
     const configured = await configuredAgents(ports);

package/dist/cli/updateCommand.js

@@ -1,6 +1,8 @@
 import { resolveYuiHome } from "../storage/taskStore.js";
 import { createUpdatePorts } from "./updatePorts.js";
 import { runUpdate } from "./updateOrchestrator.js";
+import { isConcreteVersion } from "../domain/validation.js";
+import { usageError } from "../errors/cliError.js";
 /**
  * Run `yui update` as a side-by-side, recoverable orchestration.
  *
@@ -11,15 +13,24 @@ import { runUpdate } from "./updateOrchestrator.js";
  *
  * Returns a process exit code: 0 on success or already-current, 5 on abort.
  */
-export function runUpdateCommand(environment = process.env, spawn, write = (text) => process.stdout.write(text), ports) {
+export function runUpdateCommand(args = [], environment = process.env, spawn, write = (text) => process.stdout.write(text), ports) {
+    const version = parseUpdateVersion(args);
     const home = resolveYuiHome(environment);
     const resolvedPorts = ports ?? createUpdatePorts(environment, spawn);
-    const result = runUpdate(resolvedPorts, { home });
+    const result = runUpdate(resolvedPorts, { home, version });
     write(`${renderUpdateResult(result)}\n`);
     if (result.outcome === "aborted")
         return 5;
     return 0;
 }
+function parseUpdateVersion(args) {
+    if (args.length === 0)
+        return undefined;
+    if (args.length === 2 && args[0] === "--version" && isConcreteVersion(args[1])) {
+        return args[1].trim();
+    }
+    throw usageError("Update usage: yui update [--version <exact-version>]");
+}
 /** Render an {@link UpdateResult} as concise, CLI-style text. */
 export function renderUpdateResult(result) {
     const rendered = (() => {
@@ -33,14 +44,18 @@ export function renderUpdateResult(result) {
             case "aborted":
                 return [
                     `Update aborted during ${result.phase}: ${result.message}`,
-                    result.phase === "migrate-storage"
-                        || (result.phase === "post-verify" && result.recoverable)
-                        ? "The target binary is installed; the Home remains quiesced pending successful verification."
-                        : result.recoverable
-                            ? "The current install and Home remain usable."
-                            : result.phase === "activate-binary"
-                                ? "The Home was unchanged, but binary health is unknown; do not assume the current install is usable."
-                                : "Manual recovery is required (see below).",
+                    result.controllerOwnershipUnknown === true || result.controllerRestore?.outcome === "unknown"
+                        || result.controllerReconciliation?.attempts.some(attempt => attempt.outcome === "unknown")
+                        || result.controllerReconciliation?.observationError !== undefined
+                        ? "Controller resource effects are uncertain; do not assume the Home is quiesced or usable."
+                        : result.phase === "migrate-storage"
+                            || (result.phase === "post-verify" && result.recoverable)
+                            ? "The target binary is installed; the Home remains quiesced pending successful verification."
+                            : result.recoverable
+                                ? "The current install and Home remain usable."
+                                : result.phase === "activate-binary"
+                                    ? "The Home was unchanged, but binary health is unknown; do not assume the current install is usable."
+                                    : "Manual recovery is required (see below).",
                     ...(result.backupPath === undefined
                         ? []
                         : [`Storage backup: ${result.backupPath}`]),
@@ -48,7 +63,14 @@ export function renderUpdateResult(result) {
                 ].join("\n");
         }
     })();
-    return result.cleanupWarning === undefined
-        ? rendered
-        : `${rendered}\nWarning: ${result.cleanupWarning}`;
+    return [
+        rendered,
+        ...(result.controllerReconciliation === undefined ? [] : [
+            `Controller reconciliation: ${JSON.stringify(result.controllerReconciliation)}`
+        ]),
+        ...(result.controllerRestore === undefined ? [] : [
+            `Controller restore: ${JSON.stringify(result.controllerRestore)}`
+        ]),
+        ...(result.cleanupWarning === undefined ? [] : [`Warning: ${result.cleanupWarning}`])
+    ].join("\n");
 }