@indigoai-us/hq-cloud 6.11.6 → 6.11.7

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"),
+    ]);
+  });
+});

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

@@ -263,6 +263,47 @@ describe("US-002: createWatchPathFilter — personal-vault exclusions", () => {
     expect(personal(path.join(ROOT, "repos/private/foo/file.ts"))).toBe(false);
   });
 
+  // ── DEV-1778 continuity-pointer carve-out ───────────────────────────────
+  it("DOES emit for workspace/threads/handoff.json (the continuity pointer)", () => {
+    expect(personal(path.join(ROOT, "workspace/threads/handoff.json"))).toBe(
+      true,
+    );
+  });
+
+  it("still does NOT emit for other workspace/ files (carve-out is pointer-only)", () => {
+    // The pointer is the ONLY re-include — sibling threads, the journal, and
+    // unrelated workspace litter stay machine-local.
+    expect(personal(path.join(ROOT, "workspace/threads/T-old.json"))).toBe(
+      false,
+    );
+    expect(personal(path.join(ROOT, "workspace/threads/INDEX.md"))).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/locks/x.lock"))).toBe(false);
+    // The pointer queried as a directory is not an emit target either.
+    expect(
+      personal(path.join(ROOT, "workspace/threads/handoff.json"), true),
+    ).toBe(false);
+  });
+
+  it("allows chokidar to DESCEND through the pointer's ancestor dirs (dir probe)", () => {
+    // Without this the Linux chokidar backend prunes `workspace/` before ever
+    // reaching the leaf. Ancestor dirs return true ONLY when queried as dirs.
+    expect(personal(path.join(ROOT, "workspace"), true)).toBe(true);
+    expect(personal(path.join(ROOT, "workspace/threads"), true)).toBe(true);
+    // A non-ancestor dir under workspace/ is still pruned.
+    expect(personal(path.join(ROOT, "workspace/locks"), true)).toBe(false);
+    // Ancestor dirs queried as FILES are not emit targets.
+    expect(personal(path.join(ROOT, "workspace"), false)).toBe(false);
+  });
+
+  it("does not apply the carve-out in non-personal mode", () => {
+    // In non-personal mode the excluded-top-level layer never runs, so the
+    // carve-out is irrelevant; handoff.json passes via the ordinary ignore
+    // stack like any other tracked file (no special-casing needed).
+    expect(
+      nonPersonal(path.join(ROOT, "workspace/threads/handoff.json")),
+    ).toBe(true);
+  });
+
   it("DOES emit for an included top-level personal path in personalMode", () => {
     expect(personal(path.join(ROOT, "personal/notes.md"))).toBe(true);
     expect(personal(path.join(ROOT, "core/policies/x.md"))).toBe(true);

package/src/watcher.ts

@@ -19,7 +19,10 @@ import { readJournal, writeJournal, hashFile, updateEntry } from "./journal.js";
 import { uploadFile, deleteRemoteFile, toPosixKey } from "./s3.js";
 import type { UploadAuthor } from "./s3.js";
 import { isPersonalVaultExcluded } from "./personal-vault-exclusions.js";
-import { PERSONAL_VAULT_EXCLUDED_TOP_LEVEL } from "./personal-vault.js";
+import {
+  CONTINUITY_POINTER_REL,
+  PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
+} from "./personal-vault.js";
 import type { PushEvent } from "./sync/push-event.js";
 import type { PushTransport } from "./sync/push-transport.js";
 import type { EventDrivenPushFlagProvider } from "./sync/feature-flags.js";
@@ -498,6 +501,26 @@ export function createWatchPathFilter(
     if (!ignoreFilter(absolutePath, isDir)) return false;
 
     if (personalMode) {
+      // Continuity-pointer carve-out: the session pointer lives under the
+      // otherwise-excluded `workspace/`, so it must re-include BEFORE the
+      // top-level bucket rejection below. Two cases:
+      //   (a) the pointer FILE itself → emit. Waking on the pointer is
+      //       sufficient: `/handoff` rewrites handoff.json AFTER its
+      //       (immutable) thread file, and the resulting personal push
+      //       re-enumerates via computePersonalVaultPaths, which sweeps the
+      //       pointer + its active thread file together.
+      //   (b) an ANCESTOR DIR of the pointer (`workspace`, `workspace/threads`)
+      //       queried as a directory → allow descent. The Linux chokidar
+      //       backend prunes a subtree the instant its dir probe says "ignore",
+      //       so without this it would prune `workspace/` before ever reaching
+      //       the leaf (the same ancestor-descent subtlety `.hqinclude` handles
+      //       via its ancestor matcher). The native recursive backend ignores
+      //       descent decisions and re-checks each path at event time, so this
+      //       only matters for chokidar but is harmless everywhere.
+      // See computeContinuityPointerPaths for the matching push-side carve-out.
+      if (rel === CONTINUITY_POINTER_REL && !isDir) return true;
+      if (isDir && CONTINUITY_POINTER_REL.startsWith(rel + "/")) return true;
+
       // Layer 3: excluded top-level buckets (.git/companies/repos/workspace).
       const topLevel = rel.split("/")[0];
       if (excludedTopLevel.has(topLevel)) return false;