@zq-silk/yui 0.16.1 → 1.0.0-alpha

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

@@ -34,8 +34,9 @@ not from terminal windows you juggle or details you have to remember.
 - **Isolated by default** — repository work happens in managed Git worktrees;
   the stable checkout stays read-only.
 
-> **Status:** pre-1.0 (0.15.x). CLI surfaces and configuration may still change
-> between releases; each upgrade migrates valid existing Homes.
+> **Status:** 1.0.0-alpha, with a clean storage 1.0 baseline. Default updates
+> support only declared minor upgrades within one storage major. Existing v37
+> Homes require the separate [one-time conversion](docs/storage-baseline.md).
 
 [Quick start](#quick-start) · [Working through conversation](#working-through-conversation) · [Architecture](#architecture) · [Design principles](#design-principles)
 
@@ -140,6 +141,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).
 
@@ -380,8 +384,9 @@ npm users do not need to compile it.
 
 To exercise your checkout, run `make install-local`, then use the absolute
 `<checkout>/output/dev/bin/yui` launcher. It defaults to an isolated Home under
-that checkout; run its `setup` before stateful use. Do not use the global `yui`
-or `make link` to validate local changes. Live-model, paid or shared-resource
+that checkout; run its `setup` before stateful use. Development tooling does not
+manage global installations; do not use the global `yui` to validate local changes.
+Live-model, paid or shared-resource
 tests require an explicit request for those resources.
 
 ## Community and support

package/dist/agent/agent.js

@@ -9,7 +9,7 @@ export function createConfiguredAgent(id, adapterId, command, baseArgs, environm
     validateAgentBaseArguments(adapterId, baseArgs);
     const timestamp = now.toISOString();
     return {
-        schemaVersion: 3,
+        schemaVersion: 1,
         id: normalizedId,
         // An unnamed component resolves from the plan, which for ACP means the
         // unidentified entry rather than a guess at which product is installed.
@@ -45,18 +45,13 @@ export function resolveAgentEnvironment(agent, processEnvironment = process.env)
     }));
 }
 export function validateConfiguredAgent(agent) {
-    if (agent.schemaVersion !== 3)
+    if (agent.schemaVersion !== 1)
         throw new Error("Agent schema version is invalid.");
     requireSafeIdentity(agent.id, "Agent id");
     if (!isAgentAdapterId(agent.adapterId))
         throw new Error(`Agent adapter is unsupported: ${agent.adapterId}.`);
-    // A schema 3 record always carries a component: storage 10 backfilled every
-    // stored Agent, and the constructor resolves one for every new Agent. So an
-    // absent value here is a corrupt record, not an old one, and resolving it to
-    // the plan default would invent a product identity for data that never lost
-    // one. That default belongs to the constructor, where an operator naming
-    // only a plan is a real and supported request — this validator reads records
-    // that were already written, where the same silence means something else.
+    // Creation resolves an omitted component before persistence. Reading a
+    // stored record must not invent a missing product identity.
     if (agent.component === undefined) {
         throw new Error(`Agent is missing its execution component: ${agent.id}.`);
     }

package/dist/agent/executionComponents.js

@@ -138,10 +138,10 @@ export function displayExecutionComponent(adapterId, componentId) {
 /**
  * Resolve the component for a connection plan, given what the caller stated.
  *
- * An absent component is not an error: it means the caller named only the plan,
- * which is how every binding made before this axis existed reads. It resolves
- * to the plan's default, which for ACP is the unidentified entry — the value is
- * never inferred from a command, an argument or an environment variable.
+ * Creation may name only a connection plan. Resolve its default before
+ * persistence; current stored Agents and bindings require an explicit component.
+ * ACP defaults to the unidentified entry, never a product inferred from command,
+ * arguments or environment.
  */
 export function resolveAgentExecutionComponent(adapterId, componentId) {
     if (componentId === undefined)

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,8 +32,11 @@ 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,
+        schemaVersion: 1,
         id: requireSafeIdentity(id, "AgentRun id"),
         taskId: requireSafeIdentity(taskId, "Task id"),
         roleName: requireSafeIdentity(roleName, "Role name"),
@@ -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}.`);
@@ -144,8 +132,8 @@ export function validateRun(run) {
         "createdAt",
         "updatedAt"
     ], "AgentRun");
-    if (run.schemaVersion !== 5)
-        throw new Error("AgentRun must use schemaVersion 5.");
+    if (run.schemaVersion !== 1)
+        throw new Error("AgentRun must use schemaVersion 1.");
     validateTaskRecordReference({ taskId: run.taskId, localId: run.id }, "run");
     requireSafeIdentity(run.roleName, "Role name");
     if (run.mode !== "new" && run.mode !== "resume") {
@@ -295,6 +283,8 @@ export function validateRun(run) {
         throw new Error("Execution AgentRun cannot carry Review effective provenance.");
     }
     for (const record of run.inputs) {
+        // Validate readable evidence, not readiness to execute. A missing Snapshot
+        // must still allow inspection, failure settlement and explicit retirement.
         createRunInputEnvelope(runEnvelopeContext(run), record.input);
     }
     if (!["active", "completed", "failed"].includes(run.status)) {
@@ -345,7 +335,7 @@ function finishRun(run, status, output, now, failureReason, provider, systemEvid
         ...run,
         status,
         result: {
-            schemaVersion: 2,
+            schemaVersion: 1,
             ...(output === undefined ? {} : { output: requireResultText(output, "AgentRun result output") }),
             ...(diagnostic === undefined
                 ? {}
@@ -362,8 +352,8 @@ function finishRun(run, status, output, now, failureReason, provider, systemEvid
     return validateRun(terminal);
 }
 function validateRunResult(result) {
-    if (result === undefined || result.schemaVersion !== 2) {
-        throw new Error("A terminal AgentRun requires AgentRunResult schemaVersion 2.");
+    if (result === undefined || result.schemaVersion !== 1) {
+        throw new Error("A terminal AgentRun requires AgentRunResult schemaVersion 1.");
     }
     rejectUnknownFields(result, [
         "schemaVersion",

package/dist/artifacts/managedGit.js

@@ -1,4 +1,4 @@
-import { execFile, execFileSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const executeFile = promisify(execFile);
 /**
@@ -259,8 +259,8 @@ function isExternalProgramConfigKey(key) {
  * list of repo-local keys that can execute an external program. Empty means the
  * repository's own config is within the managed boundary.
  *
- * PURE: no I/O. Callers (sync migration and async runtime) read the config with
- * their own managed runner and pass the bytes here, so the security policy lives
+ * PURE: no I/O. Callers read the config with the managed runner and pass the
+ * bytes here, so the security policy lives
  * in exactly one testable place. Reading `--local` deliberately excludes the
  * command-line `-c` hardening flags (which are safe and not persisted) and the
  * null-device'd global/system config; it sees only what is written in the repo.
@@ -277,56 +277,3 @@ export function externalProgramConfigViolations(localConfigListZ) {
     }
     return [...offending].sort();
 }
-/**
- * SYNCHRONOUS managed invocation, used ONLY where an async runner is
- * structurally impossible: a storage `migrateData(db)` step runs inside
- * `db.transaction(...)`, which better-sqlite3 requires to be synchronous, yet
- * the 18->19 migration must build per-Task artifact repositories on disk. This
- * shares the SAME hardening as {@link spawnManagedGit} — identical argument
- * refusal, identical scrubbed environment, identical prepended flags — so the
- * synchronous path never weakens the trust boundary. It is not exported for
- * ordinary runtime use; the async runner remains the only production write path.
- */
-function spawnManagedGitSync(repoPath, args, options) {
-    assertSafeArguments(args);
-    const env = managedGitEnvironment();
-    if (options?.commitDates !== undefined) {
-        // Deterministic history: fixed author/committer dates make a rebuild of the
-        // same source data reproduce the same commit ids. This only sets metadata.
-        env.GIT_AUTHOR_DATE = options.commitDates.author;
-        env.GIT_COMMITTER_DATE = options.commitDates.committer;
-    }
-    try {
-        const stdout = execFileSync("git", [...HARDENING_FLAGS, "-C", repoPath, ...args], {
-            encoding: "buffer",
-            env,
-            maxBuffer: options?.maxBuffer ?? 16 * 1024 * 1024,
-            timeout: options?.timeoutMs ?? 30_000,
-            windowsHide: true
-        });
-        return { stdout: stdout, stderr: Buffer.alloc(0) };
-    }
-    catch (error) {
-        throw new ManagedGitError([...args], readErrorStream(error), error);
-    }
-}
-/** Synchronous counterpart to {@link managedGit}; returns trimmed UTF-8 stdout. */
-export function managedGitSync(repoPath, args, options) {
-    return spawnManagedGitSync(repoPath, args, options).stdout.toString("utf8");
-}
-/** Synchronous counterpart to {@link managedGitBuffer}; returns raw stdout bytes. */
-export function managedGitSyncBuffer(repoPath, args, options) {
-    return spawnManagedGitSync(repoPath, args, options).stdout;
-}
-/** Synchronous counterpart to {@link managedGitSucceeds}; never throws on non-zero exit. */
-export function managedGitSyncSucceeds(repoPath, args, options) {
-    try {
-        spawnManagedGitSync(repoPath, args, options);
-        return true;
-    }
-    catch (error) {
-        if (error instanceof ManagedGitError)
-            return false;
-        throw error;
-    }
-}

package/dist/brief/taskBrief.js

@@ -1,6 +1,6 @@
 export function createTaskBrief(input, now) {
     return {
-        schemaVersion: 2,
+        schemaVersion: 1,
         objective: requireText(input.objective, "Task objective"),
         boundaries: normalizeBoundaries(input.boundaries),
         technicalApproach: optionalText(input.technicalApproach, "Task technical approach"),
@@ -22,8 +22,8 @@ export function updateTaskBrief(brief, patch, updatedBy, now) {
     }, now);
 }
 export function validateTaskBrief(brief) {
-    if (brief.schemaVersion !== 2) {
-        throw new Error("Task Brief requires schemaVersion 2.");
+    if (brief.schemaVersion !== 1) {
+        throw new Error("Task Brief requires schemaVersion 1.");
     }
     if (!Array.isArray(brief.boundaries) || typeof brief.technicalApproach !== "string"
         || typeof brief.updatedAt !== "string" || !Number.isFinite(Date.parse(brief.updatedAt))) {

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