@indigoai-us/hq-cli 5.75.0 → 5.77.0

package/dist/commands/agents.js

@@ -25,7 +25,7 @@ import chalk from "chalk";
 import { randomUUID } from "node:crypto";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
-import { AGENT_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingRequired, } from "../utils/billing-gate.js";
+import { AGENT_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
     "minimal",
@@ -64,7 +64,12 @@ export async function agentsRequest(opts) {
     const res = await vaultApiFetch(opts);
     if (!res.ok) {
         const body = (await res.json().catch(() => ({})));
-        throw new AgentsHttpError(res.status, body.error ?? body.message ?? res.statusText, body.code, parseBillingPayload(body));
+        throw new AgentsHttpError(res.status, 
+        // `message` FIRST: on a payment_failed envelope it carries the friendly
+        // 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));
     }
     return (await res.json());
 }
@@ -371,7 +376,7 @@ export function registerAgentsCommand(program) {
                 if (err instanceof AgentsHttpError &&
                     err.status === 402 &&
                     err.billing) {
-                    await surfaceBillingRequired(token, err.billing);
+                    await surfaceBillingBlocked(token, err.billing, err.message);
                     process.exit(1);
                 }
                 throw err;

package/dist/commands/files.d.ts

@@ -92,5 +92,66 @@ export declare function stripRedundantCompanyScope(prefix: string): {
 export declare function runFilesDelete(params: RunFilesDeleteParams, deps?: {
     confirm?: ConfirmFn;
 }): Promise<void>;
+export interface FileVersionRow {
+    versionId: string;
+    isLatest: boolean;
+    lastModified: string;
+    size: number;
+    isDeleteMarker?: boolean;
+}
+export interface FilesVersionsResponse {
+    key: string;
+    versions: FileVersionRow[];
+    computedAt: string;
+}
+export interface FileTombstoneRow {
+    key: string;
+    deletedAt: string;
+    deletedBy: string;
+    deletedPrefix: string;
+}
+export interface FilesTrashResponse {
+    companyUid?: string;
+    personal?: true;
+    tombstones: FileTombstoneRow[];
+    cursor?: string | null;
+    truncated: boolean;
+    computedAt: string;
+}
+export interface FilesRestoreResponse {
+    key: string;
+    wasDeleted: boolean;
+    restoredFromVersionId: string;
+    newVersionId: string;
+}
+export declare class FilesRecoveryHttpError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+/** Render the exact-key version history, including S3 delete markers. */
+export declare function formatFilesVersionsTable(rows: FileVersionRow[]): string;
+/** Render durable delete tombstones without implying the objects still exist. */
+export declare function formatFilesTrashTable(rows: FileTombstoneRow[]): string;
+export declare function runFilesVersions(params: {
+    key: string;
+    personal: boolean;
+    companySlug: string | undefined;
+}): Promise<FilesVersionsResponse>;
+export declare function runFilesRestore(params: {
+    key: string;
+    versionId?: string;
+    yes: boolean;
+    personal: boolean;
+    companySlug: string | undefined;
+}, deps?: {
+    confirm?: ConfirmFn;
+}): Promise<FilesRestoreResponse | undefined>;
+export declare function runFilesTrash(params: {
+    prefix: string;
+    cursor?: string;
+    personal: boolean;
+    companySlug: string | undefined;
+}): Promise<FilesTrashResponse>;
 export {};
 //# sourceMappingURL=files.d.ts.map

package/dist/commands/files.js

@@ -379,6 +379,69 @@ export function registerFilesCommand(program) {
             process.exit(1);
         }
     });
+    files
+        .command("versions <path>")
+        .description("List prior content versions and delete markers for one exact vault key. Use --personal for your personal vault.")
+        .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
+        .action(async (path, opts) => {
+        try {
+            const companySlug = files.opts().company;
+            const personal = opts.personal === true;
+            assertRecoveryScope(personal, companySlug);
+            await runFilesVersions({ key: path, personal, companySlug });
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    files
+        .command("restore <path>")
+        .description("Restore a prior version or undelete an exact vault key. Prompts before overwriting unless --yes. Use --personal for your personal vault.")
+        .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
+        .option("--version <id>", "Content version ID to restore")
+        .option("-y, --yes", "Skip the overwrite confirmation prompt (for scripts)")
+        .action(async (path, opts) => {
+        try {
+            const companySlug = files.opts().company;
+            const personal = opts.personal === true;
+            assertRecoveryScope(personal, companySlug);
+            await runFilesRestore({
+                key: path,
+                versionId: opts.version,
+                yes: opts.yes === true,
+                personal,
+                companySlug,
+            });
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    files
+        .command("trash")
+        .description("List deleted vault keys retained as tombstones. Use --personal for your personal vault.")
+        .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
+        .option("--prefix <prefix>", "Literal key prefix to filter tombstones")
+        .option("--cursor <cursor>", "Continue from an opaque tombstone cursor")
+        .action(async (opts) => {
+        try {
+            const companySlug = files.opts().company;
+            const personal = opts.personal === true;
+            assertRecoveryScope(personal, companySlug);
+            await runFilesTrash({
+                prefix: opts.prefix ?? "",
+                cursor: opts.cursor,
+                personal,
+                companySlug,
+            });
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
     // Return the `files` Commander group so callers (src/index.ts) can attach
     // additional subcommands (e.g. `hq files browse`/`hq files cat` from
     // files-browse.ts) onto the same group without re-creating it.
@@ -737,4 +800,215 @@ export async function runFilesDelete(params, deps = {}) {
         console.log(chalk.dim(`${result.skipped} object(s) under this prefix you can't delete were left untouched.`));
     }
 }
+export class FilesRecoveryHttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "FilesRecoveryHttpError";
+    }
+}
+function assertRecoveryScope(personal, companySlug) {
+    if (personal && companySlug) {
+        throw new Error("Pass either --personal or --company, not both.");
+    }
+}
+function assertExactRecoveryKey(key) {
+    if (!key || key.includes("*")) {
+        throw new Error("Restore and version history require one exact, wildcard-free vault key.");
+    }
+}
+function quoteRecoveryShellArg(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return String(bytes) + " B";
+    if (bytes < 1024 * 1024)
+        return (bytes / 1024).toFixed(1) + " KiB";
+    if (bytes < 1024 * 1024 * 1024) {
+        return (bytes / (1024 * 1024)).toFixed(1) + " MiB";
+    }
+    return (bytes / (1024 * 1024 * 1024)).toFixed(1) + " GiB";
+}
+/** Render the exact-key version history, including S3 delete markers. */
+export function formatFilesVersionsTable(rows) {
+    if (rows.length === 0) {
+        return "No version history exists for that key.";
+    }
+    const cols = ["VERSION", "TYPE", "LATEST", "MODIFIED", "SIZE"];
+    const data = rows.map((row) => [
+        row.versionId,
+        row.isDeleteMarker ? "delete marker" : "content",
+        row.isLatest ? "yes" : "",
+        row.lastModified,
+        row.isDeleteMarker ? "—" : formatBytes(row.size),
+    ]);
+    const widths = cols.map((col, index) => Math.max(col.length, ...data.map((row) => row[index].length)));
+    const renderRow = (row) => row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
+    return [
+        chalk.bold(renderRow(cols)),
+        chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
+        ...data.map(renderRow),
+    ].join("\n");
+}
+/** Render durable delete tombstones without implying the objects still exist. */
+export function formatFilesTrashTable(rows) {
+    if (rows.length === 0) {
+        return "Trash is empty.";
+    }
+    const cols = ["KEY", "DELETED", "DELETED BY", "DELETE PREFIX"];
+    const data = rows.map((row) => [
+        row.key,
+        row.deletedAt,
+        row.deletedBy,
+        row.deletedPrefix,
+    ]);
+    const widths = cols.map((col, index) => Math.max(col.length, ...data.map((row) => row[index].length)));
+    const renderRow = (row) => row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
+    return [
+        chalk.bold(renderRow(cols)),
+        chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
+        ...data.map(renderRow),
+    ].join("\n");
+}
+function throwRecoveryHttpError(status, body, statusText) {
+    throw new FilesRecoveryHttpError(status, body.message ?? body.error ?? statusText, body.code);
+}
+function formatFilesRecoveryError(err, key) {
+    if (err.status === 401) {
+        return "Not authenticated — please run hq login";
+    }
+    if (err.status === 403) {
+        return key
+            ? "Not authorized to modify '" + key + "' — you need write access on it"
+            : "Not authorized to view this vault path";
+    }
+    if (err.code === "FILES_RESTORE_VERSION_NOT_FOUND") {
+        return "That version is unavailable or is a delete marker.";
+    }
+    if (err.code === "FILES_RESTORE_NO_PRIOR_VERSION") {
+        return "There is no prior content version to restore.";
+    }
+    if (err.code === "FILES_RESTORE_NO_RECOVERABLE_VERSION") {
+        return "There is no recoverable content version for this key.";
+    }
+    if (err.status === 400) {
+        return "Invalid request: " + err.message;
+    }
+    if (err.status >= 500) {
+        return "Server error: " + err.message;
+    }
+    return err.message || "Request failed (" + String(err.status) + ")";
+}
+async function resolveRecoveryScope(params) {
+    assertRecoveryScope(params.personal, params.companySlug);
+    const token = await ensureCognitoToken();
+    if (params.personal) {
+        return { token, personal: true };
+    }
+    return {
+        token,
+        personal: false,
+        companyUid: await getCompanyUid(token, params.companySlug),
+    };
+}
+export async function runFilesVersions(params) {
+    assertExactRecoveryKey(params.key);
+    const scope = await resolveRecoveryScope(params);
+    const res = await vaultApiFetch({
+        token: scope.token,
+        path: "/v1/files/versions",
+        query: scope.personal
+            ? { personal: "1", key: params.key }
+            : { company: scope.companyUid, key: params.key },
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throwRecoveryHttpError(res.status, body, res.statusText);
+    }
+    const data = (await res.json());
+    console.log(chalk.green("Versions for '" + data.key + "':"));
+    console.log(formatFilesVersionsTable(data.versions));
+    return data;
+}
+export async function runFilesRestore(params, deps = {}) {
+    assertExactRecoveryKey(params.key);
+    if (params.versionId !== undefined && params.versionId.trim() === "") {
+        throw new Error("versionId must not be empty.");
+    }
+    const confirm = deps.confirm ?? realConfirm;
+    if (!params.yes) {
+        const ok = await confirm(params.personal
+            ? "Restore '" + params.key + "' in your personal vault? This overwrites current content."
+            : "Restore '" + params.key + "'? This overwrites current content in the shared vault.");
+        if (!ok) {
+            console.log(chalk.dim("Aborted — nothing was restored."));
+            return undefined;
+        }
+    }
+    const scope = await resolveRecoveryScope(params);
+    const body = scope.personal
+        ? { personal: true, key: params.key }
+        : { company: scope.companyUid, key: params.key };
+    if (params.versionId !== undefined)
+        body.versionId = params.versionId;
+    const res = await vaultApiFetch({
+        token: scope.token,
+        path: "/v1/files/restore",
+        method: "POST",
+        body,
+    });
+    if (!res.ok) {
+        const errBody = (await res.json().catch(() => ({})));
+        const err = new FilesRecoveryHttpError(res.status, errBody.message ?? errBody.error ?? res.statusText, errBody.code);
+        throw new Error(formatFilesRecoveryError(err, params.key));
+    }
+    const data = (await res.json());
+    const verb = data.wasDeleted ? "Undeleted" : "Restored";
+    console.log(chalk.green(verb + " '" + data.key + "' from version '" + data.restoredFromVersionId + "'."));
+    console.log(chalk.dim("New version: " + data.newVersionId));
+    return data;
+}
+export async function runFilesTrash(params) {
+    if (params.prefix.includes("*")) {
+        throw new Error("Trash prefix must be literal; wildcard expansion is not supported.");
+    }
+    const scope = await resolveRecoveryScope(params);
+    const query = scope.personal
+        ? { personal: "1" }
+        : { company: scope.companyUid };
+    if (params.prefix)
+        query.prefix = params.prefix;
+    if (params.cursor)
+        query.cursor = params.cursor;
+    const res = await vaultApiFetch({
+        token: scope.token,
+        path: "/v1/files/tombstones",
+        query,
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throwRecoveryHttpError(res.status, body, res.statusText);
+    }
+    const data = (await res.json());
+    console.log(formatFilesTrashTable(data.tombstones));
+    if (data.truncated && data.cursor) {
+        let continuation = "hq files";
+        if (params.companySlug) {
+            continuation += " --company " + quoteRecoveryShellArg(params.companySlug);
+        }
+        continuation += " trash";
+        if (params.personal)
+            continuation += " --personal";
+        if (params.prefix) {
+            continuation += " --prefix " + quoteRecoveryShellArg(params.prefix);
+        }
+        continuation += " --cursor " + quoteRecoveryShellArg(data.cursor);
+        console.log(chalk.dim("More results: " + continuation));
+    }
+    return data;
+}
 //# sourceMappingURL=files.js.map

package/dist/commands/mcp-registration.d.ts

@@ -429,11 +429,10 @@ export interface McpManifest {
 /**
  * Resolve a `${secret:NAME}` reference to its plaintext value, or return `null`
  * when the secret is unavailable (un-minted / TTL-expired / no company context).
- * Production binds this to `secrets-cache.ts` (`readCache(companyUid, NAME)`,
- * AES-256-GCM, 0600, 5-min TTL); TESTS inject a pure map so they NEVER read the
- * real encrypted cache. Returning `null` for a referenced secret is a hard error
- * at emit (we refuse to write a broken header), distinct from a name with no
- * reference at all.
+ * Production binds this to an in-memory map populated by a fresh vault `/load`
+ * authorization response; tests inject a pure map. Returning `null` for a
+ * referenced secret is a hard error at emit (we refuse to write a broken
+ * header), distinct from a name with no reference at all.
  */
 export type SecretResolver = (name: string) => string | null;
 /** True iff `value` contains at least one `${secret:NAME}` reference. */

package/dist/commands/mcp-registration.js

@@ -848,7 +848,8 @@ function restoreSafely(realTarget, backupDir) {
 //
 // SECRET SAFETY (the hard rule from the PRD authModel / US-002 AC):
 //   - `${secret:NAME}` resolves ONLY here, at emit, via the injected
-//     {@link SecretResolver} (production = the AES-256-GCM `secrets-cache.ts`).
+//     {@link SecretResolver}. Production injects values returned by a fresh
+//     server authorization; the encrypted disk cache is never a value fallback.
 //   - The RESOLVED value lands in `~/.claude.json` — a 0600 user-global file that
 //     is NOT synced/committed — because the runtime needs the real header to work.
 //   - The resolved value is REDACTED from every return value and never echoed; we
@@ -885,9 +886,9 @@ export function resolveSecretRefs(value, resolve, secretSink) {
     return value.replace(SECRET_REF_RE, (_match, name) => {
         const resolved = resolve(name);
         if (resolved === null || resolved === undefined) {
-            throw new McpManifestError(`cannot resolve \${secret:${name}} at emit — the secret is not in the cache ` +
-                '(mint it via the pack onboarding / `hq run`, then re-install). HQ refuses to ' +
-                'write a half-resolved header.');
+            throw new McpManifestError(`cannot resolve \${secret:${name}} at emit — the secret was not available ` +
+                'after online vault authorization (check login, company scope, and access, ' +
+                'then re-install). HQ refuses to write a half-resolved header.');
         }
         if (resolved.length > 0)
             secretSink.add(resolved);

package/dist/commands/outposts.d.ts

@@ -23,13 +23,27 @@
 import { Command } from "commander";
 import { spawnSync } from "node:child_process";
 import { type BillingErrorPayload } from "../utils/billing-gate.js";
+/**
+ * hq-pro's per-person cap envelope on a `409` provision block. Unlike every
+ * other `/outpost/*` failure this body carries NO `message`/`error` field —
+ * only the cap facts — so it has to be decoded structurally or the reason
+ * degrades to a bare `res.statusText` ("Conflict").
+ */
+export interface OutpostCappedPayload {
+    limit: number;
+    outposts: OutpostSummary[];
+}
+/** Decode hq-pro's `{ capped, limit, outposts }` cap envelope, if present. */
+export declare function parseCappedPayload(body: unknown): OutpostCappedPayload | undefined;
 /** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
 export declare class OutpostHttpError extends Error {
     status: number;
     step?: string;
     /** hq-pro's billing envelope on a `402 billing_required` provision block. */
     billing?: BillingErrorPayload;
-    constructor(status: number, message: string, step?: string, billing?: BillingErrorPayload);
+    /** hq-pro's cap envelope on a `409` provision block. */
+    capped?: OutpostCappedPayload;
+    constructor(status: number, message: string, step?: string, billing?: BillingErrorPayload, capped?: OutpostCappedPayload);
 }
 /** Row summary from `GET /outpost/list`. */
 export interface OutpostSummary {
@@ -59,9 +73,11 @@ export declare function outpostRequest<T>(opts: {
 /**
  * Provision the caller's Outpost. Sends the cached Cognito refresh token so the
  * box can authenticate AS the caller (the same body the console's
- * `provisionMyOutpost` sends). Idempotent server-side: a caller already at their
- * per-person cap gets their existing box back rather than a duplicate. The
- * refresh token is sent over HTTPS and NEVER printed.
+ * `provisionMyOutpost` sends). No duplicate is ever created: a caller already at
+ * their per-person cap gets a `409` whose body lists their existing boxes —
+ * thrown here as an `OutpostHttpError` carrying `capped` (hq-pro checks the cap
+ * BEFORE activation billing, so a capped call is never charged). The refresh
+ * token is sent over HTTPS and NEVER printed.
  */
 export declare function provisionOutpost(token: string, input: {
     refreshToken: string;

package/dist/commands/outposts.js

@@ -31,19 +31,34 @@ import * as yaml from "js-yaml";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
-import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingRequired, } from "../utils/billing-gate.js";
+import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
+/** Decode hq-pro's `{ capped, limit, outposts }` cap envelope, if present. */
+export function parseCappedPayload(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const b = body;
+    if (b.capped !== true)
+        return undefined;
+    return {
+        limit: typeof b.limit === "number" ? b.limit : 0,
+        outposts: Array.isArray(b.outposts) ? b.outposts : [],
+    };
+}
 /** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
 export class OutpostHttpError extends Error {
     status;
     step;
     /** hq-pro's billing envelope on a `402 billing_required` provision block. */
     billing;
-    constructor(status, message, step, billing) {
+    /** hq-pro's cap envelope on a `409` provision block. */
+    capped;
+    constructor(status, message, step, billing, capped) {
         super(message);
         this.name = "OutpostHttpError";
         this.status = status;
         this.step = step;
         this.billing = billing;
+        this.capped = capped;
     }
 }
 /**
@@ -62,16 +77,18 @@ export async function outpostRequest(opts) {
             : typeof body.error === "string"
                 ? body.error
                 : res.statusText;
-        throw new OutpostHttpError(res.status, message, body.step, parseBillingPayload(body));
+        throw new OutpostHttpError(res.status, message, body.step, parseBillingPayload(body), parseCappedPayload(body));
     }
     return (await res.json());
 }
 /**
  * Provision the caller's Outpost. Sends the cached Cognito refresh token so the
  * box can authenticate AS the caller (the same body the console's
- * `provisionMyOutpost` sends). Idempotent server-side: a caller already at their
- * per-person cap gets their existing box back rather than a duplicate. The
- * refresh token is sent over HTTPS and NEVER printed.
+ * `provisionMyOutpost` sends). No duplicate is ever created: a caller already at
+ * their per-person cap gets a `409` whose body lists their existing boxes —
+ * thrown here as an `OutpostHttpError` carrying `capped` (hq-pro checks the cap
+ * BEFORE activation billing, so a capped call is never charged). The refresh
+ * token is sent over HTTPS and NEVER printed.
  */
 export async function provisionOutpost(token, input) {
     return outpostRequest({
@@ -300,6 +317,24 @@ function ensureTrailingNewline(s) {
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
+/**
+ * Explain a `409` per-person cap. hq-pro checks the cap BEFORE activation
+ * billing, so nothing was charged — worth saying, since the caller just
+ * confirmed a recurring charge to get here.
+ */
+function surfaceOutpostCapped(capped) {
+    const owned = capped.outposts.length;
+    console.error(chalk.yellow(`You're already at your Outpost limit (${owned} of ${capped.limit}). ` +
+        `No new box was provisioned and you have not been charged.`));
+    for (const o of capped.outposts) {
+        const detail = [o.state, o.instanceName, o.region]
+            .filter(Boolean)
+            .join("  ");
+        console.error(`  ${o.outpostId}  ${detail}`);
+    }
+    console.error(chalk.dim("Inspect it: hq outposts status"));
+    console.error(chalk.dim("Or tear it down first: hq outposts destroy --id <id> --yes"));
+}
 function fail(err) {
     if (err instanceof OutpostHttpError) {
         console.error(chalk.red(err.message));
@@ -615,7 +650,17 @@ function authGitHubViaVault(deps) {
         "unset GITHUB_TOKEN",
         'printf "%s" "$TOKEN" | gh auth login --with-token',
     ].join("\n");
-    const authed = runBestEffort(deps, "hq", ["secrets", "--personal", "exec", "--only", "GITHUB_TOKEN", "--", "bash", "-c", ghLogin], "GitHub auth via vault");
+    const authed = runBestEffort(deps, "hq", [
+        "secrets",
+        "--personal",
+        "exec",
+        "--only",
+        "GITHUB_TOKEN",
+        "--",
+        "bash",
+        "-c",
+        ghLogin,
+    ], "GitHub auth via vault");
     if (authed) {
         // Let plain `git clone https://github.com/...` reuse gh's token so private
         // repos don't prompt for a username/password.
@@ -670,7 +715,15 @@ async function replicaSyncOutpost(opts, deps) {
         console.warn("replica-sync: auth refresh failed — skipping this cycle (token likely expired).");
         return;
     }
-    runBestEffort(deps, "hq", ["sync", "pull", "--personal", "--hq-root", hqRoot, "--on-conflict", "keep"], "personal vault pull");
+    runBestEffort(deps, "hq", [
+        "sync",
+        "pull",
+        "--personal",
+        "--hq-root",
+        hqRoot,
+        "--on-conflict",
+        "keep",
+    ], "personal vault pull");
     // rescue lays down the core kernel and expects companies/ to exist.
     deps.mkdirp(path.join(hqRoot, "companies"));
     runBestEffort(deps, "hq", ["rescue", "--hq-root", hqRoot, "--yes"], "HQ kernel rescue");
@@ -722,9 +775,17 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
         .option("--yes", "Confirm the $80/month charge (required to provision)")
         .action(async function (opts) {
         try {
+            // Reject an unrecognized runtime rather than resolving it to claude:
+            // `--runtime codx` would otherwise hand back a silently Claude box.
+            if (opts.runtime !== undefined &&
+                opts.runtime !== "claude" &&
+                opts.runtime !== "codex") {
+                console.error(chalk.red(`Invalid --runtime '${opts.runtime}': must be 'claude' or 'codex'.`));
+                process.exit(1);
+            }
             const agentRuntime = opts.runtime === "codex"
                 ? "codex"
-                : opts.runtime
+                : opts.runtime === "claude"
                     ? "claude"
                     : undefined;
             let diskSizeGb;
@@ -764,7 +825,15 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
                 if (err instanceof OutpostHttpError &&
                     err.status === 402 &&
                     err.billing) {
-                    await surfaceBillingRequired(token, err.billing);
+                    await surfaceBillingBlocked(token, err.billing, err.message);
+                    process.exit(1);
+                }
+                // Already at the per-person cap → say so and name the box they own,
+                // not a bare "Conflict".
+                if (err instanceof OutpostHttpError &&
+                    err.status === 409 &&
+                    err.capped) {
+                    surfaceOutpostCapped(err.capped);
                     process.exit(1);
                 }
                 throw err;