@indigoai-us/hq-cloud 6.14.1 → 6.14.3

package/src/index.ts

@@ -152,7 +152,11 @@ export type {
 // the SAME effective scope the menubar runner does, instead of defaulting every
 // CLI pull to `syncMode: "all"` (the seed of the all→shared scope-shrink wedge,
 // DEV-1768).
-export { resolvePullScope, readPinnedPrefixes } from "./sync/pull-scope.js";
+export {
+  resolvePullScope,
+  readPinnedPrefixes,
+  SESSIONS_SCOPE_PREFIX,
+} from "./sync/pull-scope.js";
 export type { PullScope, PullScopeClient } from "./sync/pull-scope.js";
 
 // Personal-vault scope helpers — shared between hq-sync-runner and `hq sync`
@@ -160,9 +164,11 @@ export {
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
   PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
   CONTINUITY_POINTER_REL,
+  SESSION_LOGS_SYNC_REL,
   computePersonalVaultPaths,
   computePersonalCompanySubdirs,
   computeContinuityPointerPaths,
+  computeSessionLogsSyncPaths,
 } from "./personal-vault.js";
 export type { PersonalVaultOptions } from "./personal-vault.js";
 
@@ -200,6 +206,9 @@ export type {
   TelemetryOptInResponse,
   UsageBatch,
   UsageIngestResult,
+  RawTelemetryEventInput,
+  TelemetryEventsBatch,
+  TelemetryEventsIngestResult,
   SkillInvocationBatch,
   SkillInvocationIngestResult,
   // US-004 — browse-vs-sync membership sync-mode + ACL surface
@@ -219,6 +228,20 @@ export type {
   TelemetryClientSurface,
 } from "./telemetry.js";
 
+// hq-cloud ACTION telemetry (`/v1/telemetry/events`). Unlike token/skill
+// collectors, these sync/CLI events are not gated by `/v1/usage` opt-in.
+export {
+  agentUidFromClaims,
+  emitCloudTelemetry,
+} from "./telemetry-events.js";
+export type {
+  CloudTelemetryClient,
+  EmitCloudTelemetryOptions,
+  TelemetryClaims,
+  TelemetryEvent,
+  TelemetryProperties,
+} from "./telemetry-events.js";
+
 // Skill-invocation telemetry collector (`/v1/skill-invocations`). Reads the
 // same Claude Code session logs as the token collector but extracts which
 // skill / slash-command was invoked. Independent cursor; same opt-in gate.

package/src/journal.ts

@@ -404,6 +404,18 @@ export function hashSymlinkTarget(target: string): string {
     .digest("hex");
 }
 
+/**
+ * Record a per-file journal entry after a transfer.
+ *
+ * `direction` (`"up"` = pushed / locally authored, `"down"` = pulled) is what
+ * lets scope-shrink tell your own work apart from a mirror of someone else's.
+ * It underpins the US-006 push-only sessions contract: a session transcript
+ * this machine authored and pushed is stamped `direction:"up"`, so even though
+ * `sessions/` is excluded from every pull scope, `buildScopeShrinkPlan` skips
+ * `direction:"up"` entries and never orphans it. (Sessions fetched on demand
+ * via `hq files get` are pulled — `direction:"down"` — but ride the pin union
+ * in the caller's inclusion prefixSet, so they are likewise never pruned.)
+ */
 export function updateEntry(
   journal: SyncJournal,
   relativePath: string,

package/src/lib/exit-codes.ts

@@ -0,0 +1,24 @@
+/**
+ * Runner exit code for a partial sync pass: the pass ran to completion but one
+ * or more per-file transfers threw (`errors.length > 0` in the all-complete
+ * aggregate). Deterministic per-file failures — an oversized object on a
+ * pre-skip runner, a presign denial, an expired token late in a long pass, a
+ * corrupt doubly-scoped vault key — all land here.
+ *
+ * A one-shot `hq sync` exits with this code so humans and scripts see the
+ * failure. The watch loop must NOT exit on it: auto-sync runs unattended, and
+ * a watcher that dies on every partial pass gets hot-respawned by the menubar
+ * supervisor, which Sentry-captures each death as "auto-sync watcher exited
+ * unexpectedly (code=Some(2))". Because the watcher typically runs healthily
+ * for minutes before the failing pass, the supervisor's fast-crash-loop
+ * dampening never engages and EVERY death ships an event — the July 2026
+ * #hq-sentry-alerts flood (~1,700 events across 60+ machines in 5 days).
+ * Instead the loop logs, stays alive, and re-attempts on the next tick; the
+ * per-file errors still surface through the ndjson `error` events and the
+ * `partial: true` all-complete aggregate.
+ *
+ * Kept off the other codes in use by the runner: 0 ok, 1 hard error, 17
+ * op-locked (`OPERATION_LOCKED_EXIT`), 75 transient network
+ * (`TRANSIENT_NETWORK_EXIT`).
+ */
+export const PARTIAL_SYNC_EXIT = 2;

package/src/object-io.test.ts

@@ -234,13 +234,78 @@ describe("PresignObjectIO.putObject", () => {
     // per-path skip (scopeExcludedSet) + the "N paths skipped — outside your
     // granted access" aggregate, instead of a fatal `type:"error"` that exits
     // the runner non-zero and floods Sentry. This is the PUT/GET symmetry that
-    // fixes the fleet-wide presign-put-denied crash-loop.
+    // fixes the presign-put-denied crash-loop across user machines.
     expect((caught as Error).name).toBe("Forbidden");
     expect(isAccessDenied(caught)).toBe(true);
     // Denied at mint time — the byte-moving PUT is never attempted.
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  it("US-006 AC5: a transcript-consent denial (FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED) is skip-with-log, not fatal", async () => {
+    const { vault, setPresign } = makeVault();
+    // The US-005 consent code ends `_REQUIRED`, not `_FORBIDDEN`, so the plain
+    // suffix test alone would MISS it and let it fall through to the fatal
+    // generic Error — the recurring partial-failure this AC5 fix prevents.
+    setPresign([
+      {
+        key: "sessions/prs_1/2026-07-11T10-00-00.json",
+        op: "get",
+        error: "transcript consent required",
+        code: "FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED",
+      },
+    ]);
+    const io = new PresignObjectIO(vault, COMPANY);
+    // Monkeypatch console.warn (vitest's console interception can shadow a spy)
+    // to assert the REAL skip log fires.
+    const warnings: string[] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    let caught: unknown;
+    try {
+      await io
+        .getObject("sessions/prs_1/2026-07-11T10-00-00.json")
+        .catch((e) => {
+          caught = e;
+        });
+    } finally {
+      console.warn = originalWarn;
+    }
+    // Same shape a denied GET already throws → isAccessDenied → the per-key
+    // scope-excluded skip, NOT a fatal `type:"error"` that poisons the run.
+    expect((caught as Error).name).toBe("Forbidden");
+    expect(isAccessDenied(caught)).toBe(true);
+    // A one-line skip log fires so operators can see WHY the key was skipped.
+    expect(
+      warnings.some((w) =>
+        w.includes("FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED"),
+      ),
+    ).toBe(true);
+  });
+
+  it("US-006 AC5: a sessions structural-ACL denial (FILES_PRESIGN_SESSIONS_FORBIDDEN) is skip-with-log", async () => {
+    const { vault, setPresign } = makeVault();
+    // A spoofed/foreign `sessions/{uid}/` prefix the hq-pro structural gate
+    // refuses to presign. Ends `_FORBIDDEN`, so the suffix test already covers
+    // it — this pins that coverage as a regression contract for US-006.
+    setPresign([
+      {
+        key: "sessions/prs_other/y.json",
+        op: "get",
+        error: "not your session prefix",
+        code: "FILES_PRESIGN_SESSIONS_FORBIDDEN",
+      },
+    ]);
+    const io = new PresignObjectIO(vault, COMPANY);
+    let caught: unknown;
+    await io.getObject("sessions/prs_other/y.json").catch((e) => {
+      caught = e;
+    });
+    expect((caught as Error).name).toBe("Forbidden");
+    expect(isAccessDenied(caught)).toBe(true);
+  });
+
   it("a non-authorization presign failure stays a generic (fatal) error — not silently skipped", async () => {
     const { vault, setPresign } = makeVault();
     setPresign([

package/src/object-io.ts

@@ -344,6 +344,35 @@ function metaFromHeaders(headers: Headers): Record<string, string> {
   return meta;
 }
 
+/**
+ * Per-key presign denial codes that are EXPECTED and must be reclassified as
+ * skip-with-log — throwing the `name: "Forbidden"` shape (see
+ * {@link accessDeniedError}) so `isAccessDenied` in sync.ts / share.ts routes
+ * them into the silent per-key scope-excluded skip, never a FATAL sync error.
+ *
+ * Two families qualify:
+ *   1. Any `*_FORBIDDEN` code — an authorization/ACL denial. Covers
+ *      FILES_PRESIGN_FORBIDDEN (no write on a shared prefix), FILES_RAW_FORBIDDEN,
+ *      and — the structural sessions-ACL rejection this US-006 phase relies on —
+ *      FILES_PRESIGN_SESSIONS_FORBIDDEN (a spoofed/foreign `sessions/{uid}/`
+ *      prefix the server refuses to presign).
+ *   2. FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED — the US-005 transcript-consent
+ *      denial. It ends `_REQUIRED`, not `_FORBIDDEN`, so the suffix test alone
+ *      would MISS it and let it fall through to the fatal generic Error below,
+ *      re-introducing exactly the recurring partial-failure that poisons every
+ *      subsequent sync run (US-006 AC5).
+ */
+const SKIP_WITH_LOG_DENIAL_CODES: ReadonlySet<string> = new Set([
+  "FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED",
+]);
+
+function isSkipWithLogDenialCode(code: unknown): code is string {
+  return (
+    typeof code === "string" &&
+    (code.endsWith("_FORBIDDEN") || SKIP_WITH_LOG_DENIAL_CODES.has(code))
+  );
+}
+
 function firstRowOrThrow(
   results: PresignResultRow[],
   key: string,
@@ -354,22 +383,30 @@ function firstRowOrThrow(
     throw new Error(`presign ${op} returned no row for ${key}`);
   }
   if (row.error || !row.url) {
-    // An authorization denial (server `*_FORBIDDEN` code — e.g.
-    // FILES_PRESIGN_FORBIDDEN when the caller lacks write on a shared prefix,
-    // or FILES_RAW_FORBIDDEN) must throw the SAME `name: "Forbidden"` shape the
-    // GET/HEAD path uses (see {@link accessDeniedError}) so it routes through
-    // the `isAccessDenied` skip in sync.ts / share.ts. Without this, a denied
-    // PUT presign fell to the generic Error below — `isAccessDenied` returned
-    // false — and the per-file ACL skip the GET path handles gracefully became
-    // a FATAL sync error: the crash-loop + Sentry flood behind the fleet-wide
-    // "presign put denied" incident (members pushing net-new keys to a
-    // company-wide-read prefix under private-by-default). The denial is
-    // expected; only the fatal handling of it was the bug.
-    if (typeof row.code === "string" && row.code.endsWith("_FORBIDDEN")) {
+    // An expected per-key denial (see {@link isSkipWithLogDenialCode}) must
+    // throw the SAME `name: "Forbidden"` shape the GET/HEAD path uses so it
+    // routes through the `isAccessDenied` skip in sync.ts / share.ts. Without
+    // this, a denied presign fell to the generic Error below — `isAccessDenied`
+    // returned false — and the per-file ACL skip the GET path handles gracefully
+    // became a FATAL sync error: the crash-loop + Sentry flood behind the
+    // widespread "presign put denied" incident (members pushing net-new keys to
+    // a company-wide-read prefix under private-by-default), and — for the
+    // sessions/consent codes — a recurring partial-failure that poisoned every
+    // subsequent sync run (US-006 AC5). The denial is expected; only the fatal
+    // handling of it was the bug. Log a one-line skip so the reason is visible
+    // without the run failing.
+    if (isSkipWithLogDenialCode(row.code)) {
+      // Shared presign layer: this fires for sync legs AND for non-sync callers
+      // (hq files get, signals/sources internals) where the denial surfaces as a
+      // user-facing error, not a continued sync. State only what THIS layer did
+      // (denied → skipped this row) and let the caller own any "sync continues"
+      // / error framing — don't assert an outcome the caller may not take.
+      console.warn(
+        `presign ${op} denied for '${key}' (${row.code}) — skipped`,
+      );
       throw accessDeniedError(
         key,
-        `no write access to '${key}' (server ${op} denied: ${row.code}) — ` +
-          `ask an admin to grant write on this shared prefix`,
+        `no ${op} access to '${key}' (server ${op} denied: ${row.code})`,
       );
     }
     throw new Error(

package/src/operation-lock.test.ts

@@ -73,6 +73,39 @@ describe("operation-lock", () => {
     expect(lockPathFor(rootA + path.sep)).toBe(a);
   });
 
+  it("scopes partition the lock: same root, different scope → different file, no mutual block", () => {
+    // feedback_ed98d810: reindex must not be starved by a long-lived sync/watch
+    // holder. Distinct scopes hash to distinct lock files and never block each
+    // other, while the same scope stays a real cross-process mutex.
+    const opPath = lockPathFor(rootA); // default "operation" scope
+    const reindexPath = lockPathFor(rootA, "reindex");
+    expect(reindexPath).not.toBe(opPath);
+    expect(path.basename(reindexPath).startsWith("reindex-")).toBe(true);
+    expect(path.basename(opPath).startsWith("operation-")).toBe(true);
+
+    let opHandle: ReturnType<typeof acquireOperationLock> | undefined;
+    let reindexHandle: ReturnType<typeof acquireOperationLock> | undefined;
+    try {
+      // A live "operation" holder (as a watch-mode runner keeps) does NOT block
+      // a "reindex"-scope acquire, even with no wait.
+      opHandle = acquireOperationLock(rootA, "sync");
+      expect(() => {
+        reindexHandle = acquireOperationLock(rootA, "reindex", {
+          scope: "reindex",
+          wait: false,
+        });
+      }).not.toThrow();
+      expect(reindexHandle && fs.existsSync(reindexHandle.path)).toBe(true);
+      // ...but a second acquire on the SAME "reindex" scope is still refused.
+      expect(() =>
+        acquireOperationLock(rootA, "reindex", { scope: "reindex", wait: false }),
+      ).toThrowError(OperationLockedError);
+    } finally {
+      reindexHandle?.release();
+      opHandle?.release();
+    }
+  });
+
   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");

package/src/operation-lock.ts

@@ -3,10 +3,19 @@
  * (`sync`, `rescue`, `reindex`).
  *
  * Contract:
- *   - At most ONE of sync / rescue / reindex runs at a time **per HQ root**.
- *     The lock is shared across all three (keyed only by the root, not the
- *     command), so e.g. a rescue refuses while a sync holds it. Different HQ
- *     roots are fully independent — they hash to different lock files.
+ *   - `sync` and `rescue` share ONE per-root lock (the "operation" scope, keyed
+ *     only by the root, not the command), so at most one of them runs at a time
+ *     and e.g. a rescue refuses while a sync holds it. Different HQ roots are
+ *     fully independent — they hash to different lock files.
+ *   - `reindex` uses a SEPARATE per-root scope ("reindex"), so it is guarded
+ *     against other reindexes but is NOT blocked by a held sync/rescue lock.
+ *     This is deliberate: a watch-mode `hq-sync-runner` holds the "operation"
+ *     lock across its entire lifetime, and a shared lock would starve a
+ *     standalone `hq reindex` indefinitely (feedback_ed98d810). reindex only
+ *     READS the source trees to rebuild derived artifacts (skill wrappers,
+ *     overlay mirrors, the workers registry) and is idempotent + re-run after
+ *     every sync pass, so decoupling it from the sync writer lock is safe.
+ *     See {@link lockPathFor} for how the scope partitions the lock file.
  *   - The push watcher / watch+event-push runner is EXEMPT: it never calls in
  *     here, so it neither takes the lock nor is blocked by it (its targeted
  *     in-process push passes are likewise lock-free).
@@ -202,6 +211,13 @@ export interface AcquireOptions {
    * (or a no-op) to redirect/silence the status line.
    */
   onWaitStart?: (holder: LockInfo, attempted: string) => void;
+  /**
+   * Lock scope — partitions the per-root mutex into independent lock files (see
+   * {@link lockPathFor}). Defaults to {@link DEFAULT_LOCK_SCOPE} ("operation"),
+   * which `sync`/`rescue` share. `reindex` passes "reindex" so it is guarded
+   * against other reindexes without being blocked by a held sync/rescue lock.
+   */
+  scope?: string;
 }
 
 interface ResolvedWaitConfig {
@@ -280,11 +296,26 @@ function canonicalRoot(hqRoot: string): string {
   }
 }
 
-/** Absolute lock path for a given HQ root. Exported for tests. */
-export function lockPathFor(hqRoot: string): string {
+/**
+ * Default lock scope. `sync` and `rescue` share this one so they stay mutually
+ * exclusive with each other, keyed only by the root.
+ */
+export const DEFAULT_LOCK_SCOPE = "operation";
+
+/**
+ * Absolute lock path for a given HQ root and `scope`. Exported for tests.
+ *
+ * The `scope` prefixes the lock filename so callers can partition the mutex:
+ * `sync`/`rescue` use {@link DEFAULT_LOCK_SCOPE} ("operation"); `reindex` uses
+ * its own "reindex" scope so a long-lived watch-mode sync-runner (which holds
+ * the "operation" lock across its whole lifetime) can never starve a standalone
+ * `hq reindex`. Different scopes hash to different lock files and never block
+ * one another; the same scope is a real cross-process mutex.
+ */
+export function lockPathFor(hqRoot: string, scope: string = DEFAULT_LOCK_SCOPE): string {
   const canon = canonicalRoot(hqRoot);
   const key = crypto.createHash("sha1").update(canon).digest("hex").slice(0, 16);
-  return path.join(stateDir(), "locks", `operation-${key}.lock`);
+  return path.join(stateDir(), "locks", `${scope}-${key}.lock`);
 }
 
 /**
@@ -425,8 +456,12 @@ export function rethrowLockCreateError(err: unknown, lockDir: string): never {
 }
 
 /** Build the lock payload + ensure the locks dir exists. */
-function prepareLock(hqRoot: string, command: string): { p: string; info: LockInfo; payload: string } {
-  const p = lockPathFor(hqRoot);
+function prepareLock(
+  hqRoot: string,
+  command: string,
+  scope: string = DEFAULT_LOCK_SCOPE,
+): { p: string; info: LockInfo; payload: string } {
+  const p = lockPathFor(hqRoot, scope);
   const dir = path.dirname(p);
   try {
     fs.mkdirSync(dir, { recursive: true });
@@ -565,7 +600,7 @@ export function acquireOperationLock(
 ): LockHandle {
   if (process.env.HQ_DISABLE_OP_LOCK === "1") return disabledHandle(hqRoot, command);
 
-  const { p, info, payload } = prepareLock(hqRoot, command);
+  const { p, info, payload } = prepareLock(hqRoot, command, opts.scope);
   const cfg = resolveWaitConfig(opts);
   const deadline = cfg.timeoutMs === null ? null : Date.now() + cfg.timeoutMs;
   let announced = false;
@@ -596,7 +631,7 @@ export async function acquireOperationLockAsync(
 ): Promise<LockHandle> {
   if (process.env.HQ_DISABLE_OP_LOCK === "1") return disabledHandle(hqRoot, command);
 
-  const { p, info, payload } = prepareLock(hqRoot, command);
+  const { p, info, payload } = prepareLock(hqRoot, command, opts.scope);
   const cfg = resolveWaitConfig(opts);
   const deadline = cfg.timeoutMs === null ? null : Date.now() + cfg.timeoutMs;
   let announced = false;

package/src/personal-vault.test.ts

@@ -25,6 +25,8 @@ import {
   CONTINUITY_POINTER_REL,
   computeAgencySyncPaths,
   AGENCY_SYNC_REL,
+  computeSessionLogsSyncPaths,
+  SESSION_LOGS_SYNC_REL,
   PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
 } from "./personal-vault.js";
@@ -628,3 +630,58 @@ describe("personal-vault: agency-workspace carve-out", () => {
     );
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────
+// Session-logs carve-out (workspace/.session-logs) — reindex-captured Claude
+// Code transcripts pierce the workspace/ exclusion and round-trip to the vault.
+// ─────────────────────────────────────────────────────────────────────────
+describe("personal-vault: session-logs carve-out", () => {
+  let hqRoot: string;
+  beforeEach(() => {
+    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-sesslog-test-"));
+  });
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+  const relAll = (abs: string[]): string[] =>
+    abs.map((p) => path.relative(hqRoot, p)).sort();
+
+  it("constant: SESSION_LOGS_SYNC_REL is workspace/.session-logs", () => {
+    expect(SESSION_LOGS_SYNC_REL).toBe("workspace/.session-logs");
+  });
+
+  it("includes workspace/.session-logs when it exists", () => {
+    fs.mkdirSync(path.join(hqRoot, "workspace", ".session-logs", "tool-results"), {
+      recursive: true,
+    });
+    expect(relAll(computeSessionLogsSyncPaths(hqRoot))).toEqual([
+      path.join("workspace", ".session-logs"),
+    ]);
+  });
+
+  it("empty when workspace/.session-logs is absent (fail-soft)", () => {
+    fs.mkdirSync(path.join(hqRoot, "workspace"), { recursive: true });
+    expect(computeSessionLogsSyncPaths(hqRoot)).toEqual([]);
+  });
+
+  it("composes into computePersonalVaultPaths without broadening workspace/", () => {
+    fs.mkdirSync(path.join(hqRoot, "workspace", ".session-logs"), { recursive: true });
+    fs.writeFileSync(
+      path.join(hqRoot, "workspace", ".session-logs", "session.jsonl"),
+      "l\n",
+    );
+    // A sibling under workspace/ that must STAY local.
+    fs.mkdirSync(path.join(hqRoot, "workspace", "locks"), { recursive: true });
+    fs.writeFileSync(path.join(hqRoot, "workspace", "locks", "x.lock"), "1");
+    fs.mkdirSync(path.join(hqRoot, ".claude"), { recursive: true });
+
+    const out = relAll(computePersonalVaultPaths(hqRoot));
+    expect(out).toContain(path.join("workspace", ".session-logs"));
+    expect(out).toContain(".claude");
+    // The carve-out is exactly the .session-logs subtree — no other workspace/
+    // sibling is pulled in.
+    expect(out.some((p) => p.startsWith(path.join("workspace", "locks")))).toBe(
+      false,
+    );
+  });
+});

package/src/personal-vault.ts

@@ -26,7 +26,12 @@
  *     the routing source-of-truth.)
  *   - `repos/`, `workspace/`: per user directive — heavy local-only
  *     content (cloned remotes, session threads) that has no business in
- *     the personal vault.
+ *     the personal vault. Three explicit sub-paths pierce this exclusion and
+ *     DO round-trip: `workspace/threads/handoff.json` (+ its active thread) via
+ *     {@link computeContinuityPointerPaths}, `workspace/agency/` via
+ *     {@link computeAgencySyncPaths}, and `workspace/.session-logs/` (the
+ *     reindex-captured Claude Code transcripts) via
+ *     {@link computeSessionLogsSyncPaths}.
  *
  * Note: `core/`, `data/`, and `personal/` were previously excluded but are
  * INCLUDED as of user directive 2026-05-13. `core/` ships the hq-core
@@ -134,7 +139,15 @@ export function computePersonalVaultPaths(
   );
   const continuity = computeContinuityPointerPaths(hqRoot);
   const agency = computeAgencySyncPaths(hqRoot);
-  return [...topLevel, ...manifest, ...companySubdirs, ...continuity, ...agency];
+  const sessionLogs = computeSessionLogsSyncPaths(hqRoot);
+  return [
+    ...topLevel,
+    ...manifest,
+    ...companySubdirs,
+    ...continuity,
+    ...agency,
+    ...sessionLogs,
+  ];
 }
 
 /**
@@ -261,6 +274,39 @@ export function computeAgencySyncPaths(hqRoot: string): string[] {
   return [];
 }
 
+/**
+ * Fixed relative path (forward-slash, hq-root-relative) of the session-logs
+ * subtree. See {@link computeSessionLogsSyncPaths}.
+ */
+export const SESSION_LOGS_SYNC_REL = "workspace/.session-logs";
+
+/**
+ * Compute the absolute path of the session-logs carve-out:
+ * `workspace/.session-logs/` (the whole subtree).
+ *
+ * `hq reindex` copies this HQ root's Claude Code session transcripts here (see
+ * reindex's copySessionLogs). Like the agency carve-out above, this pierces the
+ * `workspace/` top-level exclusion for ONE specific subtree so those raw
+ * transcripts round-trip to the personal vault / S3 — the operator's explicit
+ * directive is that the session logs travel with the vault. The rest of
+ * `workspace/` (session scratch, locks, reports, worktrees) stays machine-local.
+ *
+ * Returns the directory path when it exists; share()'s per-file walk handles
+ * recursion, and the nested personal-vault exclusions still apply to files
+ * inside it. Fail-soft: a missing or unreadable `workspace/.session-logs/`
+ * returns []. Callers tolerate empty arrays — same contract as the manifest,
+ * continuity, and agency special-cases.
+ */
+export function computeSessionLogsSyncPaths(hqRoot: string): string[] {
+  const sessionLogsDir = path.join(hqRoot, "workspace", ".session-logs");
+  try {
+    if (fs.statSync(sessionLogsDir).isDirectory()) return [sessionLogsDir];
+  } catch {
+    // No session logs captured on this machine yet — nothing to carry.
+  }
+  return [];
+}
+
 /**
  * Discover `companies/{slug}/` subdirs that should sync to the personal
  * bucket as a fallback for companies the operator has not designated as

package/src/s3.test.ts

@@ -93,6 +93,7 @@ import {
   decodeSymlinkMetadataValue,
   FILE_MTIME_META_KEY,
   FILE_BTIME_META_KEY,
+  validateVaultUploadKey,
 } from "./s3.js";
 import {
   setObjectIOFactory,
@@ -1384,3 +1385,89 @@ describe("downloadFile", () => {
     expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
   });
 });
+
+describe("validateVaultUploadKey — direct-S3 key poisoning guard (incident 2026-07-11)", () => {
+  // The direct-S3 STS transport bypasses hq-pro's server-side validateObjectKey
+  // (files-acl.ts), so uploadFile/uploadSymlink must enforce the SAME rules
+  // before the PUT. Incident: a stale doubled local tree
+  // (companies/indigo/companies/indigo/…) pushed 25 literal `companies/…` keys
+  // into a company vault; the presign download API then rejected every one
+  // (INVALID_KEY_COMPANIES_SCOPED), erroring the whole company sync fleet-wide.
+  let tmpFile: string;
+
+  function makePersonalCtx(): EntityContext {
+    return { ...makeCtx(), uid: "prs_TEST" };
+  }
+
+  beforeEach(() => {
+    sentCommands.length = 0;
+    tmpFile = path.join(
+      os.tmpdir(),
+      `s3-keyguard-test-${Date.now()}-${Math.random()}.md`,
+    );
+    fs.writeFileSync(tmpFile, "hello");
+  });
+
+  afterEach(() => {
+    try {
+      fs.unlinkSync(tmpFile);
+    } catch {
+      // already gone
+    }
+  });
+
+  it("validateVaultUploadKey rejects companies/-prefixed keys in company scope with the server's error code", () => {
+    expect(() =>
+      validateVaultUploadKey("companies/indigo/knowledge/x.md", "company"),
+    ).toThrowError(
+      expect.objectContaining({ code: "INVALID_KEY_COMPANIES_SCOPED" }),
+    );
+  });
+
+  it("validateVaultUploadKey allows companies/-prefixed keys in personal scope (local non-cloud companies)", () => {
+    expect(() =>
+      validateVaultUploadKey("companies/indigo/knowledge/x.md", "personal"),
+    ).not.toThrow();
+  });
+
+  it.each([
+    ["", "INVALID_KEY_EMPTY"],
+    ["/leading.md", "INVALID_KEY_LEADING_SLASH"],
+    ["folder/", "INVALID_KEY_TRAILING_SLASH"],
+    ["a//b.md", "INVALID_KEY_DOUBLE_SLASH"],
+    ["a/../b.md", "INVALID_KEY_DOT_COMPONENT"],
+    ["a/./b.md", "INVALID_KEY_DOT_COMPONENT"],
+    ["bad\x00key.md", "INVALID_KEY_CONTROL_CHARS"],
+  ])(
+    "validateVaultUploadKey mirrors the server rule set: %j → %s",
+    (key, code) => {
+      expect(() => validateVaultUploadKey(key, "company")).toThrowError(
+        expect.objectContaining({ code }),
+      );
+      expect(() => validateVaultUploadKey(key, "personal")).toThrowError(
+        expect.objectContaining({ code }),
+      );
+    },
+  );
+
+  it("uploadFile refuses to PUT a companies/-prefixed key into a company (cmp_) vault — no S3 command is sent", async () => {
+    await expect(
+      uploadFile(makeCtx(), tmpFile, "companies/indigo/knowledge/x.md"),
+    ).rejects.toMatchObject({ code: "INVALID_KEY_COMPANIES_SCOPED" });
+    expect(sentCommands.length).toBe(0);
+  });
+
+  it("uploadSymlink refuses to PUT a companies/-prefixed key into a company (cmp_) vault — no S3 command is sent", async () => {
+    await expect(
+      uploadSymlink(makeCtx(), "../target.md", "companies/indigo/link.md"),
+    ).rejects.toMatchObject({ code: "INVALID_KEY_COMPANIES_SCOPED" });
+    expect(sentCommands.length).toBe(0);
+  });
+
+  it("uploadFile still allows companies/-prefixed keys for a personal (prs_) vault", async () => {
+    await expect(
+      uploadFile(makePersonalCtx(), tmpFile, "companies/indigo/knowledge/x.md"),
+    ).resolves.toBeDefined();
+    expect(sentCommands.length).toBeGreaterThan(0);
+  });
+});