@indigoai-us/hq-cloud 6.5.0 → 6.7.0

package/src/bin/sync-runner.ts

@@ -76,7 +76,11 @@ import {
   type ExplicitGrant,
 } from "../index.js";
 import { pickCanonicalPersonEntity } from "../vault-client.js";
-import { coalescePrefixes, grantPathToPrefix } from "../prefix-coalesce.js";
+import {
+  resolvePullScope,
+  readPinnedPrefixes,
+  type PullScope,
+} from "../sync/pull-scope.js";
 import {
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
   computePersonalVaultPaths,
@@ -401,121 +405,13 @@ export interface VaultClientSurface {
   listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
 }
 
-/**
- * Effective download scope for one company leg (US-005). Resolved per company
- * just before its pull, then handed to `sync()` as `{ syncMode, prefixSet }`.
- */
-export interface PullScope {
-  syncMode: SyncMode;
-  /** Coalesced company-relative prefixes; omitted/undefined for `all`. */
-  prefixSet?: string[];
-}
-
-/**
- * Resolve the effective download scope for a company target.
- *
- *   - `all`    → no prefix set; full-bucket pull (legacy behavior).
- *   - `shared` → coalesced caller explicit grants (company-relative paths,
- *                same namespace as `RemoteFile.key`).
- *   - `custom` → coalesced `customPaths` from the sync-config row.
- *
- * DEGRADE-TO-`all` CONTRACT: any failure (missing client method, membership
- * not found, network error, grant fetch error) returns `{ syncMode: "all" }`.
- * A transient failure must NEVER silently narrow scope — that would prune the
- * local tree. Mirrors the CLI's `resolvePerCompanyPullPlan` degrade behavior.
- */
-export async function resolvePullScope(
-  client: VaultClientSurface,
-  companyUid: string,
-  // Company slug — required to normalize grant paths (which may be anchored
-  // at `companies/<slug>/` or `<slug>/`) into the company-relative namespace.
-  slug: string,
-  // Local HQ root — used to read the per-machine pin set (`.hq/pins.json`).
-  // When omitted, pins are simply not unioned (no behavior change).
-  hqRoot?: string,
-): Promise<PullScope> {
-  if (!client.getMembershipSyncConfig) return { syncMode: "all" };
-  try {
-    const memberships = await client.listMyMemberships();
-    const m = memberships.find((x) => x.companyUid === companyUid);
-    if (!m) return { syncMode: "all" };
-    const cfg = await client.getMembershipSyncConfig(m.membershipKey);
-    if (cfg.syncMode === "all") return { syncMode: "all" };
-
-    // Pins are company-relative prefixes a user explicitly materialized via
-    // `hq files get`. They're unioned into the scope so a scoped pull keeps
-    // them instead of pruning them as out-of-scope orphans. Pins only WIDEN
-    // scope, never narrow — and `all` mode (handled above) ignores them since
-    // it pulls everything anyway.
-    const pinPrefixes = hqRoot ? readPinnedPrefixes(hqRoot, slug) : [];
-
-    if (cfg.syncMode === "custom") {
-      const customPrefixes = (cfg.customPaths ?? []).map((p) =>
-        grantPathToPrefix(p, slug),
-      );
-      // A bare-everything entry ("" — e.g. a `*` path) collapses under
-      // `coalescePrefixes` (which drops empties) to "nothing", which would
-      // prune the whole tree. An everything-scope is semantically `all`.
-      if (customPrefixes.some((p) => p === "")) return { syncMode: "all" };
-      return {
-        syncMode: "custom",
-        prefixSet: coalescePrefixes([...customPrefixes, ...pinPrefixes]),
-      };
-    }
-    // shared: scope to the caller's explicit grants. Real grant paths are
-    // inconsistent — full (`companies/<slug>/x/*`), slug-anchored
-    // (`<slug>/x/*`), company-relative (`x/*`), bare globs (`*`), and exact
-    // files all coexist in production — so each is normalized via
-    // `grantPathToPrefix` into a company-relative, startsWith-friendly prefix
-    // (the namespace the engine's `RemoteFile.key`s live in) before coalescing.
-    //
-    // SAFETY: if the client can't fetch grants, we must NOT fall through to an
-    // empty `shared` scope — that would tell the engine "nothing is in scope"
-    // and scope-shrink would prune every clean local file. Degrade to `all`
-    // instead. A genuinely-empty grant list (the method exists and returns
-    // []) is a real "nothing shared with me" and is allowed to narrow.
-    if (!client.listMyExplicitGrants) return { syncMode: "all" };
-    const grants = await client.listMyExplicitGrants(companyUid);
-    const sharedPrefixes = grants.map((g) => grantPathToPrefix(g.path, slug));
-    // A wildcard grant (`*`) normalizes to "" = everything. Since
-    // `coalescePrefixes` drops empties (collapsing "everything" to "nothing"),
-    // treat any such grant as full-access `all` rather than risk pruning.
-    if (sharedPrefixes.some((p) => p === "")) return { syncMode: "all" };
-    return {
-      syncMode: "shared",
-      prefixSet: coalescePrefixes([...sharedPrefixes, ...pinPrefixes]),
-    };
-  } catch {
-    // Degrade to `all` — never prune on a resolution failure.
-    return { syncMode: "all" };
-  }
-}
-
-/**
- * Read the per-machine pin set (`<hqRoot>/.hq/pins.json`) and return the
- * company-relative pinned prefixes for `slug`. These are prefixes the user
- * materialized on demand via `hq files get` that must survive a scoped pull.
- *
- * Tolerant by construction: a missing, unreadable, or malformed file yields
- * `[]` (no pins) — pins only ever widen scope, so "no pins" is the safe
- * default. Empty-string entries are dropped (an everything-pin is meaningless
- * here; `all` mode already covers that case).
- */
-export function readPinnedPrefixes(hqRoot: string, slug: string): string[] {
-  try {
-    const raw = fs.readFileSync(path.join(hqRoot, ".hq", "pins.json"), "utf-8");
-    const parsed = JSON.parse(raw) as { pins?: Record<string, unknown> };
-    const list = parsed?.pins?.[slug];
-    if (Array.isArray(list)) {
-      return list.filter(
-        (p): p is string => typeof p === "string" && p.length > 0,
-      );
-    }
-  } catch {
-    /* missing / unreadable / malformed → no pins */
-  }
-  return [];
-}
+// `resolvePullScope`, `readPinnedPrefixes`, and the `PullScope` type now live
+// in `../sync/pull-scope.ts` so the menubar runner and `hq sync pull|now`
+// (hq-cli) share ONE scope resolver — the drift between them was the root
+// cause of the all→shared scope-shrink wedge (DEV-1768). Re-exported here so
+// existing importers (and the runner test suite) keep their import path.
+export { resolvePullScope, readPinnedPrefixes };
+export type { PullScope };
 
 /**
  * Backoff schedule (in ms) between attempts 2 and 3 of
@@ -1446,6 +1342,13 @@ export async function runRunner(
           hqRoot: parsed.hqRoot,
           onConflict: parsed.onConflict,
           syncMode: pullScope.syncMode,
+          // The menubar runner can take no interactive flag, so a scope shrink
+          // must NEVER throw here (the old `ScopeShrinkBlockedError` → exit 2
+          // was the permanent wedge in DEV-1768). Self-heal non-destructively:
+          // dirty out-of-scope files stay on disk + un-tracked, clean ones are
+          // quarantined (recoverable). This also clears an already-wedged
+          // journal — seeded by a buggy `all`-mode CLI pull — on the next sync.
+          scopeShrinkPolicy: "auto-recover",
           // Scope-shrink authorship guard: pass the caller's own sub (the very
           // sub stamped onto uploads as `created-by-sub`) so a scope shrink
           // never prunes content this owner authored. Owners hold their whole

package/src/cli/sync-scope.test.ts

@@ -340,4 +340,88 @@ describe("sync — scope-aware download (US-005)", () => {
     expect(forced.scopeOrphansBlocked).toBe(1);
     expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
   });
+
+  // DEV-1768 fix #3: a scope shrink must QUARANTINE clean orphans (recoverable),
+  // never silently delete them. The file leaves its working-tree path but is
+  // recoverable under `.hq/scope-quarantine/<slug>/`.
+  it("scope shrink QUARANTINES a clean orphan (recoverable), never silent-deletes", async () => {
+    const quarantined = path.join(
+      tmpDir,
+      ".hq",
+      "scope-quarantine",
+      "acme",
+      "docs",
+      "handoff.md",
+    );
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
+    const original = companyRel("docs/handoff.md");
+    const bodyBefore = fs.readFileSync(original, "utf-8");
+
+    const shared = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["knowledge/"],
+    });
+
+    expect(shared.scopeOrphansRemoved).toBe(1);
+    // Gone from the working tree...
+    expect(fs.existsSync(original)).toBe(false);
+    // ...but recoverable in quarantine, byte-for-byte.
+    expect(fs.existsSync(quarantined)).toBe(true);
+    expect(fs.readFileSync(quarantined, "utf-8")).toBe(bodyBefore);
+  });
+
+  // DEV-1768 fix #1 (recovery) + #2: the background runner path
+  // (`scopeShrinkPolicy: "auto-recover"`) must NEVER throw on a scope shrink —
+  // it self-heals. This reproduces the EXACT wedge: a buggy `all`-mode pull
+  // seeds the journal (all-mode PullRecord + both files), one out-of-scope file
+  // is edited locally (dirty), then the real `shared` pull arrives. Under the
+  // old code this threw ScopeShrinkBlockedError(all→shared) → exit 2 forever.
+  it("auto-recover policy clears an all→shared wedge: dirty kept on disk, clean quarantined, no throw", async () => {
+    // 1. Buggy all-mode CLI seed: journals everything + stamps an all-mode record.
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
+    // 2. User edits an out-of-scope file → it becomes a DIRTY orphan.
+    fs.writeFileSync(companyRel("docs/handoff.md"), "LOCAL EDIT — keep me");
+    const quarantinedClean = path.join(
+      tmpDir, ".hq", "scope-quarantine", "acme", "knowledge", "readme.md",
+    );
+
+    // 3. The menubar runner's real shared pull. prefixSet covers NEITHER file
+    //    (docs is dirty-orphan, knowledge becomes a clean orphan) so we exercise
+    //    both dispositions. Must resolve without throwing.
+    const recovered = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["projects/"],
+      scopeShrinkPolicy: "auto-recover",
+    });
+    expect(recovered.aborted).toBe(false);
+    // Dirty file: KEPT on disk (un-tracked), counted as blocked-but-kept.
+    expect(recovered.scopeOrphansBlocked).toBe(1);
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
+    expect(fs.readFileSync(companyRel("docs/handoff.md"), "utf-8")).toBe(
+      "LOCAL EDIT — keep me",
+    );
+    // Clean file: quarantined (recoverable), removed from the working tree.
+    expect(recovered.scopeOrphansRemoved).toBe(1);
+    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(false);
+    expect(fs.existsSync(quarantinedClean)).toBe(true);
+
+    // 4. Idempotent: the next auto-recover sync re-flags NOTHING (the orphans
+    //    were tombstoned, so the wedge does not recur).
+    const second = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["projects/"],
+      scopeShrinkPolicy: "auto-recover",
+    });
+    expect(second.scopeOrphansRemoved).toBe(0);
+    expect(second.scopeOrphansBlocked).toBe(0);
+  });
 });

package/src/cli/sync.ts

@@ -40,6 +40,7 @@ import {
   applyScopeShrink,
   ScopeShrinkBlockedError,
   ScopeShrinkLargePruneError,
+  type ScopeShrinkAdviceContext,
 } from "../scope-shrink.js";
 import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
@@ -355,6 +356,25 @@ export interface SyncOptions {
    * tombstoned. Mirrors `hq sync narrow --force`.
    */
   forceScopeShrink?: boolean;
+  /**
+   * How `sync()` handles a scope shrink (US-005 / DEV-1768):
+   *
+   *   - `"block"` (default) — a human is present (foreground `hq sync`). Dirty
+   *     out-of-scope orphans, or a clean prune over the safety cap, raise a
+   *     structured error whose advice is followable from a terminal. Clean
+   *     orphans within the cap are QUARANTINED (moved, not deleted).
+   *   - `"auto-recover"` — the background menubar runner, which can take no
+   *     interactive flag. NEVER throws on a shrink: dirty orphans are kept on
+   *     disk + un-tracked, clean orphans are quarantined, and the bulk-prune
+   *     cap is bypassed (quarantine is non-destructive). This is what clears an
+   *     already-wedged journal on the next sync, idempotently and without data
+   *     loss — the recovery seam for the all→shared seed bug.
+   *
+   * Both policies are non-destructive for CLEAN files (quarantine, never
+   * silent delete) — the deliberate `hq sync narrow --apply` ritual is the only
+   * path that hard-deletes, and it confirms first.
+   */
+  scopeShrinkPolicy?: "block" | "auto-recover";
   /**
    * The caller's own Cognito `sub`, used by the scope-shrink authorship guard
    * so a scope shrink never prunes content the caller authored. Injected by the
@@ -655,23 +675,38 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     // explicit `hq sync narrow` ritual opts out of the unknown-author shield.
     protectUnknownAuthors: true,
   });
-  if (shrinkPlan.dirty.length > 0 && options.forceScopeShrink !== true) {
+  // Policy: the background menubar runner ("auto-recover") can take no
+  // interactive flag, so it must never throw on a shrink — it self-heals
+  // non-destructively (dirty kept on disk + un-tracked, clean quarantined).
+  // A foreground `hq sync` ("block", the default) keeps the protective gate
+  // but renders FOLLOWABLE advice. `autoRecover` implies force (proceed) and
+  // bypasses the bulk-prune cap (quarantine is non-destructive, so a large
+  // recovery move is safe). DEV-1768.
+  const scopeShrinkPolicy = options.scopeShrinkPolicy ?? "block";
+  const autoRecover = scopeShrinkPolicy === "auto-recover";
+  const adviceContext: ScopeShrinkAdviceContext = autoRecover ? "runner" : "cli";
+  const effectiveForce = options.forceScopeShrink === true || autoRecover;
+
+  if (shrinkPlan.dirty.length > 0 && !effectiveForce) {
     throw new ScopeShrinkBlockedError(
       ctx.uid,
       lastRecord?.syncMode ?? "unknown",
       syncMode,
       shrinkPlan.dirty,
       shrinkPlan.clean,
+      adviceContext,
     );
   }
-  // Bulk-delete guard: refuse to auto-prune more than the safety cap of CLEAN
-  // files in a single background sync. A deliberate large narrow goes through
-  // `hq sync narrow --apply` (its own confirmation), and `--force-scope-shrink`
-  // (or raising HQ_SYNC_MAX_AUTO_PRUNE) overrides. Cap of 0 = unlimited (opt
-  // out). The engine deletes nothing when it throws here.
+  // Bulk guard: refuse to auto-move more than the safety cap of CLEAN files in
+  // a single foreground sync. A deliberate large narrow goes through
+  // `hq sync narrow --apply` (its own confirmation); `--force-scope-shrink` (or
+  // raising HQ_SYNC_MAX_AUTO_PRUNE) overrides. Cap of 0 = unlimited. Skipped
+  // under auto-recover — quarantine is non-destructive so a big recovery is
+  // safe, and the runner has no way to act on a thrown cap. The engine moves
+  // nothing when it throws here.
   const autoPruneCap = resolveAutoPruneCap();
   if (
-    options.forceScopeShrink !== true &&
+    !effectiveForce &&
     autoPruneCap > 0 &&
     shrinkPlan.clean.length > autoPruneCap
   ) {
@@ -680,27 +715,65 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       syncMode,
       shrinkPlan.clean.length,
       autoPruneCap,
+      adviceContext,
     );
   }
+  // Clean orphans are QUARANTINED (moved into `.hq/scope-quarantine/<slug>/`,
+  // recoverable), never silently deleted — a background sync purging local
+  // files unannounced was DEV-1768 fix #3. The quarantine root lives under the
+  // real HQ root's `.hq/` (outside `companyRoot` and never pushed), so moved
+  // files don't round-trip back through S3.
+  const scopeQuarantineRoot = path.join(
+    hqRoot,
+    ".hq",
+    "scope-quarantine",
+    journalSlug,
+  );
   const shrinkResult = applyScopeShrink({
     journal,
     plan: shrinkPlan,
     hqRoot: companyRoot,
-    forceScopeShrink: options.forceScopeShrink === true,
+    forceScopeShrink: effectiveForce,
     reason: "scope_shrink",
+    cleanDisposition: "quarantine",
+    quarantineRoot: scopeQuarantineRoot,
   });
-  // Surface each removed clean orphan as a `deleted` progress event so the
-  // menubar stream renders the prune the same way it renders a cross-machine
-  // tombstone (the Rust parser already handles `deleted: true`).
-  for (const orphan of shrinkPlan.clean) {
+  // Surface each affected orphan explicitly (named path) so the prune is never
+  // silent. Quarantined clean files render as `deleted: true` (removed from the
+  // working tree, recoverable in quarantine); dirty files KEPT on disk render
+  // as a non-deletion notice so the operator knows they were un-tracked, not
+  // removed. The Rust menubar parser already handles `deleted: true`.
+  for (const relPath of shrinkResult.quarantinedPaths) {
+    emit({
+      type: "progress",
+      path: relPath,
+      bytes: 0,
+      deleted: true,
+      message: `scope-narrowed: moved out-of-scope copy to ${scopeQuarantineRoot}`,
+    });
+  }
+  for (const relPath of shrinkResult.removedPaths) {
     emit({
       type: "progress",
-      path: orphan.path,
+      path: relPath,
       bytes: 0,
       deleted: true,
       message: "scope-narrowed (removed local copy outside sync scope)",
     });
   }
+  for (const relPath of shrinkResult.dirtyKeptPaths) {
+    emit({
+      type: "progress",
+      path: relPath,
+      bytes: 0,
+      message:
+        "scope-narrowed: locally-modified file KEPT on disk, un-tracked from sync (outside scope)",
+    });
+  }
+  // "Removed from the working tree" = deleted OR quarantined; both vacate the
+  // file's original path. Reported as `scopeOrphansRemoved` for back-compat.
+  const scopeOrphansRemoved =
+    shrinkResult.cleanRemoved + shrinkResult.cleanQuarantined;
 
   // Stage 2: execute the plan. Per-item branching mirrors the pre-refactor
   // inline loop; the only structural change is that classification has
@@ -949,7 +1022,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           // a conflict abort. `filesOutOfScope` reflects how far the serial
           // pass got before the abort; that's acceptable for an abort result.
           filesOutOfScope,
-          scopeOrphansRemoved: shrinkResult.cleanRemoved,
+          scopeOrphansRemoved,
           scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
         };
         break;
@@ -1328,7 +1401,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     syncMode,
     prefixSet: currentPrefixSet,
     scopeChangeDetected: shrinkPlan.scopeChangeDetected,
-    orphansRemoved: shrinkResult.cleanRemoved,
+    orphansRemoved: scopeOrphansRemoved,
     orphansBlocked: shrinkResult.dirtyTombstoned,
   });
 
@@ -1347,7 +1420,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   const changedOnDisk =
     filesDownloaded > 0 ||
     filesTombstoned > 0 ||
-    shrinkResult.cleanRemoved > 0;
+    scopeOrphansRemoved > 0;
   if (!options.skipReindex && changedOnDisk) {
     try {
       // skipLock: the surrounding sync run already holds this root's operation
@@ -1370,7 +1443,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     filesExcludedByPolicy: plan.filesExcludedByPolicy,
     filesTombstoned,
     filesOutOfScope,
-    scopeOrphansRemoved: shrinkResult.cleanRemoved,
+    scopeOrphansRemoved,
     scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
   };
 }

package/src/cognito-auth.ts

@@ -147,6 +147,157 @@ export function decodeAccessTokenClientId(accessToken: string): string | null {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Machine identity (company agents)
+// ---------------------------------------------------------------------------
+//
+// HQ company agents run headless on their own boxes with long-lived Cognito
+// MACHINE credentials ({username: "machine-agt_<ulid>", secret}) provisioned
+// by hq-pro's agent bootstrap and stored at ~/.hq-agent/machine-creds.json.
+// There is no browser, no Hosted UI, and no refresh-token dance: the creds
+// never expire, so the CLI simply re-mints a session via USER_PASSWORD_AUTH
+// whenever the cached tokens are missing or expiring.
+//
+// Token semantics matter here. The agent's identity claims
+// (custom:entityType=agent, custom:entityUid=agt_*) ride the ID token only;
+// APIs that verify token_use=access (e.g. hq-deploy) need the real access
+// token. Both are cached with correct field semantics — callers pick the
+// token type each API actually validates.
+
+export interface MachineCreds {
+  /** Cognito username, always "machine-agt_<ulid>". */
+  username: string;
+  /** Long-lived machine secret (USER_PASSWORD_AUTH password). */
+  secret: string;
+}
+
+/** Resolve the machine-creds file path (HQ_MACHINE_CREDS_FILE overrides). */
+export function machineCredsFilePath(): string {
+  return (
+    process.env.HQ_MACHINE_CREDS_FILE ??
+    path.join(os.homedir(), ".hq-agent", "machine-creds.json")
+  );
+}
+
+/**
+ * Load machine credentials, or null when this process is not running as a
+ * machine identity (no creds file / unreadable / malformed).
+ */
+export function loadMachineCreds(): MachineCreds | null {
+  const file = machineCredsFilePath();
+  try {
+    if (!fs.existsSync(file)) return null;
+    const raw = JSON.parse(fs.readFileSync(file, "utf-8")) as {
+      username?: unknown;
+      secret?: unknown;
+    };
+    if (
+      typeof raw.username === "string" &&
+      raw.username.startsWith("machine-") &&
+      typeof raw.secret === "string" &&
+      raw.secret.length > 0
+    ) {
+      return { username: raw.username, secret: raw.secret };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when machine credentials are present — the CLI is a machine identity. */
+export function isMachineIdentity(): boolean {
+  return loadMachineCreds() !== null;
+}
+
+interface InitiateAuthResponse {
+  AuthenticationResult?: {
+    AccessToken?: string;
+    IdToken?: string;
+    RefreshToken?: string;
+    ExpiresIn?: number;
+  };
+  ChallengeName?: string;
+  __type?: string;
+  message?: string;
+}
+
+/**
+ * Mint a fresh session for the machine identity via USER_PASSWORD_AUTH
+ * against the Cognito IDP endpoint (plain unsigned HTTP — no AWS SDK
+ * dependency). Caches BOTH tokens with correct field semantics and returns
+ * them.
+ */
+export async function mintMachineTokens(
+  config: CognitoAuthConfig,
+  creds?: MachineCreds,
+): Promise<CognitoTokens> {
+  const machineCreds = creds ?? loadMachineCreds();
+  if (!machineCreds) {
+    throw new CognitoAuthError(
+      `No machine credentials found at ${machineCredsFilePath()}`,
+    );
+  }
+  const res = await fetch(
+    `https://cognito-idp.${config.region}.amazonaws.com/`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-amz-json-1.1",
+        "X-Amz-Target": "AWSCognitoIdentityProviderService.InitiateAuth",
+      },
+      body: JSON.stringify({
+        AuthFlow: "USER_PASSWORD_AUTH",
+        ClientId: config.clientId,
+        AuthParameters: {
+          USERNAME: machineCreds.username,
+          PASSWORD: machineCreds.secret,
+        },
+      }),
+    },
+  );
+  const data = (await res.json().catch(() => ({}))) as InitiateAuthResponse;
+  if (!res.ok) {
+    throw new CognitoAuthError(
+      `Machine token mint failed (${res.status}): ${data.__type ?? ""} ${data.message ?? ""}`.trim(),
+    );
+  }
+  const result = data.AuthenticationResult;
+  if (!result?.AccessToken || !result?.IdToken) {
+    throw new CognitoAuthError(
+      `Machine token mint returned no tokens${data.ChallengeName ? ` (challenge: ${data.ChallengeName})` : ""}`,
+    );
+  }
+  const tokens: CognitoTokens = {
+    accessToken: result.AccessToken,
+    idToken: result.IdToken,
+    // Machine creds never expire — expiry is handled by re-minting, so the
+    // refresh token (when Cognito returns one at all) is never exercised.
+    refreshToken: result.RefreshToken ?? "",
+    expiresAt: Date.now() + (result.ExpiresIn ?? 3600) * 1000,
+    tokenType: "Bearer",
+  };
+  saveCachedTokens(tokens);
+  return tokens;
+}
+
+/**
+ * Return a valid (non-expiring) machine session, re-minting on demand.
+ * Cache-hit path never touches the network.
+ */
+export async function getValidMachineTokens(
+  config: CognitoAuthConfig,
+): Promise<CognitoTokens> {
+  const cached = loadCachedTokens();
+  if (cached && !isExpiring(cached, 120)) {
+    const cachedClientId = decodeAccessTokenClientId(cached.accessToken);
+    if (cachedClientId === null || cachedClientId === config.clientId) {
+      return cached;
+    }
+  }
+  return mintMachineTokens(config);
+}
+
 // ---------------------------------------------------------------------------
 // PKCE
 // ---------------------------------------------------------------------------
@@ -402,6 +553,14 @@ export async function getValidAccessToken(
   options: { interactive?: boolean } = {},
 ): Promise<string> {
   const interactive = options.interactive ?? true;
+
+  // Machine identities (company agents) never refresh or open a browser —
+  // they re-mint via USER_PASSWORD_AUTH on demand.
+  if (isMachineIdentity()) {
+    const machine = await getValidMachineTokens(config);
+    return machine.accessToken;
+  }
+
   let cached = loadCachedTokens();
 
   // Stale-pool detection: if the cached access token was issued by a

package/src/index.ts

@@ -69,6 +69,7 @@ export {
   buildScopeShrinkPlan,
   applyScopeShrink,
   ScopeShrinkBlockedError,
+  ScopeShrinkLargePruneError,
 } from "./scope-shrink.js";
 export type {
   OrphanClassification,
@@ -76,6 +77,8 @@ export type {
   BuildScopeShrinkPlanInput,
   ApplyScopeShrinkInput,
   ApplyScopeShrinkResult,
+  ScopeShrinkAdviceContext,
+  CleanOrphanDisposition,
 } from "./scope-shrink.js";
 
 // Engine-layer ACL-aware pull orchestration (US-005)
@@ -115,8 +118,25 @@ export {
   isExpiring,
   getValidAccessToken,
   CognitoAuthError,
+  machineCredsFilePath,
+  loadMachineCreds,
+  isMachineIdentity,
+  mintMachineTokens,
+  getValidMachineTokens,
 } from "./cognito-auth.js";
-export type { CognitoAuthConfig, CognitoTokens } from "./cognito-auth.js";
+export type {
+  CognitoAuthConfig,
+  CognitoTokens,
+  MachineCreds,
+} from "./cognito-auth.js";
+
+// Per-company PULL scope resolver (US-005) — shared between hq-sync-runner and
+// `hq sync pull|now` (hq-cli). Exported so hq-cli's foreground pull paths resolve
+// the SAME effective scope the menubar runner does, instead of defaulting every
+// CLI pull to `syncMode: "all"` (the seed of the all→shared scope-shrink wedge,
+// DEV-1768).
+export { resolvePullScope, readPinnedPrefixes } from "./sync/pull-scope.js";
+export type { PullScope, PullScopeClient } from "./sync/pull-scope.js";
 
 // Personal-vault scope helpers — shared between hq-sync-runner and `hq sync`
 export {