@indigoai-us/hq-cloud 6.11.5 → 6.11.7

package/src/cli/tombstones.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared FILE_TOMBSTONE fetch used by BOTH the pull planner (`sync.ts`) and the
+ * push planner (`share.ts`).
+ *
+ * A FILE_TOMBSTONE is the authoritative record of an intentional, scoped delete
+ * (`hq files delete <prefix>` → `POST /v1/files/delete` → `recordDeletions`).
+ * Both sync legs consult it so a deleted key is neither re-downloaded (pull) nor
+ * re-uploaded (push) and therefore cannot be resurrected by a behind peer.
+ *
+ * Lives in its own module so `share.ts` can use the fetch without importing from
+ * `sync.ts` — `sync.ts` already imports values from `share.ts`
+ * (`isEphemeralPath`, `isMalformedVaultKey`), so the reverse value-import would
+ * create a runtime ESM cycle.
+ */
+
+import type { VaultServiceConfig } from "../types.js";
+import { toPosixKey } from "../s3.js";
+
+/** Timeout for the best-effort FILE_TOMBSTONE fetch (GET /v1/files/tombstones). */
+export const FETCH_TOMBSTONES_TIMEOUT_MS = 5000;
+
+/**
+ * A FILE_TOMBSTONE as the planners need it: the deleted key + when it was
+ * deleted. The `deletedAt` timestamp is the decisive precedence signal on the
+ * pull side — a remote object newer than it is a genuine re-create (sync it), an
+ * object at or older than it is a stale resurrection of a deleted key (suppress
+ * it).
+ */
+export interface CompanyTombstone {
+  deletedAt: string;
+}
+
+/**
+ * Fetch the company's FILE_TOMBSTONE rows from hq-pro (GET /v1/files/tombstones)
+ * and return them as a POSIX-keyed map the planners consult to avoid
+ * resurrecting an intentionally-deleted object (delete-resync). The endpoint is
+ * ACL-filtered server-side, so the map only ever contains keys this caller can
+ * read — exactly the keys that can appear in the (STS-scoped) remote LIST.
+ *
+ * Best-effort and bounded by a 5s timeout: a tombstone read that fails, times
+ * out, or returns non-2xx degrades to an EMPTY map — i.e. to the pre-fix
+ * behavior (no suppression). That is the safe failure direction: a missed
+ * tombstone re-pulls/re-pushes a deleted file (a known, recoverable annoyance),
+ * whereas a spurious tombstone would HIDE a file the user wants. The failure is
+ * logged (never silently swallowed) so a persistently-degraded read is visible.
+ */
+export async function fetchCompanyTombstones(
+  vaultConfig: VaultServiceConfig,
+  companyUid: string,
+): Promise<Map<string, CompanyTombstone>> {
+  const out = new Map<string, CompanyTombstone>();
+  try {
+    const token =
+      typeof vaultConfig.authToken === "function"
+        ? await vaultConfig.authToken()
+        : vaultConfig.authToken;
+    const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+    const url = `${base}/v1/files/tombstones?company=${encodeURIComponent(
+      companyUid,
+    )}`;
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      FETCH_TOMBSTONES_TIMEOUT_MS,
+    );
+    try {
+      const res = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${token}` },
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        // Non-2xx is non-fatal: log and degrade to no-suppression. A 404 means
+        // the endpoint is not deployed yet (hq-pro release lag) — the sync
+        // proceeds with the legacy behavior until it lands.
+        console.error(
+          `[hq-sync] tombstone fetch returned ${res.status} (degrading to no-suppression)`,
+        );
+        return out;
+      }
+      const body = (await res.json()) as {
+        tombstones?: Array<{ key?: string; deletedAt?: string }>;
+      };
+      for (const t of body.tombstones ?? []) {
+        if (typeof t.key === "string" && typeof t.deletedAt === "string") {
+          out.set(toPosixKey(t.key), { deletedAt: t.deletedAt });
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    // Best-effort: a failed tombstone read must never break the sync. Log
+    // (policy: never silently swallow) and degrade to no-suppression.
+    try {
+      console.error(
+        `[hq-sync] tombstone fetch failed (non-fatal, degrading to no-suppression): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    } catch {
+      // swallow — logging must never break sync
+    }
+  }
+  return out;
+}

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/index.ts

@@ -142,8 +142,10 @@ export type { PullScope, PullScopeClient } from "./sync/pull-scope.js";
 export {
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
   PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
+  CONTINUITY_POINTER_REL,
   computePersonalVaultPaths,
   computePersonalCompanySubdirs,
+  computeContinuityPointerPaths,
 } from "./personal-vault.js";
 export type { PersonalVaultOptions } from "./personal-vault.js";
 

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/personal-vault.test.ts

@@ -16,8 +16,10 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import {
+  computeContinuityPointerPaths,
   computePersonalCompanySubdirs,
   computePersonalVaultPaths,
+  CONTINUITY_POINTER_REL,
   PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
 } from "./personal-vault.js";
@@ -347,3 +349,176 @@ describe("personal-vault helpers", () => {
     ).toBe(false);
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────
+// DEV-1778 — session-continuity pointer carve-out.
+//
+// `workspace/` is in PERSONAL_VAULT_EXCLUDED_TOP_LEVEL (machine-local by
+// design). The ONE exception is the session pointer
+// `workspace/threads/handoff.json` + the single thread file it references via
+// `thread_path`, so a `/handoff` on one machine reaches a second machine.
+// Mirrors the companies/manifest.yaml special-case: a narrow file-level
+// re-include that never broadens the rest of workspace/.
+// ─────────────────────────────────────────────────────────────────────────
+describe("personal-vault: continuity-pointer carve-out", () => {
+  let hqRoot: string;
+
+  beforeEach(() => {
+    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-cont-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  /** Helper: relative-paths-sorted projection of an absolute-path list. */
+  function rel(abs: string[]): string[] {
+    return abs.map((p) => path.relative(hqRoot, p)).sort();
+  }
+
+  const THREADS = path.join("workspace", "threads");
+
+  /** Write workspace/threads/handoff.json with the given object. */
+  function writeHandoff(obj: unknown, raw?: string): void {
+    const dir = path.join(hqRoot, THREADS);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, "handoff.json"),
+      raw !== undefined ? raw : JSON.stringify(obj),
+    );
+  }
+
+  /** Write a thread file under workspace/threads/ and return its rel path. */
+  function writeThread(name: string): string {
+    const dir = path.join(hqRoot, THREADS);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, name), "{}");
+    return path.join(THREADS, name).split(path.sep).join("/");
+  }
+
+  it("constant: CONTINUITY_POINTER_REL is the canonical pointer path", () => {
+    expect(CONTINUITY_POINTER_REL).toBe("workspace/threads/handoff.json");
+  });
+
+  it("includes handoff.json + the thread file it points to", () => {
+    const threadRel = writeThread("T-20260617-1200-demo.json");
+    writeHandoff({ thread_path: threadRel });
+
+    expect(rel(computeContinuityPointerPaths(hqRoot))).toEqual(
+      [
+        path.join(THREADS, "T-20260617-1200-demo.json"),
+        path.join(THREADS, "handoff.json"),
+      ].sort(),
+    );
+  });
+
+  it("carve-out composes into computePersonalVaultPaths", () => {
+    const threadRel = writeThread("T-20260617-1200-demo.json");
+    writeHandoff({ thread_path: threadRel });
+    fs.mkdirSync(path.join(hqRoot, ".claude"));
+
+    const out = rel(computePersonalVaultPaths(hqRoot));
+    expect(out).toContain(path.join(THREADS, "handoff.json"));
+    expect(out).toContain(path.join(THREADS, "T-20260617-1200-demo.json"));
+    // Sibling top-level dirs still travel; the rest of workspace/ does not.
+    expect(out).toContain(".claude");
+  });
+
+  it("does NOT broaden the rest of workspace/ (siblings/other threads stay local)", () => {
+    const threadRel = writeThread("T-active.json");
+    writeThread("T-old.json"); // an inactive thread — must NOT sync
+    writeHandoff({ thread_path: threadRel });
+    // Unrelated workspace litter that must stay machine-local.
+    fs.mkdirSync(path.join(hqRoot, "workspace", "locks"), { recursive: true });
+    fs.writeFileSync(path.join(hqRoot, "workspace", "locks", "x.lock"), "1");
+    fs.writeFileSync(path.join(hqRoot, "workspace", "threads", "INDEX.md"), "#");
+
+    const out = rel(computePersonalVaultPaths(hqRoot));
+    expect(out).toContain(path.join(THREADS, "handoff.json"));
+    expect(out).toContain(path.join(THREADS, "T-active.json"));
+    expect(out).not.toContain(path.join(THREADS, "T-old.json"));
+    expect(out).not.toContain(path.join(THREADS, "INDEX.md"));
+    expect(out.some((p) => p.startsWith(path.join("workspace", "locks")))).toBe(
+      false,
+    );
+  });
+
+  it("handoff.json present but thread_path absent → only the pointer", () => {
+    writeHandoff({ message: "no pointer field" });
+    expect(rel(computeContinuityPointerPaths(hqRoot))).toEqual([
+      path.join(THREADS, "handoff.json"),
+    ]);
+  });
+
+  it("handoff.json points to a non-existent thread file → only the pointer", () => {
+    writeHandoff({ thread_path: "workspace/threads/T-ghost.json" });
+    expect(rel(computeContinuityPointerPaths(hqRoot))).toEqual([
+      path.join(THREADS, "handoff.json"),
+    ]);
+  });
+
+  it("no handoff.json at all → empty (nothing to carry)", () => {
+    fs.mkdirSync(path.join(hqRoot, THREADS), { recursive: true });
+    expect(computeContinuityPointerPaths(hqRoot)).toEqual([]);
+  });
+
+  it("malformed handoff.json → fail-soft to pointer only (no throw)", () => {
+    writeHandoff(null, "{ this is : not json ]");
+    expect(() => computeContinuityPointerPaths(hqRoot)).not.toThrow();
+    expect(rel(computeContinuityPointerPaths(hqRoot))).toEqual([
+      path.join(THREADS, "handoff.json"),
+    ]);
+  });
+
+  // ── Security: thread_path must never escape workspace/threads/ ──────────
+  it("rejects an absolute thread_path (only the pointer is included)", () => {
+    // Put a real file at the absolute target so the ONLY thing rejecting it
+    // is the containment guard, not a missing-file fallthrough.
+    const evil = path.join(hqRoot, "secret.txt");
+    fs.writeFileSync(evil, "top secret");
+    writeHandoff({ thread_path: evil });
+    expect(rel(computeContinuityPointerPaths(hqRoot))).toEqual([
+      path.join(THREADS, "handoff.json"),
+    ]);
+  });
+
+  it("rejects a traversal thread_path (../../.env) — no smuggling out of threads/", () => {
+    fs.writeFileSync(path.join(hqRoot, ".env"), "SECRET=1");
+    writeHandoff({ thread_path: "workspace/threads/../../.env" });
+    const out = rel(computeContinuityPointerPaths(hqRoot));
+    expect(out).toEqual([path.join(THREADS, "handoff.json")]);
+    expect(out.some((p) => p.endsWith(".env"))).toBe(false);
+  });
+
+  it("rejects a thread_path under workspace/ but outside threads/", () => {
+    fs.mkdirSync(path.join(hqRoot, "workspace", "reports"), {
+      recursive: true,
+    });
+    fs.writeFileSync(
+      path.join(hqRoot, "workspace", "reports", "secret.md"),
+      "x",
+    );
+    writeHandoff({ thread_path: "workspace/reports/secret.md" });
+    expect(rel(computeContinuityPointerPaths(hqRoot))).toEqual([
+      path.join(THREADS, "handoff.json"),
+    ]);
+  });
+
+  it("rejects a symlink that escapes threads/ (realpath containment)", () => {
+    // A thread_path that names an in-threads symlink whose target is OUTSIDE
+    // threads/ must be rejected by the realpath re-check.
+    fs.writeFileSync(path.join(hqRoot, "outside.txt"), "secret");
+    fs.mkdirSync(path.join(hqRoot, THREADS), { recursive: true });
+    const link = path.join(hqRoot, THREADS, "escape.json");
+    try {
+      fs.symlinkSync(path.join(hqRoot, "outside.txt"), link);
+    } catch {
+      // Platform without symlink support — skip the assertion gracefully.
+      return;
+    }
+    writeHandoff({ thread_path: "workspace/threads/escape.json" });
+    expect(rel(computeContinuityPointerPaths(hqRoot))).toEqual([
+      path.join(THREADS, "handoff.json"),
+    ]);
+  });
+});