@indigoai-us/hq-cli 5.345.149 → 5.345.151

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## [Unreleased]
 
+## [5.345.151] — 2026-10-20
+- `hq lanes link _deliver` no longer hands a conductor message to a subagent. Subagent hook events share the root session id, so a subagent tool call used to claim the message and the root session never saw it. Child payloads, including Grok child sessions (`subagent_type`) and Codex child threads, now get nothing and the message stays queued until the root session's next tool call or stop. SubagentStop no longer delivers. A parent session id alone does not mark a child, so resumed, forked, or launcher-spawned Grok roots still receive their messages.
+- If you leave out `--company`, `hq meetings invite <url>` now uses your only active company. If you belong to several companies, it lists them and asks you to pick one. The command used to send the invite as Personal instead. Personal can never record, so you saw the HQ Workforce upgrade prompt even when your company already had meeting recording.
+- `hq sync push`, `pull` and `now` honour the HQ app's Settings > Sync switches on this computer. A command aimed at a vault whose sync is off (the personal vault, one company vault, or every vault with "Turn off all cloud sync") prints `Sync is off for <vault>` with how to turn it back on, and exits 3 without signing in or touching the vault. The target is the `--company` value, else `activeCompany` or `companySlug` in `.hq/config.json`; a `cmp_*` uid is matched through `companies/manifest.yaml`, and an unmatched uid is refused while any company vault is off. `--creds-from-stdin` is checked once stdin is read. With `--json`, the refusal is a `{"type":"skipped","reason":"sync_off"}` line on stderr. `--all` skips the off vaults and syncs the rest. The `hq daemon` background sync skips off vaults the same way and stays stopped while all cloud sync is off; a switch change restarts it once the current sync pass finishes. A settings file that cannot be read prints a warning (and logs one in the daemon) instead of silently syncing everything. `/handoff` still finishes locally and logs a skipped push as skipped.
+- If you already had the HQ app's personal-files switch off (`personalSyncEnabled: false`) or a company's sync off (`workspaceSyncEnabled.<slug>: false`), `hq sync` now refuses those vaults too. That includes the `/handoff` personal publish, the `/startwork` and `/resumework` prefetch, and `/delegate` for those vaults. Turn the vault back on in HQ Settings > Sync to sync it from the command line again.
+
+## [5.345.150] — 2026-10-19
+- The bundled sync engine now uses hq-cloud 6.18.90, which brings two fixes.
+- Owners and admins can now destroy one of a company's Outposts with
+  `hq outposts destroy --company <slug>`. Add `--outpost <name|id>` when the
+  company has more than one. Without `--yes`, hq shows the company, Outpost
+  name and id, and destroys it only after you type the Outpost name or `yes`.
+  A script without a terminal must pass `--yes`. With `--yes --json` it prints
+  one result object. After the request, hq keeps checking status and reports
+  whether the Outpost is destroyed or still being destroyed, instead of
+  failing on a slow or errored response. It never falls back to your personal
+  Outpost. The Company Outpost commands from the last release are unchanged:
+  `hq outposts list --company`, `--outpost <name|id>` on status, login,
+  login-code, refresh-config and the jobs commands, and `hq outposts jobs`
+  edit, pause, resume, delete and run-now.
+- HQ Sync uses much less CPU and memory on Windows when HQ holds git
+  worktrees. The sync watcher no longer watches `worktrees/` at the top of
+  HQ, `.worktrees/`, `.claude/worktrees/`, `workspace/worktrees/`,
+  `node_modules` or nested `.git` folders, including during startup. A top
+  level `worktrees/` folder and any `.worktrees/` folder also stop syncing;
+  files from them that are already in the vault are not deleted. Sync passes
+  started by local changes now run at most once every 30 seconds, and a file
+  hq just downloaded no longer triggers an upload of itself. If the sync
+  runner uses more than a quarter of a CPU core or 600 MB of memory for a
+  while, it writes one warning line to its log. You can opt in to a local
+  diagnostics capture, and `hq-sync-runner --diagnostics` prints a redacted
+  summary to paste into a bug report. Nothing is uploaded.
+- A company Outpost can now be given access to a secret. Use its `out_` id:
+  `hq secrets share <path> --with out_…` gives it that one secret, and
+  `hq groups add <group> out_…` lets it read the secrets shared with that
+  group. It gets nothing it was not explicitly given.
+- `hq members list` now shows the company Outpost as a read-only row labeled
+  "Outpost", and `--json` lists it under `outposts`. Promoting, removing or
+  revoking an Outpost is refused with a plain message.
+- `hq lanes create` now prints the new lane's `lane_id` before the list of other lanes it admitted, so a script that takes the first lane id from the output gets the lane it just created. Lane commands that accept a lane id (`hq lanes message`, `hq lanes questions list --from`, `hq lanes watch` and the other lane-target commands) still match the full id first. They now also accept a ULID prefix of 8 or more characters when it names exactly one local lane, and they refuse an ambiguous prefix with an error that lists every matching lane. `hq lanes watch` always prints full lane ids.
+- `hq lanes create --runner subagent` accepts `--provider codex` (and `grok`),
+  so Codex `spawn_agent` work from `/conduct` and `/run-project` shows on the
+  lanes board like Claude `Agent` work. A subagent lane is a board record only;
+  the provider is attribution and no process is started. The
+  `subagent_runner_requires_claude` refusal is gone.
+
 ## [5.345.149] — 2026-10-19
 - `hq access` answers faster. It checks the exact path first and, on a miss,
   looks only in the nearest folder instead of listing the whole vault. It

package/dist/command-catalog.generated.d.ts

@@ -2039,7 +2039,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "share";
-        readonly description: "Share a secret with an email address, group, or the entire company (@all)";
+        readonly description: "Share a secret with an email address, group, company Outpost (out_…), or the entire company (@all)";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -2054,7 +2054,7 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
         readonly options: readonly [{
             readonly flags: "--with <principal>";
-            readonly description: "Email address, group id, or @all (entire company) to share with";
+            readonly description: "Email address, group id, out_ Outpost id, or @all (entire company) to share with";
             readonly hidden: false;
         }, {
             readonly flags: "--permission <level>";
@@ -2079,7 +2079,7 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
         readonly options: readonly [{
             readonly flags: "--from <principal>";
-            readonly description: "Email address, group id, or @all (entire company) to remove";
+            readonly description: "Email address, group id, out_ Outpost id, or @all (entire company) to remove";
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];
@@ -2555,7 +2555,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "add";
-        readonly description: "Add a person or agent to a group (principal: email, personUid, or agentUid)";
+        readonly description: "Add a person, agent, or company Outpost to a group (principal: email, personUid, agentUid, or out_ Outpost id)";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -2577,7 +2577,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "remove";
-        readonly description: "Remove a person or agent from a group (principal: email, personUid, or agentUid)";
+        readonly description: "Remove a person, agent, or company Outpost from a group (principal: email, personUid, agentUid, or out_ Outpost id)";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -7970,6 +7970,18 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--id <outpostId>";
             readonly description: "Outpost id (defaults to your primary box)";
             readonly hidden: false;
+        }, {
+            readonly flags: "--company <slug>";
+            readonly description: "Destroy one of the company's Outposts (owner or admin)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--outpost <name|id>";
+            readonly description: "Which company Outpost, when the company has more than one";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--json";
+            readonly description: "With --company and --yes: print one result object on stdout";
+            readonly hidden: false;
         }, {
             readonly flags: "--yes";
             readonly description: "Confirm the irreversible teardown (required)";
@@ -14367,7 +14379,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }, {
             readonly flags: "--runner <kind>";
-            readonly description: "process (default) | subagent: register a lane an in-session Claude subagent runs; skips admission and starts no process";
+            readonly description: "process (default) | subagent: register a lane an in-session subagent runs (Claude Agent, Codex spawn_agent); skips admission and starts no process";
             readonly hidden: false;
         }, {
             readonly flags: "--remote-control";

package/dist/command-catalog.generated.js

@@ -2446,7 +2446,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "share",
-                "description": "Share a secret with an email address, group, or the entire company (@all)",
+                "description": "Share a secret with an email address, group, company Outpost (out_…), or the entire company (@all)",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -2464,7 +2464,7 @@ export const COMMAND_CATALOG = [
                 "options": [
                     {
                         "flags": "--with <principal>",
-                        "description": "Email address, group id, or @all (entire company) to share with",
+                        "description": "Email address, group id, out_ Outpost id, or @all (entire company) to share with",
                         "hidden": false
                     },
                     {
@@ -2495,7 +2495,7 @@ export const COMMAND_CATALOG = [
                 "options": [
                     {
                         "flags": "--from <principal>",
-                        "description": "Email address, group id, or @all (entire company) to remove",
+                        "description": "Email address, group id, out_ Outpost id, or @all (entire company) to remove",
                         "hidden": false
                     }
                 ],
@@ -3071,7 +3071,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "add",
-                "description": "Add a person or agent to a group (principal: email, personUid, or agentUid)",
+                "description": "Add a person, agent, or company Outpost to a group (principal: email, personUid, agentUid, or out_ Outpost id)",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -3097,7 +3097,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "remove",
-                "description": "Remove a person or agent from a group (principal: email, personUid, or agentUid)",
+                "description": "Remove a person, agent, or company Outpost from a group (principal: email, personUid, agentUid, or out_ Outpost id)",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -9714,6 +9714,21 @@ export const COMMAND_CATALOG = [
                         "description": "Outpost id (defaults to your primary box)",
                         "hidden": false
                     },
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Destroy one of the company's Outposts (owner or admin)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--outpost <name|id>",
+                        "description": "Which company Outpost, when the company has more than one",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "With --company and --yes: print one result object on stdout",
+                        "hidden": false
+                    },
                     {
                         "flags": "--yes",
                         "description": "Confirm the irreversible teardown (required)",
@@ -17472,7 +17487,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--runner <kind>",
-                        "description": "process (default) | subagent: register a lane an in-session Claude subagent runs; skips admission and starts no process",
+                        "description": "process (default) | subagent: register a lane an in-session subagent runs (Claude Agent, Codex spawn_agent); skips admission and starts no process",
                         "hidden": false
                     },
                     {

package/dist/commands/_patterns.d.ts

@@ -1,6 +1,12 @@
 export declare const SECRET_NAME_PATTERN: RegExp;
 export declare const GROUP_ID_PATTERN: RegExp;
 export declare const EMAIL_PATTERN: RegExp;
+/**
+ * A company Outpost identity: `out_` plus a 26-character Crockford ULID, the
+ * same shape hq-pro accepts as an Outpost grantee. It rides the `person`
+ * grantee slot on the wire.
+ */
+export declare const OUTPOST_UID_PATTERN: RegExp;
 /**
  * Keep an ACL pattern exactly as the caller supplied it.
  *

package/dist/commands/_patterns.js

@@ -1,6 +1,12 @@
 export const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]+)*$/;
 export const GROUP_ID_PATTERN = /^grp_[A-Za-z0-9_-]+$/;
 export const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
+/**
+ * A company Outpost identity: `out_` plus a 26-character Crockford ULID, the
+ * same shape hq-pro accepts as an Outpost grantee. It rides the `person`
+ * grantee slot on the wire.
+ */
+export const OUTPOST_UID_PATTERN = /^out_[0-9A-HJKMNP-TV-Z]{26}$/;
 /**
  * Keep an ACL pattern exactly as the caller supplied it.
  *

package/dist/commands/cloud-off-gate.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Sync switch gate for the manual `hq sync push|pull|now` commands
+ * (usage-only-pricing US-016).
+ *
+ * The desktop app's Settings > Sync section has one switch per vault plus one
+ * "Turn off all cloud sync" switch (see `../lib/vault-sync-switches.ts`). The
+ * switches affect only this computer. The app gates its own sync paths, but
+ * skills and scripts call these CLI commands directly (`/handoff`, the
+ * `/startwork` and `/resumework` prefetch, `/delegate`, job remediation). This
+ * gate makes those calls honour the same switches: a command aimed at an off
+ * vault refuses, and an `--all` run skips the off vaults while the rest sync.
+ *
+ * How the target vault is found, before any login or network call:
+ * - `--personal`, or a `prs_*` uid, is the personal vault;
+ * - `--company <ref>`, else the active company in `<hq-root>/.hq/config.json`
+ *   (`activeCompany ?? companySlug`, the same order hq-cloud's resolver uses);
+ * - a `cmp_*` uid is mapped to its slug through `companies/manifest.yaml`
+ *   (`cloud_uid`). A uid that cannot be mapped while any company vault is off
+ *   is refused (fail closed): the gate cannot prove it is not an off vault.
+ * - `--creds-from-stdin`: the target is the parsed EntityContext, checked
+ *   after stdin is read (`refusalForEntity`) and still before any transfer.
+ *
+ * The daemon's own `syncPaused` is not read here: it pauses background sync
+ * only (`hq daemon sync pause`, the tray pause), and a manual push while
+ * background sync is paused is expected to run.
+ */
+import { readVaultSyncSwitches, vaultSkipEnv, type VaultSyncSwitches } from "../lib/vault-sync-switches.js";
+export { readVaultSyncSwitches, vaultSkipEnv, type VaultSyncSwitches };
+/**
+ * Exit code for "skipped because sync is off". Distinct from 1 (sync failed)
+ * so a caller can tell the two apart; every non-zero exit still means "nothing
+ * was synced", which is what `/delegate` and job remediation need to see.
+ */
+export declare const CLOUD_OFF_EXIT_CODE = 3;
+export type GatedSyncCommand = "push" | "pull" | "now";
+/** True when "Turn off all cloud sync" is on. Never throws. */
+export declare function isCloudOff(home?: string): boolean;
+/** True when `company` (a slug) is a company vault whose switch is off. */
+export declare function isCompanyVaultOff(switches: VaultSyncSwitches, company: string): boolean;
+/**
+ * The refusal text when every vault is off. The first line keeps the phrase
+ * "refused immediately": `handoff-sync-prefetch` (shell and native) reports
+ * `skipped` rather than `error:<code>` when the pull log contains it, so
+ * released HQ versions treat this exit as skipped with no script change.
+ */
+export declare function cloudOffMessage(command: GatedSyncCommand): string;
+/** The refusal text when the one vault a command targets is off. */
+export declare function vaultOffMessage(command: GatedSyncCommand, vaultName: string): string;
+/** The refusal text when a company uid cannot be mapped while some vault is off. */
+export declare function unresolvedVaultMessage(command: GatedSyncCommand, ref: string): string;
+/** Which vaults a `push|pull|now` invocation targets. */
+export interface SyncSelection {
+    all?: boolean;
+    /** `true` for `--personal`; `false` is `--no-personal` (only meaningful with `--all`). */
+    personal?: boolean;
+    company?: string;
+    /** Used to find the active company and the uid-to-slug manifest. */
+    hqRoot?: string;
+    /** `--creds-from-stdin`: the target is checked after stdin is parsed. */
+    credsFromStdin?: boolean;
+}
+/** What an `--all` run must leave out. */
+export interface VaultSkips {
+    skipPersonal: boolean;
+    skipCompanies: ReadonlySet<string>;
+}
+/** A refusal: the text, and the vault it names (for JSON output). */
+export interface VaultRefusal {
+    message: string;
+    vault: string;
+}
+/** The vault a company reference or entity uid names. */
+export type ResolvedVault = {
+    kind: "personal";
+} | {
+    kind: "company";
+    slug: string;
+} | {
+    kind: "unknown";
+    ref: string;
+};
+/**
+ * Active company from `<hqRoot>/.hq/config.json`, best effort. Uses
+ * `activeCompany ?? companySlug`, the order hq-cloud's `resolveActiveCompany`
+ * uses, so a config with only `companySlug` is still gated.
+ */
+export declare function readActiveCompanyRef(hqRoot: string | undefined): string | undefined;
+/** Map a slug, `cmp_*` uid or `prs_*` uid to the vault it names. */
+export declare function resolveVaultRef(ref: string, hqRoot: string | undefined): ResolvedVault;
+/**
+ * The refusal for `selection`, or null when it may run. `--all` never
+ * refuses for one vault: it skips the off vaults (see {@link vaultSkips}).
+ * With `--creds-from-stdin` and no `--company`, the target is unknown until
+ * stdin is parsed; {@link refusalForEntity} checks it then.
+ */
+export declare function refusalFor(command: GatedSyncCommand, selection: SyncSelection, switches: VaultSyncSwitches): VaultRefusal | null;
+/**
+ * The refusal for a pre-vended EntityContext read from stdin. A `prs_*` uid
+ * is the personal vault; otherwise the slug (or the uid, through the
+ * manifest) names the company.
+ */
+export declare function refusalForEntity(command: GatedSyncCommand, entity: {
+    uid?: unknown;
+    slug?: unknown;
+}, hqRoot: string | undefined, switches: VaultSyncSwitches): VaultRefusal | null;
+/** The vaults an `--all` run leaves out. */
+export declare function vaultSkips(selection: SyncSelection, switches: VaultSyncSwitches): VaultSkips;
+/** Thrown after stdin is parsed when its target vault is off. */
+export declare class VaultSyncOffError extends Error {
+    readonly refusal: VaultRefusal;
+    constructor(refusal: VaultRefusal);
+}
+export interface CloudOffGateDeps {
+    home?: string;
+    writeErr?: (text: string) => void;
+    exit?: (code: number) => never;
+    /** `--json`: stderr is a JSON Lines stream, so write events, not prose. */
+    json?: boolean;
+}
+/** Write a refusal: plain text, or one JSON Lines event in `--json` mode. */
+export declare function writeVaultRefusal(refusal: VaultRefusal, deps?: Pick<CloudOffGateDeps, "writeErr" | "json">): void;
+/**
+ * Print the refusal and exit {@link CLOUD_OFF_EXIT_CODE} when `selection`
+ * targets an off vault (or every vault is off); otherwise return what an
+ * `--all` run must skip. Runs before any login, lock or network work, and
+ * outside the client-health report, so a refusal is not counted as a failed
+ * sync. Warns when the settings file is unreadable.
+ */
+export declare function refuseSyncForOffVaults(command: GatedSyncCommand, selection: SyncSelection, deps?: CloudOffGateDeps): VaultSkips;
+/**
+ * `--creds-from-stdin` check: throw {@link VaultSyncOffError} when the parsed
+ * EntityContext targets an off vault. The caller writes it and exits 3.
+ */
+export declare function assertEntityVaultSyncAllowed(command: GatedSyncCommand, entity: {
+    uid?: unknown;
+    slug?: unknown;
+}, hqRoot: string | undefined, home?: string): void;
+//# sourceMappingURL=cloud-off-gate.d.ts.map

package/dist/commands/cloud-off-gate.js

@@ -0,0 +1,234 @@
+/**
+ * Sync switch gate for the manual `hq sync push|pull|now` commands
+ * (usage-only-pricing US-016).
+ *
+ * The desktop app's Settings > Sync section has one switch per vault plus one
+ * "Turn off all cloud sync" switch (see `../lib/vault-sync-switches.ts`). The
+ * switches affect only this computer. The app gates its own sync paths, but
+ * skills and scripts call these CLI commands directly (`/handoff`, the
+ * `/startwork` and `/resumework` prefetch, `/delegate`, job remediation). This
+ * gate makes those calls honour the same switches: a command aimed at an off
+ * vault refuses, and an `--all` run skips the off vaults while the rest sync.
+ *
+ * How the target vault is found, before any login or network call:
+ * - `--personal`, or a `prs_*` uid, is the personal vault;
+ * - `--company <ref>`, else the active company in `<hq-root>/.hq/config.json`
+ *   (`activeCompany ?? companySlug`, the same order hq-cloud's resolver uses);
+ * - a `cmp_*` uid is mapped to its slug through `companies/manifest.yaml`
+ *   (`cloud_uid`). A uid that cannot be mapped while any company vault is off
+ *   is refused (fail closed): the gate cannot prove it is not an off vault.
+ * - `--creds-from-stdin`: the target is the parsed EntityContext, checked
+ *   after stdin is read (`refusalForEntity`) and still before any transfer.
+ *
+ * The daemon's own `syncPaused` is not read here: it pauses background sync
+ * only (`hq daemon sync pause`, the tray pause), and a manual push while
+ * background sync is paused is expected to run.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
+import { readVaultSyncSwitches, unreadableSwitchesWarning, vaultSkipEnv, } from "../lib/vault-sync-switches.js";
+export { readVaultSyncSwitches, vaultSkipEnv };
+/**
+ * Exit code for "skipped because sync is off". Distinct from 1 (sync failed)
+ * so a caller can tell the two apart; every non-zero exit still means "nothing
+ * was synced", which is what `/delegate` and job remediation need to see.
+ */
+export const CLOUD_OFF_EXIT_CODE = 3;
+/** True when "Turn off all cloud sync" is on. Never throws. */
+export function isCloudOff(home) {
+    return readVaultSyncSwitches(home).allOff;
+}
+/** True when `company` (a slug) is a company vault whose switch is off. */
+export function isCompanyVaultOff(switches, company) {
+    return switches.offCompanies.has(company.trim().toLowerCase());
+}
+const HOW_TO_TURN_ON = "To turn it back on, open HQ and go to Settings > Sync.";
+const NOTHING_MOVED = "Nothing was uploaded or downloaded. Your local files are unchanged.";
+/**
+ * The refusal text when every vault is off. The first line keeps the phrase
+ * "refused immediately": `handoff-sync-prefetch` (shell and native) reports
+ * `skipped` rather than `error:<code>` when the pull log contains it, so
+ * released HQ versions treat this exit as skipped with no script change.
+ */
+export function cloudOffMessage(command) {
+    return [
+        `Cloud sync is off for every vault on this computer, so \`hq sync ${command}\` was refused immediately.`,
+        NOTHING_MOVED,
+        HOW_TO_TURN_ON,
+    ].join("\n");
+}
+/** The refusal text when the one vault a command targets is off. */
+export function vaultOffMessage(command, vaultName) {
+    return [
+        `Sync is off for ${vaultName} on this computer, so \`hq sync ${command}\` was refused immediately.`,
+        NOTHING_MOVED,
+        HOW_TO_TURN_ON,
+    ].join("\n");
+}
+/** The refusal text when a company uid cannot be mapped while some vault is off. */
+export function unresolvedVaultMessage(command, ref) {
+    return [
+        `Sync is off for one or more company vaults on this computer, and \`hq sync ${command}\` could not tell which vault ${ref} is, so it was refused immediately.`,
+        NOTHING_MOVED,
+        `Run it with --company <slug>, or turn the vaults back on in HQ Settings > Sync.`,
+    ].join("\n");
+}
+const COMPANY_UID = /^cmp_/i;
+const PERSON_UID = /^prs_/i;
+/**
+ * Active company from `<hqRoot>/.hq/config.json`, best effort. Uses
+ * `activeCompany ?? companySlug`, the order hq-cloud's `resolveActiveCompany`
+ * uses, so a config with only `companySlug` is still gated.
+ */
+export function readActiveCompanyRef(hqRoot) {
+    if (!hqRoot)
+        return undefined;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(hqRoot, ".hq", "config.json"), "utf8"));
+        for (const value of [cfg?.activeCompany, cfg?.companySlug]) {
+            if (typeof value === "string" && value.trim())
+                return value.trim();
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Map a slug, `cmp_*` uid or `prs_*` uid to the vault it names. */
+export function resolveVaultRef(ref, hqRoot) {
+    const trimmed = ref.trim();
+    if (PERSON_UID.test(trimmed))
+        return { kind: "personal" };
+    if (!COMPANY_UID.test(trimmed))
+        return { kind: "company", slug: trimmed };
+    const manifest = hqRoot ? readCompaniesManifestMap(hqRoot) : null;
+    for (const [slug, entry] of Object.entries(manifest ?? {})) {
+        const uid = entry?.cloud_uid;
+        if (typeof uid === "string" && uid.toLowerCase() === trimmed.toLowerCase()) {
+            return { kind: "company", slug };
+        }
+    }
+    return { kind: "unknown", ref: trimmed };
+}
+function refusalForVault(command, vault, switches) {
+    switch (vault.kind) {
+        case "personal":
+            return switches.personalOff
+                ? { message: vaultOffMessage(command, "your personal vault"), vault: "personal" }
+                : null;
+        case "company":
+            return isCompanyVaultOff(switches, vault.slug)
+                ? { message: vaultOffMessage(command, vault.slug), vault: vault.slug }
+                : null;
+        case "unknown":
+            // Fail closed: with any company vault off, an unmapped uid may be it.
+            return switches.offCompanies.size > 0
+                ? { message: unresolvedVaultMessage(command, vault.ref), vault: vault.ref }
+                : null;
+    }
+}
+/**
+ * The refusal for `selection`, or null when it may run. `--all` never
+ * refuses for one vault: it skips the off vaults (see {@link vaultSkips}).
+ * With `--creds-from-stdin` and no `--company`, the target is unknown until
+ * stdin is parsed; {@link refusalForEntity} checks it then.
+ */
+export function refusalFor(command, selection, switches) {
+    if (switches.allOff)
+        return { message: cloudOffMessage(command), vault: "all" };
+    if (selection.all)
+        return null;
+    if (selection.personal === true) {
+        return refusalForVault(command, { kind: "personal" }, switches);
+    }
+    const ref = selection.company ?? (selection.credsFromStdin ? undefined : readActiveCompanyRef(selection.hqRoot));
+    if (!ref)
+        return null;
+    return refusalForVault(command, resolveVaultRef(ref, selection.hqRoot), switches);
+}
+/**
+ * The refusal for a pre-vended EntityContext read from stdin. A `prs_*` uid
+ * is the personal vault; otherwise the slug (or the uid, through the
+ * manifest) names the company.
+ */
+export function refusalForEntity(command, entity, hqRoot, switches) {
+    if (switches.allOff)
+        return { message: cloudOffMessage(command), vault: "all" };
+    const uid = typeof entity.uid === "string" ? entity.uid : "";
+    const slug = typeof entity.slug === "string" ? entity.slug : "";
+    if (PERSON_UID.test(uid))
+        return refusalForVault(command, { kind: "personal" }, switches);
+    if (slug.trim())
+        return refusalForVault(command, { kind: "company", slug }, switches);
+    if (uid.trim())
+        return refusalForVault(command, resolveVaultRef(uid, hqRoot), switches);
+    return null;
+}
+/** The vaults an `--all` run leaves out. */
+export function vaultSkips(selection, switches) {
+    return {
+        skipPersonal: selection.personal === false || switches.personalOff,
+        skipCompanies: switches.offCompanies,
+    };
+}
+/** Thrown after stdin is parsed when its target vault is off. */
+export class VaultSyncOffError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(refusal.message);
+        this.refusal = refusal;
+        this.name = "VaultSyncOffError";
+    }
+}
+/** Write a refusal: plain text, or one JSON Lines event in `--json` mode. */
+export function writeVaultRefusal(refusal, deps = {}) {
+    const writeErr = deps.writeErr ?? ((text) => process.stderr.write(text));
+    if (deps.json) {
+        writeErr(`${JSON.stringify({
+            type: "skipped",
+            reason: "sync_off",
+            vault: refusal.vault,
+            exitCode: CLOUD_OFF_EXIT_CODE,
+            message: refusal.message,
+        })}\n`);
+    }
+    else {
+        writeErr(`${refusal.message}\n`);
+    }
+}
+function warnIfUnreadable(switches, deps) {
+    if (!switches.unreadable)
+        return;
+    const writeErr = deps.writeErr ?? ((text) => process.stderr.write(text));
+    const message = unreadableSwitchesWarning(switches.unreadable);
+    writeErr(deps.json ? `${JSON.stringify({ type: "warning", message })}\n` : `${message}\n`);
+}
+/**
+ * Print the refusal and exit {@link CLOUD_OFF_EXIT_CODE} when `selection`
+ * targets an off vault (or every vault is off); otherwise return what an
+ * `--all` run must skip. Runs before any login, lock or network work, and
+ * outside the client-health report, so a refusal is not counted as a failed
+ * sync. Warns when the settings file is unreadable.
+ */
+export function refuseSyncForOffVaults(command, selection, deps = {}) {
+    const switches = readVaultSyncSwitches(deps.home);
+    warnIfUnreadable(switches, deps);
+    const refusal = refusalFor(command, selection, switches);
+    if (refusal) {
+        writeVaultRefusal(refusal, deps);
+        (deps.exit ?? ((code) => process.exit(code)))(CLOUD_OFF_EXIT_CODE);
+    }
+    return vaultSkips(selection, switches);
+}
+/**
+ * `--creds-from-stdin` check: throw {@link VaultSyncOffError} when the parsed
+ * EntityContext targets an off vault. The caller writes it and exits 3.
+ */
+export function assertEntityVaultSyncAllowed(command, entity, hqRoot, home) {
+    const refusal = refusalForEntity(command, entity, hqRoot, readVaultSyncSwitches(home));
+    if (refusal)
+        throw new VaultSyncOffError(refusal);
+}
+//# sourceMappingURL=cloud-off-gate.js.map

package/dist/commands/cloud.d.ts

@@ -196,6 +196,11 @@ export interface PullAllOptions {
      * personal vault from the run without touching the rest of the plan.
      */
     skipPersonal?: boolean;
+    /**
+     * Lowercased company slugs (or uids) to leave out: vaults whose sync is off
+     * on this computer (desktop Settings > Sync, US-016).
+     */
+    skipCompanies?: ReadonlySet<string>;
     /**
      * Forward `--force-scope-shrink` to each company leg: when a scope shrink
      * would un-track locally-modified files, proceed anyway (dirty files KEPT on
@@ -263,6 +268,8 @@ export interface PushAllOptions {
      * `hq sync push --all --no-personal`.
      */
     skipPersonal?: boolean;
+    /** Lowercased company slugs (or uids) to leave out (US-016). */
+    skipCompanies?: ReadonlySet<string>;
 }
 export interface PushAllRow {
     slug: string;