@zq-silk/yui 0.7.1 → 0.8.2

package/dist/cli.js

@@ -5,6 +5,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { renderCommandHelp } from "./cli/helpRenderer.js";
+import { describeCommandTree, findCommandNode } from "./cli/commandCatalog.js";
 import { routeInvocation } from "./cli/invocationRouter.js";
 import { renderCompletion } from "./cli/completion.js";
 import { resolveCompletionCandidates } from "./cli/dynamicCompletion.js";
@@ -16,12 +17,14 @@ import { resolveOperatorWizardArguments } from "./cli/operatorWizard.js";
 import { runUpdateCommand } from "./cli/updateCommand.js";
 import { runUpgradeCommand } from "./cli/upgradeCommand.js";
 import { formatTimestamp } from "./output/timePresentation.js";
-import { resolveTmuxBin } from "./config/yuiConfig.js";
+import { resolveTmuxBin, resolveTmuxHistoryLimit } from "./config/yuiConfig.js";
 import { renderAgentConfigurationCatalog } from "./output/agentConfigurationPresentation.js";
 import { nativeAgentEnvironmentNames } from "./agent/launchEnvironment.js";
 import { runAgentCommand } from "./commands/agentCommands.js";
 import { runGlobalRoleCommand } from "./commands/globalRoleCommands.js";
 import { runConfigCommand } from "./commands/configCommands.js";
+import { CONFIG_DOMAINS } from "./config/configCatalog.js";
+import { runConfigOverview } from "./commands/configOverview.js";
 import { parseControllerCleanupOptions, parseControllerStatusOptions, parseControllerRuntimeSnapshot, renderControllerResourceStatus, renderRuntimeIdentitySection, summarizeDurablePhysicalMismatch, runInteractiveControllerCleanup } from "./commands/controllerCommands.js";
 import { parseExecutionAuditOptions, runExecutionAuditCommand } from "./commands/executionAuditCommands.js";
 import { parseSessionReconcileOptions, runSessionReconcileCommand } from "./commands/sessionCommands.js";
@@ -33,7 +36,7 @@ import { runResourcesCommand } from "./commands/resourcesCommands.js";
 import { applyOperatorSessionControl, runOperatorCommand } from "./commands/operatorCommands.js";
 import { runProjectCommand } from "./commands/projectCommands.js";
 import { runProfileCommand } from "./commands/profileCommands.js";
-import { dispatchPreparedReviewRound, failPendingReviewRound, assertTaskRoleWritableAttachAvailable, RESUMED_PENDING_FINAL_REVIEW, TERMINALIZED_LEADER_BEFORE_FINAL_REVIEW, TaskFinalReviewDispatchDriftError, preserveReviewRoundWorkspace, parseTaskCompletionRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, validateTaskArchiveRequest } from "./commands/taskCommands.js";
+import { dispatchPreparedReviewRound, failPendingReviewRound, RESUMED_PENDING_FINAL_REVIEW, TERMINALIZED_LEADER_BEFORE_FINAL_REVIEW, TaskFinalReviewDispatchDriftError, preserveReviewRoundWorkspace, parseTaskCompletionRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, validateTaskArchiveRequest } from "./commands/taskCommands.js";
 import { taskActor } from "./commands/taskActor.js";
 import { runTaskIntegrationCommand } from "./commands/taskIntegrationCommands.js";
 import { runTaskChangeSetCommand } from "./commands/taskChangeSetCommands.js";
@@ -58,9 +61,9 @@ import { runSessionNotifyCommand } from "./controller/sessionNotify.js";
 import { openSchedulerTelemetry } from "./telemetry/telemetryWiring.js";
 import { runRuntimeObservationHookCommand } from "./controller/runtimeObservationHook.js";
 import { buildDoctorReport, renderDoctor, runDoctorCommand } from "./doctor/doctor.js";
-import { agentNotFound, CliError, usageError } from "./errors/cliError.js";
+import { agentNotFound, CliError, runtimeError, usageError } from "./errors/cliError.js";
 import { FileRoleLaunchPlanner } from "./executor/fileRoleLaunchPlanner.js";
-import { runAgentHost } from "./runtime/agentHost.js";
+import { AGENT_HOST_CONTROL_PROTOCOL, runAgentHost, sendAgentHostAuthorityControl } from "./runtime/agentHost.js";
 import { TaskWorkspaceCoordinator, WorkspaceCleanupBlockedError } from "./repository/taskWorkspaceCoordinator.js";
 import { FileTaskWorkspacePreparer, ReviewRoundWorkspaceEvidenceError } from "./repository/taskWorkspacePreparer.js";
 import { inspectStorageSchema } from "./storage/storageSchema.js";
@@ -168,10 +171,25 @@ export async function main() {
         }
         throw usageError("Release usage: yui release install <source-dir> | list | activate [release-id].");
     }
-    if (args[0] === "completion") {
+    if (args[0] === "config" && args[1] === "completion") {
         await completionCommand(home, invocation.node);
         return;
     }
+    if (args[0] === "config" && args[1] === "describe") {
+        const describeNode = findCommandNode(["config", "describe"]);
+        if (describeNode === undefined)
+            throw new Error("Config describe command is missing from the catalog.");
+        const domain = args[2];
+        const domains = describeNode.argumentValues[0] ?? [];
+        if (args.length > 3 || (domain !== undefined && !domains.includes(domain))) {
+            throw usageError(`Config describe usage: ${describeNode.usage.join(" | ")}.`);
+        }
+        const target = findCommandNode(domain === undefined ? ["config"] : ["config", domain]);
+        if (target === undefined)
+            throw new Error(`Config domain is missing from the catalog: ${domain}.`);
+        emit(renderCommandHelp(target, VERSION), false, describeCommandTree(target));
+        return;
+    }
     if (args[0] === "setup") {
         if (jsonOutput)
             throw usageError("Setup does not support --json.");
@@ -261,13 +279,13 @@ export async function main() {
         }
         throw usageError("Internal lifecycle callback usage is invalid.");
     }
-    if (args[0] === "session") {
-        if (args[1] !== "reconcile") {
-            throw usageError("Session usage: yui session reconcile [--report] [--cleanup].");
-        }
+    if (args[0] === "session" && args[1] === "reconcile") {
         const options = parseSessionReconcileOptions(args.slice(2));
         const store = openCompatibleFileTaskStore(home);
-        const tmux = new TmuxManager(resolveTmuxBin(store.getConfig().tmuxBin), new NodeCommandExecutor(), { yuiHome: home });
+        const tmux = new TmuxManager(resolveTmuxBin(store.getConfig().tmuxBin), new NodeCommandExecutor(), {
+            yuiHome: home,
+            historyLimit: resolveTmuxHistoryLimit(store.getConfig().tmuxHistoryLimit)
+        });
         const reconciliation = new SessionOwnerReconciliation({
             home,
             store,
@@ -474,6 +492,7 @@ export async function main() {
     const executor = new NodeCommandExecutor();
     const tmux = new TmuxManager(resolveTmuxBin(store.getConfig().tmuxBin), executor, {
         yuiHome: home,
+        historyLimit: resolveTmuxHistoryLimit(store.getConfig().tmuxHistoryLimit),
         terminalInput: process.stdin,
         onWarning: (message) => process.stderr.write(`Warning: ${message}\n`)
     });
@@ -531,77 +550,102 @@ export async function main() {
         process.stdout.write(`Yui web control room: http://${displayHost}:${options.port}\n`);
         return;
     }
-    if (resolved[0] === "agent") {
-        const agentArgs = resolved.slice(1);
-        if (agentArgs[0] === "capabilities") {
-            if (agentArgs.length !== 2) {
-                throw usageError("Agent capabilities usage: yui agent capabilities <agent-id>");
+    if (resolved[0] === "config") {
+        const domain = resolved[1];
+        const roleOptions = {
+            yuiHome: home,
+            env: process.env
+        };
+        if (domain === "show") {
+            const result = runConfigOverview(resolved.slice(2), store, process.env, resolveCliIdentity(process.env), roleOptions);
+            emit(result.output, false, result.data);
+            return;
+        }
+        if (CONFIG_DOMAINS.includes(domain ?? "")) {
+            const configDomain = domain;
+            const domainArgs = resolved.slice(2);
+            const result = runConfigCommand(configDomain, domainArgs, store);
+            if (domainArgs[0] === "set"
+                && domainArgs[1] === "reconciliation-interval-seconds") {
+                const refresh = await refreshRunningFileTaskControllerConfiguration(home, { environment: process.env });
+                emit(withControllerRefreshWarning(result.output, refresh, "Controller configuration"));
+                return;
             }
-            const agent = store.getConfiguredAgent(agentArgs[1] ?? "");
-            if (agent === null)
-                throw agentNotFound(agentArgs[1] ?? "");
-            const result = await catalogs.resolve({
-                agent,
-                cwd: store.getConfig().defaultWorkspace ?? process.cwd()
-            });
-            emit(renderAgentConfigurationCatalog(result), false, result);
+            emit(result.output, false, result.data);
             return;
         }
-        const affectedAgentId = agentArgs[1];
-        const previousAgent = typeof affectedAgentId === "string"
-            ? store.getConfiguredAgent(affectedAgentId)
-            : null;
-        const output = runAgentCommand(agentArgs, store);
-        if (agentArgs[0] === "add"
-            || agentArgs[0] === "update"
-            || agentArgs[0] === "remove") {
-            const currentAgent = typeof affectedAgentId === "string"
+        if (domain === "agent") {
+            const agentArgs = resolved.slice(2);
+            if (agentArgs[0] === "capabilities") {
+                if (agentArgs.length !== 2) {
+                    throw usageError("Agent capabilities usage: yui config agent capabilities <agent-id>");
+                }
+                const agent = store.getConfiguredAgent(agentArgs[1] ?? "");
+                if (agent === null)
+                    throw agentNotFound(agentArgs[1] ?? "");
+                const result = await catalogs.resolve({
+                    agent,
+                    cwd: store.getConfig().defaultWorkspace ?? process.cwd()
+                });
+                emit(renderAgentConfigurationCatalog(result), false, result);
+                return;
+            }
+            const affectedAgentId = agentArgs[1];
+            const previousAgent = typeof affectedAgentId === "string"
                 ? store.getConfiguredAgent(affectedAgentId)
                 : null;
-            const capabilityNotice = currentAgent !== null
-                && (agentArgs[0] === "add" || agentArgs[0] === "update")
-                ? renderAgentConfigurationResolutionNotice(await catalogs.resolve({
-                    agent: currentAgent,
-                    cwd: store.getConfig().defaultWorkspace ?? process.cwd()
-                }))
-                : "";
-            const scope = agentEnvironmentRefreshScope(previousAgent, currentAgent, store.listConfiguredAgents());
-            const refresh = await refreshRunningFileTaskControllerEnvironment(home, store, process.env, scope);
-            emit(withControllerRefreshWarning(`${output.trimEnd()}${capabilityNotice.length === 0 ? "\n" : `\n${capabilityNotice}`}`, refresh, "Agent environment"));
+            const output = runAgentCommand(agentArgs, store);
+            if (agentArgs[0] === "add"
+                || agentArgs[0] === "update"
+                || agentArgs[0] === "remove") {
+                const currentAgent = typeof affectedAgentId === "string"
+                    ? store.getConfiguredAgent(affectedAgentId)
+                    : null;
+                const capabilityNotice = currentAgent !== null
+                    && (agentArgs[0] === "add" || agentArgs[0] === "update")
+                    ? renderAgentConfigurationResolutionNotice(await catalogs.resolve({
+                        agent: currentAgent,
+                        cwd: store.getConfig().defaultWorkspace ?? process.cwd()
+                    }))
+                    : "";
+                const scope = agentEnvironmentRefreshScope(previousAgent, currentAgent, store.listConfiguredAgents());
+                const refresh = await refreshRunningFileTaskControllerEnvironment(home, store, process.env, scope);
+                emit(withControllerRefreshWarning(`${output.trimEnd()}${capabilityNotice.length === 0 ? "\n" : `\n${capabilityNotice}`}`, refresh, "Agent environment"));
+                return;
+            }
+            emit(output);
             return;
         }
-        emit(output);
-        return;
-    }
-    if (resolved[0] === "config") {
-        const configArgs = resolved.slice(1);
-        const result = runConfigCommand(configArgs, store);
-        if (configArgs[0] === "set"
-            && configArgs[1] === "reconciliation-interval-seconds") {
-            const refresh = await refreshRunningFileTaskControllerConfiguration(home, { environment: process.env });
-            emit(withControllerRefreshWarning(result.output, refresh, "Controller configuration"));
+        if (domain === "profile") {
+            const result = runProfileCommand(resolved.slice(2), store);
+            emit(result.output, false, result.data);
             return;
         }
-        emit(result.output, false, result.data);
-        return;
+        if (domain === "role") {
+            const result = runGlobalRoleCommand(resolved.slice(2), store, roleOptions);
+            if (typeof result !== "string") {
+                throw new Error("Config Role commands cannot enter a runtime Session.");
+            }
+            emit(result);
+            return;
+        }
+        throw usageError(`Unknown configuration domain: ${domain ?? ""}.`);
     }
     if (resolved[0] === "project") {
         const result = await runProjectCommand(resolved.slice(1), store, { environment: process.env });
         emit(result.output, false, result.data);
         return;
     }
-    if (resolved[0] === "profile") {
-        const result = runProfileCommand(resolved.slice(1), store);
-        emit(result.output, false, result.data);
-        return;
-    }
-    if (resolved[0] === "role") {
+    if (resolved[0] === "session") {
         const roleOptions = {
             yuiHome: home,
             env: process.env,
             jsonOutput
         };
-        const result = runGlobalRoleCommand(resolved.slice(1), store, roleOptions);
+        const sessionArgs = resolved[1] === "enter" || resolved[1] === "context"
+            ? [resolved[1], ...resolved.slice(2)]
+            : ["session", resolved[1] ?? "", ...resolved.slice(2)];
+        const result = runGlobalRoleCommand(sessionArgs, store, roleOptions);
         if (typeof result === "string") {
             emit(result);
             return;
@@ -1104,30 +1148,82 @@ export async function main() {
                     : { command: result.data, ...reviewData });
                 return;
             }
-            if (result.output !== undefined)
-                emit(result.output);
-            try {
-                tmux.attachRole(result.taskId, result.roleName, result.access, {
-                    ...(result.access === "read-write"
-                        ? {
-                            revalidateWritableAttach: () => {
-                                assertTaskRoleWritableAttachAvailable(store, result.taskId, result.roleName, {
-                                    isManagedProcessRunning: () => (tmux.probeRoleStatus(result.taskId, result.roleName) === "running")
-                                });
-                            }
+            if (jsonOutput) {
+                throw usageError("Task Role view/takeover requires an interactive terminal.");
+            }
+            if (result.kind === "view") {
+                if (result.output !== undefined)
+                    emit(result.output);
+                tmux.attachRole(result.taskId, result.roleName, "read-only");
+                return;
+            }
+            const syncAuthority = async (authorityResult) => {
+                let control;
+                try {
+                    control = await sendAgentHostAuthorityControl({
+                        home,
+                        scope: "task",
+                        taskId: authorityResult.taskId,
+                        roleName: authorityResult.roleName,
+                        control: {
+                            protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                            type: "set-authority",
+                            nativeSessionId: authorityResult.nativeSessionId,
+                            authority: authorityResult.authority
                         }
-                        : {})
+                    });
+                }
+                catch (error) {
+                    throw runtimeError(`Agent Host authority synchronization failed at epoch ${authorityResult.authority.epoch}: `
+                        + `${error instanceof Error ? error.message : String(error)}. `
+                        + `Durable authority is ${authorityResult.authority.owner}-owned; retry `
+                        + `'yui task role release ${authorityResult.taskId} ${authorityResult.roleName}' `
+                        + "to reconcile the Host.");
+                }
+                if (control.outcome !== "accepted"
+                    || control.snapshot.nativeSessionId !== authorityResult.nativeSessionId
+                    || control.snapshot.authorityEpoch !== authorityResult.authority.epoch
+                    || control.snapshot.authorityOwner !== authorityResult.authority.owner
+                    || control.snapshot.authorityHolderId !== authorityResult.authority.holderId) {
+                    throw runtimeError(`Agent Host did not accept Provider authority epoch ${authorityResult.authority.epoch}: `
+                        + (control.snapshot.detail ?? control.outcome)
+                        + `. Durable authority is ${authorityResult.authority.owner}-owned; `
+                        + "retry 'yui task role release "
+                        + `${authorityResult.taskId} ${authorityResult.roleName}' to reconcile the Host.`);
+                }
+                return control;
+            };
+            await syncAuthority(result);
+            emit(result.output);
+            if (result.action === "release") {
+                runtime.notifyMailboxChanged({
+                    kind: "role",
+                    taskId: result.taskId,
+                    roleName: result.roleName
                 });
+                return;
+            }
+            process.stdout.write("Provider input is now routed through the Agent Host PTY gateway. "
+                + "Use tmux detach (Ctrl-b d) to return authority to the Controller.\n");
+            try {
+                tmux.attachRole(result.taskId, result.roleName, "read-write");
             }
             finally {
-                if (result.access === "read-write") {
-                    // A Run claimed while the writer lease was visible is intentionally
-                    // paused. Releasing the lease only signals that existing durable
-                    // work may be reconsidered; it never creates or wakes a Run.
+                const currentTask = store.getTask(result.taskId);
+                // Completing or retiring the Task from inside the takeover Turn owns
+                // Provider shutdown and clears the live binding. Do not turn that
+                // successful terminal transition into a failing best-effort release.
+                if (currentTask?.status === "active") {
+                    const released = runTaskCommand(["role", "release", result.taskId, result.roleName], store, { runtime, environment: process.env, yuiHome: home });
+                    if (released.kind !== "authority" || released.action !== "release") {
+                        throw runtimeError("Provider authority release returned an invalid result.");
+                    }
+                    await syncAuthority(released);
+                    emit(released.output);
                     runtime.notifyMailboxChanged({
                         kind: "role",
-                        taskId: result.taskId,
-                        roleName: result.roleName
+                        taskId: released.taskId,
+                        roleName: released.roleName
                     });
                 }
             }
@@ -1659,7 +1755,7 @@ async function deltaRecheckPreflightForTaskCommand(args, store, actualTaskReview
     const config = store.getReviewConfig();
     if (!deltaRecheckEnabled(config)) {
         throw usageError("Delta-recheck is not enabled for this Project's review policy. "
-            + "Set `yui config set review --role <role> --trigger final --delta-recheck enabled` "
+            + "Set `yui config workflow set review --role <role> --trigger final --delta-recheck enabled` "
             + "or request a full Review.");
     }
     const reviewConfig = config;
@@ -1809,7 +1905,7 @@ async function executeOperatorSessionControl(control, home, store, runtime, tmux
                     process.stdout.write("Cancelled.\n");
                     return;
                 }
-                const updated = runGlobalRoleCommand(resolution.args.slice(1), store, { yuiHome: home, env: process.env });
+                const updated = runGlobalRoleCommand(resolution.args.slice(2), store, { yuiHome: home, env: process.env });
                 if (typeof updated !== "string") {
                     throw new Error("Operator Agent configuration returned an invalid control result.");
                 }
@@ -1865,11 +1961,11 @@ function renderControllerResult(method, value) {
         : "Controller was already stopped.";
 }
 async function completionCommand(home, node) {
-    if (args[1] === "candidates") {
-        const separator = args.indexOf("--");
-        const prefix = args[2];
-        if (prefix === undefined || separator !== 3) {
-            throw usageError("Completion candidates usage: yui completion candidates <prefix> -- <words...>");
+    if (args[2] === "candidates") {
+        const separator = args.indexOf("--", 4);
+        const prefix = args[3];
+        if (prefix === undefined || separator !== 4) {
+            throw usageError("Completion candidates usage: yui config completion candidates <prefix> -- <words...>");
         }
         const candidates = await resolveCompletionCandidates({
             current: prefix,
@@ -1884,9 +1980,9 @@ async function completionCommand(home, node) {
     if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
         throw usageError("Completion configuration requires an interactive terminal.");
     }
-    const shell = completionShell(args[1]);
-    if (args.length > (shell === undefined ? 1 : 2)) {
-        throw usageError("Completion usage: yui completion [bash|zsh|fish]");
+    const shell = completionShell(args[2]);
+    if (args.length > (shell === undefined ? 2 : 3)) {
+        throw usageError("Completion usage: yui config completion [bash|zsh|fish]");
     }
     const store = openCompatibleFileTaskStore(home);
     const ioHandle = terminalIo();
@@ -1921,7 +2017,7 @@ async function resolveTerminalArguments(commandArgs, node, store, catalogs) {
         // Global Role add owns its Agent choice so the configured default can be
         // shown explicitly. Other commands first resolve missing positional
         // targets through the generic selector, then enter the focused Role UI.
-        if ((operatorArgs[0] === "role" && operatorArgs[1] === "add")
+        if ((operatorArgs[0] === "config" && operatorArgs[1] === "role" && operatorArgs[2] === "add")
             || (operatorArgs[0] === "task" && operatorArgs[1] === "role" && operatorArgs[2] === "add")) {
             const wizard = await resolveRoleWizardArguments(operatorArgs, ports, handle.io);
             if (wizard.kind === "cancelled")
@@ -1983,7 +2079,7 @@ async function preflightAgentConfigurationMutation(commandArgs, store, catalogs)
     });
 }
 function hasModelOrEffortMutation(args) {
-    const operation = args[0] === "role"
+    const operation = (args[0] === "config" && args[1] === "role")
         || (args[0] === "task" && args[1] === "role");
     return operation && [
         "--model", "--effort", "--clear-model", "--clear-effort"
@@ -1993,8 +2089,8 @@ function configurationMutationAgentId(args, store) {
     const explicit = optionValue(args, "--agent");
     if (explicit !== undefined)
         return explicit;
-    if (args[0] === "role" && args[1] === "update") {
-        return store.getGlobalRole(args[2] ?? "")?.activeAgentId;
+    if (args[0] === "config" && args[1] === "role" && args[2] === "update") {
+        return store.getGlobalRole(args[3] ?? "")?.activeAgentId;
     }
     if (args[0] === "task" && args[1] === "role") {
         if (args[2] === "add")

package/dist/commands/agentCommands.js

@@ -15,7 +15,7 @@ export function runAgentCommand(args, store) {
         default:
             throw usageError(command === undefined
                 ? "Agent command is required."
-                : `Unknown command: agent ${command}`);
+                : `Unknown command: config agent ${command}`);
     }
 }
 function addAgent(args, store) {
@@ -38,12 +38,12 @@ function addAgent(args, store) {
     }
     const created = store.createConfiguredAgentIfAbsent(agent);
     if (created === null) {
-        throw usageError(`Agent already exists: ${id}. Use yui agent update to change it.`);
+        throw usageError(`Agent already exists: ${id}. Use yui config agent update to change it.`);
     }
     return renderAgent(`Added agent ${id}`, created);
 }
 function listAgents(args, store) {
-    assertNoArguments(args, "Agent list usage: yui agent list");
+    assertNoArguments(args, "Agent list usage: yui config agent list");
     const agents = store.listConfiguredAgents();
     if (agents.length === 0)
         return "No agents configured.\n";
@@ -62,7 +62,7 @@ function listAgents(args, store) {
 function showAgent(args, store) {
     const [rawId, ...rest] = args;
     const id = agentId(rawId);
-    assertNoArguments(rest, "Agent show usage: yui agent show <agent-id>");
+    assertNoArguments(rest, "Agent show usage: yui config agent show <agent-id>");
     const agent = store.getConfiguredAgent(id);
     if (agent === null)
         throw agentNotFound(id);
@@ -137,7 +137,7 @@ function updateAgent(args, store) {
 function removeAgent(args, store) {
     const [rawId, ...rest] = args;
     const id = agentId(rawId);
-    assertNoArguments(rest, "Agent remove usage: yui agent remove <agent-id>");
+    assertNoArguments(rest, "Agent remove usage: yui config agent remove <agent-id>");
     const removed = store.transaction((tx) => {
         if (tx.getConfiguredAgent(id) === null)
             return false;