@withandeo/cli 0.19.11 → 0.19.13

package/dist/main.js

@@ -18,7 +18,10 @@ import { captureCommand, runProjectCommand } from "./processes.js";
 import { createDefaultProfileBindings, } from "./profile-bindings.js";
 import { initializeStarter } from "./starter.js";
 import { normalizeAndeoEnvironment } from "./andeo-environment.js";
-import { DOC_TOPICS, readDocumentation, installDocumentation, installedSkillCheck } from "./documentation.js";
+import { readNetworkSecret } from "./network-secret.js";
+import { cloudAgentClient } from "./cloud-agent.js";
+import { DOC_TOPICS, readDocumentation, installDocumentation, installedSkillCheck, skillDocumentationStatus, syncDocumentation } from "./documentation.js";
+import { CLI_PACKAGE_DIRECTORY, configureAutoUpgrade, runUpdateCommand, upgradeCli } from "./updates.js";
 import { capabilityPreflight } from "./capability-preflight.js";
 import { flagEnvironment, flagKey, validateFlagDefinition, flagContext, FLAGSHIP_SCHEMA, FLAG_DELETION_GUIDANCE, FlagCompatibilityError } from "./flagship-contract.js";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
@@ -38,6 +41,8 @@ const DEFAULT_RUNTIME = {
     sleep: async (milliseconds) => await new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)),
     runProjectCommand,
     captureCommand,
+    updateCommand: runUpdateCommand,
+    packageDirectory: CLI_PACKAGE_DIRECTORY,
     authStore: createDefaultAuthStore(process.env),
     profileBindings: createDefaultProfileBindings(process.env),
     openBrowser: openSystemBrowser,
@@ -112,9 +117,21 @@ async function execute(topic, options, cwd, runtime) {
         return { value: await workflowCommand(topic.slice(10), cwd, options, runtime) };
     if (topic.startsWith("email "))
         return { value: await emailCommand(topic.slice(6), cwd, options, runtime) };
+    if (topic.startsWith("agents "))
+        return { value: await agentsCommand(topic.slice(7), cwd, options, runtime) };
     if (topic.startsWith("flagship "))
         return { value: await flagshipCommand(topic.slice(9), cwd, options, runtime) };
     switch (topic) {
+        case "upgrade":
+            if (options.positionals.length)
+                throw new CliError("argument_invalid", "upgrade does not accept positional arguments.");
+            return { value: await upgradeCli(updateRuntime(runtime)) };
+        case "config autoupgrade on":
+        case "config autoupgrade off":
+        case "config autoupgrade status":
+            if (options.positionals.length)
+                throw new CliError("argument_invalid", "autoupgrade does not accept positional arguments.");
+            return { value: await configureAutoUpgrade(topic.split(" ")[2], updateRuntime(runtime)) };
         case "docs": {
             const name = options.positionals[0];
             if (!name)
@@ -144,6 +161,14 @@ async function execute(topic, options, cwd, runtime) {
                 : { raw: await readSkill() };
         case "skill install":
             return { value: await installSkill(cwd, options, runtime) };
+        case "skill status":
+        case "skill sync": {
+            if (options.positionals.length)
+                throw new CliError("argument_invalid", "skill status/sync do not accept positional arguments.");
+            const { agent, base } = skillDestination(cwd, options, runtime);
+            const action = topic === "skill sync" ? syncDocumentation : skillDocumentationStatus;
+            return { value: { agent, ...await action(base, CLI_VERSION, { fetcher: runtime.fetcher }) } };
+        }
         case "skills list": {
             if (options.positionals.length)
                 throw new CliError("skills_arguments_invalid", "skills list does not accept positional arguments.");
@@ -173,6 +198,17 @@ async function execute(topic, options, cwd, runtime) {
             return { value: await preview(cwd, options, runtime, true) };
         case "auth status":
             return { value: await authStatus(cwd, options, runtime) };
+        case "agent status":
+            if (runtime.environment.ANDEO_CLOUD_BOOTSTRAP === undefined)
+                throw new CliError("cloud_agent_required", "This command requires Cloud task-run authentication.");
+            return { value: await authStatus(cwd, options, runtime) };
+        case "agent complete":
+        case "agent cancel": {
+            const client = await cloudAgentClient(runtime.environment, cwd, runtime.fetcher, { tokenStdin: options.booleans.has("token-stdin"), profile: options.flags.has("profile"), apiUrl: selectedApiUrl(options, null, runtime.environment, runtime.defaultApiUrl) });
+            if (!client)
+                throw new CliError("cloud_agent_required", "This command requires Cloud task-run authentication.");
+            return { value: await client.finish(topic === "agent complete" ? "complete" : "cancel") };
+        }
         case "auth list":
             return { value: await authList(runtime) };
         case "auth create":
@@ -351,6 +387,45 @@ async function execute(topic, options, cwd, runtime) {
             throw new CliError("command_unknown", `Unknown command: ${topic}.`, "tender-accounts --help");
     }
 }
+async function agentsCommand(action, cwd, options, runtime) {
+    if (!["list", "show", "suspend", "revoke", "resume", "cancel", "complete"].includes(action))
+        throw new CliError("argument_unknown", "Unknown agents command.");
+    if (runtime.environment.ANDEO_CLOUD_BOOTSTRAP !== undefined || runtime.environment.ANDEO_NETWORK_TOKEN !== undefined
+        || runtime.environment.TENDER_ACCOUNTS_TOKEN !== undefined || options.booleans.has("token-stdin"))
+        throw new CliError("human_cli_required", "Agent management requires a human administrator login profile.", "andeo auth login");
+    const id = options.positionals[0];
+    if (id !== undefined && !/^agt_[A-Za-z0-9_-]+$/u.test(id))
+        throw new CliError("argument_invalid", "Use an agent ID returned by agents list.");
+    let revision;
+    if (!["list", "show"].includes(action)) {
+        const value = requiredFlag(options, "expected-revision");
+        revision = Number(value);
+        if (!/^\d+$/u.test(value) || !Number.isSafeInteger(revision))
+            throw new CliError("argument_invalid", "Use a nonnegative observed agent revision.");
+    }
+    const targets = ["grant", "installation", "bootstrap", "run"].filter(kind => options.flags.has(kind));
+    if (targets.length > 1 || ["cancel", "complete"].includes(action) && targets[0] !== "run"
+        || ["suspend", "resume"].includes(action) && ["bootstrap", "run"].includes(targets[0] ?? ""))
+        throw new CliError("argument_invalid", "Choose one target compatible with this lifecycle action.");
+    const target = targets.length ? { kind: { grant: "grants", installation: "installations", bootstrap: "bootstraps", run: "runs" }[targets[0]], id: options.flags.get(targets[0]) } : undefined;
+    if (target && !/^[A-Za-z0-9_-]{3,180}$/u.test(target.id))
+        throw new CliError("argument_invalid", "Use a target ID returned by agents show.");
+    const access = await authenticatedClient(cwd, (await optionalContext(cwd))?.link ?? null, options, runtime);
+    if (access.source !== "login")
+        throw new CliError("human_cli_required", "Agent management requires a human administrator login profile.", "andeo auth login");
+    const result = await access.client.agents(id, ["list", "show"].includes(action) ? undefined : action, revision, target);
+    if (action === "resume") {
+        const response = result;
+        if (response.status !== "human_confirmation_required" || typeof response.approvalUrl !== "string")
+            throw new CliApiError("invalid_api_response", "Fresh browser confirmation instructions are required.");
+        const url = new URL(response.approvalUrl);
+        if (url.protocol !== "https:" || url.username || url.password)
+            throw new CliApiError("invalid_api_response", "The approval URL must be HTTPS.");
+        if (!options.booleans.has("no-open"))
+            await runtime.openBrowser(url.href);
+    }
+    return result;
+}
 async function emailCommand(action, cwd, options, runtime) {
     if (options.positionals.length)
         throw new CliError("email_arguments_invalid", "Use named email command options.");
@@ -1180,7 +1255,11 @@ async function sourcePush(cwd, options, runtime) {
     const remote = options.flags.get("remote") ?? "tender";
     await ensureGitRemote(gitRoot, remote, source.repository.remoteUrl, runtime);
     const currentBranch = (await runtime.captureCommand("git", ["branch", "--show-current"], gitRoot)).stdout;
-    const branch = options.flags.get("branch") ?? (currentBranch || source.repository.defaultBranch);
+    const branch = options.flags.get("branch") ?? source.repository.assignedFeatureBranch ?? (currentBranch || source.repository.defaultBranch);
+    if (source.repository.assignedFeatureBranch && branch !== source.repository.assignedFeatureBranch)
+        throw new CliError("agent_branch_scope_mismatch", "This run may push only its assigned feature branch.");
+    if (source.repository.assignedFeatureBranch && source.repository.changeRequestProtection !== "enabled")
+        throw new CliError("agent_source_protection_required", "A human administrator must enable reviewed source protection before agent writes.");
     assertGitBranchName(branch);
     const expectedCurrentSha = options.flags.has("expected-current")
         ? requiredSourceSha(options, "expected-current")
@@ -1429,7 +1508,9 @@ async function sourceChangeCreate(cwd, options, runtime) {
         throw new CliError("source_review_not_enabled", "A merchant administrator must enable reviewed changes for this managed repository first.");
     }
     const baseBranch = options.flags.get("base") ?? access.repository.defaultBranch;
-    const headBranch = requiredFlag(options, "head");
+    const headBranch = options.flags.get("head") ?? access.repository.assignedFeatureBranch ?? requiredFlag(options, "head");
+    if (access.repository.assignedFeatureBranch && headBranch !== access.repository.assignedFeatureBranch)
+        throw new CliError("agent_branch_scope_mismatch", "This run may prepare review only for its assigned feature branch.");
     const title = requiredFlag(options, "title");
     assertGitBranchName(baseBranch);
     assertGitBranchName(headBranch);
@@ -1673,6 +1754,9 @@ async function authList(runtime) {
     };
 }
 async function authLogin(cwd, options, runtime) {
+    if (runtime.environment.ANDEO_NETWORK_TOKEN !== undefined || runtime.environment.ANDEO_CLOUD_BOOTSTRAP !== undefined) {
+        assertNoEnvironmentCredentialForProfileManagement(runtime.environment);
+    }
     return await authenticateProfile(cwd, options, runtime, DEFAULT_AUTH_PROFILE, options.booleans.has("force"));
 }
 async function authCreate(cwd, options, runtime) {
@@ -1734,8 +1818,8 @@ async function authenticateProfile(cwd, options, runtime, profile, replaceExisti
             };
         }
         const token = await waitForDeviceToken(oauth, pending, profile, runtime);
-        await saveTokenResponse(runtime.authStore, profile, apiUrl, token, oauth, pending);
-        return await authenticatedLoginSummary(apiUrl, token, profile, runtime);
+        const stored = await saveTokenResponse(runtime.authStore, profile, apiUrl, token, oauth, pending);
+        return await authenticatedLoginSummary(apiUrl, token, profile, runtime, stored);
     }
     const pkce = createPkcePair();
     const callback = await runtime.waitForLoopbackAuthorization({
@@ -1759,8 +1843,8 @@ async function authenticateProfile(cwd, options, runtime, profile, replaceExisti
         codeVerifier: pkce.verifier,
         redirectUri: callback.redirectUri,
     });
-    await saveTokenResponse(runtime.authStore, profile, apiUrl, token, oauth, null);
-    return await authenticatedLoginSummary(apiUrl, token, profile, runtime);
+    const stored = await saveTokenResponse(runtime.authStore, profile, apiUrl, token, oauth, null);
+    return await authenticatedLoginSummary(apiUrl, token, profile, runtime, stored);
 }
 async function authActivate(cwd, options, runtime) {
     assertNoEnvironmentCredentialForProfileManagement(runtime.environment);
@@ -1811,11 +1895,19 @@ async function authDelete(_cwd, options, runtime) {
     };
 }
 function assertNoEnvironmentCredentialForProfileManagement(environment) {
+    if (environment.ANDEO_CLOUD_BOOTSTRAP !== undefined)
+        throw new CliError("auth_profile_environment_override", "Cloud agent mode disables human profile management.", "Manage the installation in Andeo and the bootstrap in the Cloud network-secret vault.");
+    if (environment.ANDEO_NETWORK_TOKEN !== undefined) {
+        throw new CliError("auth_profile_environment_override", "ANDEO_NETWORK_TOKEN selects proxy-supplied authentication; local profile management is disabled.", "Manage the network secret in the cloud environment and revoke its credential in Andeo.");
+    }
     if (!environment.TENDER_ACCOUNTS_TOKEN)
         return;
     throw new CliError("auth_profile_environment_override", "TENDER_ACCOUNTS_TOKEN overrides local auth profiles, so profile management is disabled for this command.", "Unset TENDER_ACCOUNTS_TOKEN, then retry the auth profile command.");
 }
 async function authLogout(_cwd, options, runtime) {
+    if (runtime.environment.ANDEO_NETWORK_TOKEN !== undefined || runtime.environment.ANDEO_CLOUD_BOOTSTRAP !== undefined) {
+        assertNoEnvironmentCredentialForProfileManagement(runtime.environment);
+    }
     if (options.booleans.has("all") && options.booleans.has("local")) {
         await runtime.authStore.clearAll();
         await runtime.profileBindings.clearAll();
@@ -2144,6 +2236,16 @@ async function deliveryRetry(cwd, options, runtime) {
 }
 async function authenticatedClient(cwd, link, options, runtime) {
     let apiUrl = selectedApiUrl(options, link, runtime.environment, runtime.defaultApiUrl);
+    const cloud = await cloudAgentClient(runtime.environment, cwd, runtime.fetcher, { tokenStdin: options.booleans.has("token-stdin"), profile: options.flags.has("profile"), apiUrl });
+    if (cloud)
+        return { client: new AgentApiClient(apiUrl, "task-run", cloud.fetcher), apiUrl, source: "cloud-agent", accessTokenExpiresAt: cloud.accessTokenExpiresAt };
+    const networkSecret = readNetworkSecret(runtime.environment, apiUrl);
+    if (networkSecret !== undefined) {
+        if (options.booleans.has("token-stdin") || options.flags.has("profile")) {
+            throw new CliError("network_secret_auth_conflict", "ANDEO_NETWORK_TOKEN cannot be combined with --token-stdin or --profile.");
+        }
+        return { client: new AgentApiClient(apiUrl, networkSecret, runtime.fetcher), apiUrl, source: "network-secret" };
+    }
     const stdin = options.booleans.has("token-stdin") ? runtime.stdin : undefined;
     const explicit = await readOptionalToken(cwd, runtime.environment, stdin);
     if (explicit) {
@@ -2247,13 +2349,23 @@ function authCommandForProfile(profile) {
 }
 async function saveTokenResponse(store, profile, apiUrl, token, oauth, previous, acceptConcurrentRefreshWinner = false) {
     const now = Date.now();
+    const accessDeadline = Date.parse(tokenDeadline(token.expires_at, token.expires_in, now));
+    let sessionDeadline = Date.parse(tokenDeadline(token.session_expires_at, token.refresh_expires_in, now));
+    if (previous?.refreshToken && previous.refreshTokenExpiresAt) {
+        // Rotation cannot extend a human session, including against older servers
+        // that advertise the original full duration again on every refresh.
+        const previousDeadline = Date.parse(previous.refreshTokenExpiresAt);
+        if (Number.isFinite(previousDeadline)) {
+            sessionDeadline = Math.min(previousDeadline, sessionDeadline);
+        }
+    }
     const stored = {
         schema: CLI_AUTH_SCHEMA,
         apiUrl,
         accessToken: token.access_token,
-        accessTokenExpiresAt: new Date(now + token.expires_in * 1000).toISOString(),
+        accessTokenExpiresAt: new Date(Math.min(accessDeadline, sessionDeadline)).toISOString(),
         refreshToken: token.refresh_token,
-        refreshTokenExpiresAt: new Date(now + token.refresh_expires_in * 1000).toISOString(),
+        refreshTokenExpiresAt: new Date(sessionDeadline).toISOString(),
         ...(previous?.principal ? { principal: previous.principal } : {}),
     };
     if (!await store.compareAndSwap(profile, previous, stored)) {
@@ -2272,6 +2384,21 @@ async function saveTokenResponse(store, profile, apiUrl, token, oauth, previous,
     }
     return stored;
 }
+function tokenDeadline(absolute, seconds, now) {
+    if (absolute !== undefined) {
+        if (typeof absolute !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(absolute)
+            || !Number.isFinite(Date.parse(absolute)) || new Date(absolute).toISOString() !== absolute) {
+            throw new CliApiError("invalid_api_response", "Andeo returned an invalid credential deadline.");
+        }
+        return absolute;
+    }
+    // Compatibility with APIs released before absolute deadline reporting.
+    if (!Number.isSafeInteger(seconds) || seconds < 0 || !Number.isFinite(now + seconds * 1000)
+        || now + seconds * 1000 > 8.64e15) {
+        throw new CliApiError("invalid_api_response", "Andeo returned an invalid credential lifetime.");
+    }
+    return new Date(now + seconds * 1000).toISOString();
+}
 async function concurrentRefreshWinner(store, profile, previous) {
     const current = await store.read(profile);
     if (!current
@@ -2320,7 +2447,7 @@ async function waitForDeviceToken(oauth, pending, profile, runtime) {
     await clearStoredProfile(runtime.authStore, profile, pending);
     throw new CliError("device_authorization_expired", "The device authorization expired.", `${authCommandForProfile(profile)} --device --json`);
 }
-async function authenticatedLoginSummary(apiUrl, token, profile, runtime) {
+async function authenticatedLoginSummary(apiUrl, token, profile, runtime, stored) {
     const principal = await new AgentApiClient(apiUrl, token.access_token, runtime.fetcher).whoami();
     await savePrincipalSummary(runtime.authStore, profile, principal);
     return {
@@ -2329,9 +2456,10 @@ async function authenticatedLoginSummary(apiUrl, token, profile, runtime) {
         apiUrl,
         profile,
         ownerEmail: principal.ownerEmail,
+        ...(principal.ownerPrincipalId ? { ownerPrincipalId: principal.ownerPrincipalId } : {}),
         tenantId: principal.tenantId,
         projects: principal.projects,
-        accessTokenExpiresAt: new Date(Date.now() + token.expires_in * 1000).toISOString(),
+        accessTokenExpiresAt: stored.accessTokenExpiresAt,
         storage: runtime.authStore.description(),
         containsCredential: false,
     };
@@ -2434,6 +2562,14 @@ async function optionalContext(cwd) {
     }
 }
 async function installSkill(cwd, options, runtime) {
+    const { agent, base } = skillDestination(cwd, options, runtime);
+    return { status: "installed", agent, ...await installDocumentation(base, options.booleans.has("force"), CLI_VERSION, { fetcher: runtime.fetcher, bundled: options.booleans.has("bundled") }) };
+}
+function updateRuntime(runtime) {
+    return { ...runtime, version: CLI_VERSION, runner: runtime.updateCommand, now: Date.now,
+        notify: message => { runtime.stderr.write(`${message}\n`); } };
+}
+function skillDestination(cwd, options, runtime) {
     const agent = options.flags.get("agent") ?? "codex";
     const requestedDirectory = options.flags.get("directory");
     const base = requestedDirectory
@@ -2446,7 +2582,7 @@ async function installSkill(cwd, options, runtime) {
     if (!base) {
         throw new CliError("skill_target_invalid", "--agent must be codex or claude unless --directory is provided.");
     }
-    return { status: "installed", agent, ...await installDocumentation(base, options.booleans.has("force"), CLI_VERSION, { fetcher: runtime.fetcher, bundled: options.booleans.has("bundled") }) };
+    return { agent, base };
 }
 async function readSkill() {
     return await readFile(skillPath(), "utf8");
@@ -2570,10 +2706,16 @@ function commandTopic(argv) {
         const topic = `preview ${argv[1]}`;
         return argv.includes("--help") || argv.includes("-h") ? { topic: "help", values: [topic] } : { topic, values: argv.slice(2) };
     }
-    if (parent === "artifact" || parent === "email" || parent === "auth" || parent === "delivery" || parent === "source" || parent === "vars" || parent === "skill" || parent === "skills" || parent === "config" || parent === "production" || parent === "workflows") {
+    if (parent === "agents" || parent === "agent" || parent === "artifact" || parent === "email" || parent === "auth" || parent === "delivery" || parent === "source" || parent === "vars" || parent === "skill" || parent === "skills" || parent === "config" || parent === "production" || parent === "workflows") {
         const child = argv[1];
         if (!child || child.startsWith("--"))
             return { topic: "help", values: [parent] };
+        if (parent === "config" && child === "autoupgrade") {
+            const action = argv[2];
+            if (!action || action.startsWith("-") || argv.includes("--help") || argv.includes("-h"))
+                return { topic: "help", values: ["config autoupgrade"] };
+            return { topic: `config autoupgrade ${action}`, values: argv.slice(3) };
+        }
         if (parent === "source" && child === "merge" && argv[2] && !argv[2].startsWith("-")) {
             const topic = `source merge ${argv[2]}`;
             return argv.includes("--help") || argv.includes("-h") ? { topic: "help", values: [topic] } : { topic, values: argv.slice(3) };
@@ -2661,6 +2803,10 @@ function assertAllowedOptions(topic, options) {
     const authentication = ["api-url", "token-stdin", "profile"];
     const allowed = {
         "artifact finalize": [...common, "artifact-directory"],
+        upgrade: common,
+        "config autoupgrade on": common,
+        "config autoupgrade off": common,
+        "config autoupgrade status": common,
         docs: common,
         capabilities: [...common, ...authentication, "project"],
         "email capabilities": [...common, ...authentication, "tenant", "project"],
@@ -2690,6 +2836,8 @@ function assertAllowedOptions(topic, options) {
         "config example": common,
         "skill print": common,
         "skill install": [...common, "agent", "directory", "force", "bundled"],
+        "skill status": [...common, "agent", "directory"],
+        "skill sync": [...common, "agent", "directory"],
         "skills list": [...common, ...authentication],
         "skills get": [...common, ...authentication],
         "skills file": [...common, ...authentication, "path"],
@@ -2705,6 +2853,16 @@ function assertAllowedOptions(topic, options) {
         "auth deactivate": common,
         "auth login": [...common, "api-url", "project", "client-name", "timeout-seconds", "device", "wait", "no-open", "force"],
         "auth logout": [...common, "local", "all"],
+        "agent status": [...common, ...authentication],
+        "agent complete": [...common],
+        "agent cancel": [...common],
+        "agents list": [...common, ...authentication],
+        "agents show": [...common, ...authentication],
+        "agents suspend": [...common, ...authentication, "expected-revision", "grant", "installation"],
+        "agents revoke": [...common, ...authentication, "expected-revision", "grant", "installation", "bootstrap", "run"],
+        "agents resume": [...common, ...authentication, "expected-revision", "no-open", "grant", "installation"],
+        "agents cancel": [...common, ...authentication, "expected-revision", "run"],
+        "agents complete": [...common, ...authentication, "expected-revision", "run"],
         link: [...common, ...authentication, "project"],
         doctor: [...common, ...authentication],
         preview: [
@@ -2811,6 +2969,12 @@ function assertAllowedOptions(topic, options) {
         "auth delete": { minimum: 1, maximum: 1 },
         "auth activate": { minimum: 1, maximum: 2 },
         "auth deactivate": { minimum: 0, maximum: 1 },
+        "agents show": { minimum: 1, maximum: 1 },
+        "agents suspend": { minimum: 1, maximum: 1 },
+        "agents revoke": { minimum: 1, maximum: 1 },
+        "agents resume": { minimum: 1, maximum: 1 },
+        "agents cancel": { minimum: 1, maximum: 1 },
+        "agents complete": { minimum: 1, maximum: 1 },
     };
     const limit = positionalLimits[topic] ?? { minimum: 0, maximum: 0 };
     if (options.positionals.length < limit.minimum) {
@@ -2899,6 +3063,26 @@ function writeOutput(value, options, runtime) {
     runtime.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 function helpText(topic) {
+    if (topic === "agents" || topic?.startsWith("agents "))
+        return `Usage: andeo agents list [--profile HUMAN_PROFILE] [--json]
+       andeo agents show AGENT_ID [--profile HUMAN_PROFILE] [--json]
+       andeo agents <suspend|revoke|resume> AGENT_ID --expected-revision N [--profile HUMAN_PROFILE] [--json]
+       andeo agents <cancel|complete> AGENT_ID --run RUN_ID --expected-revision N [--profile HUMAN_PROFILE] [--json]
+
+Human administrators inspect and manage persistent agents within their CLI project's ceiling.
+Use authorization_epoch from agents show as --expected-revision. Suspend and revoke commit immediately.
+Use --grant ID or --installation ID for one descendant; revoke also accepts --bootstrap ID or --run ID.
+Resume opens the organization's Persistent agents panel for fresh browser review and confirmation;
+it reports human_confirmation_required and does not resume authority itself. Use --no-open for instructions.
+Resuming permits new runs only. Lost or compromised credentials require grant replacement in the panel.
+Agents are separate from human login profiles; agent task credentials cannot manage grants.`;
+    if (topic === "agent" || topic?.startsWith("agent "))
+        return `Usage: andeo agent <status|complete|cancel> [--json]
+
+Inspect or end this Cloud task's exact admitted run. Complete and cancel remove local task keys only after Andeo confirms the outcome. A completed, cancelled or expired task cannot re-admit with the same state directory.
+Requires the Cloud bootstrap placeholder, dedicated admission origin, private task state directory, explicit scope and run duration. Human profiles and legacy tokens cannot be combined with Cloud mode.`;
+    if (topic?.startsWith("config autoupgrade "))
+        topic = "config autoupgrade";
     if (topic === "flagship")
         return `Usage: andeo flagship apps ensure|list --env ENV [--collection NAME] [--project ID] [--json]
        andeo flagship apps get|rename|disconnect|delete|reconcile APP_ID --env ENV [--expected-revision N] [--name NAME] [--confirm EXACT_ID]
@@ -2945,6 +3129,8 @@ Choose background preview routing with preview-service-set --target-project PROJ
 Only non-secret JSON belongs in workflow params/events. Keep credentials in the connected service's native secrets.
 Account workflow entitlement is required for new starts. Run status is authoritative; list results are a timestamped projection.`;
     const topics = {
+        upgrade: "Usage: andeo upgrade [--json]\n\nUpgrade a verified global npm, pnpm or Yarn 1 installation to the latest stable CLI. Explicit upgrades can cross compatibility boundaries. CI, temporary npx and project-local installs must use their package manager. The next invocation uses the new CLI.",
+        "config autoupgrade": "Usage: andeo config autoupgrade <on|off|status> [--json]\n\nGlobal CLI upgrades default on and run after successful commands at most once daily. Before 1.0, only patches within the current minor are automatic; afterward, updates stay in the current major. Off retains daily reminders and independent global skill refresh. Help, version, CI and explicit maintenance commands skip automatic maintenance.",
         vars: "Usage: andeo vars <list|set|unset> --environment preview|production [options]\n\nManage saved non-secret runtime variables. Changes apply on the next delivery.",
         "source reconnect": "Usage: andeo source reconnect <prepare|status|complete|cancel> [options]\n\nMove a legacy managed repository to its tenant namespace by preparing, pushing, and completing.",
         "source reconnect prepare": "Usage: andeo source reconnect prepare --repository SRC_ID --idempotency-key KEY [--project PROJECT_ID] [--json]\n\nPause the old source and prepare its tenant destination. Merchant administrator required.",
@@ -3023,19 +3209,21 @@ Account workflow entitlement is required for new starts. Run status is authorita
         "preview entries": "Usage: andeo preview entries [--json]\n\nList eligible published entry apps and the selected default for this linked app.",
         "preview open": "Usage: andeo preview open --from dly_...|sbl_... [--through PROJECT_ID] [--return-path /account] [--json]\n\nOpen the exact deployed preview without rebuilding or uploading. Private apps open through their published connections. Opening again renews access.",
         "delivery retry": "Usage: andeo delivery retry --delivery dly_... [--reauthorize] [--json]\n\nRetry one requested or failed developer preview idempotently. --reauthorize explicitly authorizes a legacy preview for the same owner and linked project using the current CLI login; it cannot replace another login's recorded grant or publish production. Normal credential refresh needs no flag. A dwf_ production workflow is resumed by a merchant administrator from Activity.",
-        skill: "Usage: andeo skill <print|install> [options]",
+        skill: "Usage: andeo skill <print|install|status|sync> [options]",
+        "skill status": "Usage: andeo skill status [--agent codex|claude] [--directory PATH] [--json]\n\nCheck the installed guide against the compatible public revision. Reports local_changes, unmanaged or not_installed without overwriting files. Offline and incompatible checks fail explicitly.",
+        "skill sync": "Usage: andeo skill sync [--agent codex|claude] [--directory PATH] [--json]\n\nRefresh an existing, unchanged Andeo-managed guide. Preserve local edits and unrelated files. Outages and incompatible bundles retain installed guidance. After status=updated, reread SKILL.md and relevant references in active chats. Use skill install for a missing guide.",
         "skill print": "Usage: andeo skill print [--json]",
         "skill install": "Usage: andeo skill install [--agent codex|claude] [--directory PATH] [--force] [--bundled] [--json]\n\nFetch the latest compatible public Andeo guide without login. A fresh install falls back to the bundled guide during an outage; existing installations are preserved. --bundled explicitly selects this CLI's offline guide. --force replaces owned files, preserving unrelated files. Installs globally: ~/.agents/skills for Codex or ~/.claude/skills for Claude. --directory overrides the location.\n\nExamples:\n  andeo skill install --agent codex --json\n  andeo skill install --agent codex --force --json\n  andeo skill install --bundled --directory ./skills --json",
         skills: "Usage: andeo skills <list|get|file> [options]\n\nAuthenticated, session-only access to Andeo practice skills. Content is not installed into the repository.\n\nExamples:\n  andeo skills list --json\n  andeo skills get recharge-client\n  andeo skills file recharge-customer-operations --path references/subscriptions.md",
         "skills list": "Usage: andeo skills list [--profile NAME] [--api-url URL] [--json]\n\nList the practice skills available to the authenticated Andeo user.",
         "skills get": "Usage: andeo skills get SKILL_ID [--profile NAME] [--api-url URL] [--json]\n\nRead one skill entrypoint for the current invocation.\n\nExample:\n  andeo skills get guardrailed-design-system",
         "skills file": "Usage: andeo skills file SKILL_ID --path PATH [--profile NAME] [--api-url URL] [--json]\n\nRead one catalog-listed supporting file for the current invocation.\n\nExample:\n  andeo skills file recharge-customer-operations --path references/subscriptions.md",
-        config: "Usage: andeo config example [--json]",
+        config: "Usage: andeo config example [--json]\n       andeo config autoupgrade <on|off|status> [--json]",
         "config example": "Usage: andeo config example [--json]\n\nPrint the committed tender-accounts.json contract.",
     };
     if (topic && topics[topic])
         return topics[topic];
-    return `Andeo merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  docs              Read version-matched offline guides\n  capabilities      Inspect scoped support, enablement and permissions\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  upload            Retain a build for administrator publication\n  preview           Build and deploy an exact preview\n  preview entries   List eligible connected entry apps\n  preview open      Reopen an exact deployed preview\n  source status     Inspect Andeo-managed Git and recent builds\n  source branches   List exact managed branches and default policy\n  source compare    Compare two managed branches\n  source connect    Connect this linked project to managed Git\n  source reconnect  Prepare, inspect, complete or cancel a tenant namespace cutover\n  source pull       Clone or fast-forward the exact connected repository\n  source token      Issue a short-lived repository credential\n  source push       Push the exact commit without persisting a token\n  source promote    Fast-forward the default after successful preview checks\n  source history    Run guarded, archived source-history migration\n  email             Create and reuse merchant email identities\n  workflows         Inspect and control app-defined background runs\n  vars              Manage saved per-environment runtime variables\n  source policy     Inspect or change automatic publication\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery retry    Retry a failed preview workflow\n  skill install     Install the Andeo agent skill\n  skills list       Discover authenticated practice skills\n  skills get        Read an authenticated practice skill\n  skills file       Read one authenticated skill resource\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun andeo <command> --help for examples.`;
+    return `Andeo merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  docs              Read version-matched offline guides\n  capabilities      Inspect scoped support, enablement and permissions\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  agents            Human administration of persistent agents\n  agent             Inspect or end this Cloud task's run\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  upload            Retain a build for administrator publication\n  preview           Build and deploy an exact preview\n  preview entries   List eligible connected entry apps\n  preview open      Reopen an exact deployed preview\n  source status     Inspect Andeo-managed Git and recent builds\n  source branches   List exact managed branches and default policy\n  source compare    Compare two managed branches\n  source connect    Connect this linked project to managed Git\n  source reconnect  Prepare, inspect, complete or cancel a tenant namespace cutover\n  source pull       Clone or fast-forward the exact connected repository\n  source token      Issue a short-lived repository credential\n  source push       Push the exact commit without persisting a token\n  source promote    Fast-forward the default after successful preview checks\n  source history    Run guarded, archived source-history migration\n  email             Create and reuse merchant email identities\n  workflows         Inspect and control app-defined background runs\n  vars              Manage saved per-environment runtime variables\n  source policy     Inspect or change automatic publication\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery retry    Retry a failed preview workflow\n  upgrade           Upgrade a verified global CLI installation\n  config autoupgrade Configure automatic CLI upgrades\n  skill install     Install the Andeo agent skill\n  skill status      Inspect installed guidance freshness\n  skill sync        Refresh unchanged managed guidance\n  skills list       Discover authenticated practice skills\n  skills get        Read an authenticated practice skill\n  skills file       Read one authenticated skill resource\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun andeo <command> --help for examples.`;
 }
 function normalizeError(error) {
     if (error instanceof FlagCompatibilityError)