@indigoai-us/hq-cli 5.62.0 → 5.62.2

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.62.1]
+
+### Added
+
+- **`hq db provision` / `hq db status --remote` use Cognito + vault API** to call the live control plane (`POST /v1/db/provision`, `GET /v1/db/status`). Team plan required for provision; local `status|sql|migrate` unchanged.
+
+
 ## [5.55.1]
 
 ### Fixed

package/dist/commands/cloud.d.ts

@@ -66,6 +66,17 @@ export interface SyncCallOptions {
      */
     syncMode?: SyncMode;
     prefixSet?: string[];
+    /**
+     * Company-relative prefixes the pull must NOT materialize even when the
+     * caller's STS scope is wide enough to read them (sessions-exclusion /
+     * company-work-corpus). Derived by `resolvePullScope` in the hq-cloud release
+     * carrying the sessions/ pull-exclusion, forwarded to `sync()` here so the CLI
+     * honors the same "session transcripts never sync DOWN" invariant the
+     * background sync engine enforces. A company OWNER can read `sessions/` keys,
+     * so without this the CLI would bulk-download everyone's full-content session
+     * transcripts to local disk. Undefined/empty ⇒ nothing excluded (legacy).
+     */
+    excludePrefixes?: string[];
     /** Honor a `--force-scope-shrink` on a foreground pull (dirty files kept). */
     forceScopeShrink?: boolean;
 }

package/dist/commands/cloud.js

@@ -13,7 +13,7 @@
  *   hq sync status            — show local journal summary
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fa72780b-ae22-5125-98b6-4e7b866b7d17")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5e2703d2-1874-5625-8508-67ff641ff1a6")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -74,6 +74,25 @@ function pickCanonicalPerson(persons) {
         return a.uid < b.uid ? -1 : 1;
     })[0];
 }
+/**
+ * Read the sessions-exclusion prefix set off a resolved {@link PullScope}.
+ *
+ * `resolvePullScope` in hq-cloud derives the sessions/ pull-exclusion and
+ * derives `excludePrefixes` (e.g. `["sessions/"]`) so a company OWNER — whose STS
+ * scope is wide enough to read `sessions/` keys — does not bulk-download
+ * everyone's full-content session transcripts to local disk, upholding the
+ * "session transcripts never sync DOWN" invariant hq-cloud enforces for the
+ * background engine. Keep the small runtime shape check even though PullScope
+ * now declares the field: it protects the CLI when an older external resolver
+ * implementation is injected by tests or downstream callers.
+ */
+function readScopeExcludePrefixes(scope) {
+    const raw = scope?.excludePrefixes;
+    if (!Array.isArray(raw))
+        return undefined;
+    const prefixes = raw.filter((p) => typeof p === "string" && p.length > 0);
+    return prefixes.length > 0 ? prefixes : undefined;
+}
 export async function pullAll(options, deps) {
     const memberships = await deps.vaultClient.listMyMemberships();
     const persons = await deps.vaultClient.listPersonEntities();
@@ -145,6 +164,12 @@ export async function pullAll(options, deps) {
                 if (scope.prefixSet !== undefined) {
                     entry.syncOptions.prefixSet = scope.prefixSet;
                 }
+                // Sessions-exclusion: thread the resolver's excludePrefixes into the
+                // pull so a wide-STS OWNER never bulk-downloads session transcripts.
+                const excludePrefixes = readScopeExcludePrefixes(scope);
+                if (excludePrefixes) {
+                    entry.syncOptions.excludePrefixes = excludePrefixes;
+                }
             }
             catch {
                 resolvedMode = undefined;
@@ -742,6 +767,7 @@ export function registerCloudCommands(program) {
                     "to migrate, or re-run with --mode-all."));
                 process.exit(1);
             }
+            const excludePrefixes = readScopeExcludePrefixes(pullScope);
             const result = await sync({
                 company: options.company,
                 onConflict: options.onConflict,
@@ -753,6 +779,9 @@ export function registerCloudCommands(program) {
                 ...(pullScope?.prefixSet !== undefined
                     ? { prefixSet: pullScope.prefixSet }
                     : {}),
+                // Sessions-exclusion: never materialize excluded prefixes even for
+                // a wide-STS owner.
+                ...(excludePrefixes ? { excludePrefixes } : {}),
                 ...(options.forceScopeShrink ? { forceScopeShrink: true } : {}),
             });
             if (result.aborted) {
@@ -944,6 +973,11 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
                     : {}),
                 ...(opts.syncMode !== undefined ? { syncMode: opts.syncMode } : {}),
                 ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
+                // Sessions-exclusion: forward the per-company excludePrefixes that
+                // pullAll stamped onto SyncCallOptions into the real hq-cloud sync().
+                ...(opts.excludePrefixes?.length
+                    ? { excludePrefixes: opts.excludePrefixes }
+                    : {}),
                 ...(opts.forceScopeShrink ? { forceScopeShrink: true } : {}),
             }),
         });
@@ -1226,6 +1260,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             }
         }
         console.log(chalk.dim("  → pull leg"));
+        const excludePrefixes = readScopeExcludePrefixes(pullScope);
         const pullResult = await sync({
             company: targetCompany,
             vaultConfig,
@@ -1239,6 +1274,9 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             ...(pullScope?.prefixSet !== undefined
                 ? { prefixSet: pullScope.prefixSet }
                 : {}),
+            // Sessions-exclusion: honor the resolver's excludePrefixes on the
+            // `hq sync now` pull leg too.
+            ...(excludePrefixes ? { excludePrefixes } : {}),
             ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
         });
         console.log(`    ${pullResult.aborted ? chalk.yellow("⚠") : chalk.green("✓")} ` +
@@ -1368,4 +1406,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=fa72780b-ae22-5125-98b6-4e7b866b7d17
+//# debugId=5e2703d2-1874-5625-8508-67ff641ff1a6

package/dist/commands/db-provision.js

@@ -2,31 +2,34 @@
  * hq db provision — request remote vault DB binding (US-009).
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cecdf1ea-3f73-54c4-adc0-f11caebf1e55")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f0d312c6-3730-5e46-b21f-c694723d0f5b")}catch(e){}}();
 import chalk from "chalk";
 import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
+import { DEFAULT_VAULT_API_URL, ensureCognitoToken, } from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
 const defaultDeps = () => ({
     async resolveCompany(slug) {
-        // Production path: resolve via vault API membership. Tests inject mocks.
-        // Keep slug as placeholder uid only when HQ_DB_MOCK_CONTROL_PLANE=1.
         if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
             return { companyUid: `cmp_${slug}`, companySlug: slug };
         }
-        throw new Error("company resolution not wired in this build path — inject deps or set HQ_DB_MOCK_CONTROL_PLANE=1 for local mock");
+        const token = await ensureCognitoToken({ interactive: false });
+        const companyUid = await getCompanyUid(token, slug);
+        return { companyUid, companySlug: slug.trim().toLowerCase() };
     },
     async getAccessToken() {
         if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
             return "mock-token";
         }
-        throw new Error("auth token resolution not wired — inject deps for production");
+        return ensureCognitoToken({ interactive: false });
     },
-    apiBaseUrl: process.env.HQ_API_BASE_URL ||
+    apiBaseUrl: process.env.HQ_VAULT_API_URL ||
+        process.env.HQ_API_BASE_URL ||
         process.env.HQ_CLOUD_API_URL ||
-        "https://hqapi.getindigo.ai",
+        DEFAULT_VAULT_API_URL,
 });
 export function registerDbProvisionCommand(db, depsFactory = defaultDeps) {
     db.command("provision")
-        .description("Provision (or re-bind) the company remote vault DB via HQ control plane")
+        .description("Provision (or re-bind) the company remote vault DB via HQ control plane (Team plan)")
         .requiredOption("--company <slug>", "Company slug")
         .option("--region <region>", "AWS region", "us-east-1")
         .action(async (opts) => {
@@ -64,6 +67,10 @@ export function registerDbProvisionCommand(db, depsFactory = defaultDeps) {
                 console.error(chalk.red("Error:"), "Remote vault DB requires the HQ Team plan ($500/mo).");
                 console.error(chalk.dim("Local databases still work: hq db status|sql|migrate — no Team plan required."));
             }
+            else if (status === 404 || /Unknown route|Not Found/i.test(msg)) {
+                console.error(chalk.red("Error:"), "Remote DB control plane is not available yet (routes not deployed).");
+                console.error(chalk.dim("Local hq db status|sql|migrate still work offline."));
+            }
             else {
                 console.error(chalk.red("Error:"), msg);
             }
@@ -75,4 +82,4 @@ export function registerDbProvisionCommand(db, depsFactory = defaultDeps) {
     });
 }
 //# sourceMappingURL=db-provision.js.map
-//# debugId=cecdf1ea-3f73-54c4-adc0-f11caebf1e55
+//# debugId=f0d312c6-3730-5e46-b21f-c694723d0f5b

package/dist/commands/db-status.js

@@ -3,7 +3,7 @@
  * Optionally reports remote tier when control plane returns a binding (US-009).
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8b820218-b1e5-57a2-8acd-d8e749a0d83f")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b0f21394-45cb-572c-890b-bcdf0fc9e7d7")}catch(e){}}();
 import chalk from "chalk";
 import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
 import { ensureAndStatusLocalDb, formatLocalDbStatus, } from "../lib/db/local.js";
@@ -26,19 +26,23 @@ export function registerDbStatusCommand(db) {
             // Never print remote connection material.
             console.log(formatLocalDbStatus(status));
             if (opts.remote) {
-                const companyUid = opts.companyUid || `cmp_${company}`;
-                const baseUrl = process.env.HQ_API_BASE_URL ||
-                    process.env.HQ_CLOUD_API_URL ||
-                    "https://hqapi.getindigo.ai";
+                const { DEFAULT_VAULT_API_URL, ensureCognitoToken } = await import("../utils/cognito-session.js");
+                const { getCompanyUid } = await import("../utils/vault-api.js");
                 try {
+                    const token = process.env.HQ_DB_MOCK_CONTROL_PLANE === "1"
+                        ? "mock-token"
+                        : await ensureCognitoToken({ interactive: false });
+                    const companyUid = opts.companyUid ||
+                        (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1"
+                            ? `cmp_${company}`
+                            : await getCompanyUid(token, company));
+                    const baseUrl = process.env.HQ_VAULT_API_URL ||
+                        process.env.HQ_API_BASE_URL ||
+                        process.env.HQ_CLOUD_API_URL ||
+                        DEFAULT_VAULT_API_URL;
                     const client = new ControlPlaneDbClient({
                         baseUrl,
-                        getAccessToken: async () => {
-                            if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
-                                return "mock-token";
-                            }
-                            throw new Error("auth required for remote status");
-                        },
+                        getAccessToken: async () => token,
                     });
                     const remote = await client.status(companyUid);
                     if (!remote.remote) {
@@ -67,4 +71,4 @@ export function registerDbStatusCommand(db) {
     });
 }
 //# sourceMappingURL=db-status.js.map
-//# debugId=8b820218-b1e5-57a2-8acd-d8e749a0d83f
+//# debugId=b0f21394-45cb-572c-890b-bcdf0fc9e7d7

package/dist/commands/members.d.ts

@@ -1,5 +1,7 @@
 import { Command } from "commander";
 export declare const VALID_ROLES: Set<string>;
+/** Roles allowed when inviting an existing fleet agent into a company. */
+export declare const AGENT_INVITE_ROLES: Set<string>;
 export type Role = "owner" | "admin" | "member" | "guest";
 export interface PendingInvite {
     membershipKey: string;
@@ -81,6 +83,13 @@ export interface InviteResult {
     emailSkipped?: boolean;
     /** Resend was attempted but failed — human-readable reason. */
     emailError?: string;
+    /**
+     * Present when hq-pro treated the target as a fleet agent (guest invite).
+     * Always `false` on the agent path — host keeps billing.
+     */
+    activationBilled?: boolean;
+    /** Host company uid when the server returned an agent guest-invite result. */
+    hostCompanyUid?: string;
 }
 export interface ResendInviteOptions {
     inviteeEmail: string;
@@ -100,8 +109,10 @@ export interface ResendInviteResult {
     emailError?: string;
 }
 export interface DetectedTarget {
-    type: "email" | "person";
+    type: "email" | "person" | "agent";
     value: string;
+    /** True when the target is a fleet agent (uid or machine email). */
+    isAgent?: boolean;
 }
 export declare function detectTarget(target: string): DetectedTarget | null;
 export declare function shortDate(iso: string): string;

package/dist/commands/members.js

@@ -1,17 +1,33 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e3c1d5a2-b7f4-5f0f-8603-000df9bcca33")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9dbfcbea-adf6-5852-b0de-aa6ee4391615")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/i;
+/** Fleet agent machine email: agt-…@agents.getindigo.ai */
+const AGENT_EMAIL_PATTERN = /^agt-[a-z0-9]+@agents\.getindigo\.ai$/i;
 export const VALID_ROLES = new Set(["owner", "admin", "member", "guest"]);
+/** Roles allowed when inviting an existing fleet agent into a company. */
+export const AGENT_INVITE_ROLES = new Set(["admin", "member"]);
 export function detectTarget(target) {
-    if (EMAIL_PATTERN.test(target)) {
-        return { type: "email", value: target.trim().toLowerCase() };
+    const trimmed = target.trim();
+    if (AGENT_UID_PATTERN.test(trimmed)) {
+        return { type: "agent", value: trimmed, isAgent: true };
     }
-    if (PERSON_UID_PATTERN.test(target)) {
-        return { type: "person", value: target };
+    if (AGENT_EMAIL_PATTERN.test(trimmed)) {
+        return {
+            type: "email",
+            value: trimmed.toLowerCase(),
+            isAgent: true,
+        };
+    }
+    if (EMAIL_PATTERN.test(trimmed)) {
+        return { type: "email", value: trimmed.toLowerCase() };
+    }
+    if (PERSON_UID_PATTERN.test(trimmed)) {
+        return { type: "person", value: trimmed };
     }
     return null;
 }
@@ -45,9 +61,24 @@ export async function inviteMember(options) {
     }
     const detected = detectTarget(options.target);
     if (!detected) {
-        throw new Error(`Invalid target '${options.target}': must be an email address or a personUid matching prs_<alphanumeric>`);
+        throw new Error(`Invalid target '${options.target}': must be an email, personUid (prs_…), agent uid (agt_…), or agent email (agt-…@agents.getindigo.ai)`);
     }
-    if (options.groupIds && options.groupIds.length > 0 && detected.type === "person") {
+    // Fleet agents: same invite command as humans, but only member|admin.
+    // Host company keeps billing — server never double-bills on guest invite.
+    if (detected.isAgent) {
+        if (!AGENT_INVITE_ROLES.has(options.role)) {
+            throw new Error(`Agents can only be invited as member or admin (got '${options.role}'). Host company keeps billing.`);
+        }
+        if (options.paths) {
+            throw new Error("--paths / guest role is not valid for agents — invite as member or admin");
+        }
+        if (options.groupIds && options.groupIds.length > 0) {
+            throw new Error("--groups is not supported on agent invites — share secrets after membership with `hq secrets share`");
+        }
+    }
+    if (options.groupIds &&
+        options.groupIds.length > 0 &&
+        (detected.type === "person" || detected.type === "agent")) {
         throw new Error("--groups is only valid on email-keyed invites (server rejects personUid + groupIds with 400)");
     }
     const allowedPrefixes = options.paths
@@ -108,6 +139,12 @@ export async function inviteMember(options) {
             ? { emailSkipped: data.emailSkipped }
             : {}),
         ...(data.emailError ? { emailError: data.emailError } : {}),
+        ...(typeof data.activationBilled === "boolean"
+            ? { activationBilled: data.activationBilled }
+            : {}),
+        ...(typeof data.hostCompanyUid === "string"
+            ? { hostCompanyUid: data.hostCompanyUid }
+            : {}),
     };
 }
 /**
@@ -337,8 +374,8 @@ export function registerMembersCommand(program) {
     });
     members
         .command("invite <target>")
-        .description("Invite a person to the company by email or personUid (sends an invitation email by default)")
-        .option("--role <role>", "Role for the invitee: owner, admin, member, or guest", "member")
+        .description("Invite a person or fleet agent to the company. People: email or prs_…. Agents: agt_… or agt-…@agents.getindigo.ai (member|admin; host keeps billing, no double charge).")
+        .option("--role <role>", "Role: person → owner|admin|member|guest; agent → member|admin only", "member")
         .option("--paths <prefixes>", "Comma-separated allowed prefixes (only valid with --role guest)")
         .option("--groups <ids>", "Comma-separated secret-group ids the invitee will be added to on claim (email-keyed invites only)")
         .option("--send-email", "Have hq-pro send an invitation email via Resend (default true for email-keyed invites). Pre-resend hq-pro versions ignore this and the legacy 'no email sent' instructions print instead.", true)
@@ -376,12 +413,34 @@ export function registerMembersCommand(program) {
                 role: opts.role,
                 paths: opts.paths,
                 groupIds,
-                sendEmail: opts.sendEmail,
+                // Agents join actively — no Resend email.
+                sendEmail: detectTarget(target)?.isAgent ? false : opts.sendEmail,
                 companyUid,
                 callerUid,
                 token,
             });
+            const agentTarget = detectTarget(target)?.isAgent === true;
             console.log(chalk.green(`Invited ${target} as ${result.membership.role} (status: ${result.membership.status})`));
+            // Agent path is confirmed only when the server returned the guest-invite
+            // envelope (activationBilled present) AND status is active. A pending
+            // row means this hq-pro stage has not rolled the agent invite path yet —
+            // do NOT claim active join / no-double-bill.
+            if (agentTarget &&
+                result.membership.status === "active" &&
+                typeof result.activationBilled === "boolean") {
+                console.log(chalk.dim(`Fleet agent: active membership granted immediately` +
+                    (result.hostCompanyUid
+                        ? ` (host ${result.hostCompanyUid} keeps billing)`
+                        : " (host keeps billing, no double charge)") +
+                    `. Next: share secrets / vault paths as needed (\`hq secrets share\`, \`/new-agent\`).`));
+                console.log();
+                return;
+            }
+            if (agentTarget && result.membership.status !== "active") {
+                console.log(chalk.yellow("⚠ Agent invite landed as a pending membership — this hq-pro stage may not yet have multi-company agent invite. Wait for prod deploy of the agent membership path, then re-invite (or revoke this pending row)."));
+                console.log();
+                return;
+            }
             console.log();
             if (result.magicLink) {
                 // Legacy server schema — magic-link redemption.
@@ -564,4 +623,4 @@ export function registerMembersCommand(program) {
     });
 }
 //# sourceMappingURL=members.js.map
-//# debugId=e3c1d5a2-b7f4-5f0f-8603-000df9bcca33
+//# debugId=9dbfcbea-adf6-5852-b0de-aa6ee4391615

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.62.0",
+  "version": "5.62.2",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -19,7 +19,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.12.1",
+    "@indigoai-us/hq-cloud": "^6.14.2",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "better-sqlite3": "^12.11.1",

package/src/commands/cloud.pull-all.test.ts

@@ -180,6 +180,59 @@ describe("pullAll", () => {
     expect(companyCall?.prefixSet).toEqual(["knowledge/", "policies/"]);
   });
 
+  // ── 1c. Sessions-exclusion: excludePrefixes is threaded into sync() ───────
+  //
+  // Guards the "session transcripts never sync DOWN" invariant on the CLI path:
+  // a company OWNER's STS scope is wide enough to read `sessions/` keys, so if
+  // the 4-site scope→sync-options mapping dropped `excludePrefixes` the CLI
+  // would bulk-download everyone's full-content session transcripts to local
+  // disk. This asserts the resolver's excludePrefixes reaches the SyncCallOptions
+  // handed to sync(); it FAILS if any mapping site drops the field.
+  it("threads the resolved excludePrefixes into sync() (sessions never pull DOWN)", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_a" }],
+      entitiesBySlug: { cmp_a: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+    // hq-cloud derives excludePrefixes on the resolved scope.
+    const resolveScope = vi.fn(async (_uid: string, _slug: string) => ({
+      syncMode: "shared" as const,
+      prefixSet: ["knowledge/", "policies/"],
+      excludePrefixes: ["sessions/"],
+    }));
+
+    await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn, resolveScope },
+    );
+
+    const companyCall = sync.calls.find((c) => c.company === "cmp_a");
+    expect(companyCall?.excludePrefixes).toEqual(["sessions/"]);
+    // Sibling scope fields still flow — excludePrefixes rides alongside them.
+    expect(companyCall?.syncMode).toBe("shared");
+    expect(companyCall?.prefixSet).toEqual(["knowledge/", "policies/"]);
+  });
+
+  it("omits excludePrefixes when the resolved scope carries none", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_a" }],
+      entitiesBySlug: { cmp_a: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+    const resolveScope = vi.fn(async () => ({
+      syncMode: "shared" as const,
+      prefixSet: ["knowledge/"],
+    }));
+
+    await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn, resolveScope },
+    );
+
+    const companyCall = sync.calls.find((c) => c.company === "cmp_a");
+    expect(companyCall?.excludePrefixes).toBeUndefined();
+  });
+
   it("passes no prefixSet for an all-mode membership (full pull preserved)", async () => {
     const vaultClient = makeVaultClient({
       memberships: [{ companyUid: "cmp_a" }],

package/src/commands/cloud.ts

@@ -153,6 +153,17 @@ export interface SyncCallOptions {
    */
   syncMode?: SyncMode;
   prefixSet?: string[];
+  /**
+   * Company-relative prefixes the pull must NOT materialize even when the
+   * caller's STS scope is wide enough to read them (sessions-exclusion /
+   * company-work-corpus). Derived by `resolvePullScope` in the hq-cloud release
+   * carrying the sessions/ pull-exclusion, forwarded to `sync()` here so the CLI
+   * honors the same "session transcripts never sync DOWN" invariant the
+   * background sync engine enforces. A company OWNER can read `sessions/` keys,
+   * so without this the CLI would bulk-download everyone's full-content session
+   * transcripts to local disk. Undefined/empty ⇒ nothing excluded (legacy).
+   */
+  excludePrefixes?: string[];
   /** Honor a `--force-scope-shrink` on a foreground pull (dirty files kept). */
   forceScopeShrink?: boolean;
 }
@@ -320,6 +331,29 @@ function pickCanonicalPerson<
   })[0];
 }
 
+/**
+ * Read the sessions-exclusion prefix set off a resolved {@link PullScope}.
+ *
+ * `resolvePullScope` in hq-cloud derives the sessions/ pull-exclusion and
+ * derives `excludePrefixes` (e.g. `["sessions/"]`) so a company OWNER — whose STS
+ * scope is wide enough to read `sessions/` keys — does not bulk-download
+ * everyone's full-content session transcripts to local disk, upholding the
+ * "session transcripts never sync DOWN" invariant hq-cloud enforces for the
+ * background engine. Keep the small runtime shape check even though PullScope
+ * now declares the field: it protects the CLI when an older external resolver
+ * implementation is injected by tests or downstream callers.
+ */
+function readScopeExcludePrefixes(
+  scope: PullScope | undefined,
+): string[] | undefined {
+  const raw: unknown = scope?.excludePrefixes;
+  if (!Array.isArray(raw)) return undefined;
+  const prefixes = raw.filter(
+    (p): p is string => typeof p === "string" && p.length > 0,
+  );
+  return prefixes.length > 0 ? prefixes : undefined;
+}
+
 export async function pullAll(
   options: PullAllOptions,
   deps: PullAllDeps,
@@ -398,6 +432,12 @@ export async function pullAll(
         if (scope.prefixSet !== undefined) {
           entry.syncOptions.prefixSet = scope.prefixSet;
         }
+        // Sessions-exclusion: thread the resolver's excludePrefixes into the
+        // pull so a wide-STS OWNER never bulk-downloads session transcripts.
+        const excludePrefixes = readScopeExcludePrefixes(scope);
+        if (excludePrefixes) {
+          entry.syncOptions.excludePrefixes = excludePrefixes;
+        }
       } catch {
         resolvedMode = undefined;
       }
@@ -1205,6 +1245,7 @@ export function registerCloudCommands(program: Command): void {
             process.exit(1);
           }
 
+          const excludePrefixes = readScopeExcludePrefixes(pullScope);
           const result = await sync({
             company: options.company,
             onConflict: options.onConflict,
@@ -1216,6 +1257,9 @@ export function registerCloudCommands(program: Command): void {
             ...(pullScope?.prefixSet !== undefined
               ? { prefixSet: pullScope.prefixSet }
               : {}),
+            // Sessions-exclusion: never materialize excluded prefixes even for
+            // a wide-STS owner.
+            ...(excludePrefixes ? { excludePrefixes } : {}),
             ...(options.forceScopeShrink ? { forceScopeShrink: true } : {}),
           });
 
@@ -1519,6 +1563,11 @@ async function runPullAll(
               : {}),
             ...(opts.syncMode !== undefined ? { syncMode: opts.syncMode } : {}),
             ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
+            // Sessions-exclusion: forward the per-company excludePrefixes that
+            // pullAll stamped onto SyncCallOptions into the real hq-cloud sync().
+            ...(opts.excludePrefixes?.length
+              ? { excludePrefixes: opts.excludePrefixes }
+              : {}),
             ...(opts.forceScopeShrink ? { forceScopeShrink: true } : {}),
           }),
       },
@@ -1877,6 +1926,7 @@ async function runNowSingle(
     }
 
     console.log(chalk.dim("  → pull leg"));
+    const excludePrefixes = readScopeExcludePrefixes(pullScope);
     const pullResult = await sync({
       company: targetCompany,
       vaultConfig,
@@ -1890,6 +1940,9 @@ async function runNowSingle(
       ...(pullScope?.prefixSet !== undefined
         ? { prefixSet: pullScope.prefixSet }
         : {}),
+      // Sessions-exclusion: honor the resolver's excludePrefixes on the
+      // `hq sync now` pull leg too.
+      ...(excludePrefixes ? { excludePrefixes } : {}),
       ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
     });
     console.log(

package/src/commands/db-provision.ts

@@ -6,6 +6,11 @@ import { Command } from "commander";
 import chalk from "chalk";
 
 import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
+import {
+  DEFAULT_VAULT_API_URL,
+  ensureCognitoToken,
+} from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
 
 export interface DbProvisionCommandDeps {
   resolveCompany: (slug: string) => Promise<{ companyUid: string; companySlug: string }>;
@@ -16,25 +21,24 @@ export interface DbProvisionCommandDeps {
 
 const defaultDeps = (): DbProvisionCommandDeps => ({
   async resolveCompany(slug) {
-    // Production path: resolve via vault API membership. Tests inject mocks.
-    // Keep slug as placeholder uid only when HQ_DB_MOCK_CONTROL_PLANE=1.
     if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
       return { companyUid: `cmp_${slug}`, companySlug: slug };
     }
-    throw new Error(
-      "company resolution not wired in this build path — inject deps or set HQ_DB_MOCK_CONTROL_PLANE=1 for local mock",
-    );
+    const token = await ensureCognitoToken({ interactive: false });
+    const companyUid = await getCompanyUid(token, slug);
+    return { companyUid, companySlug: slug.trim().toLowerCase() };
   },
   async getAccessToken() {
     if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
       return "mock-token";
     }
-    throw new Error("auth token resolution not wired — inject deps for production");
+    return ensureCognitoToken({ interactive: false });
   },
   apiBaseUrl:
+    process.env.HQ_VAULT_API_URL ||
     process.env.HQ_API_BASE_URL ||
     process.env.HQ_CLOUD_API_URL ||
-    "https://hqapi.getindigo.ai",
+    DEFAULT_VAULT_API_URL,
 });
 
 export function registerDbProvisionCommand(
@@ -43,7 +47,7 @@ export function registerDbProvisionCommand(
 ): void {
   db.command("provision")
     .description(
-      "Provision (or re-bind) the company remote vault DB via HQ control plane",
+      "Provision (or re-bind) the company remote vault DB via HQ control plane (Team plan)",
     )
     .requiredOption("--company <slug>", "Company slug")
     .option("--region <region>", "AWS region", "us-east-1")
@@ -90,6 +94,14 @@ export function registerDbProvisionCommand(
               "Local databases still work: hq db status|sql|migrate — no Team plan required.",
             ),
           );
+        } else if (status === 404 || /Unknown route|Not Found/i.test(msg)) {
+          console.error(
+            chalk.red("Error:"),
+            "Remote DB control plane is not available yet (routes not deployed).",
+          );
+          console.error(
+            chalk.dim("Local hq db status|sql|migrate still work offline."),
+          );
         } else {
           console.error(chalk.red("Error:"), msg);
         }

package/src/commands/db-status.ts

@@ -55,20 +55,28 @@ export function registerDbStatusCommand(db: Command): void {
           console.log(formatLocalDbStatus(status));
 
           if (opts.remote) {
-            const companyUid = opts.companyUid || `cmp_${company}`;
-            const baseUrl =
-              process.env.HQ_API_BASE_URL ||
-              process.env.HQ_CLOUD_API_URL ||
-              "https://hqapi.getindigo.ai";
+            const { DEFAULT_VAULT_API_URL, ensureCognitoToken } = await import(
+              "../utils/cognito-session.js"
+            );
+            const { getCompanyUid } = await import("../utils/vault-api.js");
             try {
+              const token =
+                process.env.HQ_DB_MOCK_CONTROL_PLANE === "1"
+                  ? "mock-token"
+                  : await ensureCognitoToken({ interactive: false });
+              const companyUid =
+                opts.companyUid ||
+                (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1"
+                  ? `cmp_${company}`
+                  : await getCompanyUid(token, company));
+              const baseUrl =
+                process.env.HQ_VAULT_API_URL ||
+                process.env.HQ_API_BASE_URL ||
+                process.env.HQ_CLOUD_API_URL ||
+                DEFAULT_VAULT_API_URL;
               const client = new ControlPlaneDbClient({
                 baseUrl,
-                getAccessToken: async () => {
-                  if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
-                    return "mock-token";
-                  }
-                  throw new Error("auth required for remote status");
-                },
+                getAccessToken: async () => token,
               });
               const remote = await client.status(companyUid);
               if (!remote.remote) {

package/src/commands/members.test.ts

@@ -95,6 +95,24 @@ describe("detectTarget", () => {
     });
   });
 
+  it("recognizes fleet agent uids", () => {
+    expect(detectTarget("agt_01HXYZABCDEFGHJKMNPQRSTVWX")).toEqual({
+      type: "agent",
+      value: "agt_01HXYZABCDEFGHJKMNPQRSTVWX",
+      isAgent: true,
+    });
+  });
+
+  it("recognizes fleet agent machine emails", () => {
+    expect(
+      detectTarget("agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai"),
+    ).toEqual({
+      type: "email",
+      value: "agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai",
+      isAgent: true,
+    });
+  });
+
   it("returns null for invalid targets", () => {
     expect(detectTarget("not-a-target")).toBeNull();
     expect(detectTarget("cmp_company")).toBeNull();
@@ -234,6 +252,48 @@ describe("inviteMember", () => {
     expect(fetchSpy).not.toHaveBeenCalled();
   });
 
+  it("invites a fleet agent by uid as member via /membership/invite", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(201, {
+        membership: {
+          membershipKey: "agt_01HXYZ#cmp_acme",
+          role: "member",
+          status: "active",
+        },
+        agentUid: "agt_01HXYZABCDEFGHJKMNPQRSTVWX",
+        hostCompanyUid: "cmp_host",
+        activationBilled: false,
+      }),
+    );
+
+    const result = await inviteMember({
+      target: "agt_01HXYZABCDEFGHJKMNPQRSTVWX",
+      role: "member",
+      companyUid: "cmp_acme",
+      callerUid: "prs_admin",
+      token: "test-token",
+    });
+
+    expect(result.membership.status).toBe("active");
+    expect(result.membership.role).toBe("member");
+    const body = JSON.parse((fetchSpy.mock.calls[0][1]?.body as string) ?? "{}");
+    expect(body.personUid).toBe("agt_01HXYZABCDEFGHJKMNPQRSTVWX");
+    expect(body.role).toBe("member");
+  });
+
+  it("rejects owner/guest roles for agent invites", async () => {
+    await expect(
+      inviteMember({
+        target: "agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai",
+        role: "owner",
+        companyUid: "cmp_acme",
+        callerUid: "prs_admin",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/member or admin/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
   it("rejects an unknown role", async () => {
     await expect(
       inviteMember({

package/src/commands/members.ts

@@ -5,7 +5,13 @@ import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/i;
+/** Fleet agent machine email: agt-…@agents.getindigo.ai */
+const AGENT_EMAIL_PATTERN =
+  /^agt-[a-z0-9]+@agents\.getindigo\.ai$/i;
 export const VALID_ROLES = new Set(["owner", "admin", "member", "guest"]);
+/** Roles allowed when inviting an existing fleet agent into a company. */
+export const AGENT_INVITE_ROLES = new Set(["admin", "member"]);
 
 export type Role = "owner" | "admin" | "member" | "guest";
 
@@ -100,6 +106,13 @@ export interface InviteResult {
   emailSkipped?: boolean;
   /** Resend was attempted but failed — human-readable reason. */
   emailError?: string;
+  /**
+   * Present when hq-pro treated the target as a fleet agent (guest invite).
+   * Always `false` on the agent path — host keeps billing.
+   */
+  activationBilled?: boolean;
+  /** Host company uid when the server returned an agent guest-invite result. */
+  hostCompanyUid?: string;
 }
 
 export interface ResendInviteOptions {
@@ -122,16 +135,29 @@ export interface ResendInviteResult {
 }
 
 export interface DetectedTarget {
-  type: "email" | "person";
+  type: "email" | "person" | "agent";
   value: string;
+  /** True when the target is a fleet agent (uid or machine email). */
+  isAgent?: boolean;
 }
 
 export function detectTarget(target: string): DetectedTarget | null {
-  if (EMAIL_PATTERN.test(target)) {
-    return { type: "email", value: target.trim().toLowerCase() };
+  const trimmed = target.trim();
+  if (AGENT_UID_PATTERN.test(trimmed)) {
+    return { type: "agent", value: trimmed, isAgent: true };
+  }
+  if (AGENT_EMAIL_PATTERN.test(trimmed)) {
+    return {
+      type: "email",
+      value: trimmed.toLowerCase(),
+      isAgent: true,
+    };
   }
-  if (PERSON_UID_PATTERN.test(target)) {
-    return { type: "person", value: target };
+  if (EMAIL_PATTERN.test(trimmed)) {
+    return { type: "email", value: trimmed.toLowerCase() };
+  }
+  if (PERSON_UID_PATTERN.test(trimmed)) {
+    return { type: "person", value: trimmed };
   }
   return null;
 }
@@ -180,11 +206,35 @@ export async function inviteMember(
   const detected = detectTarget(options.target);
   if (!detected) {
     throw new Error(
-      `Invalid target '${options.target}': must be an email address or a personUid matching prs_<alphanumeric>`,
+      `Invalid target '${options.target}': must be an email, personUid (prs_…), agent uid (agt_…), or agent email (agt-…@agents.getindigo.ai)`,
     );
   }
 
-  if (options.groupIds && options.groupIds.length > 0 && detected.type === "person") {
+  // Fleet agents: same invite command as humans, but only member|admin.
+  // Host company keeps billing — server never double-bills on guest invite.
+  if (detected.isAgent) {
+    if (!AGENT_INVITE_ROLES.has(options.role)) {
+      throw new Error(
+        `Agents can only be invited as member or admin (got '${options.role}'). Host company keeps billing.`,
+      );
+    }
+    if (options.paths) {
+      throw new Error(
+        "--paths / guest role is not valid for agents — invite as member or admin",
+      );
+    }
+    if (options.groupIds && options.groupIds.length > 0) {
+      throw new Error(
+        "--groups is not supported on agent invites — share secrets after membership with `hq secrets share`",
+      );
+    }
+  }
+
+  if (
+    options.groupIds &&
+    options.groupIds.length > 0 &&
+    (detected.type === "person" || detected.type === "agent")
+  ) {
     throw new Error(
       "--groups is only valid on email-keyed invites (server rejects personUid + groupIds with 400)",
     );
@@ -236,6 +286,8 @@ export async function inviteMember(
     emailSent?: boolean;
     emailSkipped?: boolean;
     emailError?: string;
+    activationBilled?: boolean;
+    hostCompanyUid?: string;
   };
   if (!data.membership) {
     const keys = Object.keys(data ?? {}).join(", ") || "<empty>";
@@ -267,6 +319,12 @@ export async function inviteMember(
       ? { emailSkipped: data.emailSkipped }
       : {}),
     ...(data.emailError ? { emailError: data.emailError } : {}),
+    ...(typeof data.activationBilled === "boolean"
+      ? { activationBilled: data.activationBilled }
+      : {}),
+    ...(typeof data.hostCompanyUid === "string"
+      ? { hostCompanyUid: data.hostCompanyUid }
+      : {}),
   };
 }
 
@@ -604,11 +662,11 @@ export function registerMembersCommand(program: Command): void {
   members
     .command("invite <target>")
     .description(
-      "Invite a person to the company by email or personUid (sends an invitation email by default)",
+      "Invite a person or fleet agent to the company. People: email or prs_…. Agents: agt_… or agt-…@agents.getindigo.ai (member|admin; host keeps billing, no double charge).",
     )
     .option(
       "--role <role>",
-      "Role for the invitee: owner, admin, member, or guest",
+      "Role: person → owner|admin|member|guest; agent → member|admin only",
       "member",
     )
     .option(
@@ -681,17 +739,49 @@ export function registerMembersCommand(program: Command): void {
             role: opts.role,
             paths: opts.paths,
             groupIds,
-            sendEmail: opts.sendEmail,
+            // Agents join actively — no Resend email.
+            sendEmail: detectTarget(target)?.isAgent ? false : opts.sendEmail,
             companyUid,
             callerUid,
             token,
           });
 
+          const agentTarget = detectTarget(target)?.isAgent === true;
           console.log(
             chalk.green(
               `Invited ${target} as ${result.membership.role} (status: ${result.membership.status})`,
             ),
           );
+          // Agent path is confirmed only when the server returned the guest-invite
+          // envelope (activationBilled present) AND status is active. A pending
+          // row means this hq-pro stage has not rolled the agent invite path yet —
+          // do NOT claim active join / no-double-bill.
+          if (
+            agentTarget &&
+            result.membership.status === "active" &&
+            typeof result.activationBilled === "boolean"
+          ) {
+            console.log(
+              chalk.dim(
+                `Fleet agent: active membership granted immediately` +
+                  (result.hostCompanyUid
+                    ? ` (host ${result.hostCompanyUid} keeps billing)`
+                    : " (host keeps billing, no double charge)") +
+                  `. Next: share secrets / vault paths as needed (\`hq secrets share\`, \`/new-agent\`).`,
+              ),
+            );
+            console.log();
+            return;
+          }
+          if (agentTarget && result.membership.status !== "active") {
+            console.log(
+              chalk.yellow(
+                "⚠ Agent invite landed as a pending membership — this hq-pro stage may not yet have multi-company agent invite. Wait for prod deploy of the agent membership path, then re-invite (or revoke this pending row).",
+              ),
+            );
+            console.log();
+            return;
+          }
           console.log();
           if (result.magicLink) {
             // Legacy server schema — magic-link redemption.