@indigoai-us/hq-cloud 6.5.0 → 6.6.0

package/src/bin/sync-runner.ts

@@ -76,7 +76,11 @@ import {
   type ExplicitGrant,
 } from "../index.js";
 import { pickCanonicalPersonEntity } from "../vault-client.js";
-import { coalescePrefixes, grantPathToPrefix } from "../prefix-coalesce.js";
+import {
+  resolvePullScope,
+  readPinnedPrefixes,
+  type PullScope,
+} from "../sync/pull-scope.js";
 import {
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
   computePersonalVaultPaths,
@@ -401,121 +405,13 @@ export interface VaultClientSurface {
   listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
 }
 
-/**
- * Effective download scope for one company leg (US-005). Resolved per company
- * just before its pull, then handed to `sync()` as `{ syncMode, prefixSet }`.
- */
-export interface PullScope {
-  syncMode: SyncMode;
-  /** Coalesced company-relative prefixes; omitted/undefined for `all`. */
-  prefixSet?: string[];
-}
-
-/**
- * Resolve the effective download scope for a company target.
- *
- *   - `all`    → no prefix set; full-bucket pull (legacy behavior).
- *   - `shared` → coalesced caller explicit grants (company-relative paths,
- *                same namespace as `RemoteFile.key`).
- *   - `custom` → coalesced `customPaths` from the sync-config row.
- *
- * DEGRADE-TO-`all` CONTRACT: any failure (missing client method, membership
- * not found, network error, grant fetch error) returns `{ syncMode: "all" }`.
- * A transient failure must NEVER silently narrow scope — that would prune the
- * local tree. Mirrors the CLI's `resolvePerCompanyPullPlan` degrade behavior.
- */
-export async function resolvePullScope(
-  client: VaultClientSurface,
-  companyUid: string,
-  // Company slug — required to normalize grant paths (which may be anchored
-  // at `companies/<slug>/` or `<slug>/`) into the company-relative namespace.
-  slug: string,
-  // Local HQ root — used to read the per-machine pin set (`.hq/pins.json`).
-  // When omitted, pins are simply not unioned (no behavior change).
-  hqRoot?: string,
-): Promise<PullScope> {
-  if (!client.getMembershipSyncConfig) return { syncMode: "all" };
-  try {
-    const memberships = await client.listMyMemberships();
-    const m = memberships.find((x) => x.companyUid === companyUid);
-    if (!m) return { syncMode: "all" };
-    const cfg = await client.getMembershipSyncConfig(m.membershipKey);
-    if (cfg.syncMode === "all") return { syncMode: "all" };
-
-    // Pins are company-relative prefixes a user explicitly materialized via
-    // `hq files get`. They're unioned into the scope so a scoped pull keeps
-    // them instead of pruning them as out-of-scope orphans. Pins only WIDEN
-    // scope, never narrow — and `all` mode (handled above) ignores them since
-    // it pulls everything anyway.
-    const pinPrefixes = hqRoot ? readPinnedPrefixes(hqRoot, slug) : [];
-
-    if (cfg.syncMode === "custom") {
-      const customPrefixes = (cfg.customPaths ?? []).map((p) =>
-        grantPathToPrefix(p, slug),
-      );
-      // A bare-everything entry ("" — e.g. a `*` path) collapses under
-      // `coalescePrefixes` (which drops empties) to "nothing", which would
-      // prune the whole tree. An everything-scope is semantically `all`.
-      if (customPrefixes.some((p) => p === "")) return { syncMode: "all" };
-      return {
-        syncMode: "custom",
-        prefixSet: coalescePrefixes([...customPrefixes, ...pinPrefixes]),
-      };
-    }
-    // shared: scope to the caller's explicit grants. Real grant paths are
-    // inconsistent — full (`companies/<slug>/x/*`), slug-anchored
-    // (`<slug>/x/*`), company-relative (`x/*`), bare globs (`*`), and exact
-    // files all coexist in production — so each is normalized via
-    // `grantPathToPrefix` into a company-relative, startsWith-friendly prefix
-    // (the namespace the engine's `RemoteFile.key`s live in) before coalescing.
-    //
-    // SAFETY: if the client can't fetch grants, we must NOT fall through to an
-    // empty `shared` scope — that would tell the engine "nothing is in scope"
-    // and scope-shrink would prune every clean local file. Degrade to `all`
-    // instead. A genuinely-empty grant list (the method exists and returns
-    // []) is a real "nothing shared with me" and is allowed to narrow.
-    if (!client.listMyExplicitGrants) return { syncMode: "all" };
-    const grants = await client.listMyExplicitGrants(companyUid);
-    const sharedPrefixes = grants.map((g) => grantPathToPrefix(g.path, slug));
-    // A wildcard grant (`*`) normalizes to "" = everything. Since
-    // `coalescePrefixes` drops empties (collapsing "everything" to "nothing"),
-    // treat any such grant as full-access `all` rather than risk pruning.
-    if (sharedPrefixes.some((p) => p === "")) return { syncMode: "all" };
-    return {
-      syncMode: "shared",
-      prefixSet: coalescePrefixes([...sharedPrefixes, ...pinPrefixes]),
-    };
-  } catch {
-    // Degrade to `all` — never prune on a resolution failure.
-    return { syncMode: "all" };
-  }
-}
-
-/**
- * Read the per-machine pin set (`<hqRoot>/.hq/pins.json`) and return the
- * company-relative pinned prefixes for `slug`. These are prefixes the user
- * materialized on demand via `hq files get` that must survive a scoped pull.
- *
- * Tolerant by construction: a missing, unreadable, or malformed file yields
- * `[]` (no pins) — pins only ever widen scope, so "no pins" is the safe
- * default. Empty-string entries are dropped (an everything-pin is meaningless
- * here; `all` mode already covers that case).
- */
-export function readPinnedPrefixes(hqRoot: string, slug: string): string[] {
-  try {
-    const raw = fs.readFileSync(path.join(hqRoot, ".hq", "pins.json"), "utf-8");
-    const parsed = JSON.parse(raw) as { pins?: Record<string, unknown> };
-    const list = parsed?.pins?.[slug];
-    if (Array.isArray(list)) {
-      return list.filter(
-        (p): p is string => typeof p === "string" && p.length > 0,
-      );
-    }
-  } catch {
-    /* missing / unreadable / malformed → no pins */
-  }
-  return [];
-}
+// `resolvePullScope`, `readPinnedPrefixes`, and the `PullScope` type now live
+// in `../sync/pull-scope.ts` so the menubar runner and `hq sync pull|now`
+// (hq-cli) share ONE scope resolver — the drift between them was the root
+// cause of the all→shared scope-shrink wedge (DEV-1768). Re-exported here so
+// existing importers (and the runner test suite) keep their import path.
+export { resolvePullScope, readPinnedPrefixes };
+export type { PullScope };
 
 /**
  * Backoff schedule (in ms) between attempts 2 and 3 of
@@ -1446,6 +1342,13 @@ export async function runRunner(
           hqRoot: parsed.hqRoot,
           onConflict: parsed.onConflict,
           syncMode: pullScope.syncMode,
+          // The menubar runner can take no interactive flag, so a scope shrink
+          // must NEVER throw here (the old `ScopeShrinkBlockedError` → exit 2
+          // was the permanent wedge in DEV-1768). Self-heal non-destructively:
+          // dirty out-of-scope files stay on disk + un-tracked, clean ones are
+          // quarantined (recoverable). This also clears an already-wedged
+          // journal — seeded by a buggy `all`-mode CLI pull — on the next sync.
+          scopeShrinkPolicy: "auto-recover",
           // Scope-shrink authorship guard: pass the caller's own sub (the very
           // sub stamped onto uploads as `created-by-sub`) so a scope shrink
           // never prunes content this owner authored. Owners hold their whole

package/src/cli/sync-scope.test.ts

@@ -340,4 +340,88 @@ describe("sync — scope-aware download (US-005)", () => {
     expect(forced.scopeOrphansBlocked).toBe(1);
     expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
   });
+
+  // DEV-1768 fix #3: a scope shrink must QUARANTINE clean orphans (recoverable),
+  // never silently delete them. The file leaves its working-tree path but is
+  // recoverable under `.hq/scope-quarantine/<slug>/`.
+  it("scope shrink QUARANTINES a clean orphan (recoverable), never silent-deletes", async () => {
+    const quarantined = path.join(
+      tmpDir,
+      ".hq",
+      "scope-quarantine",
+      "acme",
+      "docs",
+      "handoff.md",
+    );
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
+    const original = companyRel("docs/handoff.md");
+    const bodyBefore = fs.readFileSync(original, "utf-8");
+
+    const shared = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["knowledge/"],
+    });
+
+    expect(shared.scopeOrphansRemoved).toBe(1);
+    // Gone from the working tree...
+    expect(fs.existsSync(original)).toBe(false);
+    // ...but recoverable in quarantine, byte-for-byte.
+    expect(fs.existsSync(quarantined)).toBe(true);
+    expect(fs.readFileSync(quarantined, "utf-8")).toBe(bodyBefore);
+  });
+
+  // DEV-1768 fix #1 (recovery) + #2: the background runner path
+  // (`scopeShrinkPolicy: "auto-recover"`) must NEVER throw on a scope shrink —
+  // it self-heals. This reproduces the EXACT wedge: a buggy `all`-mode pull
+  // seeds the journal (all-mode PullRecord + both files), one out-of-scope file
+  // is edited locally (dirty), then the real `shared` pull arrives. Under the
+  // old code this threw ScopeShrinkBlockedError(all→shared) → exit 2 forever.
+  it("auto-recover policy clears an all→shared wedge: dirty kept on disk, clean quarantined, no throw", async () => {
+    // 1. Buggy all-mode CLI seed: journals everything + stamps an all-mode record.
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
+    // 2. User edits an out-of-scope file → it becomes a DIRTY orphan.
+    fs.writeFileSync(companyRel("docs/handoff.md"), "LOCAL EDIT — keep me");
+    const quarantinedClean = path.join(
+      tmpDir, ".hq", "scope-quarantine", "acme", "knowledge", "readme.md",
+    );
+
+    // 3. The menubar runner's real shared pull. prefixSet covers NEITHER file
+    //    (docs is dirty-orphan, knowledge becomes a clean orphan) so we exercise
+    //    both dispositions. Must resolve without throwing.
+    const recovered = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["projects/"],
+      scopeShrinkPolicy: "auto-recover",
+    });
+    expect(recovered.aborted).toBe(false);
+    // Dirty file: KEPT on disk (un-tracked), counted as blocked-but-kept.
+    expect(recovered.scopeOrphansBlocked).toBe(1);
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
+    expect(fs.readFileSync(companyRel("docs/handoff.md"), "utf-8")).toBe(
+      "LOCAL EDIT — keep me",
+    );
+    // Clean file: quarantined (recoverable), removed from the working tree.
+    expect(recovered.scopeOrphansRemoved).toBe(1);
+    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(false);
+    expect(fs.existsSync(quarantinedClean)).toBe(true);
+
+    // 4. Idempotent: the next auto-recover sync re-flags NOTHING (the orphans
+    //    were tombstoned, so the wedge does not recur).
+    const second = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["projects/"],
+      scopeShrinkPolicy: "auto-recover",
+    });
+    expect(second.scopeOrphansRemoved).toBe(0);
+    expect(second.scopeOrphansBlocked).toBe(0);
+  });
 });

package/src/cli/sync.ts

@@ -40,6 +40,7 @@ import {
   applyScopeShrink,
   ScopeShrinkBlockedError,
   ScopeShrinkLargePruneError,
+  type ScopeShrinkAdviceContext,
 } from "../scope-shrink.js";
 import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
@@ -355,6 +356,25 @@ export interface SyncOptions {
    * tombstoned. Mirrors `hq sync narrow --force`.
    */
   forceScopeShrink?: boolean;
+  /**
+   * How `sync()` handles a scope shrink (US-005 / DEV-1768):
+   *
+   *   - `"block"` (default) — a human is present (foreground `hq sync`). Dirty
+   *     out-of-scope orphans, or a clean prune over the safety cap, raise a
+   *     structured error whose advice is followable from a terminal. Clean
+   *     orphans within the cap are QUARANTINED (moved, not deleted).
+   *   - `"auto-recover"` — the background menubar runner, which can take no
+   *     interactive flag. NEVER throws on a shrink: dirty orphans are kept on
+   *     disk + un-tracked, clean orphans are quarantined, and the bulk-prune
+   *     cap is bypassed (quarantine is non-destructive). This is what clears an
+   *     already-wedged journal on the next sync, idempotently and without data
+   *     loss — the recovery seam for the all→shared seed bug.
+   *
+   * Both policies are non-destructive for CLEAN files (quarantine, never
+   * silent delete) — the deliberate `hq sync narrow --apply` ritual is the only
+   * path that hard-deletes, and it confirms first.
+   */
+  scopeShrinkPolicy?: "block" | "auto-recover";
   /**
    * The caller's own Cognito `sub`, used by the scope-shrink authorship guard
    * so a scope shrink never prunes content the caller authored. Injected by the
@@ -655,23 +675,38 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     // explicit `hq sync narrow` ritual opts out of the unknown-author shield.
     protectUnknownAuthors: true,
   });
-  if (shrinkPlan.dirty.length > 0 && options.forceScopeShrink !== true) {
+  // Policy: the background menubar runner ("auto-recover") can take no
+  // interactive flag, so it must never throw on a shrink — it self-heals
+  // non-destructively (dirty kept on disk + un-tracked, clean quarantined).
+  // A foreground `hq sync` ("block", the default) keeps the protective gate
+  // but renders FOLLOWABLE advice. `autoRecover` implies force (proceed) and
+  // bypasses the bulk-prune cap (quarantine is non-destructive, so a large
+  // recovery move is safe). DEV-1768.
+  const scopeShrinkPolicy = options.scopeShrinkPolicy ?? "block";
+  const autoRecover = scopeShrinkPolicy === "auto-recover";
+  const adviceContext: ScopeShrinkAdviceContext = autoRecover ? "runner" : "cli";
+  const effectiveForce = options.forceScopeShrink === true || autoRecover;
+
+  if (shrinkPlan.dirty.length > 0 && !effectiveForce) {
     throw new ScopeShrinkBlockedError(
       ctx.uid,
       lastRecord?.syncMode ?? "unknown",
       syncMode,
       shrinkPlan.dirty,
       shrinkPlan.clean,
+      adviceContext,
     );
   }
-  // Bulk-delete guard: refuse to auto-prune more than the safety cap of CLEAN
-  // files in a single background sync. A deliberate large narrow goes through
-  // `hq sync narrow --apply` (its own confirmation), and `--force-scope-shrink`
-  // (or raising HQ_SYNC_MAX_AUTO_PRUNE) overrides. Cap of 0 = unlimited (opt
-  // out). The engine deletes nothing when it throws here.
+  // Bulk guard: refuse to auto-move more than the safety cap of CLEAN files in
+  // a single foreground sync. A deliberate large narrow goes through
+  // `hq sync narrow --apply` (its own confirmation); `--force-scope-shrink` (or
+  // raising HQ_SYNC_MAX_AUTO_PRUNE) overrides. Cap of 0 = unlimited. Skipped
+  // under auto-recover — quarantine is non-destructive so a big recovery is
+  // safe, and the runner has no way to act on a thrown cap. The engine moves
+  // nothing when it throws here.
   const autoPruneCap = resolveAutoPruneCap();
   if (
-    options.forceScopeShrink !== true &&
+    !effectiveForce &&
     autoPruneCap > 0 &&
     shrinkPlan.clean.length > autoPruneCap
   ) {
@@ -680,27 +715,65 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       syncMode,
       shrinkPlan.clean.length,
       autoPruneCap,
+      adviceContext,
     );
   }
+  // Clean orphans are QUARANTINED (moved into `.hq/scope-quarantine/<slug>/`,
+  // recoverable), never silently deleted — a background sync purging local
+  // files unannounced was DEV-1768 fix #3. The quarantine root lives under the
+  // real HQ root's `.hq/` (outside `companyRoot` and never pushed), so moved
+  // files don't round-trip back through S3.
+  const scopeQuarantineRoot = path.join(
+    hqRoot,
+    ".hq",
+    "scope-quarantine",
+    journalSlug,
+  );
   const shrinkResult = applyScopeShrink({
     journal,
     plan: shrinkPlan,
     hqRoot: companyRoot,
-    forceScopeShrink: options.forceScopeShrink === true,
+    forceScopeShrink: effectiveForce,
     reason: "scope_shrink",
+    cleanDisposition: "quarantine",
+    quarantineRoot: scopeQuarantineRoot,
   });
-  // Surface each removed clean orphan as a `deleted` progress event so the
-  // menubar stream renders the prune the same way it renders a cross-machine
-  // tombstone (the Rust parser already handles `deleted: true`).
-  for (const orphan of shrinkPlan.clean) {
+  // Surface each affected orphan explicitly (named path) so the prune is never
+  // silent. Quarantined clean files render as `deleted: true` (removed from the
+  // working tree, recoverable in quarantine); dirty files KEPT on disk render
+  // as a non-deletion notice so the operator knows they were un-tracked, not
+  // removed. The Rust menubar parser already handles `deleted: true`.
+  for (const relPath of shrinkResult.quarantinedPaths) {
+    emit({
+      type: "progress",
+      path: relPath,
+      bytes: 0,
+      deleted: true,
+      message: `scope-narrowed: moved out-of-scope copy to ${scopeQuarantineRoot}`,
+    });
+  }
+  for (const relPath of shrinkResult.removedPaths) {
     emit({
       type: "progress",
-      path: orphan.path,
+      path: relPath,
       bytes: 0,
       deleted: true,
       message: "scope-narrowed (removed local copy outside sync scope)",
     });
   }
+  for (const relPath of shrinkResult.dirtyKeptPaths) {
+    emit({
+      type: "progress",
+      path: relPath,
+      bytes: 0,
+      message:
+        "scope-narrowed: locally-modified file KEPT on disk, un-tracked from sync (outside scope)",
+    });
+  }
+  // "Removed from the working tree" = deleted OR quarantined; both vacate the
+  // file's original path. Reported as `scopeOrphansRemoved` for back-compat.
+  const scopeOrphansRemoved =
+    shrinkResult.cleanRemoved + shrinkResult.cleanQuarantined;
 
   // Stage 2: execute the plan. Per-item branching mirrors the pre-refactor
   // inline loop; the only structural change is that classification has
@@ -949,7 +1022,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           // a conflict abort. `filesOutOfScope` reflects how far the serial
           // pass got before the abort; that's acceptable for an abort result.
           filesOutOfScope,
-          scopeOrphansRemoved: shrinkResult.cleanRemoved,
+          scopeOrphansRemoved,
           scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
         };
         break;
@@ -1328,7 +1401,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     syncMode,
     prefixSet: currentPrefixSet,
     scopeChangeDetected: shrinkPlan.scopeChangeDetected,
-    orphansRemoved: shrinkResult.cleanRemoved,
+    orphansRemoved: scopeOrphansRemoved,
     orphansBlocked: shrinkResult.dirtyTombstoned,
   });
 
@@ -1347,7 +1420,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   const changedOnDisk =
     filesDownloaded > 0 ||
     filesTombstoned > 0 ||
-    shrinkResult.cleanRemoved > 0;
+    scopeOrphansRemoved > 0;
   if (!options.skipReindex && changedOnDisk) {
     try {
       // skipLock: the surrounding sync run already holds this root's operation
@@ -1370,7 +1443,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     filesExcludedByPolicy: plan.filesExcludedByPolicy,
     filesTombstoned,
     filesOutOfScope,
-    scopeOrphansRemoved: shrinkResult.cleanRemoved,
+    scopeOrphansRemoved,
     scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
   };
 }

package/src/index.ts

@@ -69,6 +69,7 @@ export {
   buildScopeShrinkPlan,
   applyScopeShrink,
   ScopeShrinkBlockedError,
+  ScopeShrinkLargePruneError,
 } from "./scope-shrink.js";
 export type {
   OrphanClassification,
@@ -76,6 +77,8 @@ export type {
   BuildScopeShrinkPlanInput,
   ApplyScopeShrinkInput,
   ApplyScopeShrinkResult,
+  ScopeShrinkAdviceContext,
+  CleanOrphanDisposition,
 } from "./scope-shrink.js";
 
 // Engine-layer ACL-aware pull orchestration (US-005)
@@ -118,6 +121,14 @@ export {
 } from "./cognito-auth.js";
 export type { CognitoAuthConfig, CognitoTokens } from "./cognito-auth.js";
 
+// Per-company PULL scope resolver (US-005) — shared between hq-sync-runner and
+// `hq sync pull|now` (hq-cli). Exported so hq-cli's foreground pull paths resolve
+// 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 type { PullScope, PullScopeClient } from "./sync/pull-scope.js";
+
 // Personal-vault scope helpers — shared between hq-sync-runner and `hq sync`
 export {
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,

package/src/s3.test.ts

@@ -6,7 +6,7 @@
  * `Metadata`, so the listing's HEAD fan-out had nothing to attribute.
  */
 
-import { describe, it, expect, beforeEach, vi } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -83,6 +83,7 @@ import {
   uploadFile,
   uploadSymlink,
   toPosixKey,
+  primeUploads,
   downloadFile,
   listRemoteFiles,
   SYMLINK_BODY_PREFIX,
@@ -92,6 +93,12 @@ import {
   FILE_MTIME_META_KEY,
   FILE_BTIME_META_KEY,
 } from "./s3.js";
+import {
+  setObjectIOFactory,
+  presignObjectIOFactory,
+  type PresignTransportClient,
+} from "./object-io.js";
+import type { PresignResultRow } from "./vault-client.js";
 import type { EntityContext } from "./types.js";
 
 function makeCtx(): EntityContext {
@@ -158,6 +165,89 @@ describe("backslash key normalization (Windows client → POSIX S3 key)", () =>
   });
 });
 
+describe("backslash key normalization on the PRESIGNED (GA) transport", () => {
+  // The tests above assert normalization on the S3-SDK transport (sentCommands
+  // capture SDK PutObjectCommands). As of 6.5.0 the presigned-URL transport is
+  // GA for every company vault (cmp_*) — that's the path a real Windows client
+  // like Ridge's now takes. These lock the SAME write-side invariant on that
+  // transport: a backslash key is canonicalized to POSIX before the server is
+  // ever asked to presign it, so a non-POSIX vault key can never be minted.
+  let tmpFile: string;
+  let presignCalls: Array<{ op?: string; keys: Array<{ key?: string }> }>;
+
+  function presignKeysFor(op: string): string[] {
+    return presignCalls
+      .filter((c) => c.op === op)
+      .flatMap((c) => c.keys.map((k) => k.key ?? ""));
+  }
+
+  beforeEach(() => {
+    tmpFile = path.join(
+      os.tmpdir(),
+      `s3-presign-backslash-${Date.now()}-${Math.random()}.md`,
+    );
+    fs.writeFileSync(tmpFile, "hello");
+
+    presignCalls = [];
+    const vault: PresignTransportClient = {
+      // Echo each requested key back as a usable URL so putObject's PUT
+      // resolves; record the op + keys so we can assert what was signed.
+      presign: async (input) => {
+        presignCalls.push({ op: input.op, keys: input.keys as Array<{ key?: string }> });
+        const results: PresignResultRow[] = input.keys.map((k) => ({
+          key: (k as { key: string }).key,
+          op: input.op ?? "put",
+          url: `https://s3.test/${(k as { key: string }).key}`,
+        }));
+        return { results, expiresAt: "2099-01-01T00:00:00.000Z" };
+      },
+      listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
+    };
+    setObjectIOFactory(presignObjectIOFactory(vault));
+    // putObject moves bytes over the presigned URL via global fetch.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(null, { status: 200, headers: { etag: '"e"' } })),
+    );
+  });
+
+  afterEach(() => {
+    setObjectIOFactory(null);
+    vi.unstubAllGlobals();
+  });
+
+  it("uploadFile presigns + PUTs a POSIX key for a Windows-style backslash path", async () => {
+    await uploadFile(makeCtx(), tmpFile, "knowledge\\books-eoi.md");
+    expect(presignKeysFor("put")).toContain("knowledge/books-eoi.md");
+    // The malformed backslash key is never presigned (so never PUT).
+    expect(presignKeysFor("put")).not.toContain("knowledge\\books-eoi.md");
+  });
+
+  it("uploadSymlink presigns a POSIX key for a Windows-style backslash path", async () => {
+    await uploadSymlink(makeCtx(), "../target.md", "data\\boots-accounts.json");
+    expect(presignKeysFor("put")).toContain("data/boots-accounts.json");
+    expect(presignKeysFor("put")).not.toContain("data\\boots-accounts.json");
+  });
+
+  it("primeUploads canonicalizes keys so the primed PUT URL matches the upload lookup", async () => {
+    // Prime then upload the SAME Windows-origin key. Both must key the cache
+    // under the POSIX form: prime signs the POSIX PUT URL, and uploadFile's
+    // hasPrimedPut(toPosixKey(...)) reuses it instead of re-presigning — proving
+    // the primed fast-path can't strand a backslash key (and can't store one).
+    await primeUploads(makeCtx(), [
+      { key: "knowledge\\books-eoi.md", localPath: tmpFile, isSymlink: false },
+    ]);
+    // prime("get") + prime("put") both went out under the POSIX key only.
+    expect(presignKeysFor("get")).toEqual(["knowledge/books-eoi.md"]);
+    expect(presignKeysFor("put")).toEqual(["knowledge/books-eoi.md"]);
+
+    const putCountAfterPrime = presignKeysFor("put").length;
+    await uploadFile(makeCtx(), tmpFile, "knowledge\\books-eoi.md");
+    // No NEW put presign: uploadFile reused the primed POSIX URL (cache hit).
+    expect(presignKeysFor("put").length).toBe(putCountAfterPrime);
+  });
+});
+
 describe("uploadFile", () => {
   let tmpFile: string;
 

package/src/s3.ts

@@ -339,9 +339,14 @@ export async function primeUploads(
   if (!io.prime || items.length === 0) return;
 
   // Prime GET first so each item's created-at HEAD reuses a cached URL.
+  // Canonicalize to POSIX here (one-canonical-form, matching the uploadFile /
+  // uploadSymlink boundary): a Windows-origin backslash key must cache under
+  // the SAME key uploadFile later looks up via hasPrimedPut(toPosixKey(...)),
+  // or the primed URL silently misses and the upload re-presigns. It also
+  // keeps the created-at HEAD pointed at the real (POSIX) object.
   await io.prime(
     "get",
-    items.map((i) => ({ key: i.key })),
+    items.map((i) => ({ key: toPosixKey(i.key) })),
   );
 
   // Build per-key PUT metadata with the SAME builders the upload path uses,
@@ -356,10 +361,15 @@ export async function primeUploads(
   const worker = async (): Promise<void> => {
     while (next < items.length) {
       const it = items[next++];
-      const createdAt = await resolveCreatedAt(io, it.key, it.author);
+      // Same boundary guardrail as uploadFile/uploadSymlink: prime under the
+      // canonical POSIX key so the cached PUT URL is keyed identically to the
+      // hasPrimedPut/putObject lookup, and a backslash key can never be primed
+      // (let alone stored) as a non-POSIX vault key.
+      const key = toPosixKey(it.key);
+      const createdAt = await resolveCreatedAt(io, key, it.author);
       if (it.isSymlink) {
         putKeys.push({
-          key: it.key,
+          key,
           contentType: "application/octet-stream",
           metadata: {
             [SYMLINK_TARGET_META_KEY]: SYMLINK_MARKER_META_VALUE,
@@ -374,8 +384,8 @@ export async function primeUploads(
           // raced rm / EPERM — leave stamps off (receiver umask default).
         }
         putKeys.push({
-          key: it.key,
-          contentType: getMimeType(it.key),
+          key,
+          contentType: getMimeType(key),
           metadata: {
             ...(it.author ? buildAuthorMetadata(it.author, createdAt) : {}),
             ...modeTime,