@indigoai-us/hq-cloud 6.14.36 → 6.14.39

package/dist/cli/share.js

@@ -24,6 +24,8 @@ import { buildConflictId, buildConflictPath, readShortMachineId, } from "../lib/
 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";
+import { readlinkOrNull } from "../lib/readlink-safe.js";
 /**
  * Push-side fresh-collision convergence probe.
  *
@@ -199,6 +201,25 @@ export function isEphemeralPath(p) {
 export function isMalformedVaultKey(key) {
     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, personalMode) {
+    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
@@ -212,6 +233,8 @@ export const _testing = {
     EPHEMERAL_PATH_PATTERN,
     wrapFilterWithIgnoreVisibility,
     collectFiles,
+    resolveNamedPath,
+    isWithinLexicalOrReal,
 };
 /**
  * Pure Stage-1 pass for push: walk the candidate file list, hash each one,
@@ -344,6 +367,39 @@ function computePushPlan(filesToShare, journal, skipUnchanged) {
     }
     return { items, filesToUpload, bytesToUpload, filesToSkip };
 }
+/**
+ * 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). */
+    paths;
+    /** Per-path reason, keyed by the same original spelling. */
+    reasons;
+    constructor(unreachable, syncRoot) {
+        const paths = [...unreachable.keys()];
+        const lines = paths.map((p) => {
+            const reason = unreachable.get(p);
+            if (reason === "outside-company") {
+                return `  · ${p} — resolves outside the company folder (${syncRoot})`;
+            }
+            if (reason === "unreadable-link") {
+                return `  · ${p} — symbolic link target could not be read; it was not dereferenced or uploaded`;
+            }
+            return `  · ${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);
+    }
+}
 /**
  * A conditional-write fence rejection — the SDK's 412 (`name:
  * "PreconditionFailed"`) or the presigned transport's mirror of it. Means
@@ -490,6 +546,8 @@ async function createPushRunContext(options) {
     const onScopeExcluded = (rel) => {
         scopeExcludedSet.add(rel);
     };
+    const unreachablePaths = new Map();
+    const linkedSubtreeSet = new Set();
     const baseFilter = options.personalMode === true
         ? wrapFilterWithPersonalVaultDefaults(recordedIgnoreFilter, syncRoot, onExcluded)
         : recordedIgnoreFilter;
@@ -523,6 +581,8 @@ async function createPushRunContext(options) {
         scopeExcludedSet,
         ignoreExcludedSet,
         ignoreExcludedTotal,
+        unreachablePaths,
+        linkedSubtreeSet,
     };
 }
 function createShareCounters() {
@@ -537,7 +597,29 @@ function createShareCounters() {
     };
 }
 async function buildSharePlans(run) {
-    const collected = collectFiles(run.paths, run.hqRoot, run.syncRoot, run.shouldSync);
+    const collected = collectFiles(run.paths, 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
@@ -839,7 +921,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                         run.emit({
                             type: "error",
                             path: relativePath,
-                            message: retryErr instanceof Error ? retryErr.message : String(retryErr),
+                            message: describeError(retryErr),
                         });
                     }
                     return;
@@ -855,7 +937,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
             run.emit({
                 type: "error",
                 path: relativePath,
-                message: err instanceof Error ? err.message : String(err),
+                message: describeError(err),
             });
         }
     };
@@ -919,8 +1001,7 @@ async function writePushConflictMirror(run, item, remoteHash) {
         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),
         });
     }
 }
@@ -992,7 +1073,7 @@ async function executeDeletes(run, deletePlan, decommissionPlan, counters, files
             run.emit({
                 type: "error",
                 path: relativePath,
-                message: err instanceof Error ? err.message : String(err),
+                message: describeError(err),
             });
             pathResults.push({
                 path: relativePath,
@@ -1003,6 +1084,58 @@ async function executeDeletes(run, deletePlan, decommissionPlan, counters, files
         }
     }
     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 target = readlinkOrNull(localPath);
+                if (target === null) {
+                    run.emit({
+                        type: "not-shipped",
+                        reason: "unreadable-link",
+                        count: 1,
+                        samplePaths: [relativePath],
+                    });
+                    continue;
+                }
+                const localHash = hashSymlinkTarget(target);
+                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) {
+            const code = err && typeof err === "object" && "code" in err
+                ? err.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({
@@ -1085,6 +1218,89 @@ function finalizeShareJournal(run) {
             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) {
+    const fatal = new Map();
+    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) {
+    if (run.unreachablePaths.size === 0)
+        return;
+    const unreadableLinks = [];
+    const unreachablePaths = [];
+    for (const [namedPath, reason] of run.unreachablePaths) {
+        (reason === "unreadable-link" ? unreadableLinks : unreachablePaths).push(namedPath);
+    }
+    if (unreachablePaths.length > 0) {
+        run.emit({
+            type: "not-shipped",
+            reason: "unreachable-path",
+            count: unreachablePaths.length,
+            samplePaths: unreachablePaths.slice(0, 10),
+        });
+    }
+    if (unreadableLinks.length > 0) {
+        run.emit({
+            type: "not-shipped",
+            reason: "unreadable-link",
+            count: unreadableLinks.length,
+            samplePaths: unreadableLinks.slice(0, 10),
+        });
+    }
+}
+/** First up-to-`limit` members of an iterable, for bounded event payloads. */
+function sampleSet(set, limit = 10) {
+    const sample = [];
+    for (const value of set) {
+        sample.push(value);
+        if (sample.length >= limit)
+            break;
+    }
+    return sample;
 }
 function throwUploadWorkerErrors(workerErrors) {
     if (workerErrors.length > 0) {
@@ -1112,6 +1328,8 @@ function buildShareResult(run, counters, filesRefusedStalePaths, conflictPaths,
         filesExcludedByPolicy: run.excludedSet.size,
         filesExcludedByScope: run.scopeExcludedSet.size,
         filesExcludedByIgnore: run.ignoreExcludedSet.size,
+        unreachablePaths: [...run.unreachablePaths.keys()],
+        linkedSubtreesNotShipped: [...run.linkedSubtreeSet],
         conflictPaths,
         pathResults,
         aborted,
@@ -1189,6 +1407,263 @@ function defaultConsoleLogger(event) {
             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 if (event.reason === "unreadable-link") {
+            console.warn(`  ! ${event.count} symbolic link${event.count === 1 ? "" : "s"} could NOT be read and was skipped without dereferencing its target:`);
+        }
+        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`);
+        }
+    }
+}
+/**
+ * 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, hqRoot, syncRoot, cwd = process.cwd()) {
+    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, child, hqRoot, tenantRootsCache) {
+    // 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, syncRoot) {
+    const companiesDir = path.join(hqRoot, "companies");
+    let entries;
+    try {
+        entries = fs.readdirSync(companiesDir, { withFileTypes: true });
+    }
+    catch {
+        return []; // no companies/ tree here — nothing to be foreign to
+    }
+    const activeReal = realpathSafe(syncRoot);
+    const roots = [];
+    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, companyReal, depth, out) {
+    if (depth <= 0)
+        return;
+    let entries;
+    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;
+            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, syncRoot, relativePath, hooks) {
+    if (!hooks.onLinkedSubtree)
+        return;
+    let real;
+    try {
+        real = fs.realpathSync.native(linkPath); // resolves the link to its target
+    }
+    catch {
+        return; // dangling link — nothing behind it to report
+    }
+    let targetStat;
+    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).
@@ -1202,10 +1677,15 @@ function defaultConsoleLogger(event) {
  * Pre-fix, statSync followed the link and the target's bytes were uploaded
  * under the link's key — silently flattening the link topology.
  */
-function collectFiles(paths, hqRoot, syncRoot, filter) {
+function collectFiles(paths, hqRoot, syncRoot, filter, hooks = {}) {
     const results = [];
+    // 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();
     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
         // check matches the walkDir gate so behavior is identical whether the
@@ -1221,6 +1701,7 @@ function collectFiles(paths, hqRoot, syncRoot, filter) {
         }
         catch {
             console.error(`  Warning: ${p} does not exist, skipping.`);
+            hooks.onUnreachablePath?.(p, "missing");
             continue;
         }
         // Containment check is split by entry kind: regular files and
@@ -1238,6 +1719,7 @@ function collectFiles(paths, hqRoot, syncRoot, filter) {
         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);
@@ -1253,22 +1735,34 @@ function collectFiles(paths, hqRoot, syncRoot, filter) {
             // so two calls are free.
             if (!filter(absolutePath, false) && !filter(absolutePath, true))
                 continue;
+            const target = readlinkOrNull(absolutePath);
+            if (target === null) {
+                console.error(`  Warning: ${p} is an unreadable symbolic link, skipping.`);
+                hooks.onUnreachablePath?.(p, "unreadable-link");
+                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,
                 relativePath,
-                target: fs.readlinkSync(absolutePath),
+                target,
             });
             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);
@@ -1279,7 +1773,7 @@ function collectFiles(paths, hqRoot, syncRoot, filter) {
     }
     return results;
 }
-function walkDir(dir, syncRoot, filter, results) {
+function walkDir(dir, syncRoot, filter, results, hooks = {}) {
     // A frame per open directory preserves the recursive walk's depth-first
     // ordering without turning a completed subtree into one giant call argument
     // list. This matters for both operator-visible plan ordering and large trees.
@@ -1325,15 +1819,26 @@ function walkDir(dir, syncRoot, filter, results) {
             // private/knowledge-{co}/), causing per-company knowledge repos
             // to be uploaded into every vault that links them. Recording
             // and not following preserves the link topology while avoiding
-            // that duplication. readlinkSync on a Dirent-known link cannot
-            // 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);
+            // On win32, a Dirent-known link is not sufficient proof that readlink
+            // will succeed (notably for some reparse points). Never fall through to
+            // normal file/directory handling here: doing so would dereference the
+            // link and duplicate its target under this vault key.
+            const target = readlinkOrNull(absolutePath);
+            if (target === null) {
+                console.error(`  Warning: ${linkRelative} is an unreadable symbolic link, skipping.`);
+                hooks.onUnreachablePath?.(linkRelative, "unreadable-link");
+                continue;
+            }
+            // 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),
-                target: fs.readlinkSync(absolutePath),
+                relativePath: linkRelative,
+                target,
             });
             continue;
         }
@@ -1449,6 +1954,23 @@ function isWithinForLink(parent, linkPath) {
  *
  * 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, hqRoot, syncRoot, explicitRoots = []) {
     const prefixes = new Set();
@@ -1468,7 +1990,7 @@ function resolveDeleteScopeRoots(paths, hqRoot, syncRoot, explicitRoots = []) {
         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))
@@ -1689,6 +2211,20 @@ companyScoped = true) {
             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);
@@ -1723,19 +2259,6 @@ companyScoped = true) {
             litterToDelete.push(relativeKey);
             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