typeclaw 0.45.1 → 0.46.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/README.md +1 -1
  2. package/package.json +3 -2
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +44 -30
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/multimodal/index.ts +1 -1
  7. package/src/agent/multimodal/look-at.ts +78 -44
  8. package/src/agent/multimodal/looker.ts +161 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +207 -0
  11. package/src/agent/plugin-tools.ts +377 -157
  12. package/src/agent/provider-error.ts +52 -1
  13. package/src/agent/restart/index.ts +61 -40
  14. package/src/agent/restart-handoff/index.ts +73 -4
  15. package/src/agent/reviewer-bash-policy.ts +42 -1
  16. package/src/agent/session-origin.ts +2 -0
  17. package/src/agent/subagent-drain.ts +117 -7
  18. package/src/agent/subagents.ts +49 -16
  19. package/src/agent/throttle-circuit.ts +25 -5
  20. package/src/agent/tool-error-remediation.ts +72 -0
  21. package/src/agent/tool-file-safety.ts +1310 -0
  22. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  23. package/src/agent/tools/ddg.ts +16 -2
  24. package/src/agent/tools/post-github-review.ts +199 -0
  25. package/src/agent/tools/spawn-subagent.ts +21 -18
  26. package/src/agent/tools/webfetch/fetch.ts +163 -183
  27. package/src/agent/tools/webfetch/tool.ts +2 -3
  28. package/src/agent/tools/websearch.ts +23 -2
  29. package/src/agent/tools-without-local-file-operands.ts +30 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/README.md +23 -10
  32. package/src/bundled-plugins/backup/git-auth.ts +6 -4
  33. package/src/bundled-plugins/backup/index.ts +85 -44
  34. package/src/bundled-plugins/backup/runner.ts +85 -1
  35. package/src/bundled-plugins/doc-render/render.ts +93 -12
  36. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  37. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  38. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  39. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
  40. package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
  41. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
  42. package/src/bundled-plugins/github-cli-auth/index.ts +207 -132
  43. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  44. package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
  45. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  46. package/src/bundled-plugins/memory/README.md +32 -11
  47. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  48. package/src/bundled-plugins/memory/citations.ts +22 -9
  49. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  50. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  51. package/src/bundled-plugins/memory/index.ts +0 -4
  52. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  53. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  54. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  55. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  56. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  57. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  58. package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
  59. package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
  60. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  61. package/src/bundled-plugins/researcher/write-report.ts +8 -5
  62. package/src/bundled-plugins/reviewer/index.ts +2 -2
  63. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  64. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  65. package/src/bundled-plugins/scout/scout.ts +8 -0
  66. package/src/bundled-plugins/security/index.ts +4 -4
  67. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  68. package/src/bundled-plugins/security/policies/private-surface-read.ts +787 -36
  69. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  70. package/src/bundled-plugins/security/policies/ssrf.ts +147 -42
  71. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  72. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  73. package/src/channels/adapters/discord-bot.ts +66 -6
  74. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  75. package/src/channels/adapters/discord-id.ts +4 -0
  76. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  77. package/src/channels/adapters/discord.ts +57 -7
  78. package/src/channels/adapters/github/auth-app.ts +41 -12
  79. package/src/channels/adapters/github/inbound.ts +11 -0
  80. package/src/channels/adapters/github/index.ts +71 -65
  81. package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
  82. package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
  83. package/src/channels/adapters/github/review-submitter.ts +302 -0
  84. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  85. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  86. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  87. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  88. package/src/channels/adapters/slack-bot-edit.ts +85 -20
  89. package/src/channels/adapters/slack-bot.ts +26 -10
  90. package/src/channels/adapters/slack-classify.ts +21 -2
  91. package/src/channels/adapters/slack-format.ts +245 -0
  92. package/src/channels/adapters/slack.ts +59 -7
  93. package/src/channels/adapters/telegram-bot.ts +18 -5
  94. package/src/channels/adapters/webex-bot.ts +8 -3
  95. package/src/channels/adapters/webex.ts +8 -3
  96. package/src/channels/fetch-attachment.ts +43 -0
  97. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  98. package/src/channels/github-token-bridge.ts +12 -6
  99. package/src/channels/manager.ts +9 -0
  100. package/src/channels/router.ts +248 -6
  101. package/src/channels/types.ts +28 -1
  102. package/src/cli/channel.ts +1 -1
  103. package/src/cli/init.ts +1 -1
  104. package/src/cli/model.ts +57 -7
  105. package/src/compose/stop.ts +17 -5
  106. package/src/config/config.ts +6 -6
  107. package/src/config/models-mutation.ts +13 -1
  108. package/src/config/providers.ts +176 -0
  109. package/src/container/docker-app.ts +42 -13
  110. package/src/container/start.ts +62 -10
  111. package/src/cron/bridge.ts +9 -2
  112. package/src/doctor/checks.ts +8 -3
  113. package/src/doctor/commit.ts +2 -1
  114. package/src/doctor/file-ownership.ts +52 -0
  115. package/src/dreams/git.ts +2 -1
  116. package/src/git/bound-gc-config.ts +82 -0
  117. package/src/git/hookless.ts +5 -0
  118. package/src/git/reconcile-ignored.ts +18 -5
  119. package/src/git/system-commit.ts +12 -6
  120. package/src/hostd/spawn.ts +133 -47
  121. package/src/init/dockerfile.ts +99 -5
  122. package/src/init/index.ts +17 -5
  123. package/src/init/models-dev.ts +4 -0
  124. package/src/init/validate-api-key.ts +2 -0
  125. package/src/inspect/replay.ts +21 -9
  126. package/src/inspect/session-list.ts +71 -33
  127. package/src/mcp/tools.ts +17 -3
  128. package/src/network/internal-destinations.ts +267 -0
  129. package/src/permissions/builtins.ts +3 -1
  130. package/src/plugin/context.ts +2 -0
  131. package/src/plugin/index.ts +1 -0
  132. package/src/plugin/manager.ts +4 -0
  133. package/src/plugin/types.ts +22 -0
  134. package/src/run/index.ts +40 -0
  135. package/src/run/llm-fetch-observer.ts +41 -4
  136. package/src/sandbox/build.ts +37 -15
  137. package/src/sandbox/canonical-secrets.ts +18 -0
  138. package/src/sandbox/env-exposure.ts +83 -0
  139. package/src/sandbox/errors.ts +13 -6
  140. package/src/sandbox/hidden-paths.ts +102 -44
  141. package/src/sandbox/index.ts +22 -4
  142. package/src/sandbox/package-install.ts +3 -27
  143. package/src/sandbox/policy.ts +16 -28
  144. package/src/sandbox/privileged-runtime.ts +256 -0
  145. package/src/sandbox/session-tmp.ts +8 -2
  146. package/src/sandbox/writable-zones.ts +204 -140
  147. package/src/secrets/index.ts +8 -0
  148. package/src/secrets/refresh-provider-oauth.ts +128 -0
  149. package/src/server/command-runner.ts +48 -4
  150. package/src/server/index.ts +4 -0
  151. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  152. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  153. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  154. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  155. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  156. package/src/skills/typeclaw-config/SKILL.md +27 -11
  157. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  158. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  159. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  160. package/src/skills/typeclaw-permissions/SKILL.md +36 -19
  161. package/src/skills/typeclaw-plugins/SKILL.md +37 -0
  162. package/src/usage/scan.ts +11 -2
  163. package/typeclaw.schema.json +25 -0
@@ -1,7 +1,29 @@
1
- import { realpathSync } from 'node:fs'
1
+ import {
2
+ closeSync,
3
+ constants,
4
+ fstatSync,
5
+ lstatSync,
6
+ openSync,
7
+ opendirSync,
8
+ realpathSync,
9
+ statSync,
10
+ type Dir,
11
+ type Dirent,
12
+ type Stats,
13
+ } from 'node:fs'
14
+ import { homedir } from 'node:os'
2
15
  import path from 'node:path'
16
+ import { fileURLToPath } from 'node:url'
3
17
 
4
- import type { HiddenPaths } from '@/sandbox'
18
+ import { TOOLS_WITHOUT_LOCAL_FILE_OPERANDS } from '@/agent/tools-without-local-file-operands'
19
+ import type { ToolFileOperands } from '@/plugin'
20
+ import {
21
+ CANONICAL_AGENT_SECRET_DIRS,
22
+ CANONICAL_AGENT_SECRET_FILES,
23
+ CANONICAL_HOME_SECRET_DIRS,
24
+ CANONICAL_HOME_SECRET_FILES,
25
+ type HiddenPaths,
26
+ } from '@/sandbox'
5
27
 
6
28
  import type { SecurityBlock } from '../policy'
7
29
 
@@ -12,10 +34,20 @@ export const GUARD_PRIVATE_SURFACE_READ = 'privateSurfaceRead'
12
34
  // scanned, so a new file-reading tool — bundled or third-party — is covered
13
35
  // the day it ships without a whitelist edit. web_search/web_fetch take URLs, not
14
36
  // local paths, and the path-plausibility filter keeps their args from matching.
15
- const UNSCANNED_TOOLS = new Set(['bash'])
37
+ //
38
+ // TOOLS_WITHOUT_LOCAL_FILE_OPERANDS is the SAME set the file-operand scanner
39
+ // skips: first-party tools whose args are only remote ids/control tokens
40
+ // (channel/stream/subagent/role reads). Without this, an id equal to a working
41
+ // dir — channel_read({ workspace: "memory" }) — would resolve to /agent/memory
42
+ // and be wrongly blocked here even after the scanner cleared it. Sharing one set
43
+ // keeps both enforcement points agreeing on which tools read no local path.
44
+ const UNSCANNED_TOOLS = new Set(['bash', ...TOOLS_WITHOUT_LOCAL_FILE_OPERANDS])
45
+ const VIRTUAL_FILESYSTEM_ROOTS = ['/proc', '/sys', '/dev', '/run'] as const
46
+ const HARDLINK_SCAN_EXCLUDED_AGENT_DIRS = new Set(['.git', '.gitstore', 'node_modules'])
16
47
 
17
48
  // The bash sandbox hides the role's private surface — the working DIRECTORIES
18
- // (workspace/, memory/, sessions/) and the secret FILES (.env, secrets.json) —
49
+ // (workspace/, memory/, sessions/), unconditional credential directories, and
50
+ // secret FILES (.env, secrets.json, auth.json) —
19
51
  // via bwrap masks, but every non-bash tool runs in the main process, outside
20
52
  // any sandbox. find_entry, look_at, and the channel attachment tools all read
21
53
  // files by a caller-supplied path, so without a guard a restricted role could
@@ -26,36 +58,41 @@ const UNSCANNED_TOOLS = new Set(['bash'])
26
58
  // It covers the full deny-list rather than delegating secret files to the
27
59
  // secretExfilRead guard: that guard only inspects read/grep/find/ls (not
28
60
  // edit/write/look_at/channel_send) and is acknowledgement-bypassable, so
29
- // delegating would leave .env/secrets.json reachable through the uncovered
61
+ // delegating would leave canonical credential files reachable through uncovered
30
62
  // tools — exactly the gap the bash masks close. secretExfilRead remains as
31
63
  // independent defense in depth for the four tools it does cover.
32
64
  //
33
- // Posture is FAIL-CLOSED for restricted roles: it does not whitelist a known
65
+ // Posture is FAIL-CLOSED: it does not whitelist a known
34
66
  // set of tools (that fails open the moment a new reader is added). It scans
35
67
  // every arg of every non-bash tool — recursively, since paths hide in nested
36
68
  // shapes like look_at's images[].path and channel_send's attachments[].path —
37
69
  // and blocks any string that resolves to (a secret file) or under (a hidden
38
70
  // directory) the deny-list.
39
- export function checkPrivateSurfaceReadGuard(options: {
40
- tool: string
41
- args: Record<string, unknown>
42
- agentDir: string
43
- hidden: HiddenPaths
44
- }): SecurityBlock | undefined {
45
- const { tool, args, agentDir, hidden } = options
71
+ export function checkPrivateSurfaceReadGuard(
72
+ options: {
73
+ tool: string
74
+ args: Record<string, unknown>
75
+ agentDir: string
76
+ hidden: HiddenPaths
77
+ fileOperands?: ToolFileOperands
78
+ },
79
+ hooks: PrivateSurfaceIdentityScanHooks = {},
80
+ ): SecurityBlock | undefined {
81
+ const { tool, args, agentDir, hidden, fileOperands } = options
46
82
  if (UNSCANNED_TOOLS.has(tool)) return undefined
47
- const deniedDirs = hidden.dirs
48
- const deniedFiles = hidden.files
83
+ const { deniedDirs, deniedFiles } = deniedSurface(agentDir, hidden)
49
84
  if (deniedDirs.length === 0 && deniedFiles.length === 0) return undefined
85
+ const identityScanner = createHardlinkIdentityScanner(agentDir, deniedDirs, deniedFiles, hooks)
50
86
 
51
- for (const candidate of collectPathCandidates(args, tool)) {
52
- const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles)
87
+ const nonFile = fileOperands?.nonFile === undefined ? undefined : new Set(fileOperands.nonFile)
88
+ for (const candidate of collectPathCandidates(args, tool, nonFile)) {
89
+ const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles, identityScanner)
53
90
  if (hit !== undefined) {
54
91
  return {
55
92
  block: true,
56
93
  reason: [
57
- `Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: argument \`${candidate}\` resolves to ${hit}, which is hidden from the current role.`,
58
- 'The bash sandbox masks the same path; reaching it through another tool is the same disclosure.',
94
+ `Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: argument \`${candidate}\` resolves to ${hit}, which is not available to LLM tools.`,
95
+ 'The bash sandbox masks the same path. Privileged roles cannot bypass canonical agent credential files; use host-side redacted diagnostics such as `typeclaw doctor`, `typeclaw provider list`, or `typeclaw channel list` instead.',
59
96
  ].join(' '),
60
97
  }
61
98
  }
@@ -63,6 +100,97 @@ export function checkPrivateSurfaceReadGuard(options: {
63
100
  return undefined
64
101
  }
65
102
 
103
+ type PrivateSurfaceIdentityOptions = {
104
+ tool: string
105
+ agentDir: string
106
+ hidden: HiddenPaths
107
+ }
108
+
109
+ export type PrivateSurfaceIdentityScanHooks = {
110
+ maxEntries?: number
111
+ openDirectory?(directory: string): Pick<Dir, 'readSync' | 'closeSync'>
112
+ lstat?(candidate: string): Stats
113
+ afterEntryLstat?(candidate: string, stats: Stats): void
114
+ }
115
+
116
+ export type PrivateSurfaceIdentityVerifier = {
117
+ check(identity: Pick<Stats, 'dev' | 'ino' | 'nlink'>): SecurityBlock | undefined
118
+ }
119
+
120
+ export function createPrivateSurfaceReadIdentityVerifier(
121
+ options: PrivateSurfaceIdentityOptions,
122
+ hooks: PrivateSurfaceIdentityScanHooks = {},
123
+ ): PrivateSurfaceIdentityVerifier {
124
+ const { deniedDirs, deniedFiles } = deniedSurface(options.agentDir, options.hidden)
125
+ const scanner = createHardlinkIdentityScanner(options.agentDir, deniedDirs, deniedFiles, hooks)
126
+ return {
127
+ check(identity) {
128
+ if (identity.nlink <= 1) return undefined
129
+ const hit = scanner.check(identity)
130
+ return hit === undefined ? undefined : privateSurfaceBlock(options.tool, hit)
131
+ },
132
+ }
133
+ }
134
+
135
+ export function checkPrivateSurfaceReadIdentityGuard(
136
+ options: PrivateSurfaceIdentityOptions & { identity: Pick<Stats, 'dev' | 'ino' | 'nlink'> },
137
+ hooks: PrivateSurfaceIdentityScanHooks = {},
138
+ ): SecurityBlock | undefined {
139
+ return createPrivateSurfaceReadIdentityVerifier(options, hooks).check(options.identity)
140
+ }
141
+
142
+ function createHardlinkIdentityScanner(
143
+ agentDir: string,
144
+ deniedDirs: readonly string[],
145
+ deniedFiles: readonly string[],
146
+ hooks: PrivateSurfaceIdentityScanHooks,
147
+ ): HardlinkIdentityScanner {
148
+ const lstat = hooks.lstat ?? lstatSync
149
+ return new HardlinkIdentityScanner({
150
+ agentDir,
151
+ deniedDirs,
152
+ deniedFiles,
153
+ maxEntries: hooks.maxEntries ?? MAX_HARDLINK_IDENTITY_ENTRIES,
154
+ openDirectory:
155
+ hooks.openDirectory === undefined
156
+ ? openDescriptorAnchoredDirectory
157
+ : createPathDirectoryOpener(hooks.openDirectory, lstat),
158
+ lstat,
159
+ afterEntryLstat: hooks.afterEntryLstat,
160
+ })
161
+ }
162
+
163
+ function deniedSurface(agentDir: string, hidden: HiddenPaths): { deniedDirs: string[]; deniedFiles: string[] } {
164
+ return {
165
+ deniedDirs: [
166
+ ...new Set([
167
+ ...hidden.dirs,
168
+ ...CANONICAL_AGENT_SECRET_DIRS.map((dir) => path.join(agentDir, dir)),
169
+ ...CANONICAL_HOME_SECRET_DIRS.map((dir) => path.join(homedir(), dir)),
170
+ ]),
171
+ ],
172
+ // Keep runtime-owned credential stores independent of role-derived
173
+ // visibility so a partially-wired caller cannot expose raw credentials.
174
+ deniedFiles: [
175
+ ...new Set([
176
+ ...hidden.files,
177
+ ...CANONICAL_AGENT_SECRET_FILES.map((file) => path.join(agentDir, file)),
178
+ ...CANONICAL_HOME_SECRET_FILES.map((file) => path.join(homedir(), file)),
179
+ ]),
180
+ ],
181
+ }
182
+ }
183
+
184
+ function privateSurfaceBlock(tool: string, hit: string): SecurityBlock {
185
+ return {
186
+ block: true,
187
+ reason: [
188
+ `Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: input inode aliases ${hit}, which is not available to LLM tools.`,
189
+ 'The bash sandbox masks the same path. Privileged roles cannot bypass canonical agent credential files; use host-side redacted diagnostics instead.',
190
+ ].join(' '),
191
+ }
192
+ }
193
+
66
194
  // Field names whose values are ALWAYS free text (prose/queries/ids), NEVER a
67
195
  // filesystem path, for EVERY tool. Scanning them caused false positives: a
68
196
  // guest's `channel_reply({ text: "the memory leak" })` or `web_search({ query:
@@ -95,13 +223,12 @@ const NON_PATH_KEYS = new Set([
95
223
  'newText',
96
224
  // memory append tool: fragment topic is free text.
97
225
  'topic',
98
- // channel_send/channel_reply attachments[].filename and
99
- // channel_fetch_attachment.filename: display-only metadata (defaults to the
100
- // basename of the real `path`), never the file location the guard cares
101
- // about — `attachments[].path` carries that and is NOT exempted.
102
- 'filename',
103
226
  ])
104
227
 
228
+ const PATH_KEYS = /(?:^|[_-])(path|filepath|file)$/i
229
+ const CAMEL_PATH_KEYS = /(?:Path|Filepath|File)$/
230
+ const MAX_HARDLINK_IDENTITY_ENTRIES = 4_096
231
+
105
232
  // Keys that are free text in SPECIFIC tools but path-bearing in others, so a
106
233
  // global denylist would either over-block or open a bypass. Scoped per tool:
107
234
  // - grep.pattern : a regex/search string (e.g. "sessions"), NOT a path.
@@ -117,37 +244,73 @@ const NON_PATH_KEYS = new Set([
117
244
  // (or grep gaining a new key) scans everything.
118
245
  const FREE_TEXT_KEYS_BY_TOOL: Record<string, ReadonlySet<string>> = {
119
246
  grep: new Set(['pattern']),
247
+ // These channel tools use filename only as attachment display metadata. The
248
+ // corresponding attachments[].path is scanned independently where present.
249
+ channel_send: new Set(['filename']),
250
+ channel_reply: new Set(['filename']),
251
+ channel_fetch_attachment: new Set(['filename']),
252
+ }
253
+
254
+ // Trim before the `file:` test: an exempt prose key otherwise lets a
255
+ // leading-whitespace `file: file://…/memory` URI slip past the scan (the value
256
+ // is not path-shaped and `isFileUrl` misses it), reaching a fetcher that trims
257
+ // before parsing. Returns the trimmed URI so callers scan the real target.
258
+ function trimmedFileUri(value: string): string | undefined {
259
+ const trimmed = value.trim()
260
+ return trimmed.toLocaleLowerCase().startsWith('file:') ? trimmed : undefined
120
261
  }
121
262
 
122
263
  // Recursively collects strings that could be paths, skipping values under a
123
- // universally-free-text key or a tool-scoped free-text key. matchHidden then
264
+ // universally-free-text key or a tool-scoped free-text key. Explicit path-like
265
+ // keys still win, and file:// values are normalized before matching. matchHidden then
124
266
  // realpath-resolves each candidate and fires only on one landing inside a
125
267
  // hidden directory. Fail-closed by design: a bare path-bearing value equal to a
126
268
  // hidden dir name (e.g. `path: "memory"`) is still blocked. `underExempt`
127
269
  // propagates so nested values under an exempt key (e.g. a structured pattern)
128
270
  // stay exempt; top-level strings and array elements carry no key and are always
129
271
  // scanned (so attachments[].path is collected).
130
- function collectPathCandidates(value: unknown, tool: string): string[] {
272
+ //
273
+ // `nonFile` holds the tool author's declared control-token operand PATHS
274
+ // (`fileOperands.nonFile`, trusted metadata). A string at exactly one of those
275
+ // operand paths is skipped, mirroring the file-operand scanner so the two
276
+ // enforcement points agree — an id like `{ tenant: "memory" }` on a tool that
277
+ // declared `nonFile: ['tenant']` is not blocked here. Scoped by EXACT operand
278
+ // path (not key name), so an undeclared key still fails closed; `input`/
279
+ // `output`/`destructive` are deliberately NOT honored (a declared real-file path
280
+ // that resolves under a hidden dir must still block).
281
+ function collectPathCandidates(value: unknown, tool: string, nonFile?: ReadonlySet<string>): string[] {
131
282
  const out: string[] = []
132
- walk(value, out, tool, false)
283
+ walk(value, out, tool, false, nonFile, '')
133
284
  return out
134
285
  }
135
286
 
136
- function walk(value: unknown, out: string[], tool: string, underExempt: boolean): void {
287
+ function walk(
288
+ value: unknown,
289
+ out: string[],
290
+ tool: string,
291
+ underExempt: boolean,
292
+ nonFile: ReadonlySet<string> | undefined,
293
+ operandPath: string,
294
+ key?: string,
295
+ ): void {
137
296
  if (typeof value === 'string') {
138
- if (underExempt) return
139
- out.push(value)
297
+ if (nonFile?.has(operandPath) === true) return
298
+ const isFileUrl = trimmedFileUri(value) !== undefined
299
+ if (underExempt && !isPathKey(key) && !isFileUrl) return
300
+ const normalized = normalizeCandidate(value)
301
+ if (normalized !== undefined) out.push(normalized)
140
302
  return
141
303
  }
142
304
  if (Array.isArray(value)) {
143
- for (const item of value) walk(item, out, tool, underExempt)
305
+ for (const item of value) walk(item, out, tool, underExempt, nonFile, operandPath, key)
144
306
  return
145
307
  }
146
308
  if (value !== null && typeof value === 'object') {
147
309
  const toolFreeText = FREE_TEXT_KEYS_BY_TOOL[tool]
148
- for (const [key, item] of Object.entries(value)) {
149
- const keyIsExempt = NON_PATH_KEYS.has(key) || (toolFreeText?.has(key) ?? false)
150
- walk(item, out, tool, underExempt || keyIsExempt)
310
+ for (const [childKey, item] of Object.entries(value)) {
311
+ const keyIsExempt = NON_PATH_KEYS.has(childKey) || (toolFreeText?.has(childKey) ?? false)
312
+ const childPath = operandPath === '' ? childKey : `${operandPath}.${childKey}`
313
+ walk(item, out, tool, underExempt || keyIsExempt, nonFile, childPath, childKey)
151
314
  }
152
315
  }
153
316
  }
@@ -171,10 +334,16 @@ function matchHidden(
171
334
  agentDir: string,
172
335
  deniedDirs: string[],
173
336
  deniedFiles: string[],
337
+ identityScanner: HardlinkIdentityScanner,
174
338
  ): string | undefined {
175
- const resolved = realpathRealIntendedPath(path.resolve(agentDir, candidate))
339
+ const lexicalHit = matchLexicallyDenied(candidate, agentDir, deniedDirs, deniedFiles)
340
+ if (lexicalHit !== undefined) return lexicalHit
341
+ const lexical = path.resolve(agentDir, candidate)
342
+ const resolved = realpathRealIntendedPath(lexical)
343
+ const virtualRoot = virtualFilesystemRoot(lexical) ?? virtualFilesystemRoot(resolved)
344
+ if (virtualRoot !== undefined) return `${virtualRoot}, a virtual or process-backed filesystem`
176
345
  for (const file of deniedFiles) {
177
- if (resolved === realpathRealIntendedPath(file)) return file
346
+ if (resolved === realpathRealIntendedPath(file) || hasSameFileIdentity(resolved, file)) return file
178
347
  }
179
348
  for (const dir of deniedDirs) {
180
349
  const realDir = realpathRealIntendedPath(dir)
@@ -183,9 +352,591 @@ function matchHidden(
183
352
  // "\"-joined paths a win32 test runner produces.
184
353
  if (resolved === realDir || resolved.startsWith(`${realDir}${path.sep}`)) return dir
185
354
  }
355
+ const identity = fileIdentity(resolved)
356
+ if (identity !== undefined && identity.nlink > 1) {
357
+ const hit = identityScanner.check(identity)
358
+ if (hit !== undefined) return hit
359
+ }
360
+ return undefined
361
+ }
362
+
363
+ function matchLexicallyDenied(
364
+ candidate: string,
365
+ agentDir: string,
366
+ deniedDirs: readonly string[],
367
+ deniedFiles: readonly string[],
368
+ ): string | undefined {
369
+ const absolute = portableAbsolute(agentDir, candidate)
370
+ const virtualRoot = virtualFilesystemRoot(absolute)
371
+ if (virtualRoot !== undefined) return `${virtualRoot}, a virtual or process-backed filesystem`
372
+ for (const file of deniedFiles) {
373
+ if (portableEqual(absolute, portableAbsolute(agentDir, file))) return file
374
+ }
375
+ for (const dir of deniedDirs) {
376
+ const root = portableAbsolute(agentDir, dir)
377
+ if (portableEqual(absolute, root) || portableInside(root, absolute)) return dir
378
+ }
379
+ return undefined
380
+ }
381
+
382
+ function portableAbsolute(agentDir: string, candidate: string): string {
383
+ const normalized = candidate.replaceAll('\\', '/')
384
+ if (/^[A-Za-z]:\//.test(normalized) || normalized.startsWith('//')) return path.posix.normalize(normalized)
385
+ if (normalized.startsWith('/')) return path.posix.normalize(normalized)
386
+ return path.posix.resolve(agentDir.replaceAll('\\', '/'), normalized)
387
+ }
388
+
389
+ function portableEqual(left: string, right: string): boolean {
390
+ const windows =
391
+ /^[A-Za-z]:\//.test(left) || left.startsWith('//') || /^[A-Za-z]:\//.test(right) || right.startsWith('//')
392
+ return windows ? left.toLocaleLowerCase() === right.toLocaleLowerCase() : left === right
393
+ }
394
+
395
+ function portableInside(parent: string, child: string): boolean {
396
+ const normalizedParent = parent.endsWith('/') ? parent : `${parent}/`
397
+ return portableEqual(child.slice(0, normalizedParent.length), normalizedParent)
398
+ }
399
+
400
+ function virtualFilesystemRoot(candidate: string): string | undefined {
401
+ const normalized = candidate.replaceAll('\\', '/')
402
+ for (const root of VIRTUAL_FILESYSTEM_ROOTS) {
403
+ if (normalized === root || normalized.startsWith(`${root}/`)) return root
404
+ }
186
405
  return undefined
187
406
  }
188
407
 
408
+ function fileIdentity(candidate: string): Pick<Stats, 'dev' | 'ino' | 'nlink'> | undefined {
409
+ try {
410
+ const stats = lstatSync(candidate)
411
+ return stats.isFile() ? stats : undefined
412
+ } catch {
413
+ return undefined
414
+ }
415
+ }
416
+
417
+ type HardlinkDirectory = {
418
+ readSync(): Dirent | null
419
+ statSync(): Stats
420
+ lstatEntrySync(name: string): Stats
421
+ openChildSync(name: string): HardlinkDirectory
422
+ finishSync(): void
423
+ closeSync(): void
424
+ }
425
+
426
+ type OpenedHardlinkDirectory = { reader: HardlinkDirectory; census: Stats }
427
+
428
+ function createPathDirectoryOpener(
429
+ openDirectory: (directory: string) => Pick<Dir, 'readSync' | 'closeSync'>,
430
+ lstat: (candidate: string) => Stats,
431
+ ): (directory: string) => HardlinkDirectory {
432
+ const openPath = (directory: string): HardlinkDirectory => {
433
+ const reader = openDirectory(directory)
434
+ let finished = false
435
+ return {
436
+ readSync: () => reader.readSync(),
437
+ statSync: () => lstat(directory),
438
+ lstatEntrySync: (name) => lstat(path.join(directory, name)),
439
+ openChildSync: (name) => openPath(path.join(directory, name)),
440
+ finishSync() {
441
+ if (finished) return
442
+ finished = true
443
+ reader.closeSync()
444
+ },
445
+ closeSync() {
446
+ if (!finished) reader.closeSync()
447
+ finished = true
448
+ },
449
+ }
450
+ }
451
+ return openPath
452
+ }
453
+
454
+ function openDescriptorAnchoredDirectory(directory: string): HardlinkDirectory {
455
+ if (process.platform !== 'linux') {
456
+ throw new Error('hardlink identity traversal requires Linux descriptor anchoring')
457
+ }
458
+ const descriptor = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
459
+ const anchor = `/proc/self/fd/${descriptor}`
460
+ let reader: Dir
461
+ try {
462
+ reader = opendirSync(anchor)
463
+ } catch (error) {
464
+ closeSync(descriptor)
465
+ throw error
466
+ }
467
+ let closed = false
468
+ let finished = false
469
+ return {
470
+ readSync: () => reader.readSync(),
471
+ statSync: () => fstatSync(descriptor),
472
+ lstatEntrySync: (name) => lstatSync(path.join(anchor, name)),
473
+ openChildSync: (name) => openDescriptorAnchoredDirectory(path.join(anchor, name)),
474
+ finishSync() {
475
+ if (finished) return
476
+ finished = true
477
+ reader.closeSync()
478
+ },
479
+ closeSync() {
480
+ if (closed) return
481
+ closed = true
482
+ let closeError: unknown
483
+ if (!finished) {
484
+ try {
485
+ reader.closeSync()
486
+ } catch (error) {
487
+ closeError = error
488
+ }
489
+ }
490
+ try {
491
+ closeSync(descriptor)
492
+ } catch (error) {
493
+ closeError ??= error
494
+ }
495
+ if (closeError !== undefined) throw closeError
496
+ },
497
+ }
498
+ }
499
+
500
+ type HardlinkIdentityScannerOptions = {
501
+ agentDir: string
502
+ deniedDirs: readonly string[]
503
+ deniedFiles: readonly string[]
504
+ maxEntries: number
505
+ openDirectory(directory: string): HardlinkDirectory
506
+ lstat(candidate: string): Stats
507
+ afterEntryLstat?(candidate: string, stats: Stats): void
508
+ }
509
+
510
+ class HardlinkIdentityScanner {
511
+ private remaining: number
512
+ private readonly visibleCounts = new Map<string, number>()
513
+ private readonly deniedIdentities = new Map<string, string>()
514
+ private readonly observedEntries = new Set<string>()
515
+ private readonly openedDirectories = new Set<string>()
516
+ private visibleScanned = false
517
+ private deniedScanned = false
518
+ private visibleFailure: string | undefined
519
+ private deniedFailure: string | undefined
520
+ private deniedFilesScanned = false
521
+
522
+ constructor(private readonly options: HardlinkIdentityScannerOptions) {
523
+ this.remaining = options.maxEntries
524
+ }
525
+
526
+ check(identity: Pick<Stats, 'dev' | 'ino' | 'nlink'>): string | undefined {
527
+ const key = identityKey(identity)
528
+ this.scanDeniedFiles()
529
+ if (this.deniedFailure !== undefined) return this.deniedFailure
530
+ const deniedFile = this.deniedIdentities.get(key)
531
+ if (deniedFile !== undefined) return deniedFile
532
+
533
+ this.scanDeniedTrees()
534
+ const deniedAlias = this.deniedIdentities.get(key)
535
+ if (deniedAlias !== undefined) return deniedAlias
536
+ if (this.deniedFailure !== undefined) return this.deniedFailure
537
+
538
+ this.scanVisibleTree()
539
+ if (this.visibleFailure !== undefined) return this.visibleFailure
540
+ if ((this.visibleCounts.get(key) ?? 0) >= identity.nlink) return undefined
541
+ return 'hardlink identities could not be fully accounted within the agent tree'
542
+ }
543
+
544
+ private scanDeniedFiles(): void {
545
+ if (this.deniedFilesScanned) return
546
+ this.deniedFilesScanned = true
547
+ for (const file of this.options.deniedFiles) {
548
+ try {
549
+ const stats = this.options.lstat(file)
550
+ if (stats.isFile()) this.deniedIdentities.set(identityKey(stats), file)
551
+ } catch (error) {
552
+ if (isNotFoundError(error)) continue
553
+ this.deniedFailure = `denied-file hardlink identity could not be read: ${file}`
554
+ return
555
+ }
556
+ }
557
+ }
558
+
559
+ private scanVisibleTree(): void {
560
+ if (this.visibleScanned) return
561
+ this.visibleScanned = true
562
+ const root = realpathRealIntendedPath(this.options.agentDir)
563
+ const deniedRoots = this.options.deniedDirs.map(realpathRealIntendedPath)
564
+ const deniedFiles = new Set(this.options.deniedFiles.map(realpathRealIntendedPath))
565
+ const rootStats = this.readRootStats(root, 'visible')
566
+ if (rootStats === undefined) return
567
+ const rootDirectory = this.openVerifiedDirectory(root, rootStats, 'visible')
568
+ if (rootDirectory === undefined) return
569
+ const pending: Array<{
570
+ directory: string
571
+ reader: HardlinkDirectory
572
+ identity: Pick<Stats, 'dev' | 'ino'>
573
+ census: Stats
574
+ agentRoot: boolean
575
+ }> = [{ directory: root, ...rootDirectory, identity: rootStats, agentRoot: true }]
576
+ const opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }> = [
577
+ { directory: root, ...rootDirectory },
578
+ ]
579
+ let scanCompleted = false
580
+ try {
581
+ while (pending.length > 0) {
582
+ const current = pending.pop()
583
+ if (current === undefined) break
584
+ const completed = this.forEachEntry(current, 'visible', (entry, stats) => {
585
+ const entryPath = path.join(current.directory, entry.name)
586
+ if (current.agentRoot && HARDLINK_SCAN_EXCLUDED_AGENT_DIRS.has(entry.name)) return true
587
+ if (deniedFiles.has(entryPath) || deniedRoots.some((deniedRoot) => isPathAtOrBelow(entryPath, deniedRoot))) {
588
+ return true
589
+ }
590
+ if (stats.isDirectory()) {
591
+ const child = this.openVerifiedChild(current, entry.name, stats, 'visible')
592
+ if (child === undefined) return false
593
+ const openedChild = { directory: entryPath, ...child }
594
+ pending.push({ ...openedChild, identity: stats, agentRoot: false })
595
+ opened.push(openedChild)
596
+ } else if (stats.isFile()) {
597
+ this.recordVisibleFile(stats)
598
+ }
599
+ return true
600
+ })
601
+ if (!completed) return
602
+ }
603
+ scanCompleted = true
604
+ } finally {
605
+ this.verifyAndCloseDirectories(opened, 'visible', scanCompleted)
606
+ }
607
+ }
608
+
609
+ private scanDeniedTrees(): void {
610
+ if (this.deniedScanned) return
611
+ this.deniedScanned = true
612
+ for (const deniedDir of this.options.deniedDirs) {
613
+ let rootStats: Stats
614
+ let root: string
615
+ try {
616
+ root = realpathRealIntendedPath(deniedDir)
617
+ rootStats = this.options.lstat(root)
618
+ } catch (error) {
619
+ if (isNotFoundError(error)) continue
620
+ this.deniedFailure = `denied-directory hardlink identity could not be read: ${deniedDir}`
621
+ return
622
+ }
623
+ if (!rootStats.isDirectory()) {
624
+ this.deniedFailure = `denied-directory hardlink identity root is not a directory: ${deniedDir}`
625
+ return
626
+ }
627
+ const rootDirectory = this.openVerifiedDirectory(root, rootStats, 'denied')
628
+ if (rootDirectory === undefined) return
629
+ const pending: Array<{
630
+ directory: string
631
+ reader: HardlinkDirectory
632
+ identity: Pick<Stats, 'dev' | 'ino'>
633
+ census: Stats
634
+ }> = [{ directory: root, ...rootDirectory, identity: rootStats }]
635
+ const opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }> = [
636
+ { directory: root, ...rootDirectory },
637
+ ]
638
+ let scanCompleted = false
639
+ try {
640
+ while (pending.length > 0) {
641
+ const current = pending.pop()
642
+ if (current === undefined) break
643
+ const completed = this.forEachEntry(current, 'denied', (entry, stats) => {
644
+ const entryPath = path.join(current.directory, entry.name)
645
+ if (stats.isDirectory()) {
646
+ const child = this.openVerifiedChild(current, entry.name, stats, 'denied')
647
+ if (child === undefined) return false
648
+ const openedChild = { directory: entryPath, ...child }
649
+ pending.push({ ...openedChild, identity: stats })
650
+ opened.push(openedChild)
651
+ } else if (stats.isFile()) {
652
+ this.recordDeniedFile(stats, deniedDir)
653
+ }
654
+ return true
655
+ })
656
+ if (!completed) return
657
+ }
658
+ scanCompleted = true
659
+ } finally {
660
+ this.verifyAndCloseDirectories(opened, 'denied', scanCompleted)
661
+ }
662
+ }
663
+ }
664
+
665
+ private forEachEntry(
666
+ current: {
667
+ directory: string
668
+ reader: HardlinkDirectory
669
+ identity: Pick<Stats, 'dev' | 'ino'>
670
+ },
671
+ surface: 'visible' | 'denied',
672
+ visit: (entry: Dirent, stats: Stats) => boolean,
673
+ ): boolean {
674
+ let completed = true
675
+ try {
676
+ while (true) {
677
+ const entry = current.reader.readSync()
678
+ if (entry === null) break
679
+ if (!this.consumeEntry(surface)) {
680
+ completed = false
681
+ break
682
+ }
683
+ if (!this.claimEntryObservation(current.identity, entry.name, surface)) {
684
+ completed = false
685
+ break
686
+ }
687
+ let stats: Stats
688
+ try {
689
+ stats = current.reader.lstatEntrySync(entry.name)
690
+ this.options.afterEntryLstat?.(path.join(current.directory, entry.name), stats)
691
+ } catch {
692
+ this.recordEntryFailure(path.join(current.directory, entry.name), surface)
693
+ completed = false
694
+ break
695
+ }
696
+ if (!visit(entry, stats)) {
697
+ completed = false
698
+ break
699
+ }
700
+ try {
701
+ const confirmed = current.reader.lstatEntrySync(entry.name)
702
+ if (!sameDirectoryEntry(stats, confirmed)) {
703
+ this.recordEntryFailure(path.join(current.directory, entry.name), surface)
704
+ completed = false
705
+ break
706
+ }
707
+ } catch {
708
+ this.recordEntryFailure(path.join(current.directory, entry.name), surface)
709
+ completed = false
710
+ break
711
+ }
712
+ }
713
+ } catch {
714
+ this.recordDirectoryFailure(current.directory, surface)
715
+ completed = false
716
+ } finally {
717
+ try {
718
+ current.reader.finishSync()
719
+ } catch {
720
+ this.recordDirectoryFailure(current.directory, surface)
721
+ completed = false
722
+ }
723
+ }
724
+ return completed
725
+ }
726
+
727
+ private readRootStats(directory: string, surface: 'visible' | 'denied'): Stats | undefined {
728
+ try {
729
+ const stats = this.options.lstat(directory)
730
+ if (!stats.isDirectory()) {
731
+ this.recordDirectoryFailure(directory, surface)
732
+ return undefined
733
+ }
734
+ return stats
735
+ } catch {
736
+ this.recordDirectoryFailure(directory, surface)
737
+ return undefined
738
+ }
739
+ }
740
+
741
+ private openVerifiedDirectory(
742
+ directory: string,
743
+ expected: Pick<Stats, 'dev' | 'ino'>,
744
+ surface: 'visible' | 'denied',
745
+ ): OpenedHardlinkDirectory | undefined {
746
+ let reader: HardlinkDirectory | undefined
747
+ try {
748
+ reader = this.options.openDirectory(directory)
749
+ const opened = reader.statSync()
750
+ if (!opened.isDirectory() || opened.dev !== expected.dev || opened.ino !== expected.ino) {
751
+ this.recordDirectoryFailure(directory, surface)
752
+ reader.closeSync()
753
+ return undefined
754
+ }
755
+ if (!this.claimDirectoryIdentity(opened, directory, surface)) {
756
+ reader.closeSync()
757
+ return undefined
758
+ }
759
+ return { reader, census: opened }
760
+ } catch {
761
+ try {
762
+ reader?.closeSync()
763
+ } catch {}
764
+ this.recordDirectoryFailure(directory, surface)
765
+ return undefined
766
+ }
767
+ }
768
+
769
+ private openVerifiedChild(
770
+ parent: { directory: string; reader: HardlinkDirectory },
771
+ name: string,
772
+ expected: Pick<Stats, 'dev' | 'ino'>,
773
+ surface: 'visible' | 'denied',
774
+ ): OpenedHardlinkDirectory | undefined {
775
+ const directory = path.join(parent.directory, name)
776
+ let reader: HardlinkDirectory | undefined
777
+ try {
778
+ reader = parent.reader.openChildSync(name)
779
+ const opened = reader.statSync()
780
+ if (!opened.isDirectory() || opened.dev !== expected.dev || opened.ino !== expected.ino) {
781
+ this.recordDirectoryFailure(directory, surface)
782
+ reader.closeSync()
783
+ return undefined
784
+ }
785
+ if (!this.claimDirectoryIdentity(opened, directory, surface)) {
786
+ reader.closeSync()
787
+ return undefined
788
+ }
789
+ return { reader, census: opened }
790
+ } catch {
791
+ try {
792
+ reader?.closeSync()
793
+ } catch {}
794
+ this.recordDirectoryFailure(directory, surface)
795
+ return undefined
796
+ }
797
+ }
798
+
799
+ private verifyAndCloseDirectories(
800
+ opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }>,
801
+ surface: 'visible' | 'denied',
802
+ verify: boolean,
803
+ ): void {
804
+ for (const current of opened.reverse()) {
805
+ if (verify) {
806
+ try {
807
+ if (!sameDirectoryCensus(current.census, current.reader.statSync())) {
808
+ this.recordDirectoryFailure(current.directory, surface)
809
+ }
810
+ } catch {
811
+ this.recordDirectoryFailure(current.directory, surface)
812
+ }
813
+ }
814
+ try {
815
+ current.reader.closeSync()
816
+ } catch {
817
+ this.recordDirectoryFailure(current.directory, surface)
818
+ }
819
+ }
820
+ }
821
+
822
+ private recordDirectoryFailure(directory: string, surface: 'visible' | 'denied'): void {
823
+ const reason = `${surface} hardlink identity directory could not be read: ${directory}`
824
+ if (surface === 'visible') this.visibleFailure = reason
825
+ else this.deniedFailure = reason
826
+ }
827
+
828
+ private consumeEntry(surface: 'visible' | 'denied'): boolean {
829
+ if (this.remaining > 0) {
830
+ this.remaining -= 1
831
+ return true
832
+ }
833
+ const reason = `hardlink identity entry limit exceeded (${this.options.maxEntries})`
834
+ if (surface === 'visible') this.visibleFailure = reason
835
+ else this.deniedFailure = reason
836
+ return false
837
+ }
838
+
839
+ private recordEntryFailure(candidate: string, surface: 'visible' | 'denied'): void {
840
+ const reason = `${surface} hardlink identity could not be read: ${candidate}`
841
+ if (surface === 'visible') this.visibleFailure = reason
842
+ else this.deniedFailure = reason
843
+ }
844
+
845
+ private claimDirectoryIdentity(
846
+ identity: Pick<Stats, 'dev' | 'ino'>,
847
+ directory: string,
848
+ surface: 'visible' | 'denied',
849
+ ): boolean {
850
+ const key = identityKey(identity)
851
+ if (this.openedDirectories.has(key)) {
852
+ this.recordDirectoryFailure(directory, surface)
853
+ return false
854
+ }
855
+ this.openedDirectories.add(key)
856
+ return true
857
+ }
858
+
859
+ private claimEntryObservation(
860
+ directoryIdentity: Pick<Stats, 'dev' | 'ino'>,
861
+ name: string,
862
+ surface: 'visible' | 'denied',
863
+ ): boolean {
864
+ const key = `${identityKey(directoryIdentity)}:${JSON.stringify(name)}`
865
+ if (this.observedEntries.has(key)) {
866
+ this.recordEntryFailure(name, surface)
867
+ return false
868
+ }
869
+ this.observedEntries.add(key)
870
+ return true
871
+ }
872
+
873
+ private recordVisibleFile(stats: Stats): void {
874
+ const key = identityKey(stats)
875
+ this.visibleCounts.set(key, (this.visibleCounts.get(key) ?? 0) + 1)
876
+ }
877
+
878
+ private recordDeniedFile(stats: Stats, deniedRoot: string): void {
879
+ this.deniedIdentities.set(identityKey(stats), deniedRoot)
880
+ }
881
+ }
882
+
883
+ function identityKey(identity: Pick<Stats, 'dev' | 'ino'>): string {
884
+ return `${identity.dev}:${identity.ino}`
885
+ }
886
+
887
+ function sameDirectoryEntry(before: Stats, after: Stats): boolean {
888
+ return (
889
+ before.dev === after.dev && before.ino === after.ino && before.mode === after.mode && before.nlink === after.nlink
890
+ )
891
+ }
892
+
893
+ function sameDirectoryCensus(before: Stats, after: Stats): boolean {
894
+ return (
895
+ before.dev === after.dev &&
896
+ before.ino === after.ino &&
897
+ before.mode === after.mode &&
898
+ before.nlink === after.nlink &&
899
+ before.size === after.size &&
900
+ before.mtimeMs === after.mtimeMs &&
901
+ before.ctimeMs === after.ctimeMs
902
+ )
903
+ }
904
+
905
+ function isPathAtOrBelow(candidate: string, root: string): boolean {
906
+ return candidate === root || candidate.startsWith(`${root}${path.sep}`)
907
+ }
908
+
909
+ function isPathKey(key: string | undefined): boolean {
910
+ return key !== undefined && (PATH_KEYS.test(key) || CAMEL_PATH_KEYS.test(key))
911
+ }
912
+
913
+ function normalizeCandidate(value: string): string | undefined {
914
+ const uri = trimmedFileUri(value)
915
+ if (uri === undefined) return value
916
+ try {
917
+ const url = new URL(uri)
918
+ const pathname = decodeURIComponent(url.pathname)
919
+ if (url.hostname !== '') return `//${url.hostname}${pathname}`
920
+ if (/^\/[A-Za-z]:\//.test(pathname)) return pathname.slice(1)
921
+ // Keep synthetic POSIX container paths platform-independent. fileURLToPath
922
+ // would reinterpret file:///agent/... through the Windows host grammar.
923
+ if (pathname.startsWith('/agent/') || pathname === '/agent') return pathname
924
+ return fileURLToPath(uri)
925
+ } catch {
926
+ return value
927
+ }
928
+ }
929
+
930
+ function hasSameFileIdentity(candidate: string, deniedFile: string): boolean {
931
+ try {
932
+ const candidateStats = statSync(candidate)
933
+ const deniedStats = statSync(deniedFile)
934
+ return candidateStats.dev === deniedStats.dev && candidateStats.ino === deniedStats.ino
935
+ } catch {
936
+ return false
937
+ }
938
+ }
939
+
189
940
  // Resolves symlinks on the longest existing prefix of an absolute path, then
190
941
  // re-appends the non-existent tail. A bare realpathSync throws on a path that
191
942
  // does not exist yet (a write target, or a read of a not-yet-created file), so