@zq-silk/yui 0.16.1 → 1.0.0-alpha

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

package/dist/cli/updateOrchestrator.js

@@ -6,10 +6,12 @@
  * then activated, any required storage migration is applied, and the result is
  * verified before the Controller is restarted.
  */
+import { UpdateControllerReconciliationError } from "../controller/updateReconciliation.js";
+import { isControllerIdentity } from "../core/controllerIdentity.js";
 export function runUpdate(ports, options) {
     let staged;
     try {
-        staged = ports.stage();
+        staged = ports.stage(options.version);
     }
     catch (error) {
         return {
@@ -33,7 +35,9 @@ export function runUpdate(ports, options) {
             cleanupWarning = `Staging cleanup could not be completed: ${messageOf(error)}`;
         }
     }
-    return cleanupWarning === undefined ? result : { ...result, cleanupWarning };
+    return cleanupWarning === undefined ? result : {
+        ...result, cleanupWarning: [result.cleanupWarning, cleanupWarning].filter(Boolean).join(" ")
+    };
 }
 function runStagedUpdate(ports, staged, home) {
     let preflight;
@@ -58,8 +62,6 @@ function runStagedUpdate(ports, staged, home) {
             action: preflight.action,
             recoverable: true,
             version: staged.version,
-            ...(preflight.blockers === undefined ? {} : { blockers: preflight.blockers }),
-            ...(preflight.retryCommand === undefined ? {} : { retryCommand: preflight.retryCommand }),
             ...(preflight.sceneUnchanged === true ? { sceneUnchanged: true } : {})
         };
     }
@@ -97,38 +99,69 @@ function runStagedUpdate(ports, staged, home) {
             version: staged.version
         };
     }
+    let result;
+    let cleanupWarning;
     try {
-        const captured = captureControllerLifecycle(ports, staged.version, home);
-        if ("outcome" in captured)
-            return captured;
-        // An older Controller can finish a launch between preflight and drain.
-        // Recheck after its exact stop, before changing the install or storage.
-        let fencedPreflight;
+        result = reconcileAndUpdate(ports, staged, home);
+    }
+    finally {
         try {
-            fencedPreflight = ports.preflight(staged, home);
+            releaseHandover?.();
         }
         catch (error) {
-            return restoreControllerOrReport(ports, home, captured.lifecycle, {
-                outcome: "aborted", phase: "preflight",
-                message: `Quiesced compatibility preflight failed: ${messageOf(error)}`,
-                action: "The install and storage are unchanged; inspect the compatibility failure before retrying.",
-                recoverable: true, version: staged.version
-            });
+            cleanupWarning = `Controller handover lock release failed for ${home}: ${messageOf(error)}`;
         }
-        if (fencedPreflight.status === "blocked") {
-            return restoreControllerOrReport(ports, home, captured.lifecycle, {
-                outcome: "aborted", phase: "preflight",
-                message: fencedPreflight.message, action: fencedPreflight.action,
-                recoverable: true, version: staged.version,
-                ...(fencedPreflight.blockers === undefined ? {} : { blockers: fencedPreflight.blockers }),
-                ...(fencedPreflight.sceneUnchanged === true ? { sceneUnchanged: true } : {})
-            });
-        }
-        return activateAndVerify(ports, staged, home, captured.lifecycle, fencedPreflight);
     }
-    finally {
-        releaseHandover?.();
+    return cleanupWarning === undefined ? result : { ...result, cleanupWarning };
+}
+function reconcileAndUpdate(ports, staged, home) {
+    let reconciliation;
+    try {
+        reconciliation = ports.reconcileController?.(home);
+    }
+    catch (error) {
+        const evidence = error instanceof UpdateControllerReconciliationError ? error.result : undefined;
+        const unknown = evidence === undefined || evidence.observationError !== undefined
+            || evidence.lockReleaseError !== undefined || evidence.attempts.some(attempt => attempt.outcome === "unknown");
+        return {
+            outcome: "aborted", phase: "coordination", version: staged.version,
+            message: `Controller reconciliation failed: ${messageOf(error)}`,
+            action: "Inspect the reported current-Home targets and partial effects; binary activation was not attempted.",
+            recoverable: !unknown,
+            ...(evidence === undefined ? {} : { controllerReconciliation: evidence }),
+            ...(unknown ? { controllerOwnershipUnknown: true } : {})
+        };
     }
+    const coordinated = runCoordinatedUpdate(ports, staged, home);
+    return reconciliation === undefined ? coordinated : { ...coordinated, controllerReconciliation: reconciliation };
+}
+function runCoordinatedUpdate(ports, staged, home) {
+    const captured = captureControllerLifecycle(ports, staged.version, home);
+    if ("outcome" in captured)
+        return captured;
+    // Storage can change before the Controller drains. Recheck after its
+    // exact stop, before changing the install or storage. Its sceneUnchanged
+    // verdict does not describe the preceding runtime cleanup/stop/restore.
+    let fencedPreflight;
+    try {
+        fencedPreflight = ports.preflight(staged, home);
+    }
+    catch (error) {
+        return restoreControllerOrReport(ports, home, captured.lifecycle, {
+            outcome: "aborted", phase: "preflight",
+            message: `Quiesced storage preflight failed: ${messageOf(error)}`,
+            action: "The install and storage are unchanged; inspect the storage failure before retrying.",
+            recoverable: true, version: staged.version
+        });
+    }
+    if (fencedPreflight.status === "blocked") {
+        return restoreControllerOrReport(ports, home, captured.lifecycle, {
+            outcome: "aborted", phase: "preflight",
+            message: fencedPreflight.message, action: fencedPreflight.action,
+            recoverable: true, version: staged.version
+        });
+    }
+    return activateAndVerify(ports, staged, home, captured.lifecycle, fencedPreflight);
 }
 function activateAndVerify(ports, staged, home, lifecycle, preflight) {
     try {
@@ -256,7 +289,8 @@ function captureControllerLifecycle(ports, version, home) {
             phase: "preflight",
             message: `Controller status could not be verified: ${messageOf(error)}`,
             action: "Inspect Controller ownership and retry after its status is known.",
-            recoverable: true,
+            recoverable: false,
+            controllerOwnershipUnknown: true,
             version
         };
     }
@@ -279,7 +313,8 @@ function captureControllerLifecycle(ports, version, home) {
             phase: "preflight",
             message: `Controller stop/drain failed: ${messageOf(error)}`,
             action: "Inspect the captured Controller before retrying; binary activation was not attempted.",
-            recoverable: true,
+            recoverable: false,
+            controllerOwnershipUnknown: true,
             version
         };
     }
@@ -300,7 +335,8 @@ function malformedControllerResult(version, message) {
         phase: "preflight",
         message,
         action: "Refusing an unfenced Controller handoff; inspect ownership and retry.",
-        recoverable: true,
+        recoverable: false,
+        controllerOwnershipUnknown: true,
         version
     };
 }
@@ -309,14 +345,16 @@ function restoreControllerOrReport(ports, home, lifecycle, failure) {
         return failure;
     try {
         ports.restoreController(home, lifecycle.identity);
-        return failure;
+        return { ...failure, controllerRestore: { identity: lifecycle.identity, outcome: "restored" } };
     }
     catch (error) {
         return {
             ...failure,
             message: `${failure.message} Captured Controller restore failed: ${messageOf(error)}.`,
-            action: `${failure.action} Keep the Home quiesced and resolve the restore failure.`,
-            recoverable: false
+            action: `${failure.action} Controller liveness after the failed restore is unknown; inspect its exact identity before further action.`,
+            recoverable: false,
+            controllerOwnershipUnknown: true,
+            controllerRestore: { identity: lifecycle.identity, outcome: "unknown", error: messageOf(error) }
         };
     }
 }
@@ -351,15 +389,6 @@ function isStorageMigrationResult(value) {
 function isPositivePid(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
-function isControllerIdentity(value) {
-    return isRecord(value)
-        && typeof value.executablePath === "string"
-        && value.executablePath.length > 0
-        && Array.isArray(value.args)
-        && value.args.every((arg) => typeof arg === "string")
-        && typeof value.version === "string"
-        && value.version.length > 0;
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }