@indigoai-us/hq-cloud 6.11.11 → 6.11.12

package/src/object-io.ts

@@ -104,6 +104,12 @@ export interface GetObjectResult {
   metadata?: Record<string, string>;
 }
 
+export interface GetObjectStreamResult {
+  body: AsyncIterable<Uint8Array>;
+  /** S3 user metadata (keys lowercased by S3). */
+  metadata?: Record<string, string>;
+}
+
 export interface ListObjectsInput {
   prefix?: string;
   continuationToken?: string;
@@ -137,6 +143,7 @@ export interface HeadObjectResult {
 export interface ObjectIO {
   putObject(input: PutObjectInput): Promise<{ etag: string }>;
   getObject(key: string): Promise<GetObjectResult>;
+  getObjectStream?(key: string): Promise<GetObjectStreamResult>;
   listObjects(input: ListObjectsInput): Promise<ListObjectsResult>;
   deleteObject(key: string): Promise<void>;
   /**
@@ -243,15 +250,23 @@ export class S3SdkObjectIO implements ObjectIO {
     return { etag: res.ETag || "" };
   }
 
-  async getObject(key: string): Promise<GetObjectResult> {
+  async getObjectStream(key: string): Promise<GetObjectStreamResult> {
     const res = await this.client.send(
       new GetObjectCommand({ Bucket: this.bucket, Key: key }),
     );
     if (!res.Body) {
       throw new Error(`Empty response for ${key}`);
     }
-    const body = await drainToBuffer(res.Body as AsyncIterable<Uint8Array>);
-    return { body, metadata: res.Metadata };
+    return {
+      body: res.Body as AsyncIterable<Uint8Array>,
+      metadata: res.Metadata,
+    };
+  }
+
+  async getObject(key: string): Promise<GetObjectResult> {
+    const res = await this.getObjectStream(key);
+    const body = await drainToBuffer(res.body);
+    return { body, metadata: res.metadata };
   }
 
   async listObjects(input: ListObjectsInput): Promise<ListObjectsResult> {
@@ -416,6 +431,19 @@ const PRIME_CONCURRENCY = 4;
 /** Treat a cached URL within this window of expiry as a miss (re-presign). */
 const CACHE_SAFETY_MS = 60_000;
 
+/**
+ * Opt-in gate for strict fail-closed enforcement of fenced presigned PUTs.
+ *
+ * Defaults OFF until the hq-pro files-presign server signs and echoes
+ * If-Match/If-None-Match. While disabled, the presigned transport preserves
+ * today's behavior: replay whatever signed headers the server returned.
+ */
+export const PRESIGN_FENCE_STRICT_ENV_VAR = "HQ_PRESIGN_FENCE_STRICT";
+
+function isPresignFenceStrictEnabled(): boolean {
+  return process.env[PRESIGN_FENCE_STRICT_ENV_VAR] === "true";
+}
+
 interface CacheEntry {
   url: string;
   headers?: Record<string, string>;
@@ -441,6 +469,24 @@ export class RateLimitedError extends Error {
   }
 }
 
+/**
+ * A fenced presigned PUT is only safe if the presign service signed and echoed
+ * the requested conditional header for replay. Missing/mismatched condition
+ * headers mean an older server or a stale primed URL would write
+ * unconditionally, so fail closed and let the caller retry later.
+ */
+export class PresignPreconditionMissingError extends Error {
+  readonly retryable = true;
+
+  constructor(
+    readonly key: string,
+    readonly header: "if-match" | "if-none-match",
+  ) {
+    super(`presigned PUT for ${key} missing required ${header} precondition`);
+    this.name = "PresignPreconditionMissing";
+  }
+}
+
 /**
  * One-way circuit breaker shared across a run's per-company transports. The
  * first 429 (vault rate budget exhausted) trips it; thereafter every UNCACHED
@@ -483,6 +529,7 @@ function isRateLimit(err: unknown): boolean {
  */
 export class PresignObjectIO implements ObjectIO {
   private readonly urlCache = new Map<string, CacheEntry>();
+  private readonly headReuseCache = new Map<string, CacheEntry>();
 
   constructor(
     private readonly vault: PresignTransportClient,
@@ -497,26 +544,45 @@ export class PresignObjectIO implements ObjectIO {
   }
 
   hasPrimedPut(key: string): boolean {
-    return this.cached("put", key) !== undefined;
+    return this.peekCached("put", key) !== undefined;
   }
 
   /** A live (non-expiring) cached URL for op+key, or undefined. */
-  private cached(op: PresignOp, key: string): CacheEntry | undefined {
-    const hit = this.urlCache.get(this.cacheKey(op, key));
+  private peekCached(op: PresignOp, key: string): CacheEntry | undefined {
+    const cacheKey = this.cacheKey(op, key);
+    const hit = this.urlCache.get(cacheKey);
     if (!hit) return undefined;
     if (Date.now() >= hit.expiresAtMs - CACHE_SAFETY_MS) {
-      this.urlCache.delete(this.cacheKey(op, key));
+      this.urlCache.delete(cacheKey);
       return undefined;
     }
     return hit;
   }
 
-  /**
-   * Resolve a presigned URL (+ replay headers) for op+key: cache hit if primed,
-   * else a single presign. Throws on per-key denial (matches the SDK path's
-   * access error). `extra` carries PUT contentType/metadata on the miss path.
-   */
-  private async resolveUrl(
+  /** Return and evict a live cached URL so primed batches are bounded. */
+  private consumeCached(op: PresignOp, key: string): CacheEntry | undefined {
+    const hit = this.peekCached(op, key);
+    if (hit) this.urlCache.delete(this.cacheKey(op, key));
+    return hit;
+  }
+
+  private peekHeadReuse(key: string): CacheEntry | undefined {
+    const hit = this.headReuseCache.get(key);
+    if (!hit) return undefined;
+    if (Date.now() >= hit.expiresAtMs - CACHE_SAFETY_MS) {
+      this.headReuseCache.delete(key);
+      return undefined;
+    }
+    return hit;
+  }
+
+  private consumeHeadReuse(key: string): CacheEntry | undefined {
+    const hit = this.peekHeadReuse(key);
+    if (hit) this.headReuseCache.delete(key);
+    return hit;
+  }
+
+  private async presignSingle(
     op: PresignOp,
     key: string,
     extra?: {
@@ -527,10 +593,6 @@ export class PresignObjectIO implements ObjectIO {
       ifNoneMatch?: "*";
     },
   ): Promise<{ url: string; headers?: Record<string, string> }> {
-    const hit = this.cached(op, key);
-    if (hit) return { url: hit.url, headers: hit.headers };
-    // Primed URLs still serve once the breaker trips (no wire needed); only an
-    // uncached key on an exhausted budget fails fast.
     if (this.breaker.isTripped()) throw new RateLimitedError(key, op);
     let results;
     try {
@@ -550,6 +612,71 @@ export class PresignObjectIO implements ObjectIO {
     return { url: row.url!, headers: row.headers };
   }
 
+  private async resolveGetUrlForBody(
+    key: string,
+  ): Promise<{ url: string; headers?: Record<string, string> }> {
+    const hit = this.consumeCached("get", key);
+    if (hit) {
+      this.headReuseCache.set(key, hit);
+      return { url: hit.url, headers: hit.headers };
+    }
+    this.headReuseCache.delete(key);
+    return this.presignSingle("get", key);
+  }
+
+  /**
+   * Resolve a presigned URL (+ replay headers) for op+key: cache hit if primed,
+   * else a single presign. Throws on per-key denial (matches the SDK path's
+   * access error). `extra` carries PUT contentType/metadata on the miss path.
+   */
+  private async resolveUrl(
+    op: PresignOp,
+    key: string,
+    extra?: {
+      contentType?: string;
+      metadata?: Record<string, string>;
+      /** Conditional-write fence for PUT presigns — see PutPrecondition. */
+      ifMatch?: string;
+      ifNoneMatch?: "*";
+    },
+  ): Promise<{ url: string; headers?: Record<string, string> }> {
+    const hasPutFence =
+      op === "put" &&
+      (extra?.ifMatch !== undefined || extra?.ifNoneMatch !== undefined);
+    if (hasPutFence) {
+      this.urlCache.delete(this.cacheKey("put", key));
+    }
+    const hit = hasPutFence ? undefined : this.consumeCached(op, key);
+    if (hit) return { url: hit.url, headers: hit.headers };
+    // Primed URLs still serve once the breaker trips (no wire needed); only an
+    // uncached key on an exhausted budget fails fast.
+    return this.presignSingle(op, key, extra);
+  }
+
+  private requireSignedPutPreconditions(
+    key: string,
+    input: PutPrecondition,
+    headers: Record<string, string> | undefined,
+  ): void {
+    const lowerHeaders = new Map<string, string>();
+    for (const [name, value] of Object.entries(headers ?? {})) {
+      lowerHeaders.set(name.toLowerCase(), value);
+    }
+
+    if (input.ifMatch) {
+      const signed = lowerHeaders.get("if-match");
+      if (signed !== quoteEtag(input.ifMatch)) {
+        throw new PresignPreconditionMissingError(key, "if-match");
+      }
+    }
+    if (input.ifNoneMatch) {
+      const signed = lowerHeaders.get("if-none-match");
+      if (signed !== input.ifNoneMatch) {
+        throw new PresignPreconditionMissingError(key, "if-none-match");
+      }
+    }
+  }
+
   async prime(op: PresignOp, keys: PresignKeyInput[]): Promise<void> {
     if (keys.length === 0) return;
     const chunks: PresignKeyInput[][] = [];
@@ -601,14 +728,10 @@ export class PresignObjectIO implements ObjectIO {
   async putObject(input: PutObjectInput): Promise<{ etag: string }> {
     // Conditional-write fields (ifMatch/ifNoneMatch) are forwarded on the
     // presign request so the server can sign If-Match/If-None-Match into the
-    // URL and echo them via `headers` for replay. Until hq-pro's
-    // files-presign signs them (follow-up to this PR), the server ignores
-    // the fields and the returned header set carries no condition — the PUT
-    // stays unconditional on this transport, exactly today's behavior. We
-    // deliberately do NOT inject the header client-side: an unsigned
-    // conditional header breaks the SigV4 signature. Enforcement on this
-    // transport activates the moment the server starts signing; the SDK
-    // transport enforces immediately.
+    // URL and echo them via `headers` for replay. Do not inject a missing
+    // condition client-side: an unsigned conditional header breaks the SigV4
+    // signature. Strict validation of echoed headers remains feature-gated
+    // until the hq-pro files-presign server signs these conditions.
     const row = await this.resolveUrl("put", input.key, {
       contentType: input.contentType,
       ...(input.metadata && Object.keys(input.metadata).length > 0
@@ -617,6 +740,9 @@ export class PresignObjectIO implements ObjectIO {
       ...(input.ifMatch ? { ifMatch: stripQuotes(input.ifMatch) } : {}),
       ...(input.ifNoneMatch ? { ifNoneMatch: input.ifNoneMatch } : {}),
     });
+    if (isPresignFenceStrictEnabled()) {
+      this.requireSignedPutPreconditions(input.key, input, row.headers);
+    }
     // The server signs Content-Type, SSE-KMS, and every x-amz-meta-* into the
     // signature and returns them in `headers`; they MUST be replayed verbatim
     // or SigV4 rejects the PUT.
@@ -642,8 +768,8 @@ export class PresignObjectIO implements ObjectIO {
     return { etag: stripQuotes(res.headers.get("etag") ?? undefined) };
   }
 
-  async getObject(key: string): Promise<GetObjectResult> {
-    const row = await this.resolveUrl("get", key);
+  async getObjectStream(key: string): Promise<GetObjectStreamResult> {
+    const row = await this.resolveGetUrlForBody(key);
     const res = await fetchWithRetry(row.url, { method: "GET" }, `presigned GET ${key}`);
     if (res.status === 404) {
       await cancelBody(res);
@@ -653,8 +779,19 @@ export class PresignObjectIO implements ObjectIO {
       const detail = await safeText(res);
       throw new Error(`presigned GET failed for ${key}: ${res.status} ${detail}`);
     }
-    const body = Buffer.from(await res.arrayBuffer());
-    return { body, metadata: metaFromHeaders(res.headers) };
+    if (!res.body) {
+      return { body: (async function* () {})(), metadata: metaFromHeaders(res.headers) };
+    }
+    return {
+      body: webReadableToAsyncIterable(res.body),
+      metadata: metaFromHeaders(res.headers),
+    };
+  }
+
+  async getObject(key: string): Promise<GetObjectResult> {
+    const res = await this.getObjectStream(key);
+    const body = await drainToBuffer(res.body);
+    return { body, metadata: res.metadata };
   }
 
   async listObjects(input: ListObjectsInput): Promise<ListObjectsResult> {
@@ -696,7 +833,7 @@ export class PresignObjectIO implements ObjectIO {
     // and conflict-detection call sites that use headObject. Reuses the GET
     // cache: a prime("get", …) before a pull warms these HEADs for free.
     let url: string;
-    const hit = this.cached("get", key);
+    const hit = this.consumeHeadReuse(key) ?? this.consumeCached("get", key);
     if (hit) {
       url = hit.url;
     } else {
@@ -776,6 +913,21 @@ async function cancelBody(res: Response): Promise<void> {
   }
 }
 
+async function* webReadableToAsyncIterable(
+  stream: ReadableStream<Uint8Array>,
+): AsyncIterable<Uint8Array> {
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (value && value.byteLength > 0) yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 function parseLastModified(value: string | null): Date {
   if (!value) return new Date();
   const d = new Date(value);

package/src/operation-lock.test.ts

@@ -70,6 +70,27 @@ describe("operation-lock", () => {
     expect(lockPathFor(rootA + path.sep)).toBe(a);
   });
 
+  it("F14: symlink aliases share the same root lock", () => {
+    const aliasParent = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rootA-link-"));
+    const aliasRoot = path.join(aliasParent, "alias");
+    fs.symlinkSync(rootA, aliasRoot, "dir");
+
+    let realHandle: ReturnType<typeof acquireOperationLock> | undefined;
+    let aliasHandle: ReturnType<typeof acquireOperationLock> | undefined;
+    try {
+      expect(lockPathFor(aliasRoot)).toBe(lockPathFor(rootA));
+
+      realHandle = acquireOperationLock(rootA, "sync");
+      expect(() => {
+        aliasHandle = acquireOperationLock(aliasRoot, "rescue", { wait: false });
+      }).toThrowError(OperationLockedError);
+    } finally {
+      aliasHandle?.release();
+      realHandle?.release();
+      fs.rmSync(aliasParent, { recursive: true, force: true });
+    }
+  });
+
   it("acquires, writes holder info, and releases (file gone after release)", () => {
     const h = acquireOperationLock(rootA, "sync");
     expect(fs.existsSync(h.path)).toBe(true);
@@ -224,13 +245,51 @@ describe("operation-lock", () => {
     h.release();
   });
 
-  it("reclaims a torn/unreadable lock file", () => {
+  it("treats a torn/unreadable lock file as busy", () => {
     const p = lockPathFor(rootA);
     fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, "{ this is not valid json");
-    const h = acquireOperationLock(rootA, "reindex");
-    expect(fs.existsSync(h.path)).toBe(true);
-    h.release();
+    expect(() => acquireOperationLock(rootA, "reindex", { wait: false })).toThrowError(
+      OperationLockedError,
+    );
+    expect(fs.readFileSync(p, "utf8")).toBe("{ this is not valid json");
+  });
+
+  it("F34: fresh empty lock files are not reclaimed as stale", () => {
+    const p = lockPathFor(rootA);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.closeSync(fs.openSync(p, "wx"));
+
+    let handle: ReturnType<typeof acquireOperationLock> | undefined;
+    try {
+      expect(() => {
+        handle = acquireOperationLock(rootA, "rescue", { wait: false });
+      }).toThrow();
+      expect(fs.existsSync(p)).toBe(true);
+      expect(fs.readFileSync(p, "utf8")).toBe("");
+    } finally {
+      handle?.release();
+      fs.rmSync(p, { force: true });
+    }
+  });
+
+  it("R-F34: initializing empty and torn locks are busy, not reclaimed", () => {
+    const p = lockPathFor(rootA);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+
+    fs.closeSync(fs.openSync(p, "wx"));
+    const old = new Date(Date.now() - 10_000);
+    fs.utimesSync(p, old, old);
+    expect(() => acquireOperationLock(rootA, "sync", { wait: false })).toThrowError(
+      OperationLockedError,
+    );
+    expect(fs.readFileSync(p, "utf8")).toBe("");
+
+    fs.writeFileSync(p, "{ torn");
+    expect(() => acquireOperationLock(rootA, "sync", { wait: false })).toThrowError(
+      OperationLockedError,
+    );
+    expect(fs.readFileSync(p, "utf8")).toBe("{ torn");
   });
 
   it("different HQ roots are independent — both may hold concurrently", () => {

package/src/operation-lock.ts

@@ -29,9 +29,10 @@
  *
  * ## Atomicity, liveness, takeover
  *
- *   - Acquisition uses `open(…, "wx")` (O_CREAT | O_EXCL) — an atomic
- *     create-if-absent. Exactly one racer can create the file; the loser sees
- *     EEXIST and re-evaluates.
+ *   - Acquisition writes the full owner payload to a same-directory temp file,
+ *     fsyncs it, then publishes that complete file into the final lock name
+ *     with create-if-absent semantics. Exactly one racer can publish; the loser
+ *     sees EEXIST and re-evaluates.
  *   - The lock records the holder's `{ pid, command, startedAt, hqRoot }`. On
  *     EEXIST we test the recorded PID with `process.kill(pid, 0)`:
  *       * ESRCH  → the holder is gone (crashed / killed -9 / stale file) →
@@ -65,11 +66,10 @@
  *   holder is reclaimed at once regardless of the wait config.
  *
  *   Ordering / scope caveats:
- *     - This is a CROSS-PROCESS mutex keyed on the holder's PID. Two concurrent
- *       acquisitions inside the SAME process share a PID, so the same-process
- *       reclaim path lets them stomp each other — in-process concurrent acquire
- *       is unsupported (the real consumers — sync / rescue / reindex — are
- *       separate processes).
+ *     - This is a CROSS-PROCESS mutex keyed on the holder's PID. In-process
+ *       concurrent acquire is unsupported (the real consumers — sync / rescue /
+ *       reindex — are separate processes), but a live same-PID holder is still
+ *       treated as busy rather than reclaimed.
  *     - When several distinct processes wait on the same lock, the next one to
  *       win the O_EXCL race after a free acquires. Order is best-effort, NOT
  *       FIFO — do not depend on arrival order.
@@ -235,9 +235,18 @@ function stateDir(): string {
   return process.env.HQ_STATE_DIR || path.join(os.homedir(), ".hq");
 }
 
+function canonicalRoot(hqRoot: string): string {
+  const resolved = path.resolve(hqRoot);
+  try {
+    return fs.realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
 /** Absolute lock path for a given HQ root. Exported for tests. */
 export function lockPathFor(hqRoot: string): string {
-  const canon = path.resolve(hqRoot);
+  const canon = canonicalRoot(hqRoot);
   const key = crypto.createHash("sha1").update(canon).digest("hex").slice(0, 16);
   return path.join(stateDir(), "locks", `operation-${key}.lock`);
 }
@@ -271,6 +280,22 @@ function readLockInfo(p: string): LockInfo | null {
   }
 }
 
+function initializingLockInfo(p: string): LockInfo {
+  let mtimeMs = Date.now();
+  try {
+    const st = fs.statSync(p);
+    mtimeMs = st.mtimeMs;
+  } catch {
+    /* lock disappeared between EEXIST and stat; treat as transient busy */
+  }
+  return {
+    pid: 0,
+    command: "operation-lock writer",
+    startedAt: new Date(mtimeMs).toISOString(),
+    hqRoot: "unknown",
+  };
+}
+
 // ── Process-wide release plumbing ──────────────────────────────────────────
 // Track every lock this process currently holds so the signal/exit hooks can
 // release all of them. The hooks are installed exactly once.
@@ -333,7 +358,7 @@ function disabledHandle(hqRoot: string, command: string): LockHandle {
     pid: process.pid,
     command,
     startedAt: new Date().toISOString(),
-    hqRoot: path.resolve(hqRoot),
+    hqRoot: canonicalRoot(hqRoot),
   };
   return { ...NOOP_HANDLE_BASE, path: "", info };
 }
@@ -346,17 +371,68 @@ function prepareLock(hqRoot: string, command: string): { p: string; info: LockIn
     pid: process.pid,
     command,
     startedAt: new Date().toISOString(),
-    hqRoot: path.resolve(hqRoot),
+    hqRoot: canonicalRoot(hqRoot),
   };
   return { p, info, payload: JSON.stringify(info, null, 2) };
 }
 
+function writeLockTemp(dir: string, payload: string): string {
+  const tmp = path.join(
+    dir,
+    `.operation-lock.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString("hex")}.tmp`,
+  );
+  const fd = fs.openSync(tmp, "wx", 0o600);
+  let closed = false;
+  try {
+    fs.writeSync(fd, payload);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    closed = true;
+    return tmp;
+  } catch (err) {
+    if (!closed) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* best-effort cleanup */
+      }
+    }
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
+}
+
+function publishLockPayload(p: string, payload: string): boolean {
+  const dir = path.dirname(p);
+  const tmp = writeLockTemp(dir, payload);
+  try {
+    // `link` is the no-overwrite atomic publish primitive available in Node:
+    // it fails with EEXIST if the final lock name is already present, and the
+    // final name never exists until the fully-written payload is linked there.
+    fs.linkSync(tmp, p);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === "EEXIST") return false;
+    throw err;
+  } finally {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+}
+
 /**
  * One acquisition pass. Returns the {@link LockHandle} on success, or
  * `{ busy }` naming the LIVE holder that blocked us (so the caller can decide
- * to wait or refuse). A stale/torn/own-leftover lock is reclaimed in-pass and
- * never reported as busy. Throws only on genuinely pathological churn or a
- * non-EEXIST fs error.
+ * to wait or refuse). A valid stale lock is reclaimed in-pass and never
+ * reported as busy; empty/torn locks are treated as initializing and left in
+ * place. Throws only on genuinely pathological churn or unexpected fs errors.
  */
 function tryAcquireOnce(
   p: string,
@@ -368,30 +444,22 @@ function tryAcquireOnce(
   // it as busy.
   const MAX_ATTEMPTS = 5;
   for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-    let fd: number;
-    try {
-      fd = fs.openSync(p, "wx"); // O_CREAT | O_EXCL — atomic
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException)?.code !== "EEXIST") throw err;
+    if (publishLockPayload(p, payload)) {
+      return { handle: makeHandle(p, info) };
+    }
 
-      const holder = readLockInfo(p);
-      if (holder && holder.pid !== process.pid && pidAlive(holder.pid)) {
-        return { busy: holder };
-      }
-      // Stale (dead holder), unreadable/torn, or our own leftover → reclaim.
+    const holder = readLockInfo(p);
+    if (holder) {
+      if (pidAlive(holder.pid)) return { busy: holder };
       try {
         fs.unlinkSync(p);
       } catch {
-        /* someone else reclaimed it first; the next openSync re-evaluates */
+        /* someone else reclaimed it first; the next publish re-evaluates */
       }
       continue;
     }
-    try {
-      fs.writeSync(fd, payload);
-    } finally {
-      fs.closeSync(fd);
-    }
-    return { handle: makeHandle(p, info) };
+
+    return { busy: initializingLockInfo(p) };
   }
 
   // Pathological churn (another process reclaiming in lockstep). Surface it

package/src/personal-vault.test.ts

@@ -523,6 +523,48 @@ describe("personal-vault: continuity-pointer carve-out", () => {
       path.join(THREADS, "handoff.json"),
     ]);
   });
+
+  it("R-F35: rejects threads symlinks below hqRoot while allowing symlinked hqRoot ancestors", () => {
+    const privateThreads = path.join(hqRoot, "repos", "private");
+    fs.mkdirSync(privateThreads, { recursive: true });
+    fs.mkdirSync(path.join(hqRoot, "workspace"), { recursive: true });
+    fs.writeFileSync(path.join(privateThreads, "handoff.json"), JSON.stringify({
+      thread_path: "workspace/threads/T-private.json",
+    }));
+    fs.writeFileSync(path.join(privateThreads, "T-private.json"), "{}");
+    fs.symlinkSync(privateThreads, path.join(hqRoot, THREADS), "dir");
+
+    expect(rel(computeContinuityPointerPaths(hqRoot))).toEqual([
+      path.join(THREADS, "handoff.json"),
+    ]);
+
+    const realParent = fs.mkdtempSync(path.join(os.tmpdir(), "hq-cont-real-"));
+    const aliasParent = fs.mkdtempSync(path.join(os.tmpdir(), "hq-cont-alias-"));
+    const realRoot = path.join(realParent, "root");
+    const aliasRoot = path.join(aliasParent, "root-link");
+    try {
+      fs.mkdirSync(path.join(realRoot, THREADS), { recursive: true });
+      fs.writeFileSync(
+        path.join(realRoot, THREADS, "handoff.json"),
+        JSON.stringify({ thread_path: "workspace/threads/T-active.json" }),
+      );
+      fs.writeFileSync(path.join(realRoot, THREADS, "T-active.json"), "{}");
+      fs.symlinkSync(realRoot, aliasRoot, "dir");
+
+      const aliasRel = computeContinuityPointerPaths(aliasRoot)
+        .map((p) => path.relative(aliasRoot, p))
+        .sort();
+      expect(aliasRel).toEqual(
+        [
+          path.join(THREADS, "T-active.json"),
+          path.join(THREADS, "handoff.json"),
+        ].sort(),
+      );
+    } finally {
+      fs.rmSync(realParent, { recursive: true, force: true });
+      fs.rmSync(aliasParent, { recursive: true, force: true });
+    }
+  });
 });
 
 // ─────────────────────────────────────────────────────────────────────────

package/src/personal-vault.ts

@@ -212,8 +212,14 @@ export function computeContinuityPointerPaths(hqRoot: string): string[] {
     p === resolvedThreads || p.startsWith(resolvedThreads + path.sep);
   if (!withinThreads(candidate)) return out;
   try {
-    const real = fs.realpathSync(candidate);
-    if (!withinThreads(real)) return out;
+    const realHqRoot = fs.realpathSync.native(hqRoot);
+    const expectedRealThreads = path.join(realHqRoot, "workspace", "threads");
+    const realThreads = fs.realpathSync.native(threadsDir);
+    if (realThreads !== expectedRealThreads) return out;
+    const withinRealThreads = (p: string): boolean =>
+      p === realThreads || p.startsWith(realThreads + path.sep);
+    const real = fs.realpathSync.native(candidate);
+    if (!withinRealThreads(real)) return out;
     if (!fs.statSync(real).isFile()) return out;
   } catch {
     // Pointer references a thread file that doesn't exist here — skip it.