@staix/agent-hub 0.19.0 → 0.21.0

package/docs/verification/2026-10-28-realpath-name-audit.md

@@ -0,0 +1,222 @@
+# Audit: policy decisions made from a realpath-derived name alone (#552, the #541 class)
+
+Date: 2026-10-28. Base: origin/main fa6ef818. Follow-up to #541 (PR #943).
+
+## The class
+
+On macOS APFS, Bun's `realpathSync` (1.4.3, and `.native`) can return another hardlink of the same file: about 1 call in 100 when a file has a second name in a different directory, and never in the 4000 calls where the system `/bin/realpath` was run on the same layout. A decision that tests a name against a name-based policy (the secrets denylist, `.git` and `.agenthub` names, `pii.paths`, `data.readonly`, the shadow ignore policy) after resolving the path with `realPath` can therefore judge a different name than the one the caller used. Both names name the same bytes, so the decision is only wrong when the policy judges the two names differently. It needs a hardlink to a file inside the project to exist first.
+
+## Method
+
+1. `bun ~/.jcode/scratch/inventory.ts` (kept in the PR description, not the repository) listed every `realPath(`, `realpathSync(` and `realpathSync.native(` call in a tracked `src/` file with its enclosing function: 170 call sites in 48 files. Comments, imports and declarations are not call sites.
+2. Each call site was read with its source line and, where the line alone did not say what policy follows, the surrounding function. The table has one row per call site. A row is **reachable** when a name-based policy decision is made from the resolved name and the typed name is not also judged.
+3. The reverse search covered every caller of `isDenied`, `isHubWritePath`, `isAgentConfigPath`, `matchesPolicy` and `matchesPolicyLexically` for a resolved name reaching it. Two callers that never call `realPath` themselves were reached this way: `screenRegistration` (`src/hub/sources.ts`) and the shadow ignore check inside `Facts.rel`.
+4. Reachable callers were measured with the hardlink flip on unmodified main, then fixed, then looped at 5000 iterations (`test/realpath-name-audit.test.ts`, five tests of 1000 each so none needs a timeout above the gate's 20 s).
+
+## Measured on unmodified main
+
+| Caller | Policy | Calls that decided wrongly |
+|---|---|---|
+| `Facts.rel` | secrets denylist | 17 of 3000 |
+| `Facts.rel` in a shadow repository | shadow ignore policy (`.agenthub/ignore`) | 17 of 5000 (found in review of this PR) |
+| `locate` in `deliverable-files.ts` | hub-owned names | 29 of 3000 |
+| `locate` in `deliverable-files.ts` | secrets denylist | 29 of 3000 |
+| `ahub source add` through `screenRegistration` | `pii.paths` | 63 of 4000 |
+
+## Behavior change to know about
+
+`Facts.rel` in a **shadow repository** (a project without `.git`, `ahub init --shadow`) now also asks `git check-ignore` about the typed name. Git answers "beyond a symbolic link" (exit 128) for any name that passes through a symlinked directory, such as `via/f.txt` where `via` is a link to `real`. An answer that is not a plain "not ignored" is never readable fact evidence, so such a path is no longer named by that spelling; the file is still named by its real path (`real/f.txt`). This fails closed and only affects shadow projects, but it is a change for a project that keeps symlinked directories there. `test/realpath-name-audit.test.ts` pins it. Ordinary Git projects do not run this check and are unchanged.
+
+## Containment of the typed name
+
+The typed-name checks run only for a typed name inside the project. That test is `insideRoot` in `src/hub/path-policy.ts`, a **segment** test (`..` itself, a path starting `../`, or an absolute path is outside). The first version used a string prefix (`startsWith("..")`), which treats a valid directory named `..ignored` or `..d` as outside the project and skipped its policies when realpath named the public hardlink (found in review of this PR: 5000 of 5000 loops failed against the old predicate, 0 against the fix). The resolved name keeps main's own test for its containment, unchanged. `test/realpath-name-audit.test.ts` loops 5000 per layout on directories called `..ignored` and `..d`.
+
+**The flip is rarer than it was.** When this was found it happened about 1 call in 100. Re-measured on a quiet machine later the same day it was 0 of 3000, and under six parallel workers about 1 of 3000 (Bun 1.4.3, the same APFS volume, the same probe). So the loops can pass on a machine where the flip does not occur, and I do not count them alone. Each decision is also pinned **deterministically** with a symlink, whose typed name differs from its resolved name on every call: a link whose own name is denied, hub-owned, ignored or in `local.deny` is refused although its target is innocent, in plain directories and in directories called `..d` or `..ignored`. Before this change such a link was named by its target. Mutants of the typed-name checks die in these deterministic tests, not only in the loops.
+
+## Plan adjustment
+
+The plan said no new exported API. `screenRegistration`'s input gains an optional `typedPath`, because the only way to judge both names for `pii.paths` is to hand it both; the field is optional and callers without it behave as before. `src/cli/main.ts` and `src/hub/sources.ts` were not in the planned paths and are in this PR for that reason.
+
+## Call sites
+
+<!-- TABLE -->
+| # | Call site | Function | Call | Reachable | Policy decided from the name | Result |
+|---|---|---|---|---|---|---|
+| 1 | `src/adapters/claude-channel.ts:264` | `connectLoop` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 2 | `src/adapters/claude-implementer.ts:55` | `fingerprint` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 3 | `src/adapters/claude-implementer.ts:111` | `start` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 4 | `src/adapters/codex-review-isolation.ts:107` | `credentialCanonicalPath` | `realPath` | no | credential and private-path deny rules for the sandboxed reviewer | not reachable at this call: builds deny rules from BOTH names: the lexical path and the resolved one (`denyCredentialRoots` takes `new Set([lexical, canonical])`, and the private-path patterns add `absolute` and `realPath(absolute)`), so a flip cannot drop a name from the rule set |
+| 5 | `src/adapters/codex-review-isolation.ts:125` | `resolveCommand` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 6 | `src/adapters/codex-review-isolation.ts:133` | `resolveCommand` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 7 | `src/adapters/codex-review-isolation.ts:140` | `resolveCommand` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 8 | `src/adapters/codex-review-isolation.ts:185` | `prepare` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 9 | `src/adapters/codex-review-isolation.ts:243` | `finish` | `realPath` | no | credential and private-path deny rules for the sandboxed reviewer | not reachable at this call: builds deny rules from BOTH names: the lexical path and the resolved one (`denyCredentialRoots` takes `new Set([lexical, canonical])`, and the private-path patterns add `absolute` and `realPath(absolute)`), so a flip cannot drop a name from the rule set |
+| 10 | `src/adapters/codex-review-isolation.ts:267` | `finish` | `realPath` | no | credential and private-path deny rules for the sandboxed reviewer | not reachable at this call: builds deny rules from BOTH names: the lexical path and the resolved one (`denyCredentialRoots` takes `new Set([lexical, canonical])`, and the private-path patterns add `absolute` and `realPath(absolute)`), so a flip cannot drop a name from the rule set |
+| 11 | `src/adapters/definitions/native-cli-claude-setup.ts:31` | `real` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 12 | `src/adapters/external-modules.ts:39` | `externalModuleIdentityCurrent` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 13 | `src/adapters/external-modules.ts:90` | `captureBundle` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 14 | `src/adapters/external-modules.ts:104` | `captureBundle` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 15 | `src/adapters/external-modules.ts:276` | `existingKinds` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 16 | `src/adapters/external-modules.ts:278` | `existingKinds` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 17 | `src/adapters/external-modules.ts:278` | `existingKinds` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 18 | `src/adapters/kimi-review.ts:117` | `prepare` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 19 | `src/adapters/kimi-review.ts:119` | `sources` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 20 | `src/adapters/kimi-review.ts:124` | `sources` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 21 | `src/adapters/kimi-review.ts:134` | `sources` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 22 | `src/adapters/kimi-review.ts:150` | `cleanup` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 23 | `src/adapters/kimi-review.ts:152` | `cleanup` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 24 | `src/adapters/kimi-review.ts:152` | `cleanup` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 25 | `src/adapters/kimi-wire-usage.ts:130` | `resolve` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 26 | `src/adapters/kimi-wire-usage.ts:133` | `resolve` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 27 | `src/adapters/kimi-wire-usage.ts:148` | `resolve` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 28 | `src/adapters/kimi-wire-usage.ts:185` | `agents` | `realPath` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 29 | `src/adapters/qwen-dual.ts:74` | `qwenDualNamesStateDir` | `realpathSync` | no | binary, credential or state-directory identity | not reachable at this call: resolves executables, credential files and state directories for isolation; compared by identity, not by a content-name policy |
+| 30 | `src/broker/store.ts:140` | `expiryIndex` | `realPath` | no | none (root identity) | not reachable at this call: session, broker and room store paths under the state directory |
+| 31 | `src/broker/store.ts:151` | `expiryIndex` | `realPath` | no | none (root identity) | not reachable at this call: session, broker and room store paths under the state directory |
+| 32 | `src/cli/agy-mcp.ts:97` | `verifyPluginDirectory` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 33 | `src/cli/agy-mcp.ts:97` | `verifyPluginDirectory` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 34 | `src/cli/agy-mcp.ts:184` | `internalPlan` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 35 | `src/cli/agy-mcp.ts:195` | `internalPlan` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 36 | `src/cli/agy-mcp.ts:305` | `ensureAgyMcp` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 37 | `src/cli/agy-mcp.ts:306` | `ensureAgyMcp` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 38 | `src/cli/bench.ts:89` | `benchPreflight` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 39 | `src/cli/bench.ts:89` | `benchPreflight` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 40 | `src/cli/facts-hook.ts:29` | `projectFileTool` | `realPath` | no | hub-owned and agent-config names, data.readonly | not reachable at this call: checks the lexical name first, then the resolved one, and refuses a hardlinked file (`hardLinked(real)`) |
+| 41 | `src/cli/facts-hook.ts:35` | `safe` | `realPath` | no | hub-owned and agent-config names, data.readonly | not reachable at this call: checks the lexical name first, then the resolved one, and refuses a hardlinked file (`hardLinked(real)`) |
+| 42 | `src/cli/init.ts:77` | `releaseHookPlan` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 43 | `src/cli/launch.ts:84` | `cleanupClaudeSettings` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 44 | `src/cli/launch.ts:85` | `cleanupClaudeSettings` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 45 | `src/cli/launch.ts:88` | `cleanupClaudeSettings` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 46 | `src/cli/launch.ts:243` | `paths` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 47 | `src/cli/main.ts:142` | `registered` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 48 | `src/cli/main.ts:145` | `registered` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 49 | `src/cli/main.ts:147` | `registered` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 50 | `src/cli/main.ts:147` | `registered` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 51 | `src/cli/main.ts:765` | `commands` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 52 | `src/cli/main.ts:765` | `commands` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 53 | `src/cli/main.ts:1331` | `operands` | `realPath` | yes | pii.paths | fixed: `ahub source add` resolves the typed path; `screenRegistration` now takes it as `typedPath` and either name under pii.paths makes the source private |
+| 54 | `src/cli/main.ts:2166` | `value` | `realPath` | no | overlap warnings only | not reachable at this call: `ahub check-path` shows advisory text; a wrong name changes a warning, never a refusal |
+| 55 | `src/cli/main.ts:2167` | `value` | `realPath` | no | overlap warnings only | not reachable at this call: `ahub check-path` shows advisory text; a wrong name changes a warning, never a refusal |
+| 56 | `src/cli/main.ts:2215` | `undoWorkspace` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 57 | `src/cli/main.ts:2215` | `undoWorkspace` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 58 | `src/cli/main.ts:2220` | `requireUndoWorkspace` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 59 | `src/cli/main.ts:2220` | `requireUndoWorkspace` | `realPath` | no | none (root identity) | not reachable at this call: compares two directories for identity |
+| 60 | `src/cli/recovery-package.ts:57` | `memoryRuntime` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 61 | `src/cli/smoke-run.ts:32` | `runSmoke` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 62 | `src/cli/smoke-target.ts:26` | `realDirectory` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 63 | `src/cli/smoke-target.ts:59` | `gitPath` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 64 | `src/cli/smoke-target.ts:75` | `inspect` | `realPath` | no | directory or executable identity | not reachable at this call: plugin, repository, state or temp directories and executables compared by identity |
+| 65 | `src/hub/claude-shell-wrapper.ts:66` | `stamp` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 66 | `src/hub/claude-shell-wrapper.ts:125` | `create` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 67 | `src/hub/code-facts.ts:63` | `changed` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 68 | `src/hub/code-facts.ts:63` | `changed` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 69 | `src/hub/code-facts.ts:178` | `result` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 70 | `src/hub/code-facts.ts:200` | `job` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 71 | `src/hub/code-facts.ts:240` | `relations` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 72 | `src/hub/code-facts.ts:240` | `relations` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 73 | `src/hub/corpus.ts:66` | `checkCorpusRoot` | `realPath` | no | vault, denylist, pii.paths on a configured folder | not reachable at this call: the object is a configured directory, not a file with several names; the walk joins readdir entries and skips symlinks, so no resolved file name reaches a name check |
+| 74 | `src/hub/corpus.ts:69` | `checkCorpusRoot` | `realPath` | no | vault, denylist, pii.paths on a configured folder | not reachable at this call: the object is a configured directory, not a file with several names; the walk joins readdir entries and skips symlinks, so no resolved file name reaches a name check |
+| 75 | `src/hub/daemon.ts:1706` | `publicCheck` | `realPath` | no | none (root identity) | not reachable at this call: project, state or execution root compared as a directory |
+| 76 | `src/hub/daemon.ts:2134` | `claudeTranscript` | `realPath` | no | transcript containment | not reachable at this call: requires the transcript under the Claude projects directory and named <session>.jsonl; a different hardlink name inside that directory is the same transcript |
+| 77 | `src/hub/daemon.ts:2135` | `claudeTranscript` | `realPath` | no | transcript containment | not reachable at this call: requires the transcript under the Claude projects directory and named <session>.jsonl; a different hardlink name inside that directory is the same transcript |
+| 78 | `src/hub/daemon.ts:2585` | `currentSandbox` | `realPath` | no | none (root identity) | not reachable at this call: project, state or execution root compared as a directory |
+| 79 | `src/hub/daemon.ts:5080` | `classed` | `realPath` | no | none (root identity) | not reachable at this call: project, state or execution root compared as a directory |
+| 80 | `src/hub/daemon.ts:5271` | `classed` | `realPath` | no | none (root identity) | not reachable at this call: project, state or execution root compared as a directory |
+| 81 | `src/hub/daemon.ts:6900` | `reply` | `realPath` | no | none (root identity) | not reachable at this call: project, state or execution root compared as a directory |
+| 82 | `src/hub/daemon.ts:7165` | `admittedEnv` | `realPath` | no | none (root identity) | not reachable at this call: project, state or execution root compared as a directory |
+| 83 | `src/hub/daemon.ts:7165` | `admittedEnv` | `realPath` | no | none (root identity) | not reachable at this call: project, state or execution root compared as a directory |
+| 84 | `src/hub/daemon.ts:7245` | `tally` | `realPath` | no | transcript containment | not reachable at this call: requires the transcript under the Claude projects directory and named <session>.jsonl; a different hardlink name inside that directory is the same transcript |
+| 85 | `src/hub/daemon.ts:7245` | `tally` | `realPath` | no | transcript containment | not reachable at this call: requires the transcript under the Claude projects directory and named <session>.jsonl; a different hardlink name inside that directory is the same transcript |
+| 86 | `src/hub/deliverable-files.ts:52` | `locate` | `realPath` | no | none at this call (the project root); the file name is judged below it | not reachable at this call: this call resolves the project root only. The file-name decision in the same function (hub-owned names, local.deny) was reachable from the resolved name returned by guardPath and is fixed here: it now judges the typed and the resolved name (measured: 29 of 3000 each on unmodified main) |
+| 87 | `src/hub/external-instance.ts:48` | `externalInstanceStateDir` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 88 | `src/hub/external-instance.ts:50` | `externalInstanceStateDir` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 89 | `src/hub/external-instance.ts:53` | `externalInstanceStateDir` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 90 | `src/hub/external-instance.ts:60` | `readExternalInstanceRecord` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 91 | `src/hub/external-instance.ts:60` | `readExternalInstanceRecord` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 92 | `src/hub/facts.ts:196` | `constructor` | `realPath` | no | none (root identity) | not reachable at this call: the Facts root, resolved once |
+| 93 | `src/hub/facts.ts:215` | `rel` | `realPath` | yes | secrets denylist, .git names, hub-owned names, shadow ignore policy | fixed: decided from the resolved name alone; this PR judges the typed name for every one of them, and the ignore check fails closed on either |
+| 94 | `src/hub/facts.ts:218` | `rel` | `realPath` | yes | secrets denylist, .git names, hub-owned names, shadow ignore policy | fixed: decided from the resolved name alone; this PR judges the typed name for every one of them, and the ignore check fails closed on either |
+| 95 | `src/hub/folder-trigger.ts:51` | `checkTriggerFolder` | `realPath` | no | none (root identity) | not reachable at this call: the trigger folder and declared data folders, directories |
+| 96 | `src/hub/folder-trigger.ts:53` | `checkTriggerFolder` | `realPath` | no | none (root identity) | not reachable at this call: the trigger folder and declared data folders, directories |
+| 97 | `src/hub/folder-trigger.ts:84` | `scanFolder` | `realpathSync` | no | none (link classification) | not reachable at this call: decides whether a link stays inside the folder; the file name it later tests comes from readdir, never from this call |
+| 98 | `src/hub/host-executable.ts:10` | `hostExecutable` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 99 | `src/hub/host-executable.ts:10` | `hostExecutable` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 100 | `src/hub/host-executable.ts:19` | `hostShellPath` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 101 | `src/hub/host-executable.ts:19` | `hostShellPath` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 102 | `src/hub/host-executable.ts:25` | `inside` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 103 | `src/hub/instance-execution.ts:26` | `commonDirectory` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 104 | `src/hub/instance-execution.ts:45` | `moduleInstance` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 105 | `src/hub/instance-execution.ts:46` | `moduleInstance` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 106 | `src/hub/instance-execution.ts:57` | `path` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 107 | `src/hub/instance-execution.ts:62` | `path` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 108 | `src/hub/instances.ts:83` | `canonicalHome` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 109 | `src/hub/memory-code-head.ts:24` | `readMemoryCodeHead` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 110 | `src/hub/memory-code-head.ts:24` | `readMemoryCodeHead` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 111 | `src/hub/memory-profile-check.ts:119` | `readProfileCheckProjects` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 112 | `src/hub/memory-profile.ts:75` | `canonicalHome` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 113 | `src/hub/path-policy.ts:17` | `policyRealPath` | `realPath` | no | pii.paths, data.readonly, deny | not reachable at this call: this is the policy comparator: it judges the declared spelling, the real target and aliases, which is the pattern the fixes follow |
+| 114 | `src/hub/path-policy.ts:25` | `policyTargets` | `realPath` | no | pii.paths, data.readonly, deny | not reachable at this call: this is the policy comparator: it judges the declared spelling, the real target and aliases, which is the pattern the fixes follow |
+| 115 | `src/hub/path-policy.ts:163` | `matchesPolicy` | `realPath` | no | pii.paths, data.readonly, deny | not reachable at this call: this is the policy comparator: it judges the declared spelling, the real target and aliases, which is the pattern the fixes follow |
+| 116 | `src/hub/read-only-shell-proof.ts:49` | `proveReadOnlyShell` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 117 | `src/hub/read-only-shell-proof.ts:49` | `proveReadOnlyShell` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 118 | `src/hub/read-only-shell-proof.ts:54` | `proveReadOnlyShell` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 119 | `src/hub/recovery-continuity.ts:36` | `canonicalRoot` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 120 | `src/hub/registry.ts:43` | `legacyRoot` | `realpathSync` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 121 | `src/hub/snapshots.ts:88` | `repoOf` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 122 | `src/hub/snapshots.ts:99` | `repoOf` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 123 | `src/hub/snapshots.ts:101` | `repoOf` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 124 | `src/hub/snapshots.ts:105` | `initShadow` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 125 | `src/hub/task-repository.ts:13` | `canonical` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 126 | `src/hub/task-repository.ts:42` | `githubOriginRepository` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 127 | `src/hub/task-shell-default.ts:31` | `readTaskShellDefaultBranch` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 128 | `src/hub/task-shell-default.ts:32` | `readTaskShellDefaultBranch` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 129 | `src/hub/task-shell-default.ts:34` | `readTaskShellDefaultBranch` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 130 | `src/hub/task-shell-default.ts:34` | `readTaskShellDefaultBranch` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 131 | `src/hub/task-shell-default.ts:38` | `remove` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 132 | `src/hub/task-shell-proof.ts:20` | `gitReader` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 133 | `src/hub/task-shell-proof.ts:38` | `readTaskShellBinding` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 134 | `src/hub/task-shell-proof.ts:39` | `readTaskShellBinding` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 135 | `src/hub/task-shell-proof.ts:39` | `readTaskShellBinding` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 136 | `src/hub/task-shell-proof.ts:98` | `proveTaskShell` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 137 | `src/hub/task-shell-proof.ts:98` | `proveTaskShell` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 138 | `src/hub/task-shell-sandbox.ts:23` | `taskShellSandboxRestrictions` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 139 | `src/hub/task-shell-sandbox.ts:24` | `taskShellSandboxRestrictions` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 140 | `src/hub/task-shell-sandbox.ts:36` | `git` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 141 | `src/hub/task-shell-sandbox.ts:37` | `git` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 142 | `src/hub/task-shell-sandbox.ts:38` | `git` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 143 | `src/hub/task-shell-sandbox.ts:44` | `directory` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 144 | `src/hub/tasks.ts:1136` | `wip` | `realPath` | no | none (root identity) | not reachable at this call: worktree and project root identity; projectPath compares to the project roots |
+| 145 | `src/hub/tasks.ts:1136` | `wip` | `realPath` | no | none (root identity) | not reachable at this call: worktree and project root identity; projectPath compares to the project roots |
+| 146 | `src/hub/tasks.ts:1136` | `wip` | `realPath` | no | none (root identity) | not reachable at this call: worktree and project root identity; projectPath compares to the project roots |
+| 147 | `src/hub/tasks.ts:1136` | `wip` | `realPath` | no | none (root identity) | not reachable at this call: worktree and project root identity; projectPath compares to the project roots |
+| 148 | `src/hub/tasks.ts:1137` | `wip` | `realPath` | no | none (root identity) | not reachable at this call: worktree and project root identity; projectPath compares to the project roots |
+| 149 | `src/hub/tasks.ts:2384` | `projectPath` | `realPath` | no | none (root identity) | not reachable at this call: worktree and project root identity; projectPath compares to the project roots |
+| 150 | `src/hub/tasks.ts:3324` | `currentNoWrites` | `realPath` | no | none (root identity) | not reachable at this call: worktree and project root identity; projectPath compares to the project roots |
+| 151 | `src/hub/text-projection.ts:75` | `project` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 152 | `src/hub/text-projection.ts:75` | `project` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 153 | `src/hub/text-projection.ts:96` | `projectBytes` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 154 | `src/hub/text-projection.ts:109` | `projectBytes` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 155 | `src/hub/text-projection.ts:121` | `projectBytes` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 156 | `src/hub/text-projection.ts:126` | `projectBytes` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 157 | `src/hub/text-projection.ts:126` | `projectBytes` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 158 | `src/hub/text-projection.ts:132` | `projectBytes` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 159 | `src/hub/text-projection.ts:133` | `programs` | `realPath` | no | containment only | not reachable at this call: containment under the project root and O_NOFOLLOW; privacy is decided by the callers (Facts.rel, registerScanned, doc_read) before this runs |
+| 160 | `src/hub/tooling.ts:35` | `real` | `realPath` | no | executable and directory containment | not reachable at this call: decides on executables and directories by identity or containment against a root, never by a file-name policy |
+| 161 | `src/local/sandbox.ts:38` | `developerDir` | `realPath` | no | none (root identity) | not reachable at this call: sandbox roots and own temp directory |
+| 162 | `src/local/sandbox.ts:149` | `inHome` | `realPath` | no | none (root identity) | not reachable at this call: sandbox roots and own temp directory |
+| 163 | `src/local/sandbox.ts:210` | `sandboxedExec` | `realPath` | no | none (root identity) | not reachable at this call: sandbox roots and own temp directory |
+| 164 | `src/local/tools.ts:60` | `guardPath` | `realPath` | yes | secrets denylist, hub-owned names, data.readonly | fixed: fixed in #541 (PR #943), not in this PR: guardPath now judges the typed name as well as the resolved one |
+| 165 | `src/local/tools.ts:68` | `guardPath` | `realPath` | yes | secrets denylist, hub-owned names, data.readonly | fixed: fixed in #541 (PR #943), not in this PR: guardPath now judges the typed name as well as the resolved one |
+| 166 | `src/pi/session.ts:23` | `validatePiSession` | `realPath` | no | none (root identity) | not reachable at this call: session, broker and room store paths under the state directory |
+| 167 | `src/pi/session.ts:23` | `validatePiSession` | `realPath` | no | none (root identity) | not reachable at this call: session, broker and room store paths under the state directory |
+| 168 | `src/pi/session.ts:31` | `validatePiSession` | `realPath` | no | none (root identity) | not reachable at this call: session, broker and room store paths under the state directory |
+| 169 | `src/pi/session.ts:31` | `validatePiSession` | `realPath` | no | none (root identity) | not reachable at this call: session, broker and room store paths under the state directory |
+| 170 | `src/rooms/store.ts:80` | `validSelection` | `realPath` | no | none (root identity) | not reachable at this call: session, broker and room store paths under the state directory |
+<!-- /TABLE -->
+
+## Not covered
+
+- Callers outside `src/` (scripts, tests) were not audited.
+- The measurement is on APFS with Bun 1.4.3. On other filesystems the behavior was not measured; the fixes only add refusals, so they are safe there.
+- Whether an actor the policies protect against can create the hardlink in the first place was not examined; each reachable row is reachable as a function call, not shown to be reachable by an agent.
+- The "not reachable" verdicts are a reading of the code at this commit. A later change that feeds a resolved name into a name-based policy would need the same treatment; `docs/agent-notes/local-worker.md` and the AGENTS.md Real paths rule say so.