@indigoai-us/hq-cloud 6.11.5 → 6.11.7

package/src/personal-vault.ts

@@ -125,7 +125,92 @@ export function computePersonalVaultPaths(
   const companySubdirs = opts.includeLocalCompanies === true
     ? computePersonalCompanySubdirs(hqRoot, opts.teamSyncedSlugs)
     : [];
-  return [...topLevel, ...manifest, ...companySubdirs];
+  const continuity = computeContinuityPointerPaths(hqRoot);
+  return [...topLevel, ...manifest, ...companySubdirs, ...continuity];
+}
+
+/**
+ * Fixed relative path (forward-slash, hq-root-relative) of the session
+ * continuity pointer. The continuity pointer is the ONE file under the
+ * otherwise machine-local `workspace/` that must travel across machines:
+ * `/handoff` writes it on machine A so a fresh session on machine B can
+ * resume via `/startwork`. See {@link computeContinuityPointerPaths}.
+ */
+export const CONTINUITY_POINTER_REL = "workspace/threads/handoff.json";
+
+/**
+ * Compute the absolute paths of the session-continuity pointer carve-out:
+ * `workspace/threads/handoff.json` plus the single thread file it points to.
+ *
+ * `workspace/` is in {@link PERSONAL_VAULT_EXCLUDED_TOP_LEVEL} — it is
+ * machine-local by design (session scratch, locks, reports, the full thread
+ * history). The continuity pointer is the one exception: without it a
+ * `/handoff` on one machine never reaches a second machine, so the session
+ * pointer doesn't follow the user even though the durable output already
+ * syncs. This carve-out pierces the exclusion for EXACTLY two files and
+ * nothing else, mirroring the `companies/manifest.yaml` special-case above
+ * (a single file pushed back in despite its parent dir being excluded).
+ *
+ * The "active thread file" is not a fixed name — it is resolved from
+ * `handoff.json.thread_path` (the pointer the finalize script writes). We
+ * read + parse `handoff.json`, then include `thread_path` ONLY when it is a
+ * relative path that resolves to an existing regular file strictly within
+ * `<hqRoot>/workspace/threads/`. This containment check is a hard security
+ * boundary: a malformed or tampered `handoff.json` must never be able to
+ * smuggle an arbitrary file (e.g. `../../.env`, an absolute path, or a
+ * symlink escaping the threads dir) into the personal vault.
+ *
+ * Fail-soft throughout: a missing/unreadable/malformed `handoff.json`, or an
+ * out-of-bounds / missing `thread_path`, silently degrades to "include
+ * whatever is valid" (handoff.json alone, or `[]`). Callers tolerate empty
+ * arrays — same contract as the manifest special-case.
+ */
+export function computeContinuityPointerPaths(hqRoot: string): string[] {
+  const out: string[] = [];
+  const threadsDir = path.join(hqRoot, "workspace", "threads");
+  const handoffPath = path.join(threadsDir, "handoff.json");
+
+  let raw: string;
+  try {
+    if (!fs.statSync(handoffPath).isFile()) return out;
+    raw = fs.readFileSync(handoffPath, "utf8");
+  } catch {
+    // No pointer on this machine yet (or unreadable) — nothing to carry.
+    return out;
+  }
+  out.push(handoffPath);
+
+  // Resolve the active thread file from the pointer's `thread_path`. Any
+  // failure leaves the pointer itself in `out` and skips the thread body —
+  // the next handoff (or a peer's push) re-converges it.
+  let threadPath: unknown;
+  try {
+    threadPath = (JSON.parse(raw) as { thread_path?: unknown })?.thread_path;
+  } catch {
+    return out;
+  }
+  if (typeof threadPath !== "string" || threadPath.length === 0) return out;
+
+  // Containment: the resolved file must live strictly inside the threads dir.
+  // Reject absolute paths, traversal, and symlink escapes. thread_path is
+  // hq-root-relative as written by handoff-finalize.sh, so resolve against
+  // hqRoot and re-check the realpath is still under the threads dir.
+  if (path.isAbsolute(threadPath)) return out;
+  const resolvedThreads = path.resolve(threadsDir);
+  const candidate = path.resolve(hqRoot, threadPath);
+  const withinThreads = (p: string): boolean =>
+    p === resolvedThreads || p.startsWith(resolvedThreads + path.sep);
+  if (!withinThreads(candidate)) return out;
+  try {
+    const real = fs.realpathSync(candidate);
+    if (!withinThreads(real)) return out;
+    if (!fs.statSync(real).isFile()) return out;
+  } catch {
+    // Pointer references a thread file that doesn't exist here — skip it.
+    return out;
+  }
+  out.push(candidate);
+  return out;
 }
 
 /**

package/src/signals/get.test.ts

@@ -2,13 +2,14 @@
  * Unit tests for signals/get.ts.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { GetObjectCommand, type S3Client } from "@aws-sdk/client-s3";
 import { getSignal, SignalNotFoundError } from "./get.js";
 import {
   _setSignalsS3Factory,
   _resetSignalsS3Factory,
 } from "./internals.js";
+import type { PresignTransportClient } from "../object-io.js";
 import type { EntityContext } from "../types.js";
 import { InvalidSignalTypeError } from "../schemas/signal-types.js";
 
@@ -202,3 +203,84 @@ Body.
     expect(doc.entityRefs).toEqual(["kept@example.com"]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Presigned transport (vault client + company vault) — HQ-59
+// ---------------------------------------------------------------------------
+
+function makePresignVault(objects: Record<string, string>): PresignTransportClient {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      const key = new URL(url).searchParams.get("key") ?? "";
+      const content = objects[key];
+      if (content === undefined) return new Response(null, { status: 404 });
+      return new Response(Buffer.from(content, "utf-8"), { status: 200 });
+    }),
+  );
+  return {
+    presign: async (input) => ({
+      results: input.keys.map((k) => ({
+        key: k.key,
+        op: k.op ?? input.op ?? "get",
+        url: `https://signed.example/?key=${encodeURIComponent(k.key)}`,
+      })),
+      expiresAt: "2099-01-01T00:00:00.000Z",
+    }),
+    listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
+  };
+}
+
+describe("getSignal — presigned transport (vault + cmp_)", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("reads via presign (no S3) and surfaces typed cross-refs", async () => {
+    _setSignalsS3Factory(
+      () =>
+        ({
+          send: async () => {
+            throw new Error("S3 must not be used on the presign path");
+          },
+        }) as unknown as S3Client,
+    );
+    const vault = makePresignVault({ "signals/action_item/foo.md": ACTION_ITEM_MD });
+
+    const doc = await getSignal({
+      entity: ENTITY,
+      signalType: "action_item",
+      signalId: "foo",
+      vault,
+    });
+
+    expect(doc.sourceRef).toBe("abc-meeting-001");
+    expect(doc.entityRefs).toEqual(["stefan@indigoai.us", "corey@indigoai.us"]);
+    expect(doc.body).toContain("Stefan will review");
+  });
+
+  it("maps a presign 404 to SignalNotFoundError", async () => {
+    const vault = makePresignVault({});
+    await expect(
+      getSignal({
+        entity: ENTITY,
+        signalType: "action_item",
+        signalId: "missing",
+        vault,
+      }),
+    ).rejects.toBeInstanceOf(SignalNotFoundError);
+  });
+
+  it("personal vault (prs_) ignores the vault client and stays on direct S3", async () => {
+    installStub({ "signals/action_item/foo.md": ACTION_ITEM_MD });
+    const vault = makePresignVault({});
+    const personal: EntityContext = { ...ENTITY, uid: "prs_me" };
+
+    const doc = await getSignal({
+      entity: personal,
+      signalType: "action_item",
+      signalId: "foo",
+      vault,
+    });
+
+    expect(doc.body).toContain("Stefan will review");
+  });
+});

package/src/signals/get.ts

@@ -4,9 +4,8 @@
  * `entityRefs` surfaced as typed fields.
  */
 
-import { GetObjectCommand } from "@aws-sdk/client-s3";
 import { assertSignalType } from "../schemas/signal-types.js";
-import { getS3Client, streamToString } from "./internals.js";
+import { readObjectText } from "./internals.js";
 import { parseMarkdown } from "./parse.js";
 import type { GetSignalOptions, SignalDocument } from "./types.js";
 
@@ -20,8 +19,12 @@ export class SignalNotFoundError extends Error {
 function isNoSuchKey(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
   const name = (err as { name?: unknown }).name;
-  // AWS SDK v3 throws either a `NoSuchKey` exception or a `NotFound` head error.
-  return name === "NoSuchKey" || name === "NoSuchKeyException";
+  // The transport normalizes a missing object to a `NoSuchKey`-named error on
+  // both the S3 and presigned paths (a presign 404 → NoSuchKey). `NotFound` is
+  // kept for defense in depth (S3 HEAD-style errors).
+  return (
+    name === "NoSuchKey" || name === "NoSuchKeyException" || name === "NotFound"
+  );
 }
 
 function asStringArray(value: unknown): string[] | undefined {
@@ -34,21 +37,14 @@ function asStringArray(value: unknown): string[] | undefined {
 }
 
 export async function getSignal(opts: GetSignalOptions): Promise<SignalDocument> {
-  // Validate signalType BEFORE any S3 call (acceptance criterion + agent-mitigation).
+  // Validate signalType BEFORE any read (acceptance criterion + agent-mitigation).
   assertSignalType(opts.signalType);
 
-  const client = getS3Client(opts.entity);
   const key = `signals/${opts.signalType}/${opts.signalId}.md`;
 
   let body: string;
   try {
-    const response = await client.send(
-      new GetObjectCommand({
-        Bucket: opts.entity.bucketName,
-        Key: key,
-      }),
-    );
-    body = await streamToString(response.Body);
+    body = await readObjectText(opts, key);
   } catch (err) {
     if (isNoSuchKey(err)) {
       throw new SignalNotFoundError(key);

package/src/signals/internals.ts

@@ -1,15 +1,34 @@
 /**
  * Internal helpers shared between signals/list.ts and signals/get.ts.
  *
- * Independent S3 client factory hook (separate from sources/internals.ts)
- * so signals tests can swap their stub without disturbing sources tests.
- * Production code never calls the setter.
+ * Two transports back the read surface (see sources/internals.ts for the full
+ * rationale): the presigned-URL path (a vault client + a company vault, cmp_*)
+ * and the direct-S3 path (no vault client, or a personal vault prs_*). The
+ * direct-S3 path goes through `getS3Client`, whose factory hook is independent
+ * from sources/internals.ts so signals tests can swap their stub without
+ * disturbing sources tests.
  */
 
-import { S3Client } from "@aws-sdk/client-s3";
+import {
+  S3Client,
+  GetObjectCommand,
+  ListObjectsV2Command,
+} from "@aws-sdk/client-s3";
 import type { EntityContext } from "../types.js";
+import { PresignObjectIO, type PresignTransportClient } from "../object-io.js";
 
 function defaultFactory(ctx: EntityContext): S3Client {
+  if (!ctx.credentials) {
+    // The direct-S3 read path needs STS creds. A credential-less context only
+    // exists on the presign path (HQ-59 company vend-skip), which reads via the
+    // vault list/presign endpoints, not this S3 client — so arriving here with
+    // no creds is a routing bug. Fail loudly rather than 403 opaquely later.
+    throw new Error(
+      `Signals S3 read for ${ctx.uid} requires STS credentials but got a ` +
+        `presign-only context; company presign reads must go through the ` +
+        `vault transport, not getS3Client.`,
+    );
+  }
   return new S3Client({
     region: ctx.region,
     credentials: {
@@ -44,3 +63,133 @@ export async function streamToString(body: unknown): Promise<string> {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
+
+// ---------------------------------------------------------------------------
+// Transport seam (presign for cmp_, direct-S3 otherwise)
+// ---------------------------------------------------------------------------
+
+/** Common shape of every reader's options: an entity + an optional vault client. */
+export interface ReaderTransportOpts {
+  entity: EntityContext;
+  /**
+   * Presign-capable vault client. When supplied and the entity is a company
+   * vault (cmp_*), reads use the presigned-URL transport instead of direct S3.
+   */
+  vault?: PresignTransportClient;
+}
+
+/** Lightweight listed object (transport-agnostic). */
+export interface ListedKey {
+  key: string;
+  size: number;
+  lastModified: Date;
+}
+
+/** True when this read should use the presigned-URL transport. */
+export function usePresign(opts: ReaderTransportOpts): boolean {
+  return opts.vault != null && opts.entity.uid.startsWith("cmp_");
+}
+
+/** A not-found error normalized to the S3 `NoSuchKey` shape callers test for. */
+function noSuchKeyError(key: string): Error {
+  return Object.assign(new Error(`No such key: ${key}`), { name: "NoSuchKey" });
+}
+
+function isNotFound(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return (
+    name === "NoSuchKey" || name === "NoSuchKeyException" || name === "NotFound"
+  );
+}
+
+/**
+ * Read an object's UTF-8 text. Throws a `NoSuchKey`-named error when the object
+ * is absent (both transports), so callers' existing not-found checks work
+ * unchanged.
+ */
+export async function readObjectText(
+  opts: ReaderTransportOpts,
+  key: string,
+): Promise<string> {
+  if (usePresign(opts)) {
+    const io = new PresignObjectIO(opts.vault!, opts.entity.uid);
+    try {
+      const { body } = await io.getObject(key);
+      return body.toString("utf-8");
+    } catch (err) {
+      if (isNotFound(err)) throw noSuchKeyError(key);
+      throw err;
+    }
+  }
+  const client = getS3Client(opts.entity);
+  const res = await client.send(
+    new GetObjectCommand({ Bucket: opts.entity.bucketName, Key: key }),
+  );
+  return streamToString(res.Body);
+}
+
+/** Like {@link readObjectText} but returns null when the object is absent. */
+export async function tryReadObjectText(
+  opts: ReaderTransportOpts,
+  key: string,
+): Promise<string | null> {
+  try {
+    return await readObjectText(opts, key);
+  } catch (err) {
+    if (isNotFound(err)) return null;
+    throw err;
+  }
+}
+
+/**
+ * List one page of objects under `prefix`.
+ *
+ * Under the presigned transport the vault `list` endpoint is ACL-filtered and
+ * controls page size server-side, so `limit` is advisory — paginate via the
+ * returned `nextToken` (the opaque vault cursor) until it is undefined. Under
+ * direct S3, `limit` maps to `MaxKeys`.
+ */
+export async function listObjects(
+  opts: ReaderTransportOpts,
+  prefix: string,
+  page: { limit?: number; continuationToken?: string },
+): Promise<{ contents: ListedKey[]; nextToken?: string }> {
+  if (usePresign(opts)) {
+    const io = new PresignObjectIO(opts.vault!, opts.entity.uid);
+    const res = await io.listObjects({
+      prefix,
+      continuationToken: page.continuationToken,
+    });
+    return {
+      contents: res.objects.map((o) => ({
+        key: o.key,
+        size: o.size,
+        lastModified: o.lastModified,
+      })),
+      nextToken: res.nextContinuationToken,
+    };
+  }
+  const client = getS3Client(opts.entity);
+  const res = await client.send(
+    new ListObjectsV2Command({
+      Bucket: opts.entity.bucketName,
+      Prefix: prefix,
+      MaxKeys: page.limit,
+      ContinuationToken: page.continuationToken,
+    }),
+  );
+  const contents: ListedKey[] = [];
+  for (const obj of res.Contents ?? []) {
+    if (!obj.Key) continue;
+    contents.push({
+      key: obj.Key,
+      size: obj.Size ?? 0,
+      lastModified: obj.LastModified ?? new Date(0),
+    });
+  }
+  return {
+    contents,
+    nextToken: res.IsTruncated ? res.NextContinuationToken : undefined,
+  };
+}

package/src/signals/list.test.ts

@@ -6,7 +6,7 @@
  * @aws-sdk/client-s3.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import {
   GetObjectCommand,
   ListObjectsV2Command,
@@ -17,6 +17,8 @@ import {
   _setSignalsS3Factory,
   _resetSignalsS3Factory,
 } from "./internals.js";
+import type { PresignTransportClient } from "../object-io.js";
+import type { VaultListedObject } from "../vault-client.js";
 import type { EntityContext } from "../types.js";
 import { InvalidSignalTypeError, SIGNAL_TYPES } from "../schemas/signal-types.js";
 
@@ -281,3 +283,114 @@ describe("listSignals", () => {
     expect(observed.commands).toHaveLength(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Presigned transport (vault client + company vault) — HQ-59
+// ---------------------------------------------------------------------------
+
+interface PresignVaultStub {
+  vault: PresignTransportClient;
+  listCalls: Array<{ prefix?: string; cursor?: string }>;
+}
+
+function makePresignVault(
+  page: { objects: VaultListedObject[]; cursor: string | null },
+  contents: Record<string, string> = {},
+): PresignVaultStub {
+  const listCalls: Array<{ prefix?: string; cursor?: string }> = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      const key = new URL(url).searchParams.get("key") ?? "";
+      const c = contents[key];
+      if (c === undefined) return new Response(null, { status: 404 });
+      return new Response(Buffer.from(c, "utf-8"), { status: 200 });
+    }),
+  );
+  const vault: PresignTransportClient = {
+    presign: async (input) => ({
+      results: input.keys.map((k) => ({
+        key: k.key,
+        op: k.op ?? input.op ?? "get",
+        url: `https://signed.example/?key=${encodeURIComponent(k.key)}`,
+      })),
+      expiresAt: "2099-01-01T00:00:00.000Z",
+    }),
+    listFiles: async (_company, prefix, cursor) => {
+      listCalls.push({ prefix, cursor });
+      return {
+        objects: page.objects,
+        cursor: page.cursor,
+        truncated: page.cursor != null,
+      };
+    },
+  };
+  return { vault, listCalls };
+}
+
+function listed(key: string): VaultListedObject {
+  return {
+    key,
+    size: 10,
+    lastModified: "2026-03-15T15:00:00.000Z",
+    etag: "etag",
+    permission: "read",
+  };
+}
+
+describe("listSignals — presigned transport (vault + cmp_)", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("lists via the ACL-filtered vault endpoint and never touches S3", async () => {
+    _setSignalsS3Factory(
+      () =>
+        ({
+          send: async () => {
+            throw new Error("S3 must not be used on the presign path");
+          },
+        }) as unknown as S3Client,
+    );
+    const { vault, listCalls } = makePresignVault({
+      objects: [listed("signals/action_item/foo.md")],
+      cursor: null,
+    });
+
+    const res = await listSignals({
+      entity: ENTITY,
+      signalType: "action_item",
+      vault,
+    });
+
+    expect(res.entries.map((e) => e.signalId)).toEqual(["foo"]);
+    expect(res.entries[0].key).toBe("signals/action_item/foo.md");
+    expect(res.nextToken).toBeUndefined();
+    expect(listCalls[0].prefix).toBe("signals/action_item/");
+  });
+
+  it("surfaces the opaque vault cursor as nextToken", async () => {
+    const { vault } = makePresignVault({
+      objects: [listed("signals/action_item/foo.md")],
+      cursor: "OPAQUE_CURSOR",
+    });
+    const res = await listSignals({
+      entity: ENTITY,
+      signalType: "action_item",
+      vault,
+    });
+    expect(res.nextToken).toBe("OPAQUE_CURSOR");
+  });
+
+  it("includeFrontmatter surfaces sourceRef via a presigned GET", async () => {
+    const { vault } = makePresignVault(
+      { objects: [listed("signals/action_item/foo.md")], cursor: null },
+      { "signals/action_item/foo.md": ACTION_ITEM_MD },
+    );
+    const res = await listSignals({
+      entity: ENTITY,
+      signalType: "action_item",
+      includeFrontmatter: true,
+      vault,
+    });
+    expect(res.entries[0].sourceRef).toBe("abc-meeting-001");
+  });
+});

package/src/signals/list.ts

@@ -6,12 +6,8 @@
  * `includeFrontmatter: true` (otherwise the field is undefined).
  */
 
-import {
-  GetObjectCommand,
-  ListObjectsV2Command,
-} from "@aws-sdk/client-s3";
 import { assertSignalType } from "../schemas/signal-types.js";
-import { getS3Client, streamToString } from "./internals.js";
+import { listObjects, readObjectText } from "./internals.js";
 import { parseFrontmatter } from "./parse.js";
 import type {
   ListSignalsOptions,
@@ -31,44 +27,35 @@ function deriveSignalId(key: string, prefix: string): string | null {
 }
 
 export async function listSignals(opts: ListSignalsOptions): Promise<ListSignalsResult> {
-  // Validate signalType BEFORE any S3 call (acceptance criterion + agent-mitigation).
+  // Validate signalType BEFORE any read (acceptance criterion + agent-mitigation).
   assertSignalType(opts.signalType);
 
-  const client = getS3Client(opts.entity);
   const prefix = `signals/${opts.signalType}/`;
 
-  const response = await client.send(
-    new ListObjectsV2Command({
-      Bucket: opts.entity.bucketName,
-      Prefix: prefix,
-      MaxKeys: opts.limit,
-      ContinuationToken: opts.continuationToken,
-    }),
-  );
+  // Presign transport ACL-filters server-side and controls page size, so
+  // `limit` is advisory there; under direct S3 it maps to MaxKeys. Paginate via
+  // the returned nextToken regardless of transport.
+  const page = await listObjects(opts, prefix, {
+    limit: opts.limit,
+    continuationToken: opts.continuationToken,
+  });
 
   const entries: SignalSummary[] = [];
-  for (const obj of response.Contents ?? []) {
-    if (!obj.Key) continue;
-    const signalId = deriveSignalId(obj.Key, prefix);
+  for (const obj of page.contents) {
+    const signalId = deriveSignalId(obj.key, prefix);
     if (!signalId) continue;
 
     const summary: SignalSummary = {
       signalId,
       signalType: opts.signalType,
-      key: obj.Key,
-      lastModified: obj.LastModified ?? new Date(0),
-      size: obj.Size ?? 0,
+      key: obj.key,
+      lastModified: obj.lastModified,
+      size: obj.size,
     };
 
     if (opts.includeFrontmatter) {
       try {
-        const get = await client.send(
-          new GetObjectCommand({
-            Bucket: opts.entity.bucketName,
-            Key: obj.Key,
-          }),
-        );
-        const text = await streamToString(get.Body);
+        const text = await readObjectText(opts, obj.key);
         const fm = parseFrontmatter(text);
         if (fm) {
           summary.frontmatter = fm;
@@ -87,6 +74,6 @@ export async function listSignals(opts: ListSignalsOptions): Promise<ListSignals
 
   return {
     entries,
-    nextToken: response.IsTruncated ? response.NextContinuationToken : undefined,
+    nextToken: page.nextToken,
   };
 }

package/src/signals/types.ts

@@ -9,6 +9,7 @@
 
 import type { SignalType } from "../schemas/signal-types.js";
 import type { EntityContext } from "../types.js";
+import type { PresignTransportClient } from "../object-io.js";
 
 /**
  * Lightweight summary returned by listSignals(). `frontmatter` and
@@ -53,12 +54,23 @@ export interface SignalDocument {
 export interface ListSignalsOptions {
   entity: EntityContext;
   signalType: SignalType;
-  /** Max keys per page; defaults to S3 default (1000). */
+  /**
+   * Max keys per page. Under direct S3 this maps to `MaxKeys`; under the
+   * presigned transport ({@link vault} + a company vault) it is advisory — the
+   * vault `list` endpoint controls page size server-side. Defaults to the S3
+   * default (1000) on the direct path.
+   */
   limit?: number;
   /** Opaque continuation token returned by a prior page. */
   continuationToken?: string;
   /** When true, fetches+parses each entry's frontmatter (extra GETs). */
   includeFrontmatter?: boolean;
+  /**
+   * Presign-capable vault client. When supplied and {@link entity} is a company
+   * vault (cmp_*), reads use the presigned-URL transport (ACL-filtered, no
+   * direct S3). Personal vaults and the absent-client path stay on direct S3.
+   */
+  vault?: PresignTransportClient;
 }
 
 export interface ListSignalsResult {
@@ -71,4 +83,9 @@ export interface GetSignalOptions {
   entity: EntityContext;
   signalType: SignalType;
   signalId: string;
+  /**
+   * Presign-capable vault client. When supplied and {@link entity} is a company
+   * vault (cmp_*), reads use the presigned-URL transport (no direct S3).
+   */
+  vault?: PresignTransportClient;
 }