@indigoai-us/hq-cloud 6.11.5 → 6.11.6

package/src/bin/sync-runner.ts

@@ -98,8 +98,10 @@ import type { UploadAuthor } from "../s3.js";
 import {
   setObjectIOFactory,
   presignObjectIOFactory,
+  type ObjectIOFactory,
   type PresignTransportClient,
 } from "../object-io.js";
+import { HQ_CLOUD_VERSION } from "../version.js";
 import { collectAndSendTelemetry } from "../telemetry.js";
 import { collectAndSendSkillTelemetry } from "../skill-telemetry.js";
 import { reindexAfterSync } from "../qmd-reindex.js";
@@ -227,34 +229,34 @@ export function resolveSkipPersonal(flag: boolean): boolean {
 }
 
 /**
- * Decide whether this session uses the presigned-URL transport.
+ * Resolve the object-transport factory for this sync session.
  *
- * GA (2026-06-11): the presigned-URL transport is now the DEFAULT for every
- * account — the staged per-domain rollout (getindigo.ai pilot → gmail.com /
- * vyg.ai / amass.com batch 2) is complete. The transport only NARROWS client
- * privilege: the client holds no raw AWS credentials (it just fetches signed
- * URLs) and every upload is validated server-side via the vault API, so it is
- * safe as the universal default.
+ * Company vaults (`cmp_*`) ALWAYS use the presigned-URL transport: the client
+ * holds no raw AWS credentials (it fetches short-lived signed URLs) and every
+ * read/write is authorized server-side per-file, so it never hits the 2048-char
+ * STS session-policy ceiling that produced the HQ-59 lockout. The STS-direct-S3
+ * (`S3SdkObjectIO`) path for company vaults is RETIRED — there is no env
+ * override or rollback lever that can route a company vault back to direct S3.
+ * (The former `HQ_SYNC_PRESIGN_TRANSPORT` kill-switch is gone with this change.)
  *
- * `HQ_SYNC_PRESIGN_TRANSPORT` still overrides in both directions
- * (`1`/`true`/`yes`/`on` → force on, `0`/`false`/`no`/`off` → force off), so
- * an individual account can be rolled back to the STS-direct path WITHOUT a
- * redeploy if a regression surfaces. An unset/blank or unrecognized override
- * falls through to the GA default (on).
+ * Personal vaults (`prs_*`) KEEP the direct-S3/STS path: the membership-gated
+ * `list`/`presign` endpoints 403 for the membership-less vend-self model, and a
+ * single-owner personal vault has no ACL-scale problem. That cmp_/prs_ split
+ * lives inside {@link presignObjectIOFactory}.
  *
- * `email` is retained in the signature for the override contract and so the
- * gate can be re-narrowed to a domain set in future without touching the call
- * site; it is intentionally unused while the transport is GA.
+ * Returns `null` only when the client predates the presign methods (never in a
+ * shipped build); the caller then resets to the SDK default factory.
  */
-export function resolvePresignTransport(
-  email: string | undefined,
-  override: string | undefined,
-): boolean {
-  void email;
-  const o = (override ?? "").trim().toLowerCase();
-  if (o === "1" || o === "true" || o === "yes" || o === "on") return true;
-  if (o === "0" || o === "false" || o === "no" || o === "off") return false;
-  return true;
+export function selectObjectIOFactory(
+  client: Partial<PresignTransportClient>,
+): ObjectIOFactory | null {
+  if (
+    typeof client.presign === "function" &&
+    typeof client.listFiles === "function"
+  ) {
+    return presignObjectIOFactory(client as PresignTransportClient);
+  }
+  return null;
 }
 
 // Personal-vault scope (exclusion list + path computer) lives in
@@ -925,10 +927,18 @@ export async function runRunner(
   }
 
   // ---- vault client -----------------------------------------------------
+  // Stamp clientInfo so every vault request (incl. /sts/vend) carries
+  // x-hq-client-name=hq-sync + x-hq-client-version=<hq-cloud version>. The
+  // company-vend min-version gate (HQ-59, hq-pro) uses this to recognize a
+  // compliant (>= 6.11.6) sync-runner and NOT force-upgrade it — the
+  // belt-and-suspenders companion to skipping the cmp_ vend on the presign
+  // path. Version is the hq-cloud package version (what the gate compares to
+  // its floor), not the desktop app version.
   const vaultConfig: VaultServiceConfig = {
     apiUrl: DEFAULT_VAULT_API_URL,
     authToken: getAccessToken,
     region: DEFAULT_COGNITO.region,
+    clientInfo: { name: "hq-sync", version: HQ_CLOUD_VERSION },
   };
   const client =
     deps.createVaultClient?.(vaultConfig) ?? new VaultClient(vaultConfig);
@@ -949,32 +959,29 @@ export async function runRunner(
       ? { userSub: claims.sub, email: claims.email }
       : undefined;
 
-  // ---- transport selection (presigned-URL vs STS-direct-S3) -------------
-  // The presigned-URL transport (vault `list` + `presign` endpoints) is now
-  // the GA default for every account. The STS-direct-S3 path (STS-vended
-  // credentials + direct S3 SDK) remains the fallback only when an account is
-  // force-disabled via HQ_SYNC_PRESIGN_TRANSPORT or the client build predates
-  // the presign methods. The gate runs ONCE here — every s3.ts call in this
-  // session's fanout resolves through the installed factory.
-  // HQ_SYNC_PRESIGN_TRANSPORT is an explicit override (1/true → force on,
-  // 0/false → force off) for testing or emergency rollback without a redeploy.
-  // Setting the factory unconditionally (even to the default) keeps the choice
+  // ---- transport selection (presigned-URL for cmp_, direct-S3/STS for prs_) -
+  // Company vaults ALWAYS use the presigned-URL transport now (HQ-59): the
+  // STS-direct-S3 path for cmp_ is retired — no env override routes a company
+  // vault back to direct S3. Personal vaults keep direct-S3 inside the factory
+  // (the cmp_/prs_ split lives in presignObjectIOFactory). selectObjectIOFactory
+  // runs ONCE here — every s3.ts call in this session's fanout resolves through
+  // the installed factory. Setting it unconditionally (even to null, which the
+  // default S3 SDK factory backs for a pre-presign client) keeps the choice
   // deterministic if a prior run mutated module state.
   const presignCapable = client as Partial<PresignTransportClient>;
-  if (
-    resolvePresignTransport(
-      claims?.email,
-      process.env.HQ_SYNC_PRESIGN_TRANSPORT,
-    ) &&
-    typeof presignCapable.presign === "function" &&
-    typeof presignCapable.listFiles === "function"
-  ) {
-    setObjectIOFactory(
-      presignObjectIOFactory(presignCapable as PresignTransportClient),
-    );
-  } else {
-    setObjectIOFactory(null);
-  }
+  const objectIOFactory = selectObjectIOFactory(presignCapable);
+  setObjectIOFactory(objectIOFactory);
+  // HQ-59 vend-skip: when company vaults run over the presign transport (the
+  // shipped case — selectObjectIOFactory only returns null for a pre-presign
+  // client), tell resolveEntityContext to SKIP `POST /sts/vend` for cmp_
+  // contexts. Two reasons, both load-bearing: (1) the presign transport never
+  // reads STS creds, so the vend is dead weight; (2) a compliant sync-runner
+  // must not call the company vend route at all — its presence is the
+  // pre-6.11.6 signal the hq-pro min-version gate denies on. Gated on the SAME
+  // value that picks the transport, so the vend-skip and the transport can
+  // never diverge. If the factory is null (S3 SDK fallback), cmp_ keeps vending
+  // because S3SdkObjectIO needs the creds. Personal vaults always vend self.
+  vaultConfig.companyVaultUsesPresign = objectIOFactory !== null;
 
   // ---- resolve targets --------------------------------------------------
   let memberships: Pick<Membership, "companyUid">[];

package/src/context.test.ts

@@ -119,7 +119,7 @@ describe("resolveEntityContext", () => {
 
     expect(ctx.uid).toBe("cmp_01ABCDEF");
     expect(ctx.bucketName).toBe("hq-vault-acme-123");
-    expect(ctx.credentials.accessKeyId).toBe("ASIA_TEST_KEY");
+    expect(ctx.credentials?.accessKeyId).toBe("ASIA_TEST_KEY");
     expect(ctx.region).toBe("us-east-1");
 
     // Verify entity lookup used the new per-user-namespace endpoint
@@ -327,6 +327,144 @@ describe("routing by UID prefix and vend-self dispatch", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// HQ-59 company vend-skip (presign transport)
+//
+// When the run uses the presigned-URL transport for company vaults
+// (`companyVaultUsesPresign`), resolveEntityContext must NOT call the company
+// `/sts/vend` route — the presign transport needs no STS creds, and the mere
+// presence of a cmp_ vend call is the pre-6.11.6 signal the hq-pro min-version
+// gate denies on. Personal vaults must still vend self.
+// ---------------------------------------------------------------------------
+describe("HQ-59 company vend-skip (companyVaultUsesPresign)", () => {
+  const presignConfig: VaultServiceConfig = {
+    ...mockConfig,
+    companyVaultUsesPresign: true,
+  };
+
+  beforeEach(() => {
+    clearContextCache();
+    vi.restoreAllMocks();
+  });
+
+  it("cmp_* UID: SKIPS /sts/vend, returns no credentials + a far-future expiry", async () => {
+    const calls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation(async (url: string) => {
+        const u = String(url);
+        calls.push(u);
+        if (u.includes("/entity/cmp_")) {
+          return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+        }
+        // If a vend ever fires, surface it as a hard failure so the test fails
+        // LOUDLY rather than silently allowing the route the gate watches.
+        if (u.includes("/sts/vend")) {
+          return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+        }
+        return { ok: false, status: 404, text: async () => "Not found" };
+      }),
+    );
+
+    const ctx = await resolveEntityContext("cmp_01ABCDEF", presignConfig);
+
+    // The load-bearing assertion: NO company vend route was hit.
+    expect(calls.some((u) => u.includes("/sts/vend"))).toBe(false);
+    expect(calls.some((u) => u.includes("/entity/cmp_01ABCDEF"))).toBe(true);
+    // Credential-less context with a sentinel far-future expiry → never re-vends.
+    expect(ctx.credentials).toBeUndefined();
+    expect(ctx.bucketName).toBe(mockEntity.bucketName);
+    expect(isExpiringSoon(ctx.expiresAt)).toBe(false);
+  });
+
+  it("company slug: SKIPS /sts/vend after the namespace + entity lookup", async () => {
+    const calls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation(async (url: string) => {
+        const u = String(url);
+        calls.push(u);
+        if (u.includes("/entity/check-slug/me")) {
+          return {
+            ok: true,
+            status: 200,
+            json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+            text: async () => "",
+          };
+        }
+        if (u.includes(`/entity/${mockEntity.uid}`)) {
+          return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+        }
+        if (u.includes("/sts/vend")) {
+          return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+        }
+        return { ok: false, status: 404, text: async () => "Not found" };
+      }),
+    );
+
+    const ctx = await resolveEntityContext("acme", presignConfig);
+
+    expect(calls.some((u) => u.includes("/sts/vend"))).toBe(false);
+    expect(ctx.credentials).toBeUndefined();
+  });
+
+  it("prs_* UID: STILL vends self even with the company flag set", async () => {
+    const prsEntity = {
+      uid: "prs_01PERSON",
+      slug: "test-person",
+      bucketName: "hq-vault-prs-01person",
+      status: "active",
+    };
+    const calls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation(async (url: string) => {
+        const u = String(url);
+        calls.push(u);
+        if (u.includes("/entity/prs_")) {
+          return { ok: true, status: 200, json: async () => ({ entity: prsEntity }), text: async () => "" };
+        }
+        if (u.includes("/sts/vend-self")) {
+          return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+        }
+        return { ok: false, status: 404, text: async () => "Not found" };
+      }),
+    );
+
+    const ctx = await resolveEntityContext("prs_01PERSON", presignConfig);
+
+    const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
+    expect(vendCalls).toHaveLength(1);
+    expect(vendCalls[0]).toContain("/sts/vend-self");
+    expect(ctx.credentials?.accessKeyId).toBe(mockVendResponse.credentials.accessKeyId);
+  });
+
+  it("flag OFF (default): cmp_* still vends — no behavior change without the flag", async () => {
+    const calls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation(async (url: string) => {
+        const u = String(url);
+        calls.push(u);
+        if (u.includes("/entity/cmp_")) {
+          return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+        }
+        if (u.includes("/sts/vend")) {
+          return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+        }
+        return { ok: false, status: 404, text: async () => "Not found" };
+      }),
+    );
+
+    const ctx = await resolveEntityContext("cmp_01ABCDEF", mockConfig);
+
+    const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
+    expect(vendCalls).toHaveLength(1);
+    expect(vendCalls[0]).toContain("/sts/vend");
+    expect(ctx.credentials?.accessKeyId).toBe(mockVendResponse.credentials.accessKeyId);
+  });
+});
+
 describe("refreshEntityContext", () => {
   beforeEach(() => {
     clearContextCache();

package/src/context.ts

@@ -15,6 +15,14 @@ const REFRESH_THRESHOLD_MS = 2 * 60 * 1000;
 /** STS session duration requested from vault-service (15 minutes). */
 const DEFAULT_SESSION_DURATION_SECONDS = 900;
 
+/**
+ * `expiresAt` stamped on a presign-only company context (HQ-59). No STS vend
+ * happened, so there is nothing to expire — a far-future sentinel keeps
+ * `isExpiringSoon` false forever, so the auto-refresh path never re-vends (and
+ * thus never re-hits) the company `/sts/vend` route the gate keys on.
+ */
+const PRESIGN_NO_VEND_EXPIRES_AT = "9999-12-31T23:59:59.000Z";
+
 /**
  * Cached contexts.
  *
@@ -78,6 +86,12 @@ export const KNOWN_UID_PREFIXES = ["cmp_", "prs_"] as const;
  *
  * Caches the result and auto-refreshes when the credentials are within
  * 2 minutes of expiry.
+ *
+ * HQ-59: when `config.companyVaultUsesPresign` is set, COMPANY (`cmp_*`)
+ * contexts skip the `POST /sts/vend` call and come back credential-less with a
+ * far-future expiry — the presign transport needs no STS creds, and skipping
+ * the vend keeps a compliant sync-runner off the company vend route. Personal
+ * (`prs_*`) contexts always vend self.
  */
 export async function resolveEntityContext(
   companyUidOrSlug: string,
@@ -122,26 +136,54 @@ export async function resolveEntityContext(
     );
   }
 
-  // Step 2: Dispatch credential vending by UID prefix.
+  // Step 2: Dispatch credential vending by RESOLVED-uid prefix.
   //   cmp_* → POST /sts/vend      (company path; membership-gated)
   //   prs_* → POST /sts/vend-self (person path; self-ownership-gated)
-  //   slug  → POST /sts/vend      (legacy slug path is company-only)
-  const vendResult = looksLikePerson
-    ? await vendSelfCredentials(entity.uid, config)
-    : await vendCredentials(entity.uid, config);
+  //   slug  → resolves to a cmp_* (the slug path is company-only)
+  //
+  // HQ-59 vend-skip: when the run uses the presigned-URL transport for company
+  // vaults, a `cmp_*` context needs no STS creds (the presign transport
+  // authorizes every object server-side) AND a compliant sync-runner must not
+  // call the company `/sts/vend` route at all — its mere presence is the
+  // pre-6.11.6 signal the hq-pro min-version gate denies on. So skip the vend
+  // entirely and return a credential-less context with a sentinel expiry. The
+  // discriminator is the RESOLVED entity uid (`cmp_`), the exact same prefix
+  // `presignObjectIOFactory` uses to route to `PresignObjectIO` — so the
+  // vend-skip and the transport choice can never disagree. Personal vaults
+  // (`prs_*`) always vend self.
+  const isCompanyEntity = entity.uid.startsWith("cmp_");
+  const skipCompanyVend =
+    config.companyVaultUsesPresign === true && isCompanyEntity;
 
-  const ctx: EntityContext = {
-    uid: entity.uid,
-    slug: entity.slug,
-    bucketName: entity.bucketName,
-    region: config.region ?? "us-east-1",
-    credentials: {
-      accessKeyId: vendResult.credentials.accessKeyId,
-      secretAccessKey: vendResult.credentials.secretAccessKey,
-      sessionToken: vendResult.credentials.sessionToken,
-    },
-    expiresAt: vendResult.expiresAt,
-  };
+  let ctx: EntityContext;
+  if (skipCompanyVend) {
+    ctx = {
+      uid: entity.uid,
+      slug: entity.slug,
+      bucketName: entity.bucketName,
+      region: config.region ?? "us-east-1",
+      // No STS vend on the presign path — see PRESIGN_NO_VEND_EXPIRES_AT.
+      credentials: undefined,
+      expiresAt: PRESIGN_NO_VEND_EXPIRES_AT,
+    };
+  } else {
+    const vendResult = looksLikePerson
+      ? await vendSelfCredentials(entity.uid, config)
+      : await vendCredentials(entity.uid, config);
+
+    ctx = {
+      uid: entity.uid,
+      slug: entity.slug,
+      bucketName: entity.bucketName,
+      region: config.region ?? "us-east-1",
+      credentials: {
+        accessKeyId: vendResult.credentials.accessKeyId,
+        secretAccessKey: vendResult.credentials.secretAccessKey,
+        sessionToken: vendResult.credentials.sessionToken,
+      },
+      expiresAt: vendResult.expiresAt,
+    };
+  }
 
   // Cache by UID (globally unique) and — if the caller asked by slug —
   // by `(callerSub, slug)` so the same slug can resolve to different

package/src/entity-resolver.test.ts

@@ -171,9 +171,9 @@ describe("resolveEntity", () => {
     expect(ctx.slug).toBe("indigo");
     expect(ctx.bucketName).toBe("hq-vault-indigo");
     expect(ctx.region).toBe("us-east-1");
-    expect(ctx.credentials.accessKeyId).toBe("ASIAMOCK000000000001");
-    expect(ctx.credentials.secretAccessKey).toBe("mockSecret");
-    expect(ctx.credentials.sessionToken).toBe("mockSession");
+    expect(ctx.credentials?.accessKeyId).toBe("ASIAMOCK000000000001");
+    expect(ctx.credentials?.secretAccessKey).toBe("mockSecret");
+    expect(ctx.credentials?.sessionToken).toBe("mockSession");
     expect(ctx.expiresAt).toBeTruthy();
   });
 

package/src/object-io.ts

@@ -199,6 +199,18 @@ export class S3SdkObjectIO implements ObjectIO {
 
   constructor(ctx: EntityContext) {
     this.bucket = ctx.bucketName;
+    if (!ctx.credentials) {
+      // A credential-less context only exists on the presign path (HQ-59
+      // company vaults skip the STS vend). Such a context must route through
+      // PresignObjectIO, never here — reaching the direct-S3 transport with no
+      // creds is a routing bug, so fail loudly instead of building a broken
+      // S3 client that would later 403 with an opaque AWS error.
+      throw new Error(
+        `S3SdkObjectIO requires STS credentials but got a presign-only ` +
+          `context for ${ctx.uid}; company presign contexts must use ` +
+          `PresignObjectIO. This is a transport-routing bug.`,
+      );
+    }
     this.client = new S3Client({
       region: ctx.region,
       credentials: {

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);