@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/agents.js

@@ -15,8 +15,11 @@
  *   hq agents start|stop <uid>     — EC2 start/stop
  *   hq agents retry <uid>          — resume setup from first non-done step
  *   hq agents rm <uid> --yes       — deprovision (destructive; flag-guarded)
+ *   hq agents rotate <uid>         — new enrollment code for an external agent
+ *   hq agents revoke <uid> --yes   — revoke an external agent (--remove deletes it)
  *   hq agents jobs list <uid>      — off-box job roster (schedule + rate)
  *   hq agents jobs pause <uid> <jobId>  — flip schedule State=DISABLED
+ *   hq agents jobs resume <uid> <jobId> — flip schedule State=ENABLED
  *   hq agents jobs cancel <uid> <jobId> — delete schedule + drop the job
  *
  * Agents are company-scoped. `--company <slug>` may sit on the group
@@ -28,11 +31,17 @@ import chalk from "chalk";
 import { randomUUID } from "node:crypto";
 import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
+import { maxLength } from "../utils/table-width.js";
+import { DEFAULT_VAULT_API_URL } from "../utils/cognito-session.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
+import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { consoleOrigin } from "./integrations-connect.js";
 import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, waitForTerminalSession, } from "@indigoai-us/hq-cloud/outposts/node";
 import { peekIdToken } from "../utils/id-token.js";
-import { isPlanGateError } from "../utils/plan-gate-error.js";
+import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, } from "../utils/plan-gate-error.js";
+import { AGENT_UID_PATTERN, isAgentUid } from "../lib/notify-recipient.js";
+import { AGENT_MODEL_PROVIDERS, modelSelectionErrorMessage, readAgentModelCatalog, validateAgentModelSelection, } from "../lib/agents/model-catalog.js";
 import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
@@ -50,6 +59,107 @@ export const VALID_PROVIDERS = new Set(["codex", "grok", "claude", "agents-v2"])
 export const VALID_AUTH_MODES = new Set(["subscription", "apiKey"]);
 /** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
 export const VALID_AGENT_SIZE_KEYS = new Set(["basic", "power", "dev"]);
+// Keep cloud agent create slugs aligned with hq-pro-agents POST /v1/agents.
+const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const CLAUDE_PROVISION_COMMAND = "hq agents provision <name> --provider agents-v2 --model <model-id>";
+const CLAUDE_API_KEY_ARGS = "--auth-mode apiKey --api-key-env <VAR>";
+function claudeProvisionGuidance() {
+    return [
+        "The account must be enabled for Claude. Subscription auth is the default.",
+        "Use `hq agents models` to see the current model ids.",
+        `Create an agent with: ${CLAUDE_PROVISION_COMMAND}`,
+        `For API-key auth, add: ${CLAUDE_API_KEY_ARGS}`,
+        "The CLI accepts --provider claude for script compatibility, but the server rejects new agents that use it.",
+    ].join("\n");
+}
+/**
+ * `hq agents create` exits with this distinct status when payment is required.
+ * Scripts can distinguish the expected upgrade state from an ordinary command
+ * failure without parsing human output.
+ */
+export const AGENT_CREATE_PAYMENT_REQUIRED_EXIT_CODE = 3;
+function isCheckoutUrl(value) {
+    if (typeof value !== "string" || !value.trim())
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decode only the priced response defined by the agent-create contract. A
+ * lookalike 403 must stay an ordinary API error rather than opening a browser
+ * or guessing at a price.
+ */
+export function agentCreatePlanLimitFromPayload(status, body) {
+    if (status !== 403 || !body || typeof body !== "object")
+        return null;
+    const payload = body;
+    if (payload.code !== "AGENT_PLAN_LIMIT" ||
+        payload.reasonCode !== "plan_limit" ||
+        payload.requiredPlan !== "agents-500" ||
+        typeof payload.amountMinor !== "number" ||
+        !Number.isSafeInteger(payload.amountMinor) ||
+        payload.amountMinor < 0 ||
+        typeof payload.currency !== "string" ||
+        !/^[A-Za-z]{3}$/.test(payload.currency)) {
+        return null;
+    }
+    if (payload.checkoutUrl !== undefined && !isCheckoutUrl(payload.checkoutUrl)) {
+        return null;
+    }
+    return {
+        requiredPlan: "agents-500",
+        amountMinor: payload.amountMinor,
+        currency: payload.currency.toUpperCase(),
+        ...(typeof payload.checkoutUrl === "string"
+            ? { checkoutUrl: payload.checkoutUrl }
+            : {}),
+    };
+}
+function formatServerPrice(amountMinor, currency) {
+    return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency,
+    }).format(amountMinor / 100);
+}
+async function offerAgentCheckout(url) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await offerUpgradeLink(url, {
+            interactive: true,
+            ask: (question) => new Promise((resolve) => rl.question(question, resolve)),
+        });
+    }
+    catch {
+        console.error("Could not open the upgrade page automatically. Use the URL above.");
+        return false;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Print a server-priced plan block without minting or rewriting its URL. */
+export async function surfaceAgentCreatePlanLimit(planLimit, opts = {}) {
+    const price = `${formatServerPrice(planLimit.amountMinor, planLimit.currency)}/month`;
+    const reason = `HQ Workforce plan required to create an agent (${price}).`;
+    const argv = opts.json ? [...process.argv, "--json"] : process.argv;
+    const interactive = canOfferTeamUpgrade(argv);
+    if (!planLimit.checkoutUrl) {
+        console.error(reason);
+        console.error("Ask a company owner to upgrade before creating an agent.");
+        queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
+        return;
+    }
+    console.error(formatUpgradeRefusal(reason, planLimit.checkoutUrl, { urlOnly: !interactive }));
+    const exposure = queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
+    if (interactive && await offerAgentCheckout(planLimit.checkoutUrl)) {
+        queueCliLimitNoticeEngagement(exposure);
+    }
+}
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the
  * offending input and the legal set.
@@ -112,14 +222,35 @@ export class AgentsHttpError extends Error {
     code;
     /** hq-pro's billing envelope on a `402 billing_required` provision block. */
     billing;
-    constructor(status, message, code, billing) {
+    /** Strictly decoded priced `403 AGENT_PLAN_LIMIT` create response. */
+    agentCreatePlanLimit;
+    constructor(status, message, code, billing, agentCreatePlanLimit) {
         super(message);
         this.name = "AgentsHttpError";
         this.status = status;
         this.code = code;
         this.billing = billing;
+        this.agentCreatePlanLimit = agentCreatePlanLimit;
     }
 }
+/**
+ * STATUS column for `hq agents list`.
+ *
+ * `agentStatus` is the agent's own stored runtime status and is NOT rewritten
+ * when a teardown starts — an agent that never finished provisioning and is
+ * now being removed keeps reading `provisioning` until the teardown completes
+ * and archives it. Observed live on liverecover/sean 2026-09-21: a removal that
+ * stalled on an object-locked vault bucket sat in the roster as `provisioning`,
+ * so the operator believed the removal had never been accepted. The roster
+ * already carries `setupPhase`, so prefer it whenever a teardown is in flight.
+ */
+export function rosterStatusLabel(agent) {
+    if (agent.setupPhase === "deprovisioning")
+        return "removing";
+    if (agent.setupPhase === "deprovisioned")
+        return "removed";
+    return agent.agentStatus ?? "";
+}
 /**
  * Authenticated JSON round-trip against the agents control plane. Throws
  * `AgentsHttpError` on any non-2xx (never swallows — hq-never-swallow-errors),
@@ -134,7 +265,7 @@ export async function agentsRequest(opts) {
         // decline copy ("Your card was declined…") while `error` is the generic
         // "payment required" — error-first would feed surfaceBillingBlocked the
         // generic string and lose the decline reason (mirrors outpostRequest).
-        body.message ?? body.error ?? res.statusText, body.code, parseBillingPayload(body));
+        body.message ?? body.error ?? res.statusText, body.code, parseBillingPayload(body), agentCreatePlanLimitFromPayload(res.status, body) ?? undefined);
     }
     return (await res.json());
 }
@@ -146,6 +277,51 @@ export function slugifyAgentName(name) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
+async function readProvisionSlackTokensFromStdin() {
+    let value = "";
+    for await (const chunk of process.stdin)
+        value += String(chunk);
+    return value;
+}
+function parseProvisionSlackTokensFromStdin(value) {
+    const lines = value
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length < 1 || lines.length > 2) {
+        throw new Error("--slack-tokens-stdin expects one line with the bot token and an optional second line with the Socket Mode app token.");
+    }
+    return { botToken: lines[0], ...(lines[1] ? { appToken: lines[1] } : {}) };
+}
+/**
+ * Resolve write-only Slack credentials without printing them. Flags are useful
+ * for automation; HQ_SLACK_BOT_TOKEN/HQ_SLACK_APP_TOKEN and stdin avoid shell
+ * history. Multiple sources are rejected so the selected credential is clear.
+ */
+export async function resolveProvisionSlackTokens(options, environment = process.env, readStdin = readProvisionSlackTokensFromStdin) {
+    const optionBotToken = options.slackBotToken?.trim();
+    const optionAppToken = options.slackAppToken?.trim();
+    const environmentBotToken = environment.HQ_SLACK_BOT_TOKEN?.trim();
+    const environmentAppToken = environment.HQ_SLACK_APP_TOKEN?.trim();
+    const hasFlagOrEnvironment = Boolean(optionBotToken || optionAppToken || environmentBotToken || environmentAppToken);
+    if (options.slackTokensStdin) {
+        if (hasFlagOrEnvironment) {
+            throw new Error("Use --slack-tokens-stdin or the Slack token flags/environment variables, not both.");
+        }
+        return parseProvisionSlackTokensFromStdin(await readStdin());
+    }
+    if ((optionBotToken || optionAppToken) && (environmentBotToken || environmentAppToken)) {
+        throw new Error("Use Slack token flags or HQ_SLACK_BOT_TOKEN/HQ_SLACK_APP_TOKEN, not both.");
+    }
+    const botToken = optionBotToken || environmentBotToken;
+    const appToken = optionAppToken || environmentAppToken;
+    if (!botToken && !appToken)
+        return undefined;
+    if (!botToken) {
+        throw new Error("A Slack app token requires a Slack bot token.");
+    }
+    return { botToken, ...(appToken ? { appToken } : {}) };
+}
 /** Closed set shared with hq-pro's agent_create_* funnel contract. */
 export const CLI_AGENT_CREATE_SURFACE = "cli_agents_create";
 /** Read hq-pro's company-specific creation prices and capacities. */
@@ -242,7 +418,7 @@ export async function promptForAgentCreateSize(view) {
     }
 }
 /** Confirm creation using the server quote, preserving $0 as a real answer. */
-export function confirmAgentCreateQuoteOrExit(option, yes) {
+export function confirmAgentCreateQuoteOrExit(option, yes, quiet = false) {
     if (option.notBilled || option.netMonthlyCents === 0) {
         const message = `${option.productName} is ${formatUsd(0)}/month for this company — ` +
             "there is no per-agent charge.";
@@ -250,14 +426,26 @@ export function confirmAgentCreateQuoteOrExit(option, yes) {
             console.error(chalk.yellow(`${message}\nRe-run with --yes to confirm agent provisioning.`));
             process.exit(1);
         }
-        console.log(chalk.dim(`${message} Provisioning…`));
+        if (!quiet) {
+            console.log(chalk.dim(`${message} Provisioning…`));
+        }
         return;
     }
-    confirmChargeOrExit({
-        resource: "agent",
-        unitCents: option.netMonthlyCents,
-        yes,
-    });
+    if (!quiet) {
+        confirmChargeOrExit({
+            resource: "agent",
+            unitCents: option.netMonthlyCents,
+            yes,
+        });
+        return;
+    }
+    if (!yes) {
+        confirmChargeOrExit({
+            resource: "agent",
+            unitCents: option.netMonthlyCents,
+            yes,
+        });
+    }
 }
 export async function provisionAgent(token, input) {
     return agentsRequest({
@@ -281,6 +469,277 @@ export async function getAgentStatus(token, agentUid) {
         path: `/v1/agents/${encodeURIComponent(agentUid)}/status`,
     });
 }
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function safeActionUrl(value) {
+    const raw = nonEmptyString(value);
+    if (!raw)
+        return null;
+    try {
+        const url = new URL(raw);
+        return url.protocol === "https:" && !url.username && !url.password ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+function signInProviderName(url) {
+    const parsed = new URL(url);
+    if (parsed.hostname === "auth.openai.com" &&
+        parsed.pathname.startsWith("/codex/")) {
+        return "Codex";
+    }
+    if (parsed.hostname === "accounts.x.ai")
+        return "Grok";
+    if (parsed.hostname.endsWith("anthropic.com"))
+        return "Claude";
+    return "your provider";
+}
+/**
+ * Brain slot a device sign-in URL belongs to, or null when the provider has no
+ * per-brain slot (Claude) or the host is unknown.
+ */
+function signInBrainSlot(url) {
+    const provider = signInProviderName(url);
+    if (provider === "Grok")
+        return "grok";
+    if (provider === "Codex")
+        return "codex";
+    return null;
+}
+/**
+ * True when the box probe already reports that brain as signed in. A device
+ * pairing file can outlive the sign-in it started, so the probe — not the
+ * leftover code — decides whether a human still has work to do.
+ */
+function brainAlreadySignedIn(status, url) {
+    const slot = signInBrainSlot(url);
+    if (!slot)
+        return false;
+    const brains = recordValue(recordValue(status.agent)?.brains);
+    return brains?.[slot] === "signed-in";
+}
+function currentDeviceSignInAction(status) {
+    const pairing = recordValue(status.pairing);
+    const url = safeActionUrl(pairing?.url);
+    if (!url)
+        return null;
+    if (brainAlreadySignedIn(status, url))
+        return null;
+    const rawCode = nonEmptyString(pairing?.code);
+    const code = rawCode && /^[A-Z0-9]{4,8}-[A-Z0-9]{4,8}$/i.test(rawCode)
+        ? rawCode
+        : undefined;
+    const provider = signInProviderName(url);
+    return {
+        type: provider === "Codex" ? "codex-device-sign-in" : "provider-sign-in",
+        title: `Sign in to ${provider}`,
+        summary: `sign in to ${provider}`,
+        instruction: code
+            ? "Open this page and enter the code."
+            : "Open this page and follow the sign-in instructions.",
+        url,
+        urlLabel: "Open",
+        code,
+    };
+}
+const SLACK_APP_TOKEN_INSTRUCTION = "Create an app-level token with the connections:write scope, then paste it into HQ. HQ verifies the token and resumes setup; if Slack asks you to install the app, follow the install link shown there.";
+function consolePasteUrl(companyKey, agentUid) {
+    const base = process.env.HQ_CONSOLE_URL?.trim().replace(/\/+$/, "") || "https://hq.computer";
+    return `${base}/companies/${encodeURIComponent(companyKey)}/agents?setup=${encodeURIComponent(agentUid)}`;
+}
+function slackAppIdFromSetupState(status) {
+    const steps = recordValue(status.setupState)?.steps;
+    if (!Array.isArray(steps))
+        return null;
+    for (const step of steps) {
+        const item = recordValue(step);
+        if (item?.name !== "channels" || item.status === "done")
+            continue;
+        const match = /https:\/\/api\.slack\.com\/apps\/(A[A-Z0-9]+)/.exec(JSON.stringify(item));
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+function serverPendingActions(status) {
+    if (!Array.isArray(status.pendingActions))
+        return [];
+    const actions = [];
+    for (const raw of status.pendingActions) {
+        const item = recordValue(raw);
+        const type = nonEmptyString(item?.type);
+        const title = nonEmptyString(item?.title);
+        if (!item || !type || !title)
+            continue;
+        const url = safeActionUrl(item.url) ?? undefined;
+        const pasteUrl = safeActionUrl(item.pasteUrl) ?? undefined;
+        const rawCode = nonEmptyString(item.code);
+        actions.push({
+            type,
+            title,
+            summary: title.charAt(0).toLowerCase() + title.slice(1),
+            instruction: nonEmptyString(item.instruction) ?? "Open this page and follow the instructions.",
+            ...(url ? { url, urlLabel: type === "slack-app-token" ? "Get token" : "Open" } : {}),
+            ...(pasteUrl ? { pasteUrl } : {}),
+            ...(rawCode && /^[A-Z0-9]{4,8}-[A-Z0-9]{4,8}$/i.test(rawCode) ? { code: rawCode } : {}),
+        });
+    }
+    return actions;
+}
+function pendingSlackAction(status, companySlug) {
+    const agent = recordValue(status.agent);
+    const configuredSlack = recordValue(recordValue(agent?.channels)?.slack);
+    const stepAppId = slackAppIdFromSetupState(status);
+    const appId = nonEmptyString(configuredSlack?.appId) ?? stepAppId;
+    const agentUid = nonEmptyString(agent?.uid);
+    const companyUid = nonEmptyString(agent?.companyUid);
+    const tokenPage = safeActionUrl(configuredSlack?.appTokenPendingUrl) ??
+        (stepAppId ? `https://api.slack.com/apps/${stepAppId}/general` : null);
+    if (tokenPage &&
+        appId && /^A[A-Z0-9]+$/.test(appId) &&
+        new URL(tokenPage).hostname === "api.slack.com" &&
+        agentUid && AGENT_UID_PATTERN.test(agentUid) &&
+        companyUid && /^cmp_[A-Za-z0-9_-]+$/.test(companyUid)) {
+        const companyUrlKey = companySlug && /^[a-z0-9][a-z0-9-]*$/.test(companySlug)
+            ? companySlug
+            : companyUid;
+        return {
+            type: "slack-app-token",
+            title: `Finish ${nonEmptyString(agent?.name) ?? "the agent"}'s Slack connection`,
+            summary: "connect it to Slack",
+            instruction: SLACK_APP_TOKEN_INSTRUCTION,
+            url: `https://api.slack.com/apps/${appId}/general`,
+            urlLabel: "Get token",
+            pasteUrl: consolePasteUrl(companyUrlKey, agentUid),
+        };
+    }
+    const diagnostics = recordValue(agent?.channelDiagnostics);
+    const slack = recordValue(diagnostics?.slack);
+    const url = safeActionUrl(slack?.pendingInstallUrl);
+    if (!url)
+        return null;
+    if (slack?.inboundCapability === "socket-mode-degraded") {
+        return {
+            type: "slack-app-token",
+            title: "Finish setting up the Slack app",
+            summary: "finish setting up the Slack app",
+            instruction: "Open this page, create the app-level token, then provide it in the agent's Slack setup.",
+            url,
+            urlLabel: "Open",
+            ...(agentUid && AGENT_UID_PATTERN.test(agentUid) && companyUid && /^cmp_[A-Za-z0-9_-]+$/.test(companyUid)
+                ? {
+                    pasteUrl: consolePasteUrl(companySlug && /^[a-z0-9][a-z0-9-]*$/.test(companySlug) ? companySlug : companyUid, agentUid),
+                }
+                : {}),
+        };
+    }
+    if (slack?.inboundCapability !== "pending-install")
+        return null;
+    return {
+        type: "slack-install",
+        title: "Install the Slack app",
+        summary: "install the Slack app so it can talk to your workspace",
+        instruction: "Open this link and install the app in your workspace.",
+        url,
+        urlLabel: "Install",
+    };
+}
+/**
+ * The server owns action detection. This client converts its safe, current
+ * status fields into a list so another operator action can be added without
+ * changing the renderers or command control flow.
+ */
+function pendingOperatorActions(status, companySlug) {
+    const fromServer = serverPendingActions(status);
+    if (fromServer.length > 0)
+        return fromServer;
+    return [
+        currentDeviceSignInAction(status),
+        pendingSlackAction(status, companySlug),
+    ].filter((action) => action !== null);
+}
+async function consoleCompanySlug(token, status, companyRef) {
+    if (companyRef && /^[a-z0-9][a-z0-9-]*$/.test(companyRef))
+        return companyRef;
+    const agent = recordValue(status.agent);
+    const slack = recordValue(recordValue(agent?.channels)?.slack);
+    if (!slack?.appTokenPendingUrl && !slackAppIdFromSetupState(status))
+        return undefined;
+    const companyUid = nonEmptyString(agent?.companyUid);
+    if (!companyUid)
+        return undefined;
+    try {
+        const response = await vaultApiFetch({
+            token,
+            path: "/membership/me",
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok)
+            return undefined;
+        const body = recordValue(await response.json());
+        const memberships = Array.isArray(body?.memberships) ? body.memberships : [];
+        const membership = memberships.map(recordValue).find((item) => item?.companyUid === companyUid && item?.status === "active");
+        const slug = nonEmptyString(membership?.companySlug);
+        return slug && /^[a-z0-9][a-z0-9-]*$/.test(slug) ? slug : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pendingActionsJson(actions) {
+    return actions.map(({ type, title, instruction, url, pasteUrl, code }) => ({
+        type,
+        title,
+        instruction,
+        ...(url ? { url } : {}),
+        ...(pasteUrl ? { pasteUrl } : {}),
+        ...(code ? { code } : {}),
+    }));
+}
+function statusAgentSlug(status) {
+    return nonEmptyString(recordValue(status.agent)?.slug);
+}
+/** The provision endpoint returns this nested identity; old response shapes omit it. */
+function provisionedAgentIdentity(result) {
+    const agent = recordValue(result.agent);
+    const uid = nonEmptyString(agent?.uid) ?? nonEmptyString(agent?.agentUid);
+    const slug = nonEmptyString(agent?.slug);
+    return uid && slug ? { uid, slug } : null;
+}
+function printPendingOperatorActions(slug, actions) {
+    if (actions.length === 0)
+        return;
+    const first = actions[0];
+    console.log(chalk.yellow(actions.length === 1
+        ? `Your agent's box is up. One step left: ${first.summary}.`
+        : "Your agent's box is up. A few steps remain before it can talk to your workspace."));
+    for (const action of actions) {
+        console.log("");
+        console.log(chalk.bold(`${action.title}:`));
+        console.log(action.instruction);
+        if (action.url)
+            console.log(chalk.cyan(`${action.urlLabel ?? "Open"}: ${action.url}`));
+        if (action.pasteUrl)
+            console.log(chalk.cyan(`Paste token: ${action.pasteUrl}`));
+        if (action.code)
+            console.log(chalk.bold(`Code: ${action.code}`));
+    }
+    const currentCodeHint = actions.some((action) => action.code)
+        ? "current sign-in code and instructions"
+        : "these instructions";
+    const statusCommand = slug
+        ? `Run \`hq agents status ${slug}\` any time to get ${currentCodeHint} again.`
+        : `Run \`hq agents status\` again any time to get ${currentCodeHint}.`;
+    console.log("");
+    console.log(chalk.dim(`Until that's done, the agent will show as still setting up. ${statusCommand}`));
+}
 export async function patchAgentProfile(token, agentUid, patch) {
     return agentsRequest({
         token,
@@ -304,6 +763,54 @@ export async function startStopAgent(token, agentUid, action) {
         method: "POST",
     });
 }
+/** Submit a human-provided Claude subscription code through hq-pro's route. */
+export async function submitAgentLoginCode(token, agentUid, code) {
+    return agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/login-code`,
+        method: "POST",
+        body: { code },
+    });
+}
+async function readLoginCode(code) {
+    let value = code;
+    if (value === undefined) {
+        if (process.stdin.isTTY) {
+            console.error("Enter the Claude sign-in code, then press Enter:");
+        }
+        const rl = readline.createInterface({ input: process.stdin });
+        try {
+            value = await new Promise((resolve, reject) => {
+                rl.once("error", reject);
+                rl.once("close", () => resolve(""));
+                rl.question("", resolve);
+            });
+        }
+        finally {
+            rl.close();
+        }
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error("Claude sign-in code required. Pass it as an argument or provide it on stdin.");
+    }
+    return trimmed;
+}
+function redactLoginCode(message, code) {
+    return code ? message.split(code).join("[redacted]") : message;
+}
+function agentConsoleResolveUrl(agentUid) {
+    const apiUrl = process.env.HQ_VAULT_API_URL?.trim() || DEFAULT_VAULT_API_URL;
+    const origin = consoleOrigin(apiUrl);
+    if (!origin)
+        return undefined;
+    // Keep the owner's canonical production sign-in URL while honoring an
+    // explicit console override or deriving the console for another API host.
+    const consoleBase = !process.env.HQ_CONSOLE_URL?.trim() && origin === "https://hq.computer"
+        ? "https://hq.getindigo.ai"
+        : origin;
+    return `${consoleBase}/resolve/agents/${encodeURIComponent(agentUid)}`;
+}
 export async function openAgentTerminal(token, agentUid, body) {
     return agentsRequest({
         token,
@@ -319,11 +826,14 @@ export async function retryAgent(token, agentUid) {
         method: "POST",
     });
 }
-export async function deprovisionAgent(token, agentUid) {
+export async function deprovisionAgent(token, agentUid, confirmDestroyAgentsV2) {
     return agentsRequest({
         token,
         path: `/v1/agents/${encodeURIComponent(agentUid)}`,
         method: "DELETE",
+        body: confirmDestroyAgentsV2 === undefined
+            ? undefined
+            : { confirmDestroyAgentsV2 },
     });
 }
 export async function listAgentJobs(token, agentUid) {
@@ -340,6 +850,13 @@ export async function pauseAgentJob(token, agentUid, jobId) {
         method: "POST",
     });
 }
+export async function resumeAgentJob(token, agentUid, jobId) {
+    return agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/resume`,
+        method: "POST",
+    });
+}
 export async function cancelAgentJob(token, agentUid, jobId) {
     return agentsRequest({
         token,
@@ -356,7 +873,7 @@ export async function cancelAgentJob(token, agentUid, jobId) {
  * the agent is cross-company) must print a clear message and exit non-zero,
  * never throw a stack trace.
  */
-export function formatJobsHttpError(err, jobId) {
+export function formatJobsHttpError(err, jobId, action) {
     if (err.status === 401)
         return "Not authenticated — run `hq login`.";
     // A 403 CROSS_AGENT_JOB is hq-pro's self-only jobs guard, not a role problem:
@@ -366,12 +883,17 @@ export function formatJobsHttpError(err, jobId) {
     // closed locally before the request, see crossAgentJobsRefusal).
     if (err.status === 403 && err.code === "CROSS_AGENT_JOB") {
         return ("Jobs are scoped to the calling agent's own identity — an agent may only " +
-            "list, pause, or cancel its OWN jobs (use the on-box `hq-agent-jobs` tool). " +
+            "list, pause, resume, or cancel its OWN jobs (use the on-box `hq-agent-jobs` tool). " +
             "Managing another agent's jobs needs a person session with owner/admin on " +
             "the company.");
     }
     if (err.status === 403)
         return "You need owner/admin on this company.";
+    if (action === "resume" &&
+        err.status === 404 &&
+        (err.code === "JOB_NOT_FOUND" || err.code === "SCHEDULE_NOT_FOUND")) {
+        return "job not found or its schedule was deleted; it cannot be resumed";
+    }
     if (err.status === 404 && err.code === "JOB_NOT_FOUND") {
         const id = jobId ?? extractQuotedJobId(err.message) ?? "unknown";
         return `Job '${id}' not found.`;
@@ -400,7 +922,7 @@ export function formatJobsTable(jobs) {
         j.lastRunOutcome ?? "-",
         j.status ?? "",
     ]);
-    const widths = cols.map((c, i) => Math.max(c.length, ...rows.map((r) => r[i].length)));
+    const widths = cols.map((c, i) => maxLength(rows, (row) => row[i].length, c.length));
     const render = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ");
     return [chalk.bold(render(cols)), ...rows.map(render)].join("\n");
 }
@@ -410,20 +932,62 @@ export function formatPauseResult(result) {
     const from = result.previousState ?? "ENABLED";
     return `Paused ${result.jobId} (${from} → ${result.scheduleState})`;
 }
+export function formatResumeResult(result) {
+    if (!result.changed)
+        return "Already active";
+    const from = result.previousState ?? "DISABLED";
+    return `Resumed ${result.jobId} (${from} → ${result.scheduleState})`;
+}
 /** Human-readable "hot-applied to the running box" vs "saved for next launch". */
 export function appliedHint(applied) {
     return applied
         ? "applied to the running box now"
         : "saved — takes effect on the agent's next launch";
 }
-// ---------------------------------------------------------------------------
-// Talking to agents (DM). Agents are members addressable over HQ's DM system:
-// a message rides `POST /v1/notify/dm` (the wire contract accepts `agt_*`), the
-// agent's box picks it up and replies over DM (a first-class agent reply
-// channel), and the two-way conversation is read back via `GET /v1/notify/thread`.
-// ---------------------------------------------------------------------------
-/** Agent uid shape (`agt_…`). */
-const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
+async function validateAgentModelOption(token, chosenProvider, modelId) {
+    const result = await readAgentModelCatalog(token);
+    if (!result.ok) {
+        if (result.reason === "unavailable") {
+            console.error(chalk.yellow("model validation skipped: catalog unavailable (the server still validates)."));
+            return;
+        }
+        throw new Error(`Could not read the model catalog (HTTP ${result.status}). Check your hq login and try again.`);
+    }
+    if (result.source === "cache") {
+        console.error(chalk.yellow(`Model catalog unavailable; validating against the cached catalog from ${new Date(result.fetchedAt).toISOString()}.`));
+    }
+    const selection = validateAgentModelSelection(result.catalog, modelId, chosenProvider);
+    if (!selection.ok) {
+        throw new Error(modelSelectionErrorMessage(modelId, selection));
+    }
+}
+/** Stable human table shared by the all-provider and provider-filtered forms. */
+export function formatAgentModelsTable(catalog, selectedProvider) {
+    const providers = selectedProvider ? [selectedProvider] : AGENT_MODEL_PROVIDERS;
+    const sections = providers.map((provider) => {
+        const view = catalog.providers[provider];
+        const columns = ["ID", "LABEL", "DEFAULT", "NEW", "AVAILABILITY"];
+        const rows = view.models.map((model) => [
+            model.id,
+            model.label,
+            model.id === view.defaultModel ? "yes" : "",
+            model.isNew ? "yes" : "",
+            model.selectable ? "available" : "not yet on agents",
+        ]);
+        const widths = columns.map((column, index) => Math.max(column.length, ...rows.map((row) => row[index].length)));
+        const render = (cells) => cells.map((cell, index) => cell.padEnd(widths[index])).join("  ").trimEnd();
+        return [
+            chalk.bold(provider.toUpperCase()),
+            render(columns),
+            ...rows.map(render),
+        ].join("\n");
+    });
+    return sections.join("\n\n");
+}
+function catalogUnavailableMessage() {
+    return ("Model catalog is unavailable and no cached copy exists. " +
+        "Check your connection and try again after model-catalog.serve is enabled.");
+}
 /**
  * Resolve an agent reference to its `agt_` uid. An `agt_…` value is used
  * directly; anything else is treated as a slug or display name and resolved
@@ -518,6 +1082,9 @@ async function resolveJobsTargetOrExit(ref, company) {
 }
 /** Send a DM to an agent. Returns nothing meaningful beyond success. */
 export async function sendAgentDm(token, agentUid, message) {
+    if (!isAgentUid(agentUid)) {
+        throw new Error(`Invalid agent recipient '${agentUid}': expected an agt_ uid.`);
+    }
     await agentsRequest({
         token,
         path: "/v1/notify/dm",
@@ -550,6 +1117,59 @@ function shortTime(iso) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * POST /v1/agents/{uid}/rotate — invalidate the current secret and host key
+ * and issue a fresh one-time enrollment code (returned exactly once).
+ */
+export async function rotateAgent(token, agentUid) {
+    const data = await agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/rotate`,
+        method: "POST",
+    });
+    const e = data.enrollment ?? {};
+    if (typeof e.code !== "string" || !e.code) {
+        throw new AgentsHttpError(502, "rotate succeeded but the response carried no enrollment code");
+    }
+    return {
+        agentUid: data.agentUid ?? agentUid,
+        enrollment: {
+            code: e.code,
+            expiresAt: typeof e.expiresAt === "string" ? e.expiresAt : "",
+            enrollmentId: typeof e.enrollmentId === "string" ? e.enrollmentId : "",
+        },
+    };
+}
+/** Display form of a 24-char code: six groups of four. */
+export function groupEnrollmentCode(code) {
+    const flat = code.replace(/[\s-]+/g, "").toUpperCase();
+    return flat.match(/.{1,4}/g)?.join("-") ?? flat;
+}
+/**
+ * POST /v1/agents/{uid}/revoke — disable the Cognito user, drop membership,
+ * mark the enrollment revoked; `remove` also deletes the entity.
+ */
+export async function revokeAgent(token, agentUid, remove) {
+    const data = await agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/revoke`,
+        method: "POST",
+        body: { remove },
+    });
+    return { removed: data.removed === true || remove };
+}
+/** Lines printed after a rotate: the code is shown once and never stored. */
+export function formatRotateOutput(result) {
+    const lines = [
+        `Rotated ${result.agentUid}. The old secret and host key no longer mint.`,
+        "",
+        `  enrollment code: ${groupEnrollmentCode(result.enrollment.code)}`,
+    ];
+    if (result.enrollment.expiresAt)
+        lines.push(`  expires:         ${result.enrollment.expiresAt} (15 minutes)`);
+    lines.push("", "Shown once. On the agent's host run:", `  hq agent enroll ${groupEnrollmentCode(result.enrollment.code)} --replace`, "  hq agent probe");
+    return lines;
+}
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -577,9 +1197,9 @@ function fail(err) {
     }
     process.exit(1);
 }
-function failJobs(err, jobId) {
+function failJobs(err, jobId, action) {
     if (err instanceof AgentsHttpError) {
-        console.error(chalk.red(formatJobsHttpError(err, jobId)));
+        console.error(chalk.red(formatJobsHttpError(err, jobId, action)));
         process.exit(1);
     }
     fail(err);
@@ -602,9 +1222,16 @@ export function registerAgentsCommand(program) {
         bySubcommand: {
             message: { capability: "agents:use", routeAvailable: false },
             thread: { capability: "agents:use", routeAvailable: false },
+            // The catalog read endpoint is JWT-only; hq-pro has no keyed parallel.
+            models: { capability: "agents:use", routeAvailable: false },
             // Interactive terminals are for humans: hq-pro serves no keyed
             // `/v1/keys/agents/{uid}/terminal` route, so machine keys fail closed.
             terminal: { capability: "agents:use", routeAvailable: false },
+            // External-agent lifecycle is an admin action on the JWT-only
+            // /v1/agents/{uid}/rotate|revoke routes (api-contract v1); no keyed
+            // parallel exists, so machine keys fail closed here too.
+            rotate: { capability: "agents:use", routeAvailable: false },
+            revoke: { capability: "agents:use", routeAvailable: false },
         },
     });
     // `--company` may live on the group or the subcommand; the subcommand value
@@ -612,6 +1239,43 @@ export function registerAgentsCommand(program) {
     // `hq agents --company acme list`.
     const companyOf = (sub) => sub.opts().company ??
         agents.opts().company;
+    agents
+        .command("models")
+        .description("List the model catalog available to cloud agents")
+        .option("--provider <provider>", "Filter to one provider: codex, grok, or claude")
+        .option("--json", "Print the stable catalog JSON shape")
+        .action(async (opts) => {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await readAgentModelCatalog(token);
+            if (!result.ok) {
+                if (result.reason === "request_failed") {
+                    throw new Error(`Could not read the model catalog (HTTP ${result.status}). Check your hq login and try again.`);
+                }
+                console.error(chalk.red(catalogUnavailableMessage()));
+                process.exit(1);
+            }
+            if (result.source === "cache") {
+                console.error(chalk.yellow(`Model catalog unavailable; showing cached catalog from ${new Date(result.fetchedAt).toISOString()}.`));
+            }
+            const providers = opts.provider
+                ? { [opts.provider]: result.catalog.providers[opts.provider] }
+                : result.catalog.providers;
+            if (opts.json) {
+                // Stable shape: { generatedAt, providers }. A provider filter selects
+                // one key but never changes or flattens the response envelope.
+                process.stdout.write(JSON.stringify({ generatedAt: result.catalog.generatedAt, providers }, null, 2) + "\n");
+                return;
+            }
+            console.log(formatAgentModelsTable(result.catalog, opts.provider));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    agents.commands.find((command) => command.name() === "models")
+        ?.options.find((option) => option.long === "--provider")
+        ?.choices(AGENT_MODEL_PROVIDERS);
     agents
         .command("message <agent> <message...>")
         .alias("msg")
@@ -764,31 +1428,56 @@ export function registerAgentsCommand(program) {
     });
     agents
         .command("provision <name>")
-        .alias("new")
+        .aliases(["new", "create"])
         .description("Provision a new cloud agent (company-specific monthly price shown before creation)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
-        .option("--provider <provider>", "Runtime: codex | grok | claude | agents-v2 (default codex). claude is subscription-only; agents-v2 boots its brain box (codex, or grok via a grok-* model) and receives the v2 runtime post-boot")
+        .option("--provider <provider>", "Runtime: agents-v2 (recommended) | codex | grok | claude (accepted for script compatibility; use agents-v2 for new Claude agents)")
+        .option("--model <model>", "Brain model from `hq agents models`")
         .option("--auth-mode <mode>", "Auth: subscription | apiKey (default subscription)", "subscription")
         .option("--api-key-env <VAR>", "Env var holding the API key for --auth-mode apiKey (never pass the key as a flag)")
+        .option("--slack-bot-token <xoxb-token>", "Reuse an existing Slack bot token; HQ_SLACK_BOT_TOKEN or --slack-tokens-stdin avoid shell history")
+        .option("--slack-app-token <xapp-token>", "Socket Mode app token for --provider agents-v2; HQ_SLACK_APP_TOKEN or --slack-tokens-stdin avoid shell history")
+        .option("--slack-tokens-stdin", "Read the bot token and optional app token from one or two stdin lines")
         .option("--title <title>", "Org-chart job title")
         .option("--description <text>", "Short description / bio")
         .option("--size <size>", "Agent box size: basic | power | dev (omitted keeps the current default)")
         .option("--yes", "Confirm the quoted monthly cost and provision the agent")
+        .option("--json", "Emit machine-readable output and never open a browser")
+        .addHelpText("after", `\n${claudeProvisionGuidance()}\n`)
         .action(async function (name, opts) {
         try {
+            const slug = opts.slug ?? slugifyAgentName(name);
+            if (!AGENT_SLUG_PATTERN.test(slug)) {
+                console.error(chalk.red("Agent slug must start with a lowercase letter or digit, contain only lowercase letters, digits, and hyphens, and be at most 63 characters. " +
+                    "Update --slug or the agent name."));
+                process.exit(1);
+            }
             // Both of these previously fell back to their default on an
             // unrecognised value, silently provisioning a billable box the operator
             // did not ask for. They now exit(1) instead — see parseEnumOption.
             const authMode = parseEnumOption(opts.authMode, VALID_AUTH_MODES, "--auth-mode") ?? "subscription";
-            const provider = parseEnumOption(opts.provider, VALID_PROVIDERS, "--provider");
+            const explicitProvider = parseEnumOption(opts.provider, VALID_PROVIDERS, "--provider");
+            if (opts.model !== undefined &&
+                !/^[A-Za-z0-9._-]{1,64}$/.test(opts.model)) {
+                console.error(chalk.red("--model must be a model identifier (letters, digits, dot, dash, underscore; max 64 chars)."));
+                process.exit(1);
+            }
+            const provider = explicitProvider ?? (opts.model ? "agents-v2" : undefined);
+            const slackTokens = await resolveProvisionSlackTokens(opts);
+            if (slackTokens?.appToken && provider !== "agents-v2") {
+                throw new Error("A Slack app token can only be supplied with --provider agents-v2 for Socket Mode.");
+            }
+            if (slackTokens && provider === "agents-v2" && !slackTokens.appToken) {
+                throw new Error("--provider agents-v2 requires a Slack app token when reusing a Slack bot token.");
+            }
             // claude is subscription-only on hq-pro (rejectIncompatibleProviderAuthMode
             // returns AGENT_PROVIDER_INCOMPATIBLE_WITH_AUTH_MODE). Catch it here so the
             // operator gets a direct message instead of a 400 from the control plane
             // AFTER clearing the charge gate. The server stays authoritative; this is
             // only a friendlier, earlier copy of the same rule.
             if (provider === "claude" && authMode === "apiKey") {
-                console.error(chalk.red("The claude provider is subscription-only — drop --auth-mode apiKey."));
+                console.error(chalk.red(`Use agents-v2 for new Claude agents. The claude provider remains accepted for script compatibility.\n${claudeProvisionGuidance()}`));
                 process.exit(1);
             }
             // Resolve the API key from the environment (never from a flag value) when
@@ -809,6 +1498,9 @@ export function registerAgentsCommand(program) {
             }
             const token = (await resolveVaultCredential()).token;
             const companyUid = await getCompanyUid(token, companyOf(this));
+            if (opts.model !== undefined) {
+                await validateAgentModelOption(token, provider, opts.model);
+            }
             const idempotencyKey = `hq-cli-${randomUUID()}`;
             const sizeKey = parseEnumOption(opts.size, VALID_AGENT_SIZE_KEYS, "--size");
             const shouldChooseInteractively = !sizeKey && process.stdin.isTTY === true;
@@ -818,13 +1510,12 @@ export function registerAgentsCommand(program) {
                 : shouldChooseInteractively
                     ? await promptForAgentCreateSize(createOptions)
                     : requireDefaultAgentCreateSize(createOptions);
-            if (!shouldChooseInteractively) {
+            if (!shouldChooseInteractively && !opts.json) {
                 console.log(chalk.dim(formatAgentCreateSize(quotedSize)));
             }
             // Every path confirms hq-pro's company-specific quote. Omission still
             // leaves the POST size implicit, preserving the server-side default.
-            confirmAgentCreateQuoteOrExit(quotedSize, opts.yes);
-            const slug = opts.slug ?? slugifyAgentName(name);
+            confirmAgentCreateQuoteOrExit(quotedSize, opts.yes, opts.json);
             try {
                 const result = await provisionAgent(token, {
                     companyUid,
@@ -832,7 +1523,12 @@ export function registerAgentsCommand(program) {
                     slug,
                     codexAuthMode: authMode,
                     ...(provider ? { provider } : {}),
+                    ...(opts.model ? { codexModel: opts.model } : {}),
                     ...(codexApiKey ? { codexApiKey } : {}),
+                    ...(slackTokens ? { slackBotToken: slackTokens.botToken } : {}),
+                    ...(slackTokens?.appToken
+                        ? { slackAppToken: slackTokens.appToken }
+                        : {}),
                     idempotencyKey,
                     ...(opts.title ? { title: opts.title } : {}),
                     ...(opts.description ? { description: opts.description } : {}),
@@ -848,11 +1544,79 @@ export function registerAgentsCommand(program) {
                     quoteCatalogVersion: createOptions.catalogVersion,
                     surface: CLI_AGENT_CREATE_SURFACE,
                 });
-                const uid = typeof result.uid === "string" ? result.uid : slug;
-                console.log(chalk.green(`Provisioning started for agent "${name}".`));
-                console.log(chalk.dim(`Track setup: hq agents status ${uid} --company <slug>`));
+                const identity = provisionedAgentIdentity(result);
+                const claudeSignIn = provider === "agents-v2" &&
+                    authMode === "subscription" &&
+                    opts.model?.toLowerCase().startsWith("claude-") &&
+                    identity
+                    ? {
+                        consoleUrl: agentConsoleResolveUrl(identity.uid) ?? null,
+                        loginCodeCommand: `hq agents login-code ${identity.uid}`,
+                    }
+                    : undefined;
+                const status = identity
+                    ? await getAgentStatus(token, identity.uid)
+                    : null;
+                const actions = status
+                    ? pendingOperatorActions(status, await consoleCompanySlug(token, status, companyOf(this)))
+                    : [];
+                const slackInstall = actions.find((action) => action.type === "slack-install");
+                if (opts.json) {
+                    console.log(JSON.stringify({
+                        ...result,
+                        ...(actions.length > 0
+                            ? { pendingActions: pendingActionsJson(actions) }
+                            : {}),
+                        ...(slackInstall?.url
+                            ? {
+                                slackInstallPending: true,
+                                slackInstallUrl: slackInstall.url,
+                            }
+                            : {}),
+                        ...(claudeSignIn ? { claudeSignIn } : {}),
+                    }));
+                }
+                else {
+                    console.log(chalk.green(`Provisioning started for agent "${name}".`));
+                    if (claudeSignIn) {
+                        if (claudeSignIn.consoleUrl) {
+                            console.log(chalk.yellow(`To sign in, open ${claudeSignIn.consoleUrl}, authorize Claude, then paste the code on that page.`));
+                        }
+                        else {
+                            console.log(chalk.yellow("The console URL for this control plane is unknown. Set HQ_CONSOLE_URL to configure it."));
+                        }
+                        console.log(chalk.dim(`A human CLI session can also submit the code with: ${claudeSignIn.loginCodeCommand}`));
+                    }
+                    if (actions.length > 0) {
+                        printPendingOperatorActions(identity?.slug ?? null, actions);
+                    }
+                    else {
+                        console.log(chalk.dim(`Track setup: hq agents status ${identity?.slug ?? slug} --company <slug>`));
+                    }
+                }
             }
             catch (err) {
+                if (provider === "claude" &&
+                    err instanceof AgentsHttpError &&
+                    err.code === "LEGACY_MANAGED_PROVIDER_RETIRED") {
+                    throw new Error(`${err.message}\n\n${claudeProvisionGuidance()}`);
+                }
+                if (err instanceof AgentsHttpError &&
+                    err.status === 403 &&
+                    err.code === "AGENT_PLAN_LIMIT") {
+                    if (!err.agentCreatePlanLimit) {
+                        throw new Error("HQ Pro returned an unrecognized agent payment-required response.");
+                    }
+                    await surfaceAgentCreatePlanLimit(err.agentCreatePlanLimit, {
+                        ...opts,
+                        companyUid,
+                    });
+                    // Keep the payment-required status through normal CLI teardown.
+                    // Unlike process.exit(), this is testable and cannot be caught by
+                    // this action's outer error boundary as a generic failure.
+                    process.exitCode = AGENT_CREATE_PAYMENT_REQUIRED_EXIT_CODE;
+                    return;
+                }
                 // No card on file → surface the shareable payment link instead of an
                 // opaque 402, then exit non-zero so scripts can react.
                 if (err instanceof AgentsHttpError &&
@@ -868,6 +1632,32 @@ export function registerAgentsCommand(program) {
             fail(err);
         }
     });
+    agents
+        .command("login-code <agentUid> [code]")
+        .description("Submit a Claude subscription sign-in code for an agent")
+        .action(async (agentUid, codeArg) => {
+        let code = "";
+        try {
+            code = await readLoginCode(codeArg);
+            const token = (await resolveVaultCredential()).token;
+            await submitAgentLoginCode(token, agentUid, code);
+            console.log(chalk.green(`Sent the Claude sign-in code to agent ${agentUid}.`));
+        }
+        catch (err) {
+            if (err instanceof AgentsHttpError &&
+                err.status === 403 &&
+                err.code === "OUTPOST_ACCOUNT_MANAGEMENT_FORBIDDEN") {
+                const consoleUrl = agentConsoleResolveUrl(agentUid);
+                console.error(chalk.yellow(consoleUrl
+                    ? `A person must paste this code in the agent console: ${consoleUrl}`
+                    : "A person must paste this code in the agent console. Set HQ_CONSOLE_URL to configure it for this control plane."));
+                process.exit(1);
+            }
+            const detail = err instanceof Error ? err.message : String(err);
+            console.error(chalk.red(`Could not submit Claude sign-in code: ${redactLoginCode(detail, code)}`));
+            process.exit(1);
+        }
+    });
     agents
         .command("list")
         .description("List the company's agents")
@@ -901,7 +1691,7 @@ export function registerAgentsCommand(program) {
             }
             const nameW = Math.max(4, ...roster.map((a) => (a.name ?? "").length));
             const slugW = Math.max(4, ...roster.map((a) => (a.slug ?? "").length));
-            const statusW = Math.max(6, ...roster.map((a) => (a.agentStatus ?? "").length));
+            const statusW = Math.max(6, ...roster.map((a) => rosterStatusLabel(a).length));
             const modelW = Math.max(5, ...roster.map((a) => (a.codexModel ?? "").length));
             console.log(chalk.bold([
                 "NAME".padEnd(nameW),
@@ -914,7 +1704,7 @@ export function registerAgentsCommand(program) {
                 console.log([
                     (a.name ?? "").padEnd(nameW),
                     (a.slug ?? "").padEnd(slugW),
-                    (a.agentStatus ?? "").padEnd(statusW),
+                    rosterStatusLabel(a).padEnd(statusW),
                     (a.codexModel ?? "").padEnd(modelW),
                     a.uid,
                 ].join("  "));
@@ -925,16 +1715,28 @@ export function registerAgentsCommand(program) {
         }
     });
     agents
-        .command("status <agentUid>")
+        .command("status <agent>")
         .description("Show an agent's setup state and runtime detail")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--json", "Emit raw JSON")
-        .action(async function (agentUid, opts) {
+        .action(async function (agent, opts) {
         try {
             const token = (await resolveVaultCredential()).token;
+            const agentUid = await resolveAgentUid(token, agent, companyOf(this));
             const status = await getAgentStatus(token, agentUid);
+            const actions = pendingOperatorActions(status, await consoleCompanySlug(token, status, companyOf(this)));
             if (opts.json) {
-                process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+                process.stdout.write(JSON.stringify({
+                    ...status,
+                    ...(actions.length > 0
+                        ? { pendingActions: pendingActionsJson(actions) }
+                        : {}),
+                }, null, 2) + "\n");
+                return;
+            }
+            if (actions.length > 0) {
+                printPendingOperatorActions(statusAgentSlug(status) ??
+                    (AGENT_UID_PATTERN.test(agent.trim()) ? null : agent.trim()), actions);
                 return;
             }
             // Pretty but faithful: dump the top-level fields as key: value.
@@ -1004,9 +1806,10 @@ export function registerAgentsCommand(program) {
     });
     agents
         .command("config <agentUid>")
+        .alias("update")
         .description("Update an agent's runtime config (model / reasoning effort / service tier), or migrate its brain/runtime provider with --provider (DESTRUCTIVE: terminates + reprovisions the box)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
-        .option("--model <model>", "Codex model id")
+        .option("--model <model>", "Model id from `hq agents models`")
         .option("--effort <effort>", "Reasoning effort: minimal | low | medium | high | xhigh")
         .option("--tier <tier>", "Service tier (speed): default | priority")
         .option("--provider <provider>", "Migrate brain/runtime provider (codex | grok | claude | agents-v2). DESTRUCTIVE: terminates and reprovisions the box; requires --model and --yes.")
@@ -1075,6 +1878,9 @@ export function registerAgentsCommand(program) {
                 process.exit(1);
             }
             const token = (await resolveVaultCredential()).token;
+            if (opts.model !== undefined) {
+                await validateAgentModelOption(token, opts.provider?.trim().toLowerCase(), opts.model);
+            }
             const result = await patchAgentRuntimeConfig(token, agentUid, patch);
             if (opts.json) {
                 process.stdout.write(JSON.stringify(result, null, 2) + "\n");
@@ -1094,8 +1900,16 @@ export function registerAgentsCommand(program) {
             .action(async function (agentUid) {
             try {
                 const token = (await resolveVaultCredential()).token;
-                await startStopAgent(token, agentUid, action);
-                console.log(chalk.green(`${action === "start" ? "Started" : "Stopped"} agent ${agentUid}.`));
+                const result = await startStopAgent(token, agentUid, action);
+                const runtimeStatus = result.runtime?.status;
+                const successMessage = action === "start"
+                    ? `Started agent ${agentUid}.`
+                    : runtimeStatus === "terminated"
+                        ? `Stopped agent ${agentUid}.`
+                        : typeof runtimeStatus === "string"
+                            ? `Stop accepted for agent ${agentUid} (status: ${runtimeStatus}).`
+                            : `Stop accepted for agent ${agentUid}.`;
+                console.log(chalk.green(successMessage));
             }
             catch (err) {
                 fail(err);
@@ -1122,6 +1936,7 @@ export function registerAgentsCommand(program) {
         .description("Deprovision (permanently tear down) an agent")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--yes", "Confirm the irreversible teardown (required)")
+        .option("--confirm-destroy-agents-v2 <instance-id>", "Confirm agents-v2 teardown by naming the live EC2 instance ID")
         .action(async function (agentUid, opts) {
         if (!opts.yes) {
             console.error(chalk.yellow(`This will permanently deprovision agent ${agentUid} and tear down its ` +
@@ -1131,7 +1946,13 @@ export function registerAgentsCommand(program) {
         }
         try {
             const token = (await resolveVaultCredential()).token;
-            const result = await deprovisionAgent(token, agentUid);
+            const status = await getAgentStatus(token, agentUid);
+            if (recordValue(status.agent)?.runtimeKind === "external") {
+                await revokeAgent(token, agentUid, true);
+                console.log(chalk.green(`Revoked and removed external agent ${agentUid}.`));
+                return;
+            }
+            const result = await deprovisionAgent(token, agentUid, opts.confirmDestroyAgentsV2);
             if (result.terminal === false) {
                 console.log(chalk.yellow(`Deprovision in progress for agent ${agentUid} (not yet fully torn down — re-run to continue).`));
             }
@@ -1143,12 +1964,56 @@ export function registerAgentsCommand(program) {
             fail(err);
         }
     });
+    agents
+        .command("rotate <agentUid>")
+        .description("Issue a fresh enrollment code for an external agent (old secret + host key stop minting)")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--json", "Emit raw JSON (code included — pipe carefully)")
+        .action(async function (agentUid, opts) {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await rotateAgent(token, agentUid);
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            for (const line of formatRotateOutput(result))
+                console.log(line);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    agents
+        .command("revoke <agentUid>")
+        .description("Revoke an external agent: disable its login and drop it from the team")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--remove", "Also delete the agent entity (it disappears from the roster)")
+        .option("--yes", "Confirm the revoke (required)")
+        .action(async function (agentUid, opts) {
+        if (!opts.yes) {
+            console.error(chalk.yellow(`This will revoke agent ${agentUid}: its credentials stop working immediately and it ` +
+                `leaves the team${opts.remove ? ", and the agent record is deleted" : ""}. ` +
+                `Re-run with --yes to confirm: hq agents revoke ${agentUid}${opts.remove ? " --remove" : ""} --yes`));
+            process.exit(1);
+        }
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await revokeAgent(token, agentUid, opts.remove === true);
+            console.log(chalk.green(result.removed
+                ? `Revoked and removed agent ${agentUid}.`
+                : `Revoked agent ${agentUid}. Its next mint will be refused (401).`));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     // Off-box job control (US-003). Nested group so `hq agents jobs --help`
-    // lists list|pause|cancel. Same vaultApiFetch + person JWT as the rest of
+    // lists list|pause|resume|cancel. Same vaultApiFetch + person JWT as the rest of
     // this file; keyed HQ_API_KEY rewrites /v1/agents → /v1/keys/agents.
     const jobs = agents
         .command("jobs")
-        .description("List, pause, or cancel an agent's scheduled jobs");
+        .description("List, pause, resume, or cancel an agent's scheduled jobs");
     jobs
         .command("list <agentUid>")
         .description("List an agent's scheduled jobs")
@@ -1186,6 +2051,20 @@ export function registerAgentsCommand(program) {
             failJobs(err, jobId);
         }
     });
+    jobs
+        .command("resume <agentUid> <jobId>")
+        .description("Resume a paused job's schedule")
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .action(async function (agentUid, jobId) {
+        const { token, targetUid } = await resolveJobsTargetOrExit(agentUid, companyOf(this));
+        try {
+            const result = await resumeAgentJob(token, targetUid, jobId);
+            console.log(chalk.green(formatResumeResult(result)));
+        }
+        catch (err) {
+            failJobs(err, jobId, "resume");
+        }
+    });
     jobs
         .command("cancel <agentUid> <jobId>")
         .description("Cancel a job and delete its schedule")