@indigoai-us/hq-cloud 6.2.4 → 6.2.6

package/src/cli/share.ts

@@ -41,6 +41,7 @@ import {
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
 import type { SyncProgressEvent } from "./sync.js";
+import { isCoveredByAny, isDirInScope } from "../prefix-coalesce.js";
 import {
   buildConflictId,
   buildConflictPath,
@@ -218,6 +219,21 @@ export function isEphemeralPath(p: string): boolean {
   return EPHEMERAL_PATH_PATTERN.test(p);
 }
 
+/**
+ * A vault key containing a backslash is never legitimate. HQ keys are POSIX
+ * (`toPosixKey` normalizes at every walker since 5.47.2 and `uploadFile`
+ * hard-normalizes at the S3 boundary), so a `\` in a remote key can only come
+ * from a pre-5.47.2 Windows client whose walker built keys with `path.sep` —
+ * verified live 2026-06-10: one such client duplicated 5,711 keys
+ * (`skills\demo-hq\SKILL.md`, …) into a company vault, and every up-to-date
+ * puller then materialized them as junk single-filename-with-backslash files
+ * that churned conflicts forever. The pull walker refuses these keys
+ * (skip-excluded-policy), symmetric with the ephemeral-mirror filter above.
+ */
+export function isMalformedVaultKey(key: string): boolean {
+  return key.includes("\\");
+}
+
 /**
  * Test-only export. Kept under a `_testing` namespace so the module's public
  * surface stays focused on `share()` / `ShareOptions` / `ShareResult` while
@@ -576,6 +592,20 @@ export interface ShareOptions {
    * `sync-journal.personal.json` file.
    */
   journalSlug?: string;
+  /**
+   * Effective ACL push scope as a list of company-relative prefixes (the same
+   * coalesced `prefixSet` the pull leg uses for `syncMode: "shared"`). When
+   * provided, the upload + delete plans are filtered to paths covered by these
+   * prefixes — any candidate outside them is skipped (and surfaced via a
+   * `scope-excluded` event) rather than PUT, because the vended child
+   * credential is scoped to exactly these prefixes and an out-of-scope PUT
+   * draws the server's correct 403 `SCOPE_EXCEEDS_PARENT`.
+   *
+   * `undefined` (the owner/`all` case, and `hq share <file>`) applies NO scope
+   * filter — full access. An empty array means "no granted prefixes" → every
+   * path is out of scope (mirrors the pull side's `isCoveredByAny([])`).
+   */
+  prefixSet?: string[];
 }
 
 export interface ShareResult {
@@ -629,6 +659,16 @@ export interface ShareResult {
    * emitted exactly once if this is > 0).
    */
   filesExcludedByPolicy: number;
+  /**
+   * Number of distinct company-relative paths/prefixes skipped because they
+   * fell OUTSIDE the run's ACL `prefixSet` (member/guest scoped push). Always
+   * 0 when `prefixSet` is undefined (owner/`all`) or the whole tree is in
+   * scope. Mirrors the `count` field of the `scope-excluded` event (emitted
+   * once if this is > 0). These paths were never PUT, so the server's correct
+   * 403 `SCOPE_EXCEEDS_PARENT` is never triggered and the company still syncs
+   * its in-scope subset.
+   */
+  filesExcludedByScope: number;
   /**
    * Paths (company-relative) that were detected as push conflicts. Mirrors
    * `SyncResult.conflictPaths` so push and pull surface conflicts the same
@@ -638,6 +678,56 @@ export interface ShareResult {
   aborted: boolean;
 }
 
+/**
+ * Is this error the S3/STS "access denied" class? Expected when a scoped
+ * member/guest credential touches a key outside its granted ACL prefixes
+ * (the server's `SCOPE_EXCEEDS_PARENT` surfaces as a 403 AccessDenied /
+ * Forbidden). Mirrors the pull-side `isAccessDenied` in sync.ts so the push
+ * leg can treat a stray out-of-scope key as a skip rather than a fatal throw.
+ */
+function isAccessDenied(err: unknown): boolean {
+  if (err && typeof err === "object" && "name" in err) {
+    const name = (err as { name?: unknown }).name;
+    return name === "AccessDenied" || name === "Forbidden";
+  }
+  return false;
+}
+
+/**
+ * Wrap an existing path filter (ignore filter, optionally already wrapped with
+ * the personal-vault defaults) so that paths OUTSIDE the run's ACL `prefixSet`
+ * are rejected before they enter the upload OR delete plan. Keeps the
+ * `(absolutePath, isDir) => boolean` shape the rest of share() already uses
+ * (collectFiles / walkDir / computeDeletePlan), so wiring is one line at the
+ * filter-construction site — exactly like `wrapFilterWithPersonalVaultDefaults`.
+ *
+ * Files use `isCoveredByAny` (plain `startsWith`); directories use
+ * `isDirInScope` (descend if the dir is inside a grant OR a grant is inside
+ * the dir) so the walk still reaches deep/exact-file grants. Rejected entries
+ * are tagged via `onScopeExcluded` (directories with a trailing slash) so the
+ * runner can emit a single `scope-excluded` summary naming what was skipped.
+ */
+function wrapFilterWithScope(
+  underlying: (absPath: string, isDir?: boolean) => boolean,
+  syncRoot: string,
+  prefixSet: readonly string[],
+  onScopeExcluded: (rel: string) => void,
+): (absPath: string, isDir?: boolean) => boolean {
+  return (absPath: string, isDir?: boolean) => {
+    if (!underlying(absPath, isDir)) return false;
+    const rel = path.relative(syncRoot, absPath).split(path.sep).join("/");
+    if (rel === "" || rel.startsWith("..")) return true; // root / outside — defer
+    if (isDir) {
+      if (isDirInScope(rel, prefixSet)) return true;
+      onScopeExcluded(rel.endsWith("/") ? rel : rel + "/");
+      return false;
+    }
+    if (isCoveredByAny(rel, prefixSet)) return true;
+    onScopeExcluded(rel);
+    return false;
+  };
+}
+
 /**
  * Share local file(s) to the entity vault.
  */
@@ -753,9 +843,22 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     excludedSet.add(rel);
     excludedById[match.id] = (excludedById[match.id] ?? 0) + 1;
   };
-  const shouldSync = options.personalMode === true
+  // ACL scope filter (member/guest scoped push). The vended child credential
+  // is scoped to `options.prefixSet`; any candidate outside those prefixes
+  // would draw the server's correct 403 SCOPE_EXCEEDS_PARENT on PUT and abort
+  // the whole company. Pre-filter the plan to the granted subset instead —
+  // the push-side analogue of the pull leg's `skip-out-of-scope` (US-005).
+  // `undefined` = owner/`all` → no scope filter (full access).
+  const scopeExcludedSet = new Set<string>();
+  const onScopeExcluded = (rel: string) => {
+    scopeExcludedSet.add(rel);
+  };
+  const baseFilter = options.personalMode === true
     ? wrapFilterWithPersonalVaultDefaults(ignoreFilter, syncRoot, onExcluded)
     : ignoreFilter;
+  const shouldSync = options.prefixSet !== undefined
+    ? wrapFilterWithScope(baseFilter, syncRoot, options.prefixSet, onScopeExcluded)
+    : baseFilter;
   const journalSlug = options.journalSlug ?? ctx.slug;
   // Seed the canonical personal-vault journal from the legacy `personal` file
   // exactly once — engine-side so every consumer (sync-runner, hq-cli) gets
@@ -993,7 +1096,32 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // single-part etag) and compare. Match → no conflict, silently skip
     // the PUT (the bytes are already there). Mismatch → treat as a
     // conflict in the same shared branch below.
-    const remoteMeta = await headRemoteFile(ctx, relativePath);
+    // Defense-in-depth for the scoped-push 403: the `prefixSet` filter above
+    // should already have dropped any out-of-scope key from the plan, but a
+    // grant that changed mid-run, a pinned prefix outside the grant, or
+    // prefix-coalesce imprecision can still leave an out-of-scope key here.
+    // This HEAD sits OUTSIDE the per-file PUT try/catch below, so a thrown
+    // 403 used to bubble to `workerErrors` and abort the ENTIRE company with
+    // a generic message and exit 2. Catch the access-denied class, surface
+    // the offending PATH clearly, and skip just this key — the rest of the
+    // company still syncs. Non-access-denied errors re-throw unchanged.
+    let remoteMeta: Awaited<ReturnType<typeof headRemoteFile>>;
+    try {
+      remoteMeta = await headRemoteFile(ctx, relativePath);
+    } catch (headErr) {
+      if (isAccessDenied(headErr)) {
+        emit({
+          type: "error",
+          path: relativePath,
+          message:
+            "skipped: outside granted ACL scope (server returned 403 " +
+            "SCOPE_EXCEEDS_PARENT / access denied on HEAD). Grant this path " +
+            "to push it, or it stays local-only.",
+        });
+        return;
+      }
+      throw headErr;
+    }
     if (remoteMeta) {
       const journalEntry = journal.files[relativePath];
       const localChanged = !!journalEntry && journalEntry.hash !== localHash;
@@ -1199,7 +1327,13 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       emit({
         type: "error",
         path: relativePath,
-        message: err instanceof Error ? err.message : String(err),
+        message: isAccessDenied(err)
+          ? "skipped: outside granted ACL scope (server returned 403 " +
+            "SCOPE_EXCEEDS_PARENT / access denied on PUT). Grant this path " +
+            "to push it, or it stays local-only."
+          : err instanceof Error
+            ? err.message
+            : String(err),
       });
     }
   };
@@ -1269,6 +1403,9 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       // abort (matches the existing convention: abort short-circuits
       // before the end-of-run telemetry emits).
       filesExcludedByPolicy: excludedSet.size,
+      // Scope exclusions are likewise computed during the upload walk, so the
+      // count is meaningful on the abort path too.
+      filesExcludedByScope: scopeExcludedSet.size,
       // Use the snapshot of conflictPaths taken at the moment the abort
       // fired — additional in-flight items may have appended to the
       // shared array after the abort signal, and those should not show
@@ -1388,6 +1525,24 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     });
   }
 
+  // ACL scope-exclusion summary. Emit at most once when one or more candidate
+  // paths fell outside the run's granted `prefixSet` and were skipped from the
+  // upload/delete plan. Informational (NOT an error): the company still syncs
+  // its in-scope subset and the run exits 0. Sample capped at 10 (insertion
+  // order = walk order, deterministic).
+  if (scopeExcludedSet.size > 0) {
+    const samplePaths: string[] = [];
+    for (const p of scopeExcludedSet) {
+      samplePaths.push(p);
+      if (samplePaths.length >= 10) break;
+    }
+    emit({
+      type: "scope-excluded",
+      count: scopeExcludedSet.size,
+      samplePaths,
+    });
+  }
+
   // Codex P1 (5.36.x): if any worker rejected (unhandled error in
   // headRemoteFile / refreshEntityContext / resolveConflict — paths
   // outside the per-item PUT try/catch), we deliberately let the pool
@@ -1414,6 +1569,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     filesRefusedStale,
     filesRefusedStalePaths,
     filesExcludedByPolicy: excludedSet.size,
+    filesExcludedByScope: scopeExcludedSet.size,
     conflictPaths,
     aborted: false,
   };

package/src/cli/sync.test.ts

@@ -1100,6 +1100,42 @@ describe("sync", () => {
     expect(result.filesExcludedByPolicy).toBeGreaterThanOrEqual(1);
   });
 
+  it("skips remote keys containing backslashes (malformed Windows-client keys)", async () => {
+    // A pre-5.47.2 Windows client built S3 keys with path.sep, duplicating a
+    // company tree under keys like `skills\\demo-hq\\SKILL.md` (verified live
+    // 2026-06-10: 5,711 such keys in one vault). On POSIX, downloading one
+    // creates a junk FILE whose name contains backslashes, which then churns
+    // conflict mirrors on every sync. The pull planner must refuse them at
+    // planning time — same policy bucket as the ephemeral-mirror filter.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      // Malformed Windows key — must be filtered, never downloaded.
+      {
+        key: "skills\\demo\\SKILL.md",
+        size: 44,
+        lastModified: new Date(),
+        etag: '"abc"',
+      },
+      // Its legitimate POSIX twin — must still download.
+      { key: "skills/demo/SKILL.md", size: 30, lastModified: new Date(), etag: '"def"' },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    // The malformed key MUST NOT be materialized — neither as a literal
+    // backslash-named file nor as a nested path.
+    expect(fs.existsSync(path.join(companyRoot, "skills\\demo\\SKILL.md"))).toBe(false);
+    // The legitimate twin MUST download.
+    expect(fs.existsSync(path.join(companyRoot, "skills", "demo", "SKILL.md"))).toBe(true);
+
+    expect(result.filesDownloaded).toBe(1);
+    expect(result.filesExcludedByPolicy).toBeGreaterThanOrEqual(1);
+  });
+
   it("overwrites local on --on-conflict overwrite", async () => {
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
     fs.mkdirSync(companyDocs, { recursive: true });

package/src/cli/sync.ts

@@ -42,7 +42,7 @@ import {
 } from "../scope-shrink.js";
 import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
-import { isEphemeralPath } from "./share.js";
+import { isEphemeralPath, isMalformedVaultKey } from "./share.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy, ConflictResolution } from "./conflict.js";
 import {
@@ -241,6 +241,28 @@ export type SyncProgressEvent =
       count: number;
       samplePaths: string[];
       byId: Record<string, number>;
+    }
+  | {
+      /**
+       * Emitted at most ONCE per `share()` call (push leg) when the run is
+       * scoped to a member/guest's ACL prefixes (`prefixSet`) and one or more
+       * candidate paths fell OUTSIDE the granted prefixes. Those paths are
+       * skipped from the upload (and delete) plan instead of being PUT — the
+       * vended child credential is scoped to the granted prefixes, so pushing
+       * them would draw the server's correct 403 `SCOPE_EXCEEDS_PARENT` and
+       * (pre-fix) abort the WHOLE company. This is the push-side analogue of
+       * the pull-side `skip-out-of-scope` action.
+       *
+       * `count` is the number of distinct company-relative paths/prefixes the
+       * scope filter excluded; `samplePaths` carries up to 10 for diagnostic
+       * display. Informational, NOT an error — the company still syncs its
+       * in-scope subset and the run exits 0.
+       *
+       * Not emitted when `count === 0` — silent on a fully in-scope tree.
+       */
+      type: "scope-excluded";
+      count: number;
+      samplePaths: string[];
     };
 
 export interface SyncOptions {
@@ -1477,6 +1499,17 @@ function computePullPlan(
       continue;
     }
 
+    // Malformed-key filter — keys with backslash separators pushed by
+    // pre-5.47.2 Windows clients. Downloading one materializes a junk local
+    // file whose NAME contains backslashes (it is not a path on POSIX), which
+    // then churns conflict mirrors forever. Refuse at planning time, same
+    // policy bucket as the ephemeral filter above. The bogus keys themselves
+    // are cleaned server-side; this keeps clean trees clean in the meantime.
+    if (isMalformedVaultKey(remoteFile.key)) {
+      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
+      continue;
+    }
+
     if (personalMode && remoteFile.key.startsWith("companies/")) {
       // Default: drop every `companies/...` key — the legacy contract
       // is that the personal bucket should never contain them.
@@ -1866,5 +1899,15 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
         console.log(`  ... and ${event.files.length - MAX_SHOWN} more`);
       }
     }
+  } else if (event.type === "scope-excluded") {
+    console.log(
+      `  ~ ${event.count} path${event.count === 1 ? "" : "s"} skipped — outside your granted access (synced the in-scope subset):`,
+    );
+    for (const p of event.samplePaths) {
+      console.log(`    · ${p}`);
+    }
+    if (event.count > event.samplePaths.length) {
+      console.log(`    ... and ${event.count - event.samplePaths.length} more`);
+    }
   }
 }

package/src/cli/watch-event-push-conflict.test.ts

@@ -0,0 +1,234 @@
+/**
+ * Regression guard: the watch + event-push path must NOT mint phantom
+ * `.conflict-*` mirrors for an ordinary single-writer local edit.
+ *
+ * Background (feedback_ef2b7c8c): a user editing files under
+ * `companies/{slug}/` saw the menubar's watch/event-push runner mint a
+ * `.conflict-<ts>-<machine>` mirror on EVERY ordinary local Edit/Write —
+ * thousands of phantom files in a single session. The watch/event-push runner
+ * reacts to a local change by running a targeted `--direction push` pass, i.e.
+ * `share()` over the changed company subtree, so the conflict-minting logic is
+ * share()'s push-side conflict gate. The original gate flagged a conflict on
+ * `localChanged` alone (`journalEntry.hash !== localHash`), which fires for
+ * every edit of any already-synced file. The gate now requires
+ * `(localChanged && remoteChanged) || isFreshCollision`: a single writer never
+ * has `remoteChanged` (the live S3 ETag still equals the journal's recorded
+ * baseline), so an ordinary edit is uploaded, not mirrored.
+ *
+ * This test pins that contract end-to-end through `share()` using the same
+ * mocked-S3 harness as `share.test.ts`, modelling a single-writer remote whose
+ * ETag is always exactly what THIS device last uploaded. A positive control
+ * (a genuine out-of-band peer write) proves the guard is not trivially
+ * always-zero: real divergence is still detected.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { clearContextCache } from "../context.js";
+import type { VaultServiceConfig } from "../types.js";
+
+vi.mock("../s3.js", () => ({
+  toPosixKey: (key: string) => key.split("\\").join("/"),
+  uploadFile: vi.fn(),
+  uploadSymlink: vi.fn().mockResolvedValue({ etag: '"upload-symlink-etag"' }),
+  downloadFile: vi.fn().mockResolvedValue(undefined),
+  listRemoteFiles: vi.fn().mockResolvedValue([]),
+  deleteRemoteFile: vi.fn().mockResolvedValue(undefined),
+  headRemoteFile: vi.fn(),
+  primeObjectTransport: vi.fn().mockResolvedValue(undefined),
+  primeUploads: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("readline", () => ({
+  createInterface: vi.fn(() => ({ question: vi.fn(), close: vi.fn() })),
+}));
+
+import { share } from "./share.js";
+import { downloadFile, headRemoteFile, uploadFile } from "../s3.js";
+
+const mockConfig: VaultServiceConfig = {
+  apiUrl: "https://vault-api.test",
+  authToken: "test-jwt-token",
+  region: "us-east-1",
+};
+
+const mockEntity = {
+  uid: "cmp_01ABCDEF",
+  slug: "acme",
+  bucketName: "hq-vault-acme-123",
+  status: "active",
+};
+
+function setupFetchMock() {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn().mockImplementation(async (url: string) => {
+      const u = String(url);
+      if (u.includes("/entity/check-slug/me"))
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+          text: async () => "",
+        };
+      if (u.includes("/entity/by-slug/") || /\/entity\/cmp_/.test(u))
+        return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+      if (u.includes("/sts/vend"))
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            credentials: {
+              accessKeyId: "ASIA_TEST",
+              secretAccessKey: "s",
+              sessionToken: "t",
+              expiration: new Date(Date.now() + 9e5).toISOString(),
+            },
+            expiresAt: new Date(Date.now() + 9e5).toISOString(),
+          }),
+          text: async () => "",
+        };
+      return { ok: false, status: 404, text: async () => "Not found" };
+    }),
+  );
+}
+
+/** Every `.conflict-<ts>-*` mirror file anywhere under `root`. */
+function countConflictMirrors(root: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (/\.conflict-/.test(e.name)) out.push(p);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * In-memory single-writer S3: the object's ETag is always exactly what THIS
+ * device last uploaded (no peer ever writes). `lastModified` advances on each
+ * PUT to model S3 stamping it server-side. The S3-module signatures are
+ * `uploadFile(ctx, localPath, key)`, `headRemoteFile(ctx, key)`,
+ * `downloadFile(ctx, key, dest)` — wire the mocks to match exactly.
+ */
+function wireSingleWriterRemote() {
+  const remote = new Map<string, { etag: string; lastModified: Date; size: number }>();
+  let clock = Date.now();
+  let seq = 0;
+  vi.mocked(uploadFile).mockImplementation(async (_ctx: unknown, localPath: string, key: string) => {
+    const etag = `"etag-${seq++}"`;
+    clock += 1000;
+    remote.set(key, { etag, lastModified: new Date(clock), size: fs.statSync(localPath).size });
+    return { etag };
+  });
+  vi.mocked(headRemoteFile).mockImplementation(async (_ctx: unknown, key: string) => {
+    const r = remote.get(key);
+    return r ? { lastModified: r.lastModified, etag: r.etag, size: r.size } : null;
+  });
+  vi.mocked(downloadFile).mockImplementation(async (_ctx: unknown, _key: string, dest: string) => {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, "remote-bytes\n");
+    return {};
+  });
+  return remote;
+}
+
+describe("watch + event-push conflict regression (feedback_ef2b7c8c)", () => {
+  let tmpDir: string;
+  let stateDir: string;
+
+  beforeEach(() => {
+    clearContextCache();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-conflict-"));
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-state-"));
+    process.env.HQ_STATE_DIR = stateDir;
+    setupFetchMock();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    delete process.env.HQ_STATE_DIR;
+  });
+
+  it("a single writer's repeated local edits mint ZERO .conflict-* files", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const files = ["notes.md", "plan.md", "ideas.md"].map((n) => path.join(companyRoot, n));
+    for (const f of files) fs.writeFileSync(f, "v0\n");
+
+    wireSingleWriterRemote();
+
+    const conflictPathsSeen: string[] = [];
+    // The event-push runner pushes the changed company subtree. Mirror that:
+    // share() over the company root on every settled change.
+    const eventPush = async () => {
+      const r = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onConflict: "keep",
+        onEvent: () => {},
+      });
+      conflictPathsSeen.push(...r.conflictPaths);
+    };
+
+    // Initial sync establishes the journal baseline (first upload of each file).
+    await eventPush();
+
+    // An editing session: 30 ordinary local edits, round-robin across the
+    // files, each followed by its targeted event-push.
+    for (let i = 0; i < 30; i++) {
+      fs.writeFileSync(files[i % files.length], `v${i + 1}\n`);
+      await eventPush();
+    }
+
+    expect(countConflictMirrors(tmpDir)).toEqual([]);
+    expect(conflictPathsSeen).toEqual([]);
+  });
+
+  it("positive control: a genuine peer write is still detected as a conflict", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const file = path.join(companyRoot, "contested.md");
+    fs.writeFileSync(file, "v0\n");
+
+    const remote = wireSingleWriterRemote();
+
+    const conflictPathsSeen: string[] = [];
+    const eventPush = async () => {
+      const r = await share({
+        paths: [companyRoot],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onConflict: "keep",
+        onEvent: () => {},
+      });
+      conflictPathsSeen.push(...r.conflictPaths);
+    };
+
+    await eventPush(); // baseline
+
+    // A peer advances the remote object out-of-band to DIFFERENT bytes. Journal
+    // keys are company-relative, so the key is "contested.md".
+    remote.set("contested.md", { etag: '"peer-etag"', lastModified: new Date(Date.now() + 60_000), size: 99 });
+    // ...and we also edit locally → both sides moved → a genuine conflict.
+    fs.writeFileSync(file, "v1-local\n");
+    await eventPush();
+
+    // Existing-entry push conflicts surface via conflictPaths (the inspection
+    // mirror is written by the pull leg). The contract under test: a REAL
+    // divergence is still flagged — the single-writer guard above did not
+    // over-correct into swallowing true conflicts.
+    expect(conflictPathsSeen).toContain("contested.md");
+  });
+});

package/src/prefix-coalesce.ts

@@ -71,6 +71,41 @@ export function isCoveredByAny(
   return false;
 }
 
+/**
+ * Directory companion to `isCoveredByAny`: should the push/pull walk DESCEND
+ * into directory `relDir` (company-relative, no leading slash) given the
+ * granted `prefixSet`?
+ *
+ * A file uses plain `startsWith` (`isCoveredByAny`), but a directory must be
+ * descended whenever it COULD contain an in-scope file — which is true in two
+ * directions:
+ *   - the directory sits INSIDE a granted prefix (`knowledge/sub` under
+ *     `knowledge/`), or
+ *   - a granted prefix sits INSIDE the directory (`knowledge/` under the
+ *     company root `""`, or `knowledge/README.md` under `knowledge/`).
+ * Without the second case the walk would refuse to descend into `knowledge/`
+ * to reach a `knowledge/README.md` exact-file grant, scoping the whole tree
+ * to nothing.
+ *
+ * The directory is normalized to a trailing-slash form so the `startsWith`
+ * comparisons line up with coalesced prefixes (which are themselves either
+ * trailing-slash dir prefixes or exact-file keys). The empty string (company
+ * root) always descends when any prefix exists.
+ */
+export function isDirInScope(
+  relDir: string,
+  prefixSet: readonly string[],
+): boolean {
+  const dir = relDir === "" || relDir.endsWith("/") ? relDir : relDir + "/";
+  for (const p of prefixSet) {
+    if (p === "") return true; // full scope
+    if (dir === "") return true; // company root — descend to reach grants
+    if (dir.startsWith(p)) return true; // dir is inside a granted prefix
+    if (p.startsWith(dir)) return true; // a granted prefix is inside dir
+  }
+  return false;
+}
+
 /**
  * Normalize a raw ACL grant `path` into a COMPANY-RELATIVE prefix suitable
  * for `coalescePrefixes` + `isCoveredByAny` (which do literal `startsWith`