@indigoai-us/hq-cli 5.75.0 → 5.76.0

package/src/run/hq-plugin.ts

@@ -2,15 +2,27 @@ import { ResolutionError } from 'varlock/plugin-lib';
 import type { Resolver } from 'varlock/plugin-lib';
 import {
   DEFAULT_SECRETS_CACHE_TTL_MS,
-  readCache,
   writeCache,
+  removeCacheEntry,
 } from '../utils/secrets-cache.js';
 import type { SecretLoadResponse, SecretUsage } from '../commands/secrets.js';
 
-function normalizeCacheTtlMs(cacheTtlMs?: number): number {
-  return typeof cacheTtlMs === 'number'
-    ? cacheTtlMs
-    : DEFAULT_SECRETS_CACHE_TTL_MS;
+function normalizeCacheTtlMs(secret: SecretLoadResponse['secrets'][number]): number {
+  if (
+    secret.tier === 'sensitive' ||
+    secret.tier === 'nuclear' ||
+    secret.scriptLock?.mode === 'enforced'
+  ) {
+    return 0;
+  }
+  if (secret.cacheTtlMs === undefined) {
+    return DEFAULT_SECRETS_CACHE_TTL_MS;
+  }
+  return typeof secret.cacheTtlMs === 'number' &&
+    Number.isFinite(secret.cacheTtlMs) &&
+    secret.cacheTtlMs > 0
+    ? secret.cacheTtlMs
+    : 0;
 }
 
 export interface InstallHqPluginOpts {
@@ -69,9 +81,9 @@ export function installHqPlugin(graph: any /* EnvGraph */, opts: InstallHqPlugin
       impliesSensitive: true,
       argsSchema: { type: 'array' as const, arrayMaxLength: 1 },
       resolve: async function (this: HqResolver) {
-        // Cache-only read. `pluginState` is captured by this inner-class closure;
-        // `prewarmHqSecrets(graph, opts, state)` populates `state.uid` and
-        // `state.errorsByName` before `graph.resolveEnvValues()` calls us.
+        // `pluginState` is captured by this inner-class closure;
+        // `prewarmHqSecrets(graph, opts, state)` server-authorizes and populates
+        // the in-memory values before `graph.resolveEnvValues()` calls us.
         const explicit = this.arrArgs?.[0]?.staticValue;
         const secretName = (typeof explicit === 'string' && explicit) ? explicit : this._ownerKey;
         if (!secretName) {
@@ -94,11 +106,6 @@ export function installHqPlugin(graph: any /* EnvGraph */, opts: InstallHqPlugin
           }
           throw new ResolutionError(`Failed to load secret "${secretName}": ${err.message ?? err.code}`);
         }
-        // Sentinel-check style throughout: `readCache` returns `string | null`
-        // (verified at `hq/packages/hq-cli/src/utils/secrets-cache.ts:45`); `pluginState.uid`
-        // is `string | null` per `PluginState`. Use `== null` (covers null AND undefined defensively)
-        // for both — do not mix in truthy checks like `if (!x)`, which would silently swallow a
-        // legitimate empty-string value if the contract ever loosened.
         if (pluginState.uid == null) {
           throw new ResolutionError('Internal error: prewarmHqSecrets was not called before resolveEnvValues');
         }
@@ -106,11 +113,9 @@ export function installHqPlugin(graph: any /* EnvGraph */, opts: InstallHqPlugin
         if (inMemory != null) {
           return inMemory;
         }
-        const cached = readCache(pluginState.uid, secretName); // string | null
-        if (cached == null) {
-          throw new ResolutionError(`Internal error: pre-warm did not populate cache for "${secretName}"`);
-        }
-        return cached;
+        throw new ResolutionError(
+          `Secret "${secretName}" was not returned by vault after server authorization`,
+        );
       },
     };
 
@@ -186,22 +191,87 @@ export async function prewarmHqSecrets(
       `hq run supports at most 100 hq() resolvers per schema; got ${uniqueNames.length}`,
     );
   }
-  const result = await opts.fetchBatch(uid, uniqueNames, opts.usage);
+  state.loadedSecretsByName.clear();
+  state.errorsByName = new Map();
+
+  let result: SecretLoadResponse;
+  try {
+    result = await opts.fetchBatch(uid, uniqueNames, opts.usage);
+    if (!Array.isArray(result.secrets) || !Array.isArray(result.errors)) {
+      throw new Error('Invalid secret load response from vault');
+    }
 
-  for (const s of result.secrets) {
-    if (s.value == null) {
-      continue;
+    const errorsByName = new Map<string, { code: string; message?: string }>();
+    const returnedNames = new Set<string>();
+    const requestedNames = new Set(uniqueNames);
+    const seenNames = new Set<string>();
+    for (const rawSecret of result.secrets) {
+      if (!rawSecret || typeof rawSecret !== 'object') {
+        throw new Error('Invalid secret load response from vault');
+      }
+      const s = rawSecret as SecretLoadResponse['secrets'][number];
+      if (
+        typeof s.name !== 'string' ||
+        !requestedNames.has(s.name) ||
+        seenNames.has(s.name) ||
+        (s.value != null && typeof s.value !== 'string')
+      ) {
+        throw new Error('Invalid secret load response from vault');
+      }
+      seenNames.add(s.name);
+      if (s.value == null) {
+        errorsByName.set(s.name, {
+          code: 'not_returned',
+          message: 'not returned by vault after server authorization',
+        });
+        removeCacheEntry(uid, s.name);
+        continue;
+      }
+      returnedNames.add(s.name);
+      state.loadedSecretsByName.set(s.name, s.value);
+      const cacheTtlMs = normalizeCacheTtlMs(s);
+      if (cacheTtlMs > 0) {
+        writeCache(uid, s.name, s.value, cacheTtlMs);
+      } else {
+        removeCacheEntry(uid, s.name);
+      }
+    }
+    for (const rawError of result.errors) {
+      if (!rawError || typeof rawError !== 'object') {
+        throw new Error('Invalid secret load response from vault');
+      }
+      const e = rawError as { name?: unknown; code?: unknown; message?: unknown };
+      if (
+        typeof e.name !== 'string' ||
+        !requestedNames.has(e.name) ||
+        seenNames.has(e.name) ||
+        typeof e.code !== 'string' ||
+        (e.message !== undefined && typeof e.message !== 'string')
+      ) {
+        throw new Error('Invalid secret load response from vault');
+      }
+      seenNames.add(e.name);
+      errorsByName.set(e.name, { code: e.code, message: e.message });
+      state.loadedSecretsByName.delete(e.name);
+      removeCacheEntry(uid, e.name);
+    }
+    for (const name of uniqueNames) {
+      if (!returnedNames.has(name) && !errorsByName.has(name)) {
+        errorsByName.set(name, {
+          code: 'not_returned',
+          message: 'not returned by vault after server authorization',
+        });
+        removeCacheEntry(uid, name);
+      }
     }
-    state.loadedSecretsByName.set(s.name, s.value);
-    const cacheTtlMs = normalizeCacheTtlMs(s.cacheTtlMs);
-    if (cacheTtlMs > 0) {
-      writeCache(uid, s.name, s.value, cacheTtlMs);
+    state.errorsByName = errorsByName;
+    state.uid = uid;
+  } catch (err) {
+    state.loadedSecretsByName.clear();
+    state.errorsByName = new Map();
+    for (const name of uniqueNames) {
+      removeCacheEntry(uid, name);
     }
+    throw err;
   }
-  const errorsByName = new Map<string, { code: string; message?: string }>();
-  for (const e of result.errors) {
-    errorsByName.set(e.name, { code: e.code, message: e.message });
-  }
-  state.errorsByName = errorsByName;
-  state.uid = uid;
 }

package/src/utils/__fixtures__/scan-packages.generated-block.sh

@@ -0,0 +1,23 @@
+# >>> BEGIN GENERATED contribution table (US-003) — do not edit by hand
+# Generated from hq-cli/src/utils/contribution-table.ts by
+# hq-cli/scripts/generate-scan-packages-table.mjs. Regenerate with:
+#   node scripts/generate-scan-packages-table.mjs --write core/scripts/scan-packages.sh
+# Each row is "payload|host|wire" (payload uses {item} for the name).
+# bash 3.2-compatible (macOS default bash has no associative arrays):
+# a plain indexed key list + a generated case-lookup function.
+CONTRIB_KEYS=(workers knowledge skills commands hooks policies scripts mcp)
+# contrib_row <key> -> echoes "payload|host|wire", empty if unknown.
+contrib_row() {
+  case "$1" in
+    workers) printf '%s' 'workers/{item}|core/workers/public|symlink' ;;
+    knowledge) printf '%s' 'knowledge/{item}|core/knowledge/public|symlink' ;;
+    skills) printf '%s' 'skills/{item}|.claude/skills|symlink' ;;
+    commands) printf '%s' 'commands/{item}.md|.claude/commands|symlink' ;;
+    hooks) printf '%s' 'hooks/{item}.sh|.claude/hooks|symlink' ;;
+    policies) printf '%s' 'policies/{item}.md|core/policies|symlink' ;;
+    scripts) printf '%s' 'scripts/{item}|core/scripts|symlink' ;;
+    mcp) printf '%s' 'mcp/{item}.json|merge:claude+codex|merge' ;;
+    *) return 0 ;;
+  esac
+}
+# <<< END GENERATED contribution table

package/src/utils/pack-contributions.test.ts

@@ -12,6 +12,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { fileURLToPath } from 'node:url';
 import {
   contributionLinks,
   linkStatus,
@@ -102,12 +103,28 @@ describe('contributionLinks: mapping', () => {
 // the WRONG payload suffix, or the WRONG wire mode.
 // ---------------------------------------------------------------------------
 describe('US-003 parity: contribution table is the single source', () => {
-  // Resolve the HQ root so we can read the GENERATED scan-packages.sh block.
-  const scanCandidates = [
-    path.resolve(process.cwd(), '../../../core/scripts/scan-packages.sh'),
-    path.resolve(process.cwd(), '../../../../core/scripts/scan-packages.sh'),
-  ];
-  const scanPath = scanCandidates.find((p) => fs.existsSync(p));
+  // The bash block that `core/scripts/scan-packages.sh` reads is GENERATED from
+  // the contribution table (scripts/generate-scan-packages-table.mjs) and lives
+  // in hq-core — a separately-versioned repo this package never contains. We
+  // vendor that generated block as a committed golden fixture and compare the
+  // table against it, so this guard runs DETERMINISTICALLY in CI and from any
+  // checkout. Regenerate after any table change: `pnpm gen:scan-golden`
+  // (hq-core's own scan-packages.sh must be regenerated from the same table —
+  // that cross-repo leg is enforced in the monorepo that holds both).
+  //
+  // Anchored to THIS module via import.meta.url — never process.cwd().
+  // REGRESSION (do NOT reintroduce): the old resolver did
+  //   path.resolve(process.cwd(), '../../../core/scripts/scan-packages.sh')
+  // which, from a checkout sitting 3 levels below an installed HQ (e.g.
+  // HQ/workspace/worktrees/<name>), bound to that unrelated, differently-
+  // versioned hq-core script and false-failed; from anywhere else it resolved
+  // outside the repo and silently skipped, so the guard NEVER ran — not even in
+  // CI. See the module-anchor regression test below.
+  const goldenBlockPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '__fixtures__',
+    'scan-packages.generated-block.sh',
+  );
 
   // Parse the generated `contrib_row` case arms back into {key:{payload,host,wire}}.
   function parseBashTable(bash: string): Record<
@@ -173,31 +190,73 @@ describe('US-003 parity: contribution table is the single source', () => {
     expect(suffix(CONTRIBUTION_TABLE.scripts.payload)).toBe('');
   });
 
-  (scanPath ? it : it.skip)(
-    'scan-packages.sh generated block matches the table on key-set + payload + host + wire',
-    () => {
-      const bash = fs.readFileSync(scanPath as string, 'utf-8');
-      const bashTable = parseBashTable(bash);
-
-      // FULL key-set equivalence (fails if a surface is MISSING a key or has an
-      // EXTRA one — not just a substring presence check).
-      expect(Object.keys(bashTable).sort()).toEqual([...CONTRIBUTION_KEYS].sort());
-
-      // Per-key payload + host + wire-mode equivalence.
-      for (const k of CONTRIBUTION_KEYS) {
-        expect(bashTable[k], `scan-packages.sh missing row for "${k}"`).toBeDefined();
-        expect(bashTable[k].payload).toBe(CONTRIBUTION_TABLE[k].payload);
-        expect(bashTable[k].host).toBe(CONTRIBUTION_TABLE[k].host);
-        expect(bashTable[k].wire).toBe(CONTRIBUTION_TABLE[k].wire);
-      }
-
-      // The CONTRIB_KEYS array in the script also lists every key.
-      const keysLine = bash.match(/CONTRIB_KEYS=\(([^)]*)\)/);
-      expect(keysLine).not.toBeNull();
-      const bashKeys = (keysLine as RegExpMatchArray)[1].trim().split(/\s+/).sort();
-      expect(bashKeys).toEqual([...CONTRIBUTION_KEYS].sort());
-    },
-  );
+  it('generated block (vendored golden) matches the table on key-set + payload + host + wire', () => {
+    const bash = fs.readFileSync(goldenBlockPath, 'utf-8');
+    const bashTable = parseBashTable(bash);
+
+    // FULL key-set equivalence (fails if the golden is MISSING a key or has an
+    // EXTRA one — not just a substring presence check). This doubles as the
+    // drift guard: if the table changed but the golden wasn't regenerated, one
+    // of these assertions fails with the exact key/field that diverged.
+    expect(Object.keys(bashTable).sort()).toEqual([...CONTRIBUTION_KEYS].sort());
+
+    // Per-key payload + host + wire-mode equivalence.
+    for (const k of CONTRIBUTION_KEYS) {
+      expect(
+        bashTable[k],
+        `golden block missing row for "${k}" — run \`pnpm gen:scan-golden\``,
+      ).toBeDefined();
+      expect(bashTable[k].payload).toBe(CONTRIBUTION_TABLE[k].payload);
+      expect(bashTable[k].host).toBe(CONTRIBUTION_TABLE[k].host);
+      expect(bashTable[k].wire).toBe(CONTRIBUTION_TABLE[k].wire);
+    }
+
+    // The CONTRIB_KEYS array in the block also lists every key.
+    const keysLine = bash.match(/CONTRIB_KEYS=\(([^)]*)\)/);
+    expect(keysLine).not.toBeNull();
+    const bashKeys = (keysLine as RegExpMatchArray)[1].trim().split(/\s+/).sort();
+    expect(bashKeys).toEqual([...CONTRIBUTION_KEYS].sort());
+  });
+
+  it('resolves the golden from the module, never from process.cwd() (regression: a co-located HQ must not bind)', () => {
+    // Rebuild the exact historical trap: an installed-HQ-shaped dir carrying a
+    // DIFFERENT scan-packages.sh, with a checkout nested 3 levels below it
+    // (the HQ/workspace/worktrees/<name> layout that first surfaced this bug).
+    const fakeHq = mkTmp('fake-hq-');
+    fs.mkdirSync(path.join(fakeHq, 'core', 'scripts'), { recursive: true });
+    fs.writeFileSync(
+      path.join(fakeHq, 'core', 'scripts', 'scan-packages.sh'),
+      '# unrelated, differently-versioned hq-core script\n',
+    );
+    const nested = path.join(fakeHq, 'workspace', 'worktrees', 'hq-cli-x');
+    fs.mkdirSync(nested, { recursive: true });
+
+    const orig = process.cwd();
+    try {
+      process.chdir(nested);
+      // Module-anchored resolution is unaffected by cwd and points at the repo
+      // golden — which really exists and is what the parity test reads.
+      expect(fs.existsSync(goldenBlockPath)).toBe(true);
+      expect(
+        goldenBlockPath.endsWith(
+          path.join('src', 'utils', '__fixtures__', 'scan-packages.generated-block.sh'),
+        ),
+      ).toBe(true);
+      // The OLD cwd-relative resolver WOULD have latched onto the fake file.
+      // Prove the trap is real, and that we no longer resolve to it.
+      const oldCwdRelative = path.resolve(
+        process.cwd(),
+        '../../../core/scripts/scan-packages.sh',
+      );
+      expect(oldCwdRelative).toBe(
+        path.join(fakeHq, 'core', 'scripts', 'scan-packages.sh'),
+      );
+      expect(oldCwdRelative).not.toBe(goldenBlockPath);
+    } finally {
+      process.chdir(orig);
+      fs.rmSync(fakeHq, { recursive: true, force: true });
+    }
+  });
 
   it('validateManifest payload reader (payloadFor) agrees with the table for every key', () => {
     for (const k of CONTRIBUTION_KEYS) {

package/src/utils/sandbox-runner-client.test.ts

@@ -225,12 +225,39 @@ describe("SandboxRunnerClient", () => {
     ).resolves.toMatchObject({
       jobId: "job_1",
       status: "failed",
+      error: undefined,
       output: "boom\n",
       exitCode: 2,
       success: false,
     });
   });
 
+  // The wire shape the server actually sends when it could not RUN the command:
+  // a reason, and no exit code, because nothing ever exited.
+  it("surfaces the reason on a job the sandbox could not execute", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      jsonRes({
+        jobId: "job_1",
+        status: "failed",
+        error: "Sandbox max-exec exceeded (28000ms)",
+      }),
+    );
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+    });
+
+    await expect(
+      client.pollJob("jwt-token", "job_1", { intervalMs: 0 }),
+    ).resolves.toMatchObject({
+      jobId: "job_1",
+      status: "failed",
+      error: "Sandbox max-exec exceeded (28000ms)",
+      exitCode: undefined,
+      output: undefined,
+    });
+  });
+
   it("uses the requested job id when the live status response omits it", async () => {
     const fetchImpl = vi.fn<typeof fetch>(async () =>
       jsonRes({ status: "succeeded", output: "ok\n" }),
@@ -244,6 +271,7 @@ describe("SandboxRunnerClient", () => {
       jobId: "job_live",
       status: "succeeded",
       output: "ok\n",
+      error: undefined,
       exitCode: undefined,
       success: undefined,
     });

package/src/utils/sandbox-runner-client.ts

@@ -15,6 +15,7 @@ export interface SandboxRunnerJob {
   jobId: string;
   status: SandboxRunnerState;
   output?: string;
+  error?: string;
   exitCode?: number;
   success?: boolean;
 }
@@ -88,6 +89,7 @@ function normalizeJob(
         : jobIdFallback ?? requireString(body, "jobId"),
     status,
     output: typeof body.output === "string" ? body.output : undefined,
+    error: typeof body.error === "string" ? body.error : undefined,
     exitCode: typeof body.exitCode === "number" ? body.exitCode : undefined,
     success: typeof body.success === "boolean" ? body.success : undefined,
   };

package/src/utils/secrets-cache.ts

@@ -144,11 +144,10 @@ export function writeCache(
 
 /**
  * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
- * secrets-cache directory on disk. Used by offline callers (e.g. install-time MCP
- * registration) that have no `--company` flag and no network token and so cannot
- * resolve a single active company UID up front: they instead probe every cached
- * scope for a given secret name. Returns `[]` when the cache root is absent or
- * unreadable (the desired graceful-deferral behavior — no scopes, no hits).
+ * secrets-cache directory on disk. Install-time MCP registration may use an
+ * exactly-one result as a scope hint before reauthorizing every value online; it
+ * never reads cached plaintext through this helper. Returns `[]` when the cache
+ * root is absent or unreadable.
  */
 export function listSecretCacheScopes(): string[] {
   try {
@@ -156,9 +155,7 @@ export function listSecretCacheScopes(): string[] {
       .readdirSync(CACHE_DIR, { withFileTypes: true })
       .filter((e) => e.isDirectory())
       .map((e) => e.name)
-      // Only real entity scopes (cmp_*/prs_*); validateInputs in readCache also
-      // rejects anything with `/` or `..`, so this is belt-and-suspenders.
-      .filter((name) => !name.startsWith("."));
+      .filter((name) => /^(?:cmp|prs)_[A-Za-z0-9_-]+$/.test(name));
   } catch {
     return [];
   }

package/test/commands/signals.test.ts

@@ -55,7 +55,7 @@ let restoreFetch: (() => void) | undefined;
 let tmpHqRoot: string;
 let savedEnv: { HQ_ACCESS_TOKEN: string | undefined };
 
-beforeEach(() => {
+beforeEach(async () => {
   savedEnv = { HQ_ACCESS_TOKEN: process.env.HQ_ACCESS_TOKEN };
   process.env.HQ_ACCESS_TOKEN = "test-access-token";
 
@@ -73,7 +73,7 @@ beforeEach(() => {
 
   // `files` serves the fixture over the presigned-URL transport (the path
   // company reads take).
-  restoreFetch = mockVaultService({
+  restoreFetch = await mockVaultService({
     entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
     files: [
       {

package/test/commands/sources.test.ts

@@ -62,7 +62,7 @@ let restoreFetch: (() => void) | undefined;
 let tmpHqRoot: string;
 let savedEnv: { HQ_ACCESS_TOKEN: string | undefined };
 
-beforeEach(() => {
+beforeEach(async () => {
   // Sidestep Cognito interactive flow.
   savedEnv = { HQ_ACCESS_TOKEN: process.env.HQ_ACCESS_TOKEN };
   process.env.HQ_ACCESS_TOKEN = "test-access-token";
@@ -83,7 +83,7 @@ beforeEach(() => {
 
   // Default vault-service mock with one entity 'indigo'. `files` serves the
   // fixture over the presigned-URL transport (the path company reads take).
-  restoreFetch = mockVaultService({
+  restoreFetch = await mockVaultService({
     entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
     files: [
       {

package/test/helpers/vault-service-mock.ts

@@ -1,17 +1,32 @@
 /**
- * vault-service-mock.ts — fetch stub for vault-service HTTP endpoints.
+ * vault-service-mock.ts — vault-service test double.
  *
- * Intercepts globalThis.fetch and handles the subset of vault-service routes
- * needed by entity-resolver and STS tests. Returns the original fetch restore
- * function so callers can clean up in afterEach/finally.
+ * Two collaborating pieces:
+ *   1. A `globalThis.fetch` stub for the vault-service JSON API (membership,
+ *      entity lookup, STS vend, files list/presign).
+ *   2. A real ephemeral localhost HTTP server that serves the presigned-object
+ *      GETs. As of hq-cloud >=6.14.x, `PresignObjectIO` fetches presigned URLs
+ *      through Node's core HTTP client (`nodePresignedGet`), NOT
+ *      `globalThis.fetch`, to bypass the runtime-bundled undici parser — so a
+ *      fetch stub alone never intercepts them and the request escapes to real
+ *      DNS (`ENOTFOUND`). A real (loopback) server is transport-agnostic: it
+ *      works for both the fetch and node-http code paths, and future ones.
  *
- * Handled endpoints (URL path suffixes):
+ * `mockVaultService` is async (it awaits the server's `listen`) and returns a
+ * restore function for `afterEach` that both un-installs the fetch stub and
+ * closes the server.
+ *
+ * Handled JSON endpoints (URL path suffixes):
  *   GET  .../membership/me                  returns { memberships: [...] }
  *   GET  .../entity/by-slug/{type}/{slug}   returns { entity: {...} }
  *   GET  .../entity/{uid}                   returns { entity: {...} }   (direct UID lookup)
- *   POST .../sts/vend                       returns { credentials, expiresAt }    (canonical company STS endpoint)
+ *   GET  .../v1/files/list                  returns { objects, cursor, truncated }
+ *   POST .../v1/files/presign               returns { results, expiresAt } (URLs point at the local server)
+ *   POST .../sts/vend                       returns { credentials, expiresAt }
  */
 
+import http from "node:http";
+import type { AddressInfo } from "node:net";
 import type { Membership, EntityInfo } from "@indigoai-us/hq-cloud";
 
 export interface MockEntity {
@@ -56,8 +71,6 @@ export interface MockVaultOptions {
   files?: MockVaultFile[];
 }
 
-/** Host for mock presigned URLs minted by POST /v1/files/presign. */
-const PRESIGN_URL_HOST = "https://presigned.test";
 const DEFAULT_FILE_DATE = new Date("2026-01-01T00:00:00Z");
 
 const DEFAULT_STS: MockStsCredentials = {
@@ -67,14 +80,56 @@ const DEFAULT_STS: MockStsCredentials = {
 };
 
 /**
- * Installs a fetch stub for vault-service endpoints.
+ * Start a loopback HTTP server that serves presigned-object GETs from the
+ * in-memory `files`. Each minted presign URL is `${origin}/obj?key=<key>`;
+ * the handler resolves the file (200 + body) or 404s (→ NoSuchKey in the
+ * reader). Returns the server + its `http://127.0.0.1:<port>` origin.
+ */
+async function startPresignedFileServer(
+  files: MockVaultFile[],
+): Promise<{ server: http.Server; origin: string }> {
+  const server = http.createServer((req, res) => {
+    const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+    const key = requestUrl.searchParams.get("key") ?? "";
+    const file = files.find((f) => f.key === key);
+    if (!file) {
+      res.statusCode = 404;
+      res.setHeader("content-length", "0");
+      res.end();
+      return;
+    }
+    const body = Buffer.from(file.content, "utf-8");
+    res.writeHead(200, {
+      "content-type": "text/markdown",
+      "content-length": String(body.byteLength),
+      "last-modified": (file.lastModified ?? DEFAULT_FILE_DATE).toUTCString(),
+      etag: '"mock-etag"',
+    });
+    res.end(body);
+  });
+  await new Promise<void>((resolve) => {
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  // Don't keep the event loop (or vitest) alive on this listener.
+  server.unref();
+  const { port } = server.address() as AddressInfo;
+  return { server, origin: `http://127.0.0.1:${port}` };
+}
+
+/**
+ * Installs the vault-service test double (fetch stub + presigned-file server).
  *
- * @returns A restore function — call it in afterEach to un-install the stub.
+ * @returns A restore function — call it in afterEach to un-install the stub and
+ *   close the server.
  */
-export function mockVaultService(opts: MockVaultOptions): () => void {
+export async function mockVaultService(
+  opts: MockVaultOptions,
+): Promise<() => void> {
   const { entities, stsCredentials = DEFAULT_STS, files = [] } = opts;
   const originalFetch = globalThis.fetch as typeof fetch | undefined;
 
+  const { server, origin: presignOrigin } = await startPresignedFileServer(files);
+
   globalThis.fetch = async (
     input: RequestInfo | URL,
     init?: RequestInit,
@@ -89,9 +144,10 @@ export function mockVaultService(opts: MockVaultOptions): () => void {
       (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
 
     // ── Presigned-URL transport (HQ-59 company reads) ──────────────────────
-    // A GET against a URL minted by POST /v1/files/presign below. Serve the
-    // file body (or 404) so PresignObjectIO.getObject resolves like real S3.
-    if (url.startsWith(`${PRESIGN_URL_HOST}/`)) {
+    // Production fetches presigned URLs over node http (served by the loopback
+    // server above), but keep a fetch branch too so any fetch-based transport
+    // resolves identically without escaping to the network.
+    if (url.startsWith(`${presignOrigin}/`)) {
       const key = new URL(url).searchParams.get("key") ?? "";
       const file = files.find((f) => f.key === key);
       if (!file) return new Response("", { status: 404 });
@@ -122,8 +178,9 @@ export function mockVaultService(opts: MockVaultOptions): () => void {
     }
 
     // POST /v1/files/presign  (VaultClient.presign) — mint a per-key URL that
-    // the GET handler above resolves. Unknown keys still get a URL → that GET
-    // 404s, which the reader normalizes to NoSuchKey (the not-found path).
+    // the loopback server (and the GET branch above) resolves. Unknown keys
+    // still get a URL → that GET 404s, which the reader normalizes to
+    // NoSuchKey (the not-found path).
     if (method === "POST" && /\/v1\/files\/presign$/.test(url)) {
       const body = init?.body ? JSON.parse(init.body.toString()) : {};
       const keys = (body.keys ?? []) as Array<{ key: string; op?: string }>;
@@ -134,7 +191,7 @@ export function mockVaultService(opts: MockVaultOptions): () => void {
       const results = keys.map((k) => ({
         key: k.key,
         op: k.op ?? "get",
-        url: `${PRESIGN_URL_HOST}/obj?key=${encodeURIComponent(k.key)}`,
+        url: `${presignOrigin}/obj?key=${encodeURIComponent(k.key)}`,
       }));
       return json({
         results,
@@ -225,6 +282,8 @@ export function mockVaultService(opts: MockVaultOptions): () => void {
     } else {
       delete (globalThis as Record<string, unknown>).fetch;
     }
+    server.closeAllConnections?.();
+    server.close();
   };
 }
 

package/test/sources-signals/smoke.test.ts

@@ -176,7 +176,7 @@ describe("mockVaultService — membership endpoint", () => {
   });
 
   it("GET /membership/me returns memberships for all configured entities", async () => {
-    restore = mockVaultService({
+    restore = await mockVaultService({
       entities: [
         { uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" },
         { uid: "prs_personal_001", slug: "personal", bucketName: "hq-personal-bucket" },
@@ -194,7 +194,7 @@ describe("mockVaultService — membership endpoint", () => {
   });
 
   it("POST /sts/vend returns credentials", async () => {
-    restore = mockVaultService({
+    restore = await mockVaultService({
       entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
     });