fix(files): optimize exact path and directory search

[techotaku39]

Summary

• Resolve non-wildcard path queries directly within the session workspace.
• Support recursive directory searches when the query ends with / or Windows \.
• Return path-specific empty-state metadata so the Web UI can show a clearer message.
• Preserve existing filename fuzzy search and wildcard behavior.

Problem / Motivation

File preview searches previously routed path-like queries through workspace-wide ripgrep scanning. This made exact path searches unnecessarily slow and allowed unrelated matching paths to appear.

Directory queries ending with a path separator were also treated as file paths instead of scoped directory searches.

User Impact

• Exact relative and in-workspace absolute paths now use direct metadata lookup.
• Missing, out-of-workspace, or directory targets do not fall back to global filename search.
• src/foo/ and src\foo\ recursively list files below that directory.
• Filename-only searches such as git.ts retain global fuzzy matching.
• Path searches with no matches show a path-specific empty message.

Validation

• bun typecheck — passed.
• bun test hub/src/web/routes/git.test.ts — 13 passed.
• bun test cli/src/modules/common/handlers/directories.test.ts — 4 passed.
• bun run test -- src/routes/sessions/files.test.tsx from web/ — 4 passed.
• pwsh -NoProfile -File .\scripts\Invoke-HapiTaskPlaywright.ps1 -Name fix-file-search-exact-path -Suite Root -TestArgs terminal-wrap-fidelity.spec.ts — 2 passed.
• bun run build — passed.
• Full task-environment smoke validation — exact file paths, missing paths, POSIX directory separators, and Windows directory separators verified through the deployed Hub/Runner environment.
• git diff --check — passed.

Risk / Rollback

• No new dependency or database migration.
• The change is limited to file-search routing, RPC metadata typing, Web state, translations, and tests.
• Revert commit acda8257 to roll back.

Related Issues

None

AI Disclosure

Implemented and validated with OpenAI Codex (GPT-5.6).

[github-actions]

Findings

• None.

Summary

• Review mode: initial
• No issues found in the added or modified lines. Residual testing risk: the route tests mock the CLI RPC boundary and do not cover a successful Windows directory search or absolute/UNC path handling through a real Windows CLI.

Testing

• Not run (automation). Suggested coverage: a Windows integration test for successful trailing-separator directory search plus drive-qualified and UNC absolute paths.

HAPI Bot

[github-actions]

Findings

• [Major] Keep path-qualified file mentions searchable while typing — GET /files is also used by the Codex/Copilot @-mention autocomplete at web/src/router.tsx:705. The new exact-path branch intercepts every non-wildcard query containing a separator, so partial input such as @src/rou stats the literal incomplete path and returns no file suggestions until the full path is entered. Evidence: hub/src/web/routes/git.ts:434.
  Suggested fix:

  const fileQuery = /[\\/]/.test(search) && !/[*?]/.test(search)
      ? `*${search}*`
      : search
  const response = await api.searchSessionFiles(sessionId, fileQuery, 50)

Summary

Review mode: follow-up after new commits

• One Major regression found: path-qualified Codex/Copilot file mentions lose incremental autocomplete.

Testing

• Not run (automation). Add a composer autocomplete test proving a partial path such as @src/rou still returns matching files.

HAPI Bot

[github-actions]

[MAJOR] Path-qualified file mentions lose incremental suggestions

This branch handles every non-wildcard path query as exact. The same endpoint is called by Codex/Copilot mention autocomplete (web/src/router.tsx:705), so typing @src/rou now stats src/rou and returns no suggestions until a complete file path is entered.

Suggested fix:

const fileQuery = /[\\/]/.test(search) && !/[*?]/.test(search)
    ? `*${search}*`
    : search
const response = await api.searchSessionFiles(sessionId, fileQuery, 50)

Add an autocomplete regression test for a partial path.

[github-actions]

Findings

• [Major] Reject symlink/junction escapes before recursive path search — the new directory branch treats the result of statFiles as authorization and then passes that path explicitly to ripgrep. However, statFiles now derives type with stat(), which follows symlinks/junctions, while its containment check is only lexical. A workspace entry such as link -> /outside is therefore accepted as a directory, and rg --files -- link enumerates files outside the session workspace. Evidence hub/src/web/routes/git.ts:395, cli/src/modules/common/handlers/directories.ts:114.
  Suggested fix:

  const workspaceRealPath = await realpath(workingDirectory)
  const targetRealPath = await realpath(resolve(workingDirectory, path))
  if (!validatePath(targetRealPath, workspaceRealPath).valid) {
      return { path }
  }
  const stats = await stat(targetRealPath)

  Apply the same canonical containment check at the CLI ripgrep execution boundary immediately before spawning, so a symlink swap cannot bypass the earlier metadata check.

Summary

• Review mode: follow-up after new commits
• One Major security regression found. The prior incremental file-mention finding is addressed by the latest commit.

Testing

• Not run (automation). Add a regression test with an in-workspace symlink/junction targeting an outside directory and assert that a trailing-separator search returns no files and never invokes ripgrep for that target.

HAPI Bot

[github-actions]

[MAJOR] Recursive path search can escape through symlinks/junctions

This explicit search root is authorized only by the preceding statFiles result. On the CLI, that handler uses lexical validatePath() and then stat(); stat() follows an in-workspace symlink/junction to an outside directory and reports type: 'directory'. Ripgrep also follows a directory symlink when it is supplied as an explicit path, so a query such as link/ can enumerate outside filenames and return their metadata.

Suggested fix:

const workspaceRealPath = await realpath(workingDirectory)
const targetRealPath = await realpath(resolve(workingDirectory, path))
if (!validatePath(targetRealPath, workspaceRealPath).valid) {
    return { path }
}
const stats = await stat(targetRealPath)

Perform the canonical containment check again at the CLI ripgrep execution boundary immediately before spawning (or use a dedicated scoped-directory-search RPC), and add a symlink/junction escape test.

[github-actions]

Findings

• [Minor] Resolve the canonical workspace root once per stat batch - statFiles calls the new helper for every result, and the helper repeats realpath(workingDirectory) each time. A default search can return 200 paths (maximum 500), so every ordinary fuzzy search now queues hundreds of identical filesystem resolutions in addition to the required per-file lookup; this can materially increase latency on network or slow filesystems. Evidence cli/src/modules/common/handlers/directories.ts:114, cli/src/modules/common/pathSecurity.ts:46.
  Suggested fix:

  const resolvedWorkingDirectory = await realpath(workingDirectory)
  const entries = await Promise.all(data.paths.map(async (path) => {
      const resolvedTarget = await realpath(resolve(workingDirectory, path))
      if (!validatePath(resolvedTarget, resolvedWorkingDirectory).valid) {
          return { path }
      }
      const stats = await stat(resolvedTarget)
      // ...
  }))

Summary

• Review mode: follow-up after new commits
• One Minor performance regression found. The previous symlink/junction containment finding is resolved in the latest diff. Residual risk: Windows junction behavior was reviewed statically only.

Testing

• Not run (automation). At review time: integration, windows-codex-mcp, and drift-gate passed; the main test check was still pending.

HAPI Bot

[github-actions]

[MINOR] Resolve the canonical workspace root once per batch

This helper invocation repeats realpath(workingDirectory) for every path. The file-search route requests metadata for up to 200 files by default and 500 at the API limit, so the change adds the same root lookup hundreds of times per fuzzy search, on top of each target's realpath and stat. Hoist the canonical root out of the per-path callback (or pass it into the helper).

Suggested fix:

const resolvedWorkingDirectory = await realpath(workingDirectory)
const entries = await Promise.all(data.paths.map(async (path) => {
    const resolvedTarget = await realpath(resolve(workingDirectory, path))
    if (!validatePath(resolvedTarget, resolvedWorkingDirectory).valid) {
        return { path }
    }
    const stats = await stat(resolvedTarget)
    // ...
}))

[github-actions]

Findings

• No Blocker, Major, Minor, or Nit findings.

Summary

• Review mode: follow-up after new commits
• Reviewed the latest PR diff in full. The prior repeated canonical-workspace lookup finding is resolved by reusing one realpath(workingDirectory) result per stat batch.
• No inadequate coverage found for the changed exact-path, recursive-directory, symlink-containment, query-state, or empty-state behavior.

Testing

• Not run: the review security policy prohibits executing PR code. GitHub test check at posting time: SUCCESS.

HAPI Bot

[github-actions]

Findings

• No actionable issues found in the latest PR diff.

Summary

Review mode: follow-up after new commits

Reviewed all 18 changed files at d4f2d098aa5e23e24697dfb05a80bd0b023d294d, using the prior review and comparison diff as context. No findings met the reporting confidence threshold. Residual risk: platform-specific filesystem behavior remains unverified by this review.

Testing

• Not run (automation): the review security policy prohibits executing PR code. Main CI test check was still in progress when checked.
• Suggested coverage: successful Windows directory searches and allowed in-workspace symlinks through the CLI/RPC path; current directory-route tests mock RPC results.

HAPI Bot