@indigoai-us/hq-cli 5.38.2 → 5.39.2

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [5.39.0]
+
+### Added
+
+- **`hq secrets exists <name>` — HEAD existence probe (HQ-4H).** Checks whether a
+  secret exists without fetching or decrypting its value, so optional-credential
+  readers can HEAD-first instead of blind-`GET`ting:
+  `hq secrets exists FOO && hq secrets get FOO --reveal`. A missing secret no
+  longer fires a spurious server-side `Secret not found` Sentry warning (HQ-4H:
+  706 nameless events / 0 users) — a `HEAD` is by contract an expected-absence
+  probe, so a not-found is its normal answer and is not captured. Exit codes are
+  built for shell chaining: `0` present, `1` absent (the normal "no", not an
+  error), `2` real failure (auth/network/permission) so `&&` chains never
+  mistake an outage for "absent and proceed". `--quiet` suppresses the
+  present/absent line. Backed by the new hq-pro `HEAD
+  /secrets/{companyUid}/name/{proxy+}` route. Callers that genuinely *require* a
+  secret keep `GET`ting directly — their 404s still surface.
+
 ## [5.38.2]
 
 ### Fixed

package/dist/commands/cloud.d.ts

@@ -13,7 +13,7 @@
  *   hq sync status            — show local journal summary
  */
 import { Command } from "commander";
-import { type ConflictStrategy, type MembershipSyncConfig } from "@indigoai-us/hq-cloud";
+import { type ConflictStrategy, type MembershipSyncConfig, type SyncMode, type PullScope, type ExplicitGrant } from "@indigoai-us/hq-cloud";
 import { type BannerLevel } from "../lib/narrow-hint-banner.js";
 export interface PullAllVaultClient {
     listMyMemberships(): Promise<Array<{
@@ -38,6 +38,12 @@ export interface PullAllVaultClient {
      * applicable.
      */
     getMembershipSyncConfig?: (membershipId: string) => Promise<MembershipSyncConfig>;
+    /**
+     * Caller's explicit grants for a company — consumed by `resolvePullScope`
+     * to build a `shared`-mode prefix set. Optional so legacy adapters degrade
+     * to `all` (the safe direction).
+     */
+    listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
 }
 export interface SyncCallOptions {
     company: string;
@@ -45,6 +51,16 @@ export interface SyncCallOptions {
     onConflict?: ConflictStrategy;
     personalMode?: boolean;
     journalSlug?: string;
+    /**
+     * Effective pull scope (DEV-1768). When set, `sync()` materializes only the
+     * in-scope keys and scope-shrinks the rest — instead of defaulting to
+     * `syncMode: "all"` and stamping an all-mode PullRecord that wedges the next
+     * menubar sync. Resolved per-company by the shared `resolvePullScope`.
+     */
+    syncMode?: SyncMode;
+    prefixSet?: string[];
+    /** Honor a `--force-scope-shrink` on a foreground pull (dirty files kept). */
+    forceScopeShrink?: boolean;
 }
 export interface SyncCallResult {
     filesDownloaded: number;
@@ -57,6 +73,13 @@ export interface SyncCallResult {
 export interface PullAllDeps {
     vaultClient: PullAllVaultClient;
     sync: (options: SyncCallOptions) => Promise<SyncCallResult>;
+    /**
+     * Resolve a company's effective pull scope (DEV-1768). Injected so `pullAll`
+     * stays pure/testable; the real entry point wires it to the shared
+     * `resolvePullScope` over a live `VaultClient`. When absent, the per-company
+     * leg falls back to `all` (legacy behavior) — only the real path injects it.
+     */
+    resolveScope?: (companyUid: string, slug: string) => Promise<PullScope>;
 }
 export interface PullAllOptions {
     hqRoot: string;
@@ -88,6 +111,12 @@ export interface PullAllOptions {
      * personal vault from the run without touching the rest of the plan.
      */
     skipPersonal?: boolean;
+    /**
+     * Forward `--force-scope-shrink` to each company leg: when a scope shrink
+     * would un-track locally-modified files, proceed anyway (dirty files KEPT on
+     * disk, only un-tracked). Makes the foreground "block" advice followable.
+     */
+    forceScopeShrink?: boolean;
 }
 export interface PullAllRow {
     slug: string;

package/dist/commands/cloud.js

@@ -13,11 +13,11 @@
  *   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]="1164bdd1-84e4-5bc5-80a8-6888a6f4313c")}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]="59cfec0e-76a2-5beb-8eb6-80a129dd62c6")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
-import { share, sync, getStateDir, listJournals, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, } from "@indigoai-us/hq-cloud";
+import { share, sync, getStateDir, listJournals, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { emitNarrowHint, isStrictRefusal, resolveBannerLevel, } from "../lib/narrow-hint-banner.js";
 /**
@@ -115,14 +115,30 @@ export async function pullAll(options, deps) {
     };
     for (const entry of plan) {
         result.attempted += 1;
-        // US-011: resolve the membership's effective sync mode so we can
-        // either nudge an all-mode owner toward `hq sync narrow` OR refuse
-        // the leg outright when strict-mode is on and the operator didn't
-        // pass `--mode-all`. Sync-config lookup is best-effort — a 404 or
-        // network blip should never block the sync itself, so we fall back
-        // to syncMode='all' (the legacy default) and skip the banner.
+        // Resolve the membership's effective sync scope. DEV-1768: this must drive
+        // the actual pull (mode + prefixSet), not just the narrow-hint banner — the
+        // old code resolved the mode for the banner and then called sync() with NO
+        // scope, so every CLI pull ran `syncMode: "all"` and stamped an all-mode
+        // PullRecord that wedged the next menubar sync (all→shared scope-shrink).
+        // The shared `resolvePullScope` (via deps.resolveScope) degrades to `all`
+        // on any failure, so a transient blip never narrows scope.
         let resolvedMode;
-        if (entry.membershipKey && getSyncConfig) {
+        if (entry.companyUid && deps.resolveScope) {
+            try {
+                const scope = await deps.resolveScope(entry.companyUid, entry.slug);
+                resolvedMode = scope.syncMode;
+                entry.syncOptions.syncMode = scope.syncMode;
+                if (scope.prefixSet !== undefined) {
+                    entry.syncOptions.prefixSet = scope.prefixSet;
+                }
+            }
+            catch {
+                resolvedMode = undefined;
+            }
+        }
+        else if (entry.membershipKey && getSyncConfig) {
+            // Fallback when no scope resolver is injected (legacy/test paths):
+            // banner-only mode resolution, preserving the pre-DEV-1768 behavior.
             try {
                 const cfg = await getSyncConfig(entry.membershipKey);
                 resolvedMode = cfg.syncMode;
@@ -131,6 +147,9 @@ export async function pullAll(options, deps) {
                 resolvedMode = undefined;
             }
         }
+        if (options.forceScopeShrink && entry.companyUid) {
+            entry.syncOptions.forceScopeShrink = true;
+        }
         if (resolvedMode === "all" &&
             isStrictRefusal(resolvedMode, narrowHintLevel) &&
             !options.modeAllOverride &&
@@ -358,6 +377,61 @@ export async function resolvePerCompanyPullPlan(client, targetCompany) {
     }
     return { resolvedCompanyUid: undefined, resolvedMode: undefined };
 }
+/** Read the active company slug/uid from `.hq/config.json` (best-effort). */
+function readActiveCompany(hqRoot) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(hqRoot, ".hq", "config.json"), "utf-8"));
+        return typeof cfg?.activeCompany === "string" ? cfg.activeCompany : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the effective PULL scope (DEV-1768) for a single foreground pull
+ * (`hq sync pull` / `hq sync now`), so the membership's REAL syncMode +
+ * prefixSet are threaded into `sync()`. Without this the CLI ran `syncMode:
+ * "all"` and stamped an all-mode PullRecord that wedged the next menubar sync.
+ *
+ * Delegates to the shared `resolvePullScope` (same resolver the runner uses),
+ * which degrades to `all` on any failure — so a transient blip never narrows
+ * scope. Returns `undefined` only when no company can be resolved at all (then
+ * `sync()` resolves the active company itself and pulls `all`, as before).
+ */
+async function resolveCliPullScope(client, companyRef, hqRoot) {
+    const ref = companyRef ?? readActiveCompany(hqRoot);
+    if (!ref)
+        return undefined;
+    // Map ref (slug OR uid) → { uid, slug }: resolvePullScope needs the slug to
+    // normalize slug-anchored grant paths in shared mode.
+    let companyUid = ref;
+    let slug = ref;
+    try {
+        const memberships = await client.listMyMemberships();
+        const direct = memberships.find((m) => m.companyUid === ref || m.membershipKey === ref);
+        if (direct) {
+            companyUid = direct.companyUid;
+            const ent = await client.entity.get(direct.companyUid).catch(() => null);
+            if (ent?.slug)
+                slug = ent.slug;
+        }
+        else {
+            for (const m of memberships) {
+                const ent = await client.entity.get(m.companyUid).catch(() => null);
+                if (ent?.slug === ref) {
+                    companyUid = m.companyUid;
+                    slug = ent.slug;
+                    break;
+                }
+            }
+        }
+    }
+    catch {
+        // Can't resolve the membership set — degrade to no explicit scope.
+        return undefined;
+    }
+    return resolvePullScope(client, companyUid, slug, hqRoot);
+}
 export function registerCloudCommands(program) {
     program
         .command("push")
@@ -585,6 +659,10 @@ export function registerCloudCommands(program) {
         "Has no effect today (default narrow-hint level is 'hint'); " +
         "wired so future hq-core-staging releases can flip the default to " +
         "'strict' without re-touching this command.")
+        .option("--force-scope-shrink", "When a scope shrink would un-track locally-modified files (e.g. after " +
+        "narrowing from all → shared), proceed anyway. Dirty files are KEPT on " +
+        "disk and only un-tracked from sync; clean out-of-scope files are " +
+        "quarantined under .hq/scope-quarantine/ (recoverable).")
         .action(async (options) => {
         try {
             assertSingleSelector(options, "pull");
@@ -597,7 +675,7 @@ export function registerCloudCommands(program) {
             // `options.personal === false` is Commander's auto-negation of
             // `--personal`; in `--all` mode that means "drop the personal
             // leg from the fanout" (see `--no-personal` option above).
-            await runPullAll(options.hqRoot, options.onConflict, options.modeAll === true, options.personal === false);
+            await runPullAll(options.hqRoot, options.onConflict, options.modeAll === true, options.personal === false, options.forceScopeShrink === true);
             return;
         }
         if (options.personal) {
@@ -617,7 +695,12 @@ export function registerCloudCommands(program) {
             // paths. Failure to resolve degrades silently — pull still works,
             // banner just stays quiet (same as the catch in runPullAll).
             const narrowHintLevel = resolveBannerLevel();
-            const { resolvedCompanyUid, resolvedMode } = await resolvePerCompanyPullPlan(new VaultClient(vaultConfig), options.company);
+            const pullClient = new VaultClient(vaultConfig);
+            const { resolvedCompanyUid, resolvedMode } = await resolvePerCompanyPullPlan(pullClient, options.company);
+            // DEV-1768: resolve the REAL effective scope (mode + prefixSet) and
+            // thread it into the pull below — not just the banner. Best-effort;
+            // degrades to "all" inside the resolver on any failure.
+            const pullScope = await resolveCliPullScope(pullClient, options.company, options.hqRoot);
             // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
             // Default banner level is 'hint' which never triggers refusal —
             // wired now so future hq-core-staging releases can flip the
@@ -641,6 +724,13 @@ export function registerCloudCommands(program) {
                 onConflict: options.onConflict,
                 vaultConfig,
                 hqRoot: options.hqRoot,
+                ...(pullScope?.syncMode !== undefined
+                    ? { syncMode: pullScope.syncMode }
+                    : {}),
+                ...(pullScope?.prefixSet !== undefined
+                    ? { prefixSet: pullScope.prefixSet }
+                    : {}),
+                ...(options.forceScopeShrink ? { forceScopeShrink: true } : {}),
             });
             if (result.aborted) {
                 console.log(chalk.yellow(`\n⚠ Pull aborted (${result.filesDownloaded} downloaded, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
@@ -756,6 +846,9 @@ export function registerCloudCommands(program) {
         .option("--mode-all", "US-011: opt out of the strict narrow-hint refusal for this run. " +
         "No-op today; wired so future hq-core-staging releases can flip " +
         "the default narrow-hint level to 'strict'.")
+        .option("--force-scope-shrink", "When a scope shrink would un-track locally-modified files, proceed " +
+        "anyway. Dirty files are KEPT on disk (only un-tracked); clean " +
+        "out-of-scope files are quarantined under .hq/scope-quarantine/.")
         .action(async (options) => {
         try {
             assertSingleSelector(options, "now");
@@ -764,10 +857,10 @@ export function registerCloudCommands(program) {
                 // of `--personal`; in `--all` mode that means "drop the
                 // personal leg from both legs of the bidirectional fanout"
                 // (see `--no-personal` option above).
-                await runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true, options.personal === false);
+                await runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true, options.personal === false, options.forceScopeShrink === true);
                 return;
             }
-            await runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true);
+            await runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true, options.forceScopeShrink === true);
         }
         catch (err) {
             console.error(chalk.red("\n✗ Sync now failed:"), err instanceof Error ? err.message : String(err));
@@ -775,7 +868,7 @@ export function registerCloudCommands(program) {
         }
     });
 }
-async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal) {
+async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, forceScopeShrink) {
     console.log(chalk.bold("\nHQ Sync — Pull (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
@@ -800,6 +893,7 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal) {
                 }
             },
             getMembershipSyncConfig: (id) => realClient.getMembershipSyncConfig(id),
+            listMyExplicitGrants: (companyUid) => realClient.listMyExplicitGrants(companyUid),
         };
         result = await pullAll({
             hqRoot,
@@ -807,8 +901,13 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal) {
             narrowHintLevel: resolveBannerLevel(),
             ...(modeAllOverride ? { modeAllOverride: true } : {}),
             ...(skipPersonal ? { skipPersonal: true } : {}),
+            ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
         }, {
             vaultClient: adapter,
+            // DEV-1768: resolve each company's REAL pull scope (mode + prefixSet)
+            // via the shared resolver, so the actual pull is scoped — the CLI no
+            // longer seeds an all-mode PullRecord that wedges the menubar runner.
+            resolveScope: (companyUid, slug) => resolvePullScope(realClient, companyUid, slug, hqRoot),
             sync: (opts) => sync({
                 company: opts.company,
                 hqRoot: opts.hqRoot,
@@ -820,6 +919,9 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal) {
                 ...(opts.journalSlug !== undefined
                     ? { journalSlug: opts.journalSlug }
                     : {}),
+                ...(opts.syncMode !== undefined ? { syncMode: opts.syncMode } : {}),
+                ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
+                ...(opts.forceScopeShrink ? { forceScopeShrink: true } : {}),
             }),
         });
     }
@@ -964,7 +1066,7 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
     if (errored > 0)
         process.exit(1);
 }
-async function runNowSingle(hqRoot, company, personal, message, onConflict, modeAllOverride) {
+async function runNowSingle(hqRoot, company, personal, message, onConflict, modeAllOverride, forceScopeShrink) {
     console.log(chalk.bold("\nHQ Sync — Now"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Target:   ${personal ? "(personal)" : (company ?? "(active company)")}`);
@@ -1073,6 +1175,18 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
                 "to migrate, or re-run with --mode-all."));
             process.exit(1);
         }
+        // DEV-1768: resolve the membership's real scope and thread it into the
+        // pull leg, so `hq sync now` stops seeding all-mode PullRecords. Personal
+        // targets have no membership scope — they stay full ("all").
+        let pullScope;
+        if (!personalMode) {
+            try {
+                pullScope = await resolveCliPullScope(new VaultClient(vaultConfig), targetCompany, hqRoot);
+            }
+            catch {
+                pullScope = undefined;
+            }
+        }
         console.log(chalk.dim("  → pull leg"));
         const pullResult = await sync({
             company: targetCompany,
@@ -1081,6 +1195,13 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             ...(onConflict ? { onConflict } : {}),
             ...(personalMode ? { personalMode: true } : {}),
             ...(journalSlug !== undefined ? { journalSlug } : {}),
+            ...(pullScope?.syncMode !== undefined
+                ? { syncMode: pullScope.syncMode }
+                : {}),
+            ...(pullScope?.prefixSet !== undefined
+                ? { prefixSet: pullScope.prefixSet }
+                : {}),
+            ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
         });
         console.log(`    ${pullResult.aborted ? chalk.yellow("⚠") : chalk.green("✓")} ` +
             `${pullResult.filesDownloaded} downloaded, ${pullResult.filesSkipped} skipped, ` +
@@ -1106,7 +1227,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         process.exit(1);
     }
 }
-async function runNowAll(hqRoot, message, onConflict, modeAllOverride, skipPersonal) {
+async function runNowAll(hqRoot, message, onConflict, modeAllOverride, skipPersonal, forceScopeShrink) {
     console.log(chalk.bold("\nHQ Sync — Now (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
@@ -1123,7 +1244,7 @@ async function runNowAll(hqRoot, message, onConflict, modeAllOverride, skipPerso
     // US-011: forward --mode-all so the strict refusal applies to the
     // pull leg (push doesn't need a narrow-hint — the narrow ritual is
     // pull-side).
-    await runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal);
+    await runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, forceScopeShrink);
 }
 /**
  * Best-effort read of the active company slug from `<hqRoot>/.hq/config.json`.
@@ -1209,4 +1330,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=1164bdd1-84e4-5bc5-80a8-6888a6f4313c
+//# debugId=59cfec0e-76a2-5beb-8eb6-80a129dd62c6

package/dist/commands/secrets.js

@@ -1,5 +1,5 @@
 
-!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]="b75c8495-7e0e-53f8-a0d2-c92a993e6492")}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]="7e988c72-7dae-5ad2-aaa3-2c5b430fa5ae")}catch(e){}}();
 import chalk from "chalk";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
@@ -227,6 +227,48 @@ export function registerSecretsCommand(program) {
             process.exit(1);
         }
     });
+    // HQ-4H: existence probe via the HEAD route. Optional-credential readers
+    // should HEAD-first so a missing secret no longer fires a spurious GET-404
+    // Sentry warning server-side: `hq secrets exists FOO && hq secrets get FOO …`.
+    // A HEAD never decrypts or reveals the value.
+    //
+    // Exit codes are designed for shell chaining:
+    //   0 → secret exists (200)
+    //   1 → secret is absent (404) — the normal "no" answer, NOT an error
+    //   2 → a real failure (auth/network/permission) — distinct from absence so
+    //       `&&` chains don't mistake an outage for "absent and proceed"
+    secrets
+        .command("exists <name>")
+        .description("Check whether a secret exists (HEAD; exit 0=present, 1=absent, 2=error)")
+        .option("--quiet", "Suppress the present/absent line (use the exit code only)")
+        .action(async (name, opts) => {
+        try {
+            const token = await ensureCognitoToken();
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const res = await vaultApiFetch({
+                token,
+                method: "HEAD",
+                path: buildSecretNamePath(companyUid, name),
+            });
+            if (res.status === 200) {
+                if (!opts.quiet)
+                    console.log(chalk.green(`exists: ${name}`));
+                process.exit(0);
+            }
+            if (res.status === 404) {
+                if (!opts.quiet)
+                    console.log(chalk.dim(`absent: ${name}`));
+                process.exit(1);
+            }
+            // Any other status (401/403/5xx) is a real failure, not an absence.
+            console.error(chalk.red(`Failed to check secret '${name}': HTTP ${res.status} ${res.statusText}`));
+            process.exit(2);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(2);
+        }
+    });
     secrets
         .command("list")
         .description("List all secrets for the company (including nested path-based names)")
@@ -712,4 +754,4 @@ export function registerSecretsCommand(program) {
     });
 }
 //# sourceMappingURL=secrets.js.map
-//# debugId=b75c8495-7e0e-53f8-a0d2-c92a993e6492
+//# debugId=7e988c72-7dae-5ad2-aaa3-2c5b430fa5ae

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.38.2",
+  "version": "5.39.2",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.5.0",
+    "@indigoai-us/hq-cloud": "^6.6.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

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

@@ -154,6 +154,70 @@ describe("pullAll", () => {
     ]);
   });
 
+  // ── 1b. DEV-1768: real scope is threaded into the actual pull ─────────────
+
+  it("threads the resolved syncMode + prefixSet into sync() (no all-mode seed)", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_a" }],
+      entitiesBySlug: { cmp_a: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+    const resolveScope = vi.fn(async (_uid: string, _slug: string) => ({
+      syncMode: "shared" as const,
+      prefixSet: ["knowledge/", "policies/"],
+    }));
+
+    await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn, resolveScope },
+    );
+
+    // Resolver invoked with the company's UID + resolved slug.
+    expect(resolveScope).toHaveBeenCalledWith("cmp_a", "acme");
+    // ...and the result is forwarded to the ACTUAL pull, not just the banner.
+    const companyCall = sync.calls.find((c) => c.company === "cmp_a");
+    expect(companyCall?.syncMode).toBe("shared");
+    expect(companyCall?.prefixSet).toEqual(["knowledge/", "policies/"]);
+  });
+
+  it("passes no prefixSet for an all-mode membership (full pull preserved)", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_a" }],
+      entitiesBySlug: { cmp_a: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+    const resolveScope = vi.fn(async () => ({ syncMode: "all" as const }));
+
+    await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn, resolveScope },
+    );
+
+    const companyCall = sync.calls.find((c) => c.company === "cmp_a");
+    expect(companyCall?.syncMode).toBe("all");
+    expect(companyCall?.prefixSet).toBeUndefined();
+  });
+
+  it("forwards forceScopeShrink to company legs when set", 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", forceScopeShrink: true },
+      { vaultClient, sync: sync.fn, resolveScope },
+    );
+
+    const companyCall = sync.calls.find((c) => c.company === "cmp_a");
+    expect(companyCall?.forceScopeShrink).toBe(true);
+  });
+
   // ── 2. Conflict strategy passthrough ──────────────────────────────────────
 
   it("forwards --on-conflict to every sync() call", async () => {

package/src/commands/cloud.ts

@@ -27,9 +27,13 @@ import {
   VaultClient,
   computePersonalVaultPaths,
   PERSONAL_VAULT_JOURNAL_SLUG,
+  resolvePullScope,
   type ConflictStrategy,
   type EntityContext,
   type MembershipSyncConfig,
+  type SyncMode,
+  type PullScope,
+  type ExplicitGrant,
   type SyncProgressEvent,
   type UploadAuthor,
 } from "@indigoai-us/hq-cloud";
@@ -111,6 +115,12 @@ export interface PullAllVaultClient {
   getMembershipSyncConfig?: (
     membershipId: string,
   ) => Promise<MembershipSyncConfig>;
+  /**
+   * Caller's explicit grants for a company — consumed by `resolvePullScope`
+   * to build a `shared`-mode prefix set. Optional so legacy adapters degrade
+   * to `all` (the safe direction).
+   */
+  listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
 }
 
 export interface SyncCallOptions {
@@ -119,6 +129,16 @@ export interface SyncCallOptions {
   onConflict?: ConflictStrategy;
   personalMode?: boolean;
   journalSlug?: string;
+  /**
+   * Effective pull scope (DEV-1768). When set, `sync()` materializes only the
+   * in-scope keys and scope-shrinks the rest — instead of defaulting to
+   * `syncMode: "all"` and stamping an all-mode PullRecord that wedges the next
+   * menubar sync. Resolved per-company by the shared `resolvePullScope`.
+   */
+  syncMode?: SyncMode;
+  prefixSet?: string[];
+  /** Honor a `--force-scope-shrink` on a foreground pull (dirty files kept). */
+  forceScopeShrink?: boolean;
 }
 
 export interface SyncCallResult {
@@ -133,6 +153,13 @@ export interface SyncCallResult {
 export interface PullAllDeps {
   vaultClient: PullAllVaultClient;
   sync: (options: SyncCallOptions) => Promise<SyncCallResult>;
+  /**
+   * Resolve a company's effective pull scope (DEV-1768). Injected so `pullAll`
+   * stays pure/testable; the real entry point wires it to the shared
+   * `resolvePullScope` over a live `VaultClient`. When absent, the per-company
+   * leg falls back to `all` (legacy behavior) — only the real path injects it.
+   */
+  resolveScope?: (companyUid: string, slug: string) => Promise<PullScope>;
 }
 
 export interface PullAllOptions {
@@ -165,6 +192,12 @@ export interface PullAllOptions {
    * personal vault from the run without touching the rest of the plan.
    */
   skipPersonal?: boolean;
+  /**
+   * Forward `--force-scope-shrink` to each company leg: when a scope shrink
+   * would un-track locally-modified files, proceed anyway (dirty files KEPT on
+   * disk, only un-tracked). Makes the foreground "block" advice followable.
+   */
+  forceScopeShrink?: boolean;
 }
 
 export interface PullAllRow {
@@ -331,14 +364,28 @@ export async function pullAll(
   for (const entry of plan) {
     result.attempted += 1;
 
-    // US-011: resolve the membership's effective sync mode so we can
-    // either nudge an all-mode owner toward `hq sync narrow` OR refuse
-    // the leg outright when strict-mode is on and the operator didn't
-    // pass `--mode-all`. Sync-config lookup is best-effort — a 404 or
-    // network blip should never block the sync itself, so we fall back
-    // to syncMode='all' (the legacy default) and skip the banner.
+    // Resolve the membership's effective sync scope. DEV-1768: this must drive
+    // the actual pull (mode + prefixSet), not just the narrow-hint banner — the
+    // old code resolved the mode for the banner and then called sync() with NO
+    // scope, so every CLI pull ran `syncMode: "all"` and stamped an all-mode
+    // PullRecord that wedged the next menubar sync (all→shared scope-shrink).
+    // The shared `resolvePullScope` (via deps.resolveScope) degrades to `all`
+    // on any failure, so a transient blip never narrows scope.
     let resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
-    if (entry.membershipKey && getSyncConfig) {
+    if (entry.companyUid && deps.resolveScope) {
+      try {
+        const scope = await deps.resolveScope(entry.companyUid, entry.slug);
+        resolvedMode = scope.syncMode;
+        entry.syncOptions.syncMode = scope.syncMode;
+        if (scope.prefixSet !== undefined) {
+          entry.syncOptions.prefixSet = scope.prefixSet;
+        }
+      } catch {
+        resolvedMode = undefined;
+      }
+    } else if (entry.membershipKey && getSyncConfig) {
+      // Fallback when no scope resolver is injected (legacy/test paths):
+      // banner-only mode resolution, preserving the pre-DEV-1768 behavior.
       try {
         const cfg = await getSyncConfig(entry.membershipKey);
         resolvedMode = cfg.syncMode;
@@ -346,6 +393,9 @@ export async function pullAll(
         resolvedMode = undefined;
       }
     }
+    if (options.forceScopeShrink && entry.companyUid) {
+      entry.syncOptions.forceScopeShrink = true;
+    }
 
     if (
       resolvedMode === "all" &&
@@ -637,6 +687,66 @@ export async function resolvePerCompanyPullPlan(
   return { resolvedCompanyUid: undefined, resolvedMode: undefined };
 }
 
+/** Read the active company slug/uid from `.hq/config.json` (best-effort). */
+function readActiveCompany(hqRoot: string): string | undefined {
+  try {
+    const cfg = JSON.parse(
+      fs.readFileSync(path.join(hqRoot, ".hq", "config.json"), "utf-8"),
+    ) as { activeCompany?: unknown };
+    return typeof cfg?.activeCompany === "string" ? cfg.activeCompany : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the effective PULL scope (DEV-1768) for a single foreground pull
+ * (`hq sync pull` / `hq sync now`), so the membership's REAL syncMode +
+ * prefixSet are threaded into `sync()`. Without this the CLI ran `syncMode:
+ * "all"` and stamped an all-mode PullRecord that wedged the next menubar sync.
+ *
+ * Delegates to the shared `resolvePullScope` (same resolver the runner uses),
+ * which degrades to `all` on any failure — so a transient blip never narrows
+ * scope. Returns `undefined` only when no company can be resolved at all (then
+ * `sync()` resolves the active company itself and pulls `all`, as before).
+ */
+async function resolveCliPullScope(
+  client: VaultClient,
+  companyRef: string | undefined,
+  hqRoot: string,
+): Promise<PullScope | undefined> {
+  const ref = companyRef ?? readActiveCompany(hqRoot);
+  if (!ref) return undefined;
+  // Map ref (slug OR uid) → { uid, slug }: resolvePullScope needs the slug to
+  // normalize slug-anchored grant paths in shared mode.
+  let companyUid = ref;
+  let slug = ref;
+  try {
+    const memberships = await client.listMyMemberships();
+    const direct = memberships.find(
+      (m) => m.companyUid === ref || m.membershipKey === ref,
+    );
+    if (direct) {
+      companyUid = direct.companyUid;
+      const ent = await client.entity.get(direct.companyUid).catch(() => null);
+      if (ent?.slug) slug = ent.slug;
+    } else {
+      for (const m of memberships) {
+        const ent = await client.entity.get(m.companyUid).catch(() => null);
+        if (ent?.slug === ref) {
+          companyUid = m.companyUid;
+          slug = ent.slug;
+          break;
+        }
+      }
+    }
+  } catch {
+    // Can't resolve the membership set — degrade to no explicit scope.
+    return undefined;
+  }
+  return resolvePullScope(client, companyUid, slug, hqRoot);
+}
+
 export function registerCloudCommands(program: Command): void {
   program
     .command("push")
@@ -970,6 +1080,13 @@ export function registerCloudCommands(program: Command): void {
         "wired so future hq-core-staging releases can flip the default to " +
         "'strict' without re-touching this command.",
     )
+    .option(
+      "--force-scope-shrink",
+      "When a scope shrink would un-track locally-modified files (e.g. after " +
+        "narrowing from all → shared), proceed anyway. Dirty files are KEPT on " +
+        "disk and only un-tracked from sync; clean out-of-scope files are " +
+        "quarantined under .hq/scope-quarantine/ (recoverable).",
+    )
     .action(
       async (
         options: CommonSyncOptions & {
@@ -977,6 +1094,7 @@ export function registerCloudCommands(program: Command): void {
           all?: boolean;
           personal?: boolean;
           modeAll?: boolean;
+          forceScopeShrink?: boolean;
         },
       ) => {
         try {
@@ -997,6 +1115,7 @@ export function registerCloudCommands(program: Command): void {
             options.onConflict,
             options.modeAll === true,
             options.personal === false,
+            options.forceScopeShrink === true,
           );
           return;
         }
@@ -1019,11 +1138,17 @@ export function registerCloudCommands(program: Command): void {
           // paths. Failure to resolve degrades silently — pull still works,
           // banner just stays quiet (same as the catch in runPullAll).
           const narrowHintLevel: BannerLevel = resolveBannerLevel();
+          const pullClient = new VaultClient(vaultConfig);
           const { resolvedCompanyUid, resolvedMode } =
-            await resolvePerCompanyPullPlan(
-              new VaultClient(vaultConfig),
-              options.company,
-            );
+            await resolvePerCompanyPullPlan(pullClient, options.company);
+          // DEV-1768: resolve the REAL effective scope (mode + prefixSet) and
+          // thread it into the pull below — not just the banner. Best-effort;
+          // degrades to "all" inside the resolver on any failure.
+          const pullScope = await resolveCliPullScope(
+            pullClient,
+            options.company,
+            options.hqRoot,
+          );
 
           // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
           // Default banner level is 'hint' which never triggers refusal —
@@ -1055,6 +1180,13 @@ export function registerCloudCommands(program: Command): void {
             onConflict: options.onConflict,
             vaultConfig,
             hqRoot: options.hqRoot,
+            ...(pullScope?.syncMode !== undefined
+              ? { syncMode: pullScope.syncMode }
+              : {}),
+            ...(pullScope?.prefixSet !== undefined
+              ? { prefixSet: pullScope.prefixSet }
+              : {}),
+            ...(options.forceScopeShrink ? { forceScopeShrink: true } : {}),
           });
 
           if (result.aborted) {
@@ -1236,6 +1368,12 @@ export function registerCloudCommands(program: Command): void {
         "No-op today; wired so future hq-core-staging releases can flip " +
         "the default narrow-hint level to 'strict'.",
     )
+    .option(
+      "--force-scope-shrink",
+      "When a scope shrink would un-track locally-modified files, proceed " +
+        "anyway. Dirty files are KEPT on disk (only un-tracked); clean " +
+        "out-of-scope files are quarantined under .hq/scope-quarantine/.",
+    )
     .action(
       async (
         options: CommonSyncOptions & {
@@ -1244,6 +1382,7 @@ export function registerCloudCommands(program: Command): void {
           all?: boolean;
           personal?: boolean;
           modeAll?: boolean;
+          forceScopeShrink?: boolean;
         },
       ) => {
         try {
@@ -1259,6 +1398,7 @@ export function registerCloudCommands(program: Command): void {
               options.onConflict,
               options.modeAll === true,
               options.personal === false,
+              options.forceScopeShrink === true,
             );
             return;
           }
@@ -1269,6 +1409,7 @@ export function registerCloudCommands(program: Command): void {
             options.message,
             options.onConflict,
             options.modeAll === true,
+            options.forceScopeShrink === true,
           );
         } catch (err) {
           console.error(
@@ -1286,6 +1427,7 @@ async function runPullAll(
   onConflict?: ConflictStrategy,
   modeAllOverride?: boolean,
   skipPersonal?: boolean,
+  forceScopeShrink?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Pull (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
@@ -1313,6 +1455,8 @@ async function runPullAll(
       },
       getMembershipSyncConfig: (id: string) =>
         realClient.getMembershipSyncConfig(id),
+      listMyExplicitGrants: (companyUid: string) =>
+        realClient.listMyExplicitGrants(companyUid),
     };
 
     result = await pullAll(
@@ -1322,9 +1466,15 @@ async function runPullAll(
         narrowHintLevel: resolveBannerLevel(),
         ...(modeAllOverride ? { modeAllOverride: true } : {}),
         ...(skipPersonal ? { skipPersonal: true } : {}),
+        ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
       },
       {
         vaultClient: adapter,
+        // DEV-1768: resolve each company's REAL pull scope (mode + prefixSet)
+        // via the shared resolver, so the actual pull is scoped — the CLI no
+        // longer seeds an all-mode PullRecord that wedges the menubar runner.
+        resolveScope: (companyUid: string, slug: string) =>
+          resolvePullScope(realClient, companyUid, slug, hqRoot),
         sync: (opts) =>
           sync({
             company: opts.company,
@@ -1337,6 +1487,9 @@ async function runPullAll(
             ...(opts.journalSlug !== undefined
               ? { journalSlug: opts.journalSlug }
               : {}),
+            ...(opts.syncMode !== undefined ? { syncMode: opts.syncMode } : {}),
+            ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
+            ...(opts.forceScopeShrink ? { forceScopeShrink: true } : {}),
           }),
       },
     );
@@ -1530,6 +1683,7 @@ async function runNowSingle(
   message?: string,
   onConflict?: ConflictStrategy,
   modeAllOverride?: boolean,
+  forceScopeShrink?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Now"));
   console.log(`  HQ root:  ${hqRoot}`);
@@ -1657,6 +1811,22 @@ async function runNowSingle(
       process.exit(1);
     }
 
+    // DEV-1768: resolve the membership's real scope and thread it into the
+    // pull leg, so `hq sync now` stops seeding all-mode PullRecords. Personal
+    // targets have no membership scope — they stay full ("all").
+    let pullScope: PullScope | undefined;
+    if (!personalMode) {
+      try {
+        pullScope = await resolveCliPullScope(
+          new VaultClient(vaultConfig),
+          targetCompany,
+          hqRoot,
+        );
+      } catch {
+        pullScope = undefined;
+      }
+    }
+
     console.log(chalk.dim("  → pull leg"));
     const pullResult = await sync({
       company: targetCompany,
@@ -1665,6 +1835,13 @@ async function runNowSingle(
       ...(onConflict ? { onConflict } : {}),
       ...(personalMode ? { personalMode: true } : {}),
       ...(journalSlug !== undefined ? { journalSlug } : {}),
+      ...(pullScope?.syncMode !== undefined
+        ? { syncMode: pullScope.syncMode }
+        : {}),
+      ...(pullScope?.prefixSet !== undefined
+        ? { prefixSet: pullScope.prefixSet }
+        : {}),
+      ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
     });
     console.log(
       `    ${pullResult.aborted ? chalk.yellow("⚠") : chalk.green("✓")} ` +
@@ -1704,6 +1881,7 @@ async function runNowAll(
   onConflict?: ConflictStrategy,
   modeAllOverride?: boolean,
   skipPersonal?: boolean,
+  forceScopeShrink?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Now (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
@@ -1722,7 +1900,13 @@ async function runNowAll(
   // US-011: forward --mode-all so the strict refusal applies to the
   // pull leg (push doesn't need a narrow-hint — the narrow ritual is
   // pull-side).
-  await runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal);
+  await runPullAll(
+    hqRoot,
+    onConflict,
+    modeAllOverride,
+    skipPersonal,
+    forceScopeShrink,
+  );
 }
 
 /**

package/src/commands/secrets.test.ts

@@ -62,6 +62,71 @@ function buildProgram(): Command {
   return program;
 }
 
+// HQ-4H: `hq secrets exists` — HEAD existence probe with shell-chaining exit
+// codes (0=present, 1=absent, 2=error). process.exit is spied so the command's
+// terminal exit doesn't kill the runner; we assert the code it requested.
+describe("secrets exists (HQ-4H HEAD probe)", () => {
+  let exitSpy: MockInstance<typeof process.exit>;
+
+  beforeEach(() => {
+    // Throw so the command stops at its first process.exit (the real runtime
+    // terminates there). The action's own try/catch re-invokes exit(2) on the
+    // thrown sentinel, so we assert on the FIRST recorded exit code — the one
+    // the command actually intended — not the last.
+    exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("__exit__");
+    }) as never);
+  });
+
+  async function firstExitCode(name: string): Promise<number | undefined> {
+    const program = buildProgram();
+    try {
+      await program.parseAsync(["node", "hq", "secrets", "exists", name]);
+    } catch {
+      // sentinel(s) from the exit spy
+    }
+    return exitSpy.mock.calls[0]?.[0] as number | undefined;
+  }
+
+  it("issues a HEAD and intends exit 0 when the secret exists (200)", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response(null, { status: 200 }),
+    );
+
+    const code = await firstExitCode("MY_KEY");
+
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      method: "HEAD",
+      path: "/secrets/prs_alice/name/MY_KEY",
+    });
+    expect(code).toBe(0);
+  });
+
+  it("intends exit 1 (absent, not an error) on 404", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ error: "Secret not found", name: "MISSING" }),
+        { status: 404, headers: { "Content-Type": "application/json" } },
+      ),
+    );
+
+    const code = await firstExitCode("MISSING");
+
+    expect(code).toBe(1);
+  });
+
+  it("intends exit 2 (real failure, distinct from absence) on a 5xx", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response("boom", { status: 503 }),
+    );
+
+    const code = await firstExitCode("MY_KEY");
+
+    expect(code).toBe(2);
+  });
+});
+
 describe("secrets generate-link", () => {
   it("mints one-time submission links for personal secrets", async () => {
     const program = buildProgram();

package/src/commands/secrets.ts

@@ -294,6 +294,58 @@ export function registerSecretsCommand(program: Command): void {
       }
     });
 
+  // HQ-4H: existence probe via the HEAD route. Optional-credential readers
+  // should HEAD-first so a missing secret no longer fires a spurious GET-404
+  // Sentry warning server-side: `hq secrets exists FOO && hq secrets get FOO …`.
+  // A HEAD never decrypts or reveals the value.
+  //
+  // Exit codes are designed for shell chaining:
+  //   0 → secret exists (200)
+  //   1 → secret is absent (404) — the normal "no" answer, NOT an error
+  //   2 → a real failure (auth/network/permission) — distinct from absence so
+  //       `&&` chains don't mistake an outage for "absent and proceed"
+  secrets
+    .command("exists <name>")
+    .description("Check whether a secret exists (HEAD; exit 0=present, 1=absent, 2=error)")
+    .option("--quiet", "Suppress the present/absent line (use the exit code only)")
+    .action(async (name: string, opts: { quiet?: boolean }) => {
+      try {
+        const token = await ensureCognitoToken();
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
+
+        const res = await vaultApiFetch({
+          token,
+          method: "HEAD",
+          path: buildSecretNamePath(companyUid, name),
+        });
+
+        if (res.status === 200) {
+          if (!opts.quiet) console.log(chalk.green(`exists: ${name}`));
+          process.exit(0);
+        }
+        if (res.status === 404) {
+          if (!opts.quiet) console.log(chalk.dim(`absent: ${name}`));
+          process.exit(1);
+        }
+        // Any other status (401/403/5xx) is a real failure, not an absence.
+        console.error(
+          chalk.red(
+            `Failed to check secret '${name}': HTTP ${res.status} ${res.statusText}`,
+          ),
+        );
+        process.exit(2);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(2);
+      }
+    });
+
   secrets
     .command("list")
     .description("List all secrets for the company (including nested path-based names)")