@indigoai-us/hq-cloud 6.14.35 → 6.14.37

package/src/cli/share.ts

@@ -71,6 +71,7 @@ import {
 import { appendConflictEntry } from "../lib/conflict-index.js";
 import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
 import { VaultAuthError } from "../vault-client.js";
+import { describeError } from "../lib/describe-error.js";
 
 /**
  * Push-side fresh-collision convergence probe.
@@ -258,6 +259,26 @@ export function isMalformedVaultKey(key: string): boolean {
   return key.includes("\\");
 }
 
+/**
+ * A remote key that begins with `companies/<slug>/` is legitimate ONLY in a
+ * PERSONAL vault, where it is handled by the dedicated `personalMode` branch
+ * in `computePullPlan` (companies/* content a peer machine pushed into the
+ * personal bucket). A COMPANY-scoped vault is already anchored at its company
+ * root, so its keys are bucket-relative — a `companies/...` key there is a
+ * doubly-scoped corrupt object. The vault-service refuses to presign such a
+ * key on GET/HEAD with `INVALID_KEY_COMPANIES_SCOPED`, so the puller can
+ * never materialize it and the whole company sync wedges at `errored` (runner
+ * exit 2) on every run. Verified live 2026-06-16: frogbear's
+ * `companies/frogbear/drafts/reports/frogbear-signals-report-2026-06-15.html`
+ * was uploaded with a doubled key and broke every sync thereafter. The pull
+ * and tombstone walkers refuse these keys (skip-excluded-policy), symmetric
+ * with the malformed-(backslash)-key filter above; the bogus objects
+ * themselves are cleaned server-side.
+ */
+export function isForbiddenCompanyVaultKey(key: string, personalMode: boolean): boolean {
+  return !personalMode && key.startsWith("companies/");
+}
+
 /**
  * Test-only export. Kept under a `_testing` namespace so the module's public
  * surface stays focused on `share()` / `ShareOptions` / `ShareResult` while
@@ -271,6 +292,8 @@ export const _testing = {
   EPHEMERAL_PATH_PATTERN,
   wrapFilterWithIgnoreVisibility,
   collectFiles,
+  resolveNamedPath,
+  isWithinLexicalOrReal,
 };
 
 /**
@@ -678,6 +701,63 @@ export interface ShareOptions {
    * the network. See the consult in the Stage-2 classification pass.
    */
   fileTombstones?: Map<string, CompanyTombstone>;
+  /**
+   * What to do when a path the caller EXPLICITLY named cannot be shipped —
+   * it does not resolve under any base, or it resolves outside the company
+   * folder (see `ShareResult.unreachablePaths`).
+   *
+   * - `"error"` (DEFAULT): a path that EXISTS on disk but resolves outside the
+   *   company folder throws {@link UnreachablePushPathsError} BEFORE any upload
+   *   runs, so the push is an atomic no-op and the CLI exits nonzero. This is
+   *   ask #2 of feedback_a51cb63d — "error, not warn-skip, when the named file
+   *   exists locally but is unreachable by the resolver". A user who typed a
+   *   path and got "✓ Pushed 0 file(s)" had no way to know their content never
+   *   left the machine. A path that resolves to NOTHING under any base is still
+   *   only warn-recorded (see `collectFatalUnreachablePaths` for why bulk
+   *   membership fanout depends on that).
+   * - `"warn"`: record it on the result + emit the `not-shipped` event and
+   *   carry on, never throwing. For callers whose `paths` are INTERNAL walk
+   *   roots rather than user input — the background sync runner — where a path
+   *   disappearing mid-run is a benign race (a directory removed between the
+   *   scan and the push) and must never fail an unattended sync.
+   */
+  unreachablePathPolicy?: "error" | "warn";
+}
+
+/** Why an explicitly-named push path could not be shipped. */
+export type UnreachablePathReason = "missing" | "outside-company";
+
+/**
+ * Thrown by `share()` when a caller-named path cannot be pushed and
+ * `unreachablePathPolicy` is `"error"` (the default). Raised while the plans
+ * are still being built, so NOTHING has been uploaded, journaled, or deleted
+ * when it surfaces — the failed push leaves no partial state behind.
+ */
+export class UnreachablePushPathsError extends Error {
+  /** Caller's original spellings, verbatim (see the CollectHooks contract). */
+  readonly paths: string[];
+  /** Per-path reason, keyed by the same original spelling. */
+  readonly reasons: Record<string, UnreachablePathReason>;
+
+  constructor(unreachable: ReadonlyMap<string, UnreachablePathReason>, syncRoot: string) {
+    const paths = [...unreachable.keys()];
+    const lines = paths.map((p) => {
+      const reason = unreachable.get(p);
+      return reason === "outside-company"
+        ? `  · ${p} — resolves outside the company folder (${syncRoot})`
+        : `  · ${p} — not found under the hq root, the company folder, or the current directory`;
+    });
+    super(
+      `${paths.length} named path${paths.length === 1 ? "" : "s"} could not be pushed; ` +
+        `nothing was uploaded.\n${lines.join("\n")}\n` +
+        `A path reached through a symlink is only pushable when it stays inside the HQ tree ` +
+        `(e.g. companies/<slug>/knowledge → repos/private/knowledge-<slug>); one that points ` +
+        `outside HQ has to sync through whatever owns it, not the vault.`,
+    );
+    this.name = "UnreachablePushPathsError";
+    this.paths = paths;
+    this.reasons = Object.fromEntries(unreachable);
+  }
 }
 
 export interface ShareResult {
@@ -757,6 +837,34 @@ export interface ShareResult {
    * once if this is > 0).
    */
   filesExcludedByIgnore: number;
+  /**
+   * Paths the caller EXPLICITLY named for push that exist locally but the
+   * resolver could not place under the company folder (or could not find under
+   * any base). Empty in the common case (internal walk roots are always the
+   * reachable company folder). A non-empty list means the push did NOT ship
+   * something the caller asked for.
+   *
+   * Only ever non-empty under `unreachablePathPolicy: "warn"` — the DEFAULT
+   * `"error"` policy throws {@link UnreachablePushPathsError} instead of
+   * returning, so an interactive `hq sync push` fails loudly rather than
+   * reporting the pre-fix silent "Pushed 0 file(s)" success. This field is the
+   * warn-mode surface for unattended callers (sync runner / watcher).
+   *
+   * Entries are the caller's ORIGINAL spellings, verbatim — a relative token
+   * stays relative, an absolute token stays absolute — so the list is directly
+   * comparable to the `paths` input. See the CollectHooks spelling contract.
+   * Mirrors the `not-shipped` event with `reason: "unreachable-path"`.
+   */
+  unreachablePaths: string[];
+  /**
+   * Company-relative keys of directory symlinks that were recorded as links but
+   * NOT descended because their target lives outside the company folder — their
+   * contents sync via their own repo, not the vault. Surfaced so files created
+   * under such a link (e.g. `companies/{co}/knowledge` → a linked repo) no
+   * longer vanish from every push bucket without a trace. Mirrors the
+   * `not-shipped` event with `reason: "linked-subtree"`.
+   */
+  linkedSubtreesNotShipped: string[];
   /**
    * Paths (company-relative) that were detected as push conflicts. Mirrors
    * `SyncResult.conflictPaths` so push and pull surface conflicts the same
@@ -935,6 +1043,18 @@ interface PushRunContext {
   scopeExcludedSet: Set<string>;
   ignoreExcludedSet: Set<string>;
   ignoreExcludedTotal: { value: number };
+  /** Explicitly-named push paths that exist locally but the resolver could not
+   * place under the company folder (or find at all), keyed by the CALLER'S
+   * ORIGINAL spelling (see the CollectHooks spelling contract) and valued by
+   * why it could not be shipped. Non-empty ⇒ the push did NOT ship something
+   * the caller named — surfaced so a "Pushed 0 file(s)" is never a silent
+   * false success, and (under the default `unreachablePathPolicy: "error"`)
+   * raised as a hard failure before any upload runs. */
+  unreachablePaths: Map<string, UnreachablePathReason>;
+  /** Company-relative keys of directory symlinks recorded but not descended
+   * because their target lives outside the company folder (contents sync via
+   * their own repo, not the vault). */
+  linkedSubtreeSet: Set<string>;
 }
 
 interface ShareCounters {
@@ -1040,6 +1160,8 @@ async function createPushRunContext(options: ShareOptions): Promise<PushRunConte
   const onScopeExcluded = (rel: string) => {
     scopeExcludedSet.add(rel);
   };
+  const unreachablePaths = new Map<string, UnreachablePathReason>();
+  const linkedSubtreeSet = new Set<string>();
   const baseFilter = options.personalMode === true
     ? wrapFilterWithPersonalVaultDefaults(recordedIgnoreFilter, syncRoot, onExcluded)
     : recordedIgnoreFilter;
@@ -1073,6 +1195,8 @@ async function createPushRunContext(options: ShareOptions): Promise<PushRunConte
     scopeExcludedSet,
     ignoreExcludedSet,
     ignoreExcludedTotal,
+    unreachablePaths,
+    linkedSubtreeSet,
   };
 }
 
@@ -1094,7 +1218,30 @@ async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
     run.hqRoot,
     run.syncRoot,
     run.shouldSync,
+    {
+      onUnreachablePath: (namedPath, reason) => {
+        // First reason wins: a path is named once, and re-adding would only
+        // churn the map ordering the error message and event sample rely on.
+        if (!run.unreachablePaths.has(namedPath)) {
+          run.unreachablePaths.set(namedPath, reason);
+        }
+      },
+      onLinkedSubtree: (rel) => run.linkedSubtreeSet.add(rel),
+    },
   );
+  // Ask #2 of feedback_a51cb63d: "error, not warn-skip, when the named file
+  // exists locally but is unreachable by the resolver". This is the throw that
+  // makes it true end-to-end — the CLI's push handler already turns a thrown
+  // error into "✗ Push failed: <message>" + exit 1, so the pre-fix silent
+  // "✓ Pushed 0 file(s)" success can no longer happen for a file that is
+  // sitting right there on disk. It fires HERE, before executeUploads, so a
+  // failed push is also an ATOMIC no-op: nothing uploaded, no journal entry
+  // written, no delete propagated.
+  const fatal = collectFatalUnreachablePaths(run);
+  if (fatal.size > 0) {
+    emitUnreachablePathEvent(run);
+    throw new UnreachablePushPathsError(fatal, run.syncRoot);
+  }
   // Scope-invalid key filter (incident 2026-07-11). In company mode the sync
   // root IS the company folder, so a local entry whose vault key starts with
   // `companies/` can only come from a stale doubled local tree
@@ -1480,8 +1627,7 @@ async function executeUploads(
             run.emit({
               type: "error",
               path: relativePath,
-              message:
-                retryErr instanceof Error ? retryErr.message : String(retryErr),
+              message: describeError(retryErr),
             });
           }
           return;
@@ -1501,7 +1647,7 @@ async function executeUploads(
       run.emit({
         type: "error",
         path: relativePath,
-        message: err instanceof Error ? err.message : String(err),
+        message: describeError(err),
       });
     }
   };
@@ -1572,9 +1718,7 @@ async function writePushConflictMirror(
     run.emit({
       type: "error",
       path: item.relativePath,
-      message:
-        "conflict mirror write failed: " +
-        (mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)),
+      message: "conflict mirror write failed: " + describeError(mirrorErr),
     });
   }
 }
@@ -1654,7 +1798,7 @@ async function executeDeletes(
       run.emit({
         type: "error",
         path: relativePath,
-        message: err instanceof Error ? err.message : String(err),
+        message: describeError(err),
       });
       pathResults.push({
         path: relativePath,
@@ -1665,6 +1809,51 @@ async function executeDeletes(
     }
   }
   for (const relativePath of deletePlan.toTombstone) {
+    const localPath = localPathForVaultKey(run.syncRoot, relativePath);
+    try {
+      const lstat = fs.lstatSync(localPath);
+      const entry = run.journal.files[relativePath];
+      if (lstat.isFile()) {
+        const localHash = hashFile(localPath);
+        if (entry?.hash && entry.hash !== localHash) {
+          run.emit({
+            type: "error",
+            path: relativePath,
+            message:
+              "scope-invalid tombstone skipped: local doubled-tree copy diverged from journal",
+          });
+          continue;
+        }
+        fs.unlinkSync(localPath);
+      } else if (lstat.isSymbolicLink()) {
+        const localHash = hashSymlinkTarget(fs.readlinkSync(localPath));
+        if (entry?.hash && entry.hash !== localHash) {
+          run.emit({
+            type: "error",
+            path: relativePath,
+            message:
+              "scope-invalid tombstone skipped: local doubled-tree copy diverged from journal",
+          });
+          continue;
+        }
+        fs.unlinkSync(localPath);
+      }
+    } catch (err: unknown) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? (err as { code?: string }).code
+          : undefined;
+      if (code !== "ENOENT") {
+        run.emit({
+          type: "error",
+          path: relativePath,
+          message: `tombstone unlink failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        });
+        continue;
+      }
+    }
     removeEntry(run.journal, relativePath);
     counters.filesTombstoned++;
     run.emit({
@@ -1748,6 +1937,77 @@ function finalizeShareJournal(run: PushRunContext): void {
       samplePaths,
     });
   }
+
+  emitUnreachablePathEvent(run);
+
+  if (run.linkedSubtreeSet.size > 0) {
+    run.emit({
+      type: "not-shipped",
+      reason: "linked-subtree",
+      count: run.linkedSubtreeSet.size,
+      samplePaths: sampleSet(run.linkedSubtreeSet),
+    });
+  }
+}
+
+/**
+ * Which unreachable named paths are FATAL under the run's policy.
+ *
+ * Under the default `"error"` policy only `"outside-company"` is fatal: the
+ * entry is sitting on disk and the resolver refused to place it under the
+ * company folder, which is precisely the "exists locally but is unreachable by
+ * the resolver" case the report asks to turn into an error, and it cannot
+ * happen for an internal walk root (a company folder is trivially inside
+ * itself).
+ *
+ * `"missing"` stays a warn-skip — recorded on `ShareResult.unreachablePaths`
+ * and surfaced by the `not-shipped` event, but never fatal. Bulk callers plan
+ * one push leg per MEMBERSHIP (`hq sync push --all`), including companies whose
+ * folder was never materialized locally; throwing there would turn "you haven't
+ * pulled that company yet" into a hard failure of an unrelated multi-company
+ * push. Same reasoning for a watcher path deleted between the event and the
+ * push. Those callers get the loud report without the regression.
+ *
+ * `"warn"` makes nothing fatal, for callers whose paths are internal walk roots
+ * end to end (the background sync runner).
+ */
+function collectFatalUnreachablePaths(
+  run: PushRunContext,
+): Map<string, UnreachablePathReason> {
+  const fatal = new Map<string, UnreachablePathReason>();
+  if (run.options.unreachablePathPolicy === "warn") return fatal;
+  for (const [namedPath, reason] of run.unreachablePaths) {
+    if (reason === "outside-company") fatal.set(namedPath, reason);
+  }
+  return fatal;
+}
+
+/**
+ * Emit the `not-shipped` / `unreachable-path` event for a run, if any named
+ * path went unshipped. Shared by BOTH policies so the operator sees the same
+ * report either way: the fail-fast path emits it immediately before throwing
+ * (the journal finalizer never runs on a throw), and the `"warn"` path emits it
+ * from the finalizer at the end of a successful run. Exactly one of those two
+ * call sites can fire per run, so the event is never duplicated.
+ */
+function emitUnreachablePathEvent(run: PushRunContext): void {
+  if (run.unreachablePaths.size === 0) return;
+  run.emit({
+    type: "not-shipped",
+    reason: "unreachable-path",
+    count: run.unreachablePaths.size,
+    samplePaths: sampleSet(run.unreachablePaths.keys()),
+  });
+}
+
+/** First up-to-`limit` members of an iterable, for bounded event payloads. */
+function sampleSet(set: Iterable<string>, limit = 10): string[] {
+  const sample: string[] = [];
+  for (const value of set) {
+    sample.push(value);
+    if (sample.length >= limit) break;
+  }
+  return sample;
 }
 
 function throwUploadWorkerErrors(workerErrors: Error[]): void {
@@ -1784,6 +2044,8 @@ function buildShareResult(
     filesExcludedByPolicy: run.excludedSet.size,
     filesExcludedByScope: run.scopeExcludedSet.size,
     filesExcludedByIgnore: run.ignoreExcludedSet.size,
+    unreachablePaths: [...run.unreachablePaths.keys()],
+    linkedSubtreesNotShipped: [...run.linkedSubtreeSet],
     conflictPaths,
     pathResults,
     aborted,
@@ -1864,6 +2126,24 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     if (event.count > event.samplePaths.length) {
       console.warn(`    ... and ${event.count - event.samplePaths.length} more`);
     }
+  } else if (event.type === "not-shipped") {
+    // The other "not silent" surface: content the walk saw but chose not to
+    // ship. Name it so a "Pushed 0 file(s)" is never a silent no-op.
+    if (event.reason === "unreachable-path") {
+      console.warn(
+        `  ! ${event.count} named path${event.count === 1 ? "" : "s"} could NOT be pushed — the file exists but is not reachable under the company folder (nothing was uploaded for ${event.count === 1 ? "it" : "them"}):`,
+      );
+    } else {
+      console.warn(
+        `  ! ${event.count} linked subtree${event.count === 1 ? "" : "s"} recorded but NOT uploaded — contents sync via their own repo, not the vault:`,
+      );
+    }
+    for (const p of event.samplePaths) {
+      console.warn(`    · ${p}`);
+    }
+    if (event.count > event.samplePaths.length) {
+      console.warn(`    ... and ${event.count - event.samplePaths.length} more`);
+    }
   }
 }
 
@@ -1881,6 +2161,285 @@ type CollectedEntry =
   | { kind: "file"; absolutePath: string; relativePath: string }
   | { kind: "symlink"; absolutePath: string; relativePath: string; target: string };
 
+/**
+ * Optional visibility callbacks for {@link collectFiles} / {@link walkDir}.
+ * They turn two previously-SILENT outcomes into surfaced signals — without
+ * changing WHAT gets uploaded (feedback_258e4a86 / feedback_a51cb63d):
+ *
+ *   - `onUnreachablePath`: a path the caller EXPLICITLY named (never an internal
+ *     walk root — those are always the reachable company folder) that exists on
+ *     disk but the resolver could not place under the company folder
+ *     (`"outside-company"`), or could not resolve to an existing file under any
+ *     base (`"missing"`). Pre-fix this was a bare `console.error` warn-skip that
+ *     still let the push report "Pushed 0 file(s)" — a false success. The caller
+ *     can now turn a non-empty set into a real error / nonzero exit.
+ *
+ *     SPELLING CONTRACT: `namedPath` is ALWAYS the caller's ORIGINAL token,
+ *     verbatim — never the resolved absolute path, and never normalized. A
+ *     relative `knowledge/agents/x.md` is reported as `knowledge/agents/x.md`;
+ *     an absolute path is reported absolute because that is what was passed.
+ *     Echoing the caller's own spelling is what makes the error actionable
+ *     ("the thing you typed did not ship"), and it keeps `unreachablePaths`
+ *     comparable to the input array without a resolution step. Both call sites
+ *     below pass the loop variable `p` for exactly this reason.
+ *   - `onLinkedSubtree`: a directory symlink recorded as a link but NOT
+ *     descended because its target resolves OUTSIDE the company folder (e.g.
+ *     `companies/{co}/knowledge` → `repos/private/knowledge-{co}/`). The link's
+ *     contents ship via their own repo, not the vault; reporting it stops files
+ *     created under such a link from vanishing from every push bucket silently.
+ */
+interface CollectHooks {
+  onUnreachablePath?: (namedPath: string, reason: "missing" | "outside-company") => void;
+  onLinkedSubtree?: (rel: string) => void;
+}
+
+/**
+ * Resolve a caller-supplied push path to an absolute path.
+ *
+ * Relative paths were historically resolved against `hqRoot` ONLY, so a
+ * company-relative spelling like `knowledge/agents/x.md` became
+ * `<hqRoot>/knowledge/agents/x.md` and reported "does not exist" no matter the
+ * caller's cwd or the company being pushed (feedback_258e4a86 /
+ * feedback_a51cb63d — "there is no path spelling that reaches the file").
+ *
+ * PRECEDENCE (documented contract, asserted by test): `hqRoot` → `syncRoot`
+ * (the company folder) → `cwd`. hqRoot stays FIRST so this change is purely
+ * ADDITIVE to the legacy behavior: every relative spelling that resolved
+ * pre-fix still resolves to exactly the same file, and the two new bases only
+ * catch spellings that previously resolved to nothing. Probing cwd first would
+ * silently re-point existing callers (a `knowledge/` directory in the shell's
+ * cwd would win over the hq-root one), which is a behavior change no reporter
+ * asked for. Fall back to the hqRoot candidate so a genuine typo still surfaces
+ * the unchanged "does not exist" diagnostic. Absolute paths are returned
+ * verbatim.
+ *
+ * `cwd` is an explicit injected parameter (defaulting to `process.cwd()`)
+ * rather than an ambient read, so resolution is deterministic and testable
+ * without mutating process state.
+ */
+function resolveNamedPath(
+  p: string,
+  hqRoot: string,
+  syncRoot: string,
+  cwd: string = process.cwd(),
+): string {
+  if (path.isAbsolute(p)) return p;
+  const hqRootCandidate = path.resolve(hqRoot, p);
+  const candidates = [
+    hqRootCandidate,
+    path.resolve(syncRoot, p),
+    path.resolve(cwd, p),
+  ];
+  for (const candidate of candidates) {
+    try {
+      fs.lstatSync(candidate);
+      // An hqRoot hit outside the company folder would be rejected by
+      // collectFiles as outside-company; skip it so a valid company-relative
+      // spelling can win (Codex P2 — common `knowledge/` homonym case).
+      if (candidate === hqRootCandidate && !isWithin(syncRoot, candidate)) {
+        continue;
+      }
+      return candidate;
+    } catch {
+      // Base did not resolve to an on-disk entry — try the next one.
+    }
+  }
+  return hqRootCandidate;
+}
+
+/**
+ * Containment check for a regular file or directory that tolerates a symlinked
+ * ANCESTOR. `isWithin` canonicalizes the full child via `realpathSync`, so a
+ * path reached through a symlinked ancestor (`companies/{co}/knowledge` →
+ * `repos/private/knowledge-{co}/`) resolves OUTSIDE the company folder and was
+ * rejected as "outside company folder" — even though its logical path is
+ * in-tree and `vaultKeyForLocalPath` (also lexical) derives a correct
+ * company-namespaced key for it. Accept when the LEXICAL path is inside
+ * (honoring the same logical topology the vault key uses) OR the realpath is
+ * inside (preserving `isWithin`'s macOS APFS case-insensitivity tolerance).
+ *
+ * The lexical arm carries TWO bounds, because it is the only place where a
+ * path's bytes and its vault key come from different trees:
+ *
+ *  1. `hqRoot` — the realpath must still land inside the HQ tree, so a
+ *     symlinked ancestor pointing at `/etc` cannot upload arbitrary machine
+ *     state under a company-namespaced key.
+ *  2. The TENANT — the realpath must not land inside another company's bytes
+ *     (`foreignTenantRoots`). The hqRoot bound alone is NOT sufficient and
+ *     must never be mistaken for a tenant boundary: hqRoot CONTAINS every
+ *     other company, so `companies/acme/knowledge → companies/other/secret`
+ *     (or → `repos/private/knowledge-other`, the linked-repo topology) is
+ *     lexically inside acme and really inside HQ, and would upload the other
+ *     tenant's bytes into acme's bucket under the key `knowledge/…`.
+ *
+ * The motivating topology (`companies/{co}/knowledge` →
+ * `repos/private/knowledge-{co}`) satisfies both, so it is unaffected. A link
+ * that escapes HQ, or one that reaches another tenant, is refused — and under
+ * the default unreachable-path policy, refused LOUDLY rather than warn-skipped.
+ *
+ * Known limit, stated so it is not mistaken for a guarantee: a foreign tenant's
+ * externally-linked subtree can only be recognized while that company's folder
+ * is materialized locally and publishes the link. A machine holding
+ * `repos/private/knowledge-other` with no `companies/other` folder has no
+ * on-disk evidence of the claim, so a link into it is indistinguishable from a
+ * link into any other local repo. Ownership metadata (not path shape) is what
+ * would close that gap.
+ */
+function isWithinLexicalOrReal(
+  parent: string,
+  child: string,
+  hqRoot: string,
+  tenantRootsCache?: Map<string, string[]>,
+): boolean {
+  // Strict arm first: the realpath is genuinely inside the company folder.
+  // This is the overwhelmingly common case, needs no relaxation, and costs no
+  // directory scan.
+  if (isWithin(parent, child)) return true;
+
+  const resolvedChild = path.resolve(child);
+  if (!isPathWithin(path.resolve(parent), resolvedChild)) return false;
+
+  const childReal = realpathSafe(resolvedChild);
+  if (!isWithin(hqRoot, childReal)) return false; // bound 1: escapes HQ
+
+  // NUL-joined: it is the one byte a path cannot contain, so no pair of
+  // (hqRoot, parent) values can collide on the key.
+  const cacheKey = `${hqRoot}\u0000${parent}`;
+  let foreignRoots = tenantRootsCache?.get(cacheKey);
+  if (foreignRoots === undefined) {
+    foreignRoots = foreignTenantRoots(hqRoot, parent);
+    tenantRootsCache?.set(cacheKey, foreignRoots);
+  }
+  for (const foreign of foreignRoots) {
+    if (isPathWithin(foreign, childReal)) return false; // bound 2: other tenant
+  }
+  return true;
+}
+
+/**
+ * Depth (in path segments below a company root) at which we look for the
+ * directory symlinks a company publishes into its own folder. HQ's linked
+ * topologies live at depth 1 (`companies/{co}/knowledge`) and depth 2
+ * (`companies/{co}/repos/{name}`); going deeper would turn a containment check
+ * into a full-tree walk for no additional coverage.
+ */
+const FOREIGN_TENANT_LINK_SCAN_DEPTH = 2;
+
+/**
+ * Canonicalized roots that belong to a tenant OTHER than the one being pushed.
+ * A lexically-contained path whose realpath lands inside any of these is
+ * another company's data wearing this company's key, and must be refused.
+ *
+ * Two kinds of root are collected per foreign company:
+ *   - the company folder itself (`companies/{other}`), and
+ *   - the targets of the directory symlinks that folder publishes — HQ's
+ *     pattern-2 topology puts a company's knowledge in `repos/private/
+ *     knowledge-{other}` and links it in, so the bytes live OUTSIDE every
+ *     `companies/` root and a companies-only check would miss them entirely.
+ *
+ * Only consulted on the rare lexical arm (a path whose realpath is not inside
+ * the company folder), never on the ordinary in-tree push, so the directory
+ * scan is not on the hot path. Callers may memoize it for the duration of a
+ * single collect pass; nothing memoizes it for longer, because the sync runner
+ * is long-lived and a stale tenant map fails OPEN — the wrong direction for a
+ * boundary whose whole job is to refuse.
+ */
+function foreignTenantRoots(hqRoot: string, syncRoot: string): string[] {
+  const companiesDir = path.join(hqRoot, "companies");
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(companiesDir, { withFileTypes: true });
+  } catch {
+    return []; // no companies/ tree here — nothing to be foreign to
+  }
+
+  const activeReal = realpathSafe(syncRoot);
+  const roots: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const companyRoot = path.join(companiesDir, entry.name);
+    const companyReal = realpathSafe(companyRoot);
+    if (companyReal === activeReal) continue; // this is the tenant being pushed
+    roots.push(companyReal);
+    collectPublishedLinkTargets(companyRoot, companyReal, FOREIGN_TENANT_LINK_SCAN_DEPTH, roots);
+  }
+  return roots;
+}
+
+/**
+ * Append the resolved targets of the directory symlinks published under
+ * `companyRoot` (down to `depth` levels) into `out`. Targets that resolve back
+ * inside the company folder are skipped — they add no reach beyond the root
+ * already recorded. Errors are swallowed per entry on purpose: an unreadable
+ * sibling directory must narrow what we can prove, never abort the push it is
+ * unrelated to.
+ */
+function collectPublishedLinkTargets(
+  dir: string,
+  companyReal: string,
+  depth: number,
+  out: string[],
+): void {
+  if (depth <= 0) return;
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const child = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      let real: string;
+      try {
+        real = fs.realpathSync.native(child);
+      } catch {
+        continue; // dangling link claims nothing
+      }
+      try {
+        if (!fs.statSync(real).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      if (isPathWithin(companyReal, real)) continue; // no reach beyond the root
+      out.push(real);
+    } else if (entry.isDirectory()) {
+      collectPublishedLinkTargets(child, companyReal, depth - 1, out);
+    }
+  }
+}
+
+/**
+ * If a recorded directory symlink's target resolves OUTSIDE `syncRoot`, invoke
+ * `onLinkedSubtree` so the caller can report that the link's contents were not
+ * uploaded to the vault. Fires only for links that (a) resolve to a directory
+ * and (b) point outside the company folder — an in-tree link is descended
+ * elsewhere, and a dangling or file link has nothing behind it to report.
+ */
+function reportLinkedSubtreeIfExternal(
+  linkPath: string,
+  syncRoot: string,
+  relativePath: string,
+  hooks: CollectHooks,
+): void {
+  if (!hooks.onLinkedSubtree) return;
+  let real: string;
+  try {
+    real = fs.realpathSync.native(linkPath); // resolves the link to its target
+  } catch {
+    return; // dangling link — nothing behind it to report
+  }
+  let targetStat: fs.Stats;
+  try {
+    targetStat = fs.statSync(real);
+  } catch {
+    return;
+  }
+  if (!targetStat.isDirectory()) return;
+  if (isWithin(syncRoot, real)) return; // in-tree target: descended elsewhere
+  hooks.onLinkedSubtree(relativePath);
+}
+
 /**
  * Collect files from paths (expanding directories recursively).
  *
@@ -1898,11 +2457,17 @@ function collectFiles(
   hqRoot: string,
   syncRoot: string,
   filter: (p: string, isDir?: boolean) => boolean,
+  hooks: CollectHooks = {},
 ): CollectedEntry[] {
   const results: CollectedEntry[] = [];
+  // Scoped to THIS collect pass and discarded with it: a watcher batch can
+  // name hundreds of paths, and rescanning the companies/ tree for each one
+  // is wasted I/O. A cache that outlived the pass could fail open on a tenant
+  // boundary, so it deliberately does not.
+  const tenantRoots = new Map<string, string[]>();
 
   for (const p of paths) {
-    const absolutePath = path.isAbsolute(p) ? p : path.resolve(hqRoot, p);
+    const absolutePath = resolveNamedPath(p, hqRoot, syncRoot);
 
     // Ephemeral artifacts (conflict mirrors) — see EPHEMERAL_PATH_PATTERN doc.
     // Caller may pass one explicitly; we still refuse to upload it. Basename
@@ -1918,6 +2483,7 @@ function collectFiles(
       lstat = fs.lstatSync(absolutePath);
     } catch {
       console.error(`  Warning: ${p} does not exist, skipping.`);
+      hooks.onUnreachablePath?.(p, "missing");
       continue;
     }
 
@@ -1936,6 +2502,7 @@ function collectFiles(
     if (lstat.isSymbolicLink()) {
       if (!isWithinForLink(syncRoot, absolutePath)) {
         console.error(`  Warning: ${p} is outside company folder, skipping.`);
+        hooks.onUnreachablePath?.(p, "outside-company");
         continue;
       }
       const relativePath = vaultKeyForLocalPath(syncRoot, absolutePath);
@@ -1950,6 +2517,11 @@ function collectFiles(
       // whole branch). The filter is pure path lookup with no I/O,
       // so two calls are free.
       if (!filter(absolutePath, false) && !filter(absolutePath, true)) continue;
+      // A directory symlink whose target lives outside the company folder is
+      // recorded here but never descended — its contents ship via their own
+      // repo, not the vault. Surface it so files created under such a link
+      // don't vanish from every push bucket silently.
+      reportLinkedSubtreeIfExternal(absolutePath, syncRoot, relativePath, hooks);
       results.push({
         kind: "symlink",
         absolutePath,
@@ -1959,14 +2531,15 @@ function collectFiles(
       continue;
     }
 
-    if (!isWithin(syncRoot, absolutePath)) {
+    if (!isWithinLexicalOrReal(syncRoot, absolutePath, hqRoot, tenantRoots)) {
       console.error(`  Warning: ${p} is outside company folder, skipping.`);
+      hooks.onUnreachablePath?.(p, "outside-company");
       continue;
     }
 
     if (lstat.isDirectory()) {
       if (!filter(absolutePath, true)) continue;
-      walkDir(absolutePath, syncRoot, filter, results);
+      walkDir(absolutePath, syncRoot, filter, results, hooks);
     } else if (lstat.isFile()) {
       const relativePath = vaultKeyForLocalPath(syncRoot, absolutePath);
       if (filter(absolutePath)) {
@@ -1983,6 +2556,7 @@ function walkDir(
   syncRoot: string,
   filter: (p: string, isDir?: boolean) => boolean,
   results: CollectedEntry[],
+  hooks: CollectHooks = {},
 ): void {
   // A frame per open directory preserves the recursive walk's depth-first
   // ordering without turning a completed subtree into one giant call argument
@@ -2032,10 +2606,15 @@ function walkDir(
       // fail under normal conditions; let the throw propagate if it
       // somehow does (race with rm, EPERM) — the operator needs to
       // see it rather than us silently dropping the link again.
+      const linkRelative = vaultKeyForLocalPath(syncRoot, absolutePath);
+      // The link is recorded but its (external) target is not descended, so
+      // any files under it are NOT uploaded. Report the subtree so a full
+      // `sync now` no longer drops it from every bucket without a trace.
+      reportLinkedSubtreeIfExternal(absolutePath, syncRoot, linkRelative, hooks);
       results.push({
         kind: "symlink",
         absolutePath,
-        relativePath: vaultKeyForLocalPath(syncRoot, absolutePath),
+        relativePath: linkRelative,
         target: fs.readlinkSync(absolutePath),
       });
       continue;
@@ -2155,6 +2734,23 @@ function isWithinForLink(parent: string, linkPath: string): boolean {
  *
  * Returns `[""]` (whole-tree) when any input path resolves to `syncRoot`
  * itself; this is the bidirectional-runner case.
+ *
+ * Path spellings are resolved with `resolveNamedPath`, the same resolver the
+ * upload leg uses, so `hq sync push knowledge/agents` scopes deletes exactly
+ * like its absolute equivalent instead of silently resolving nowhere and
+ * scoping nothing.
+ *
+ * Containment, however, deliberately stays on strict realpath `isWithin` and
+ * does NOT adopt the upload leg's `isWithinLexicalOrReal` relaxation. The two
+ * legs are asymmetric on purpose: the upload leg ships the files it was handed,
+ * while a delete scope is a PREFIX that authorizes removing every remote object
+ * beneath it. A linked subtree's contents are never walked (`walkDir` does not
+ * descend external directory symlinks), so anchoring a delete scope on one
+ * would compare an empty local walk against a populated remote prefix and sweep
+ * the whole prefix away. Narrow-and-safe beats wide-and-lossy here; the
+ * accepted cost is that deletes inside a linked subtree are not propagated,
+ * which matches the snapshot semantics `hq sync push` already documents for
+ * those paths.
  */
 function resolveDeleteScopeRoots(
   paths: string[],
@@ -2181,7 +2777,7 @@ function resolveDeleteScopeRoots(
     prefixes.add(normalized);
   }
   for (const p of paths) {
-    const absolutePath = path.isAbsolute(p) ? p : path.resolve(hqRoot, p);
+    const absolutePath = resolveNamedPath(p, hqRoot, syncRoot);
     if (!fs.existsSync(absolutePath)) continue;
     if (!isWithin(syncRoot, absolutePath)) continue;
     const stat = fs.statSync(absolutePath);
@@ -2480,6 +3076,22 @@ async function computeDeletePlan(
     if (!inScope) continue;
     inScopeJournalEntries++;
     const localPath = localPathForVaultKey(syncRoot, relativeKey);
+
+    // Scope-invalid journal keys (incident 2026-07-11): in a COMPANY-scoped
+    // context, a journal entry at a literal `companies/…` key records a
+    // doubled-tree poisoning upload. HEAD/DeleteObject on such a key via the
+    // presign transport is rejected by the server validator
+    // (INVALID_KEY_COMPANIES_SCOPED) and would error the push, so route it
+    // straight to `toTombstone` (journal drop + local doubled-tree cleanup, no
+    // remote call). Personal-vault pushes (personalMode) carry legitimate
+    // `companies/{slug}/…` keys and are unaffected (companyScoped=false).
+    // Checked before the presentLocally gate: the poison file lives at the
+    // doubled path and must drain even while still on disk.
+    if (companyScoped && relativeKey.startsWith("companies/")) {
+      plan.toTombstone.push(relativeKey);
+      continue;
+    }
+
     let presentLocally = true;
     try {
       fs.lstatSync(localPath);
@@ -2516,20 +3128,6 @@ async function computeDeletePlan(
       continue;
     }
 
-    // Scope-invalid journal keys (incident 2026-07-11): in a COMPANY-scoped
-    // context, a journal entry at a literal `companies/…` key records a
-    // doubled-tree poisoning upload. HEAD/DeleteObject on such a key via the
-    // presign transport is rejected by the server validator
-    // (INVALID_KEY_COMPANIES_SCOPED) and would error the push, so route it
-    // straight to `toTombstone` (journal drop, no remote call) — the local
-    // journal entry drains; server-side cleanup of any poisoned object is an
-    // operator action. Personal-vault pushes (personalMode) carry legitimate
-    // `companies/{slug}/…` keys and are unaffected (companyScoped=false).
-    if (companyScoped && relativeKey.startsWith("companies/")) {
-      plan.toTombstone.push(relativeKey);
-      continue;
-    }
-
     if (!shouldSync(localPath, false) && !shouldSync(localPath, true)) continue;
     // Ephemeral artifacts (conflict mirrors) never propagate-delete via the
     // normal path — see EPHEMERAL_PATH_PATTERN doc. NOTE: this is a no-op