fix(isolation): enforce copy path containment

[shixi-li]

Summary

• add one pinned-root containment boundary for isolation copies
• enforce it before directory creation, synchronous copies, and worker copies
• preserve in-root symlink behavior while failing closed on traversal and source/destination escapes
• propagate typed containment failures consistently from workers

Related issue

Closes #939

Symlink and scope policy

Source symlinks and existing destination symlinks remain allowed when their canonical targets stay inside the pinned source or destination root. Escaping source links, escaping or broken destination links, directory cycles, absolute paths, and traversal components are rejected. The supported producer remains local readdirSync(..., { withFileTypes: true }) traversal; archive or external member ingestion is out of scope.

The boundary pins root device/inode identity and revalidates canonical paths immediately before each filesystem effect. Node's path-based filesystem APIs cannot make that check/use sequence atomic against a same-user concurrent tree replacement, hard-link alias, or mount alias. Worker failure cancellation is also non-transactional: already completed safe in-root copies are not rolled back.

Testing

• 22 dedicated containment regressions pass on the exact head
• 64 related isolation and Docker-boundary tests pass
• simulated win32 separator and POSIX compatibility regressions pass
• npm run typecheck passes
• full npm run lint passes with no errors (existing warnings remain)
• changed files pass Prettier and ESLint with no errors
• 10,000-file local scale check passes in 1.104 seconds on Node 24

Broader local validation note: the default parallel npm test run exhausted this host's process-spawn capacity. A corrected single-job retry progressed until the unchanged tests/unit/attach-stdin.test.js failed to start its PTY with posix_spawnp failed; the isolated test fails at the same spawn boundary before reaching changed code. The focused, related, static, and scale gates above pass.

[greptile-apps]

Greptile Summary

The PR introduces a shared pinned-root boundary for isolation copies and applies it across traversal, directory creation, synchronous copies, and worker copies.

• Canonicalizes and pins source and destination roots by device and inode.
• Rejects traversal, escaping symlinks, broken destination links, and directory cycles.
• Propagates typed containment failures from worker threads.
• Adds focused synchronous and worker-path containment regressions.
• Updates both agent guidance files with the validation-before-effect invariant.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains, and both previously reported documentation omissions are fixed at the current head.

Important Files Changed

Filename	Overview
src/copy-containment.ts	Adds centralized relative-path validation, root identity pinning, canonical containment checks, and typed worker-error reconstruction.
src/copy-worker.ts	Routes worker copies through the shared boundary and reports the first unexpected or containment failure to the parent.
src/isolation-manager.js	Applies containment checks throughout collection, directory creation, synchronous copying, and worker orchestration.
tests/isolation-copy-containment.test.js	Covers traversal, symlink escapes and cycles, root replacement, in-root symlinks, and worker failure propagation.
CLAUDE.md	Records the shared pinned-root and immediate revalidation invariant, resolving the previous Claude-guidance finding.
AGENTS.md	Directs automated contributors to preserve the containment boundary across every isolation-copy phase, resolving the previous agent-guidance finding.

Sequence Diagram

sequenceDiagram
  participant IM as IsolationManager
  participant CB as CopyBoundary
  participant FS as Filesystem
  participant W as Copy Worker
  IM->>CB: Pin source and destination roots
  CB->>FS: Resolve canonical paths and identities
  IM->>CB: Validate traversal entries
  CB->>FS: Revalidate roots and resolve symlinks
  IM->>FS: Create validated destination directories
  alt Small copy
    IM->>CB: Resolve source and destination
    IM->>FS: copyFileSync
  else Worker copy
    IM->>W: Send files and expected boundary
    W->>CB: Re-pin and compare expected roots
    W->>CB: Resolve each source and destination
    W->>FS: copyFileSync
    W-->>IM: Result or typed containment error
  end

Loading

_{Reviews (6): Last reviewed commit: "refactor(isolation): share worker error ..." | Re-trigger Greptile}

[shixi-li]

Updated the branch and rebased it onto current main (94ef674f).

• removed the Opcore CLONE_DUPLICATE by replacing the copied try/catch test pattern with an assert.rejects predicate
• documented the shared pinned-root / validation-before-effect invariant in both CLAUDE.md and AGENTS.md
• replied to and resolved both Greptile threads

Local validation on head d709225d:

• 22 passing — tests/isolation-copy-containment.test.js
• npm run typecheck
• npm run lint (0 errors; existing warnings only)
• Prettier check for all changed files
• npm run opcore:check -- --base 94ef674f43cb03e60522e5b348f5241a3dcaabe3

The new CI run is now starting. Once it settles, could a maintainer please take a human review?

[shixi-li]

CI follow-up: the only underlying failure is invoke runs Pi in the requested worktree cwd and normalizes streamed JSONL, where its 300 ms provider timeout produced exitCode: null (295/296 provider tests passed). This PR does not touch provider code or that test; CI on the same upstream main SHA (94ef674f) is green, and npm run check:agent-cli-provider:ci passes locally. Opcore and the other executed gates passed.

Both my CLI rerun and the connected GitHub app were denied upstream Actions write permission. @mkceichelbeck, could you please rerun the failed jobs for run 31306614628 and take a human review when convenient?

[shixi-li]

Rebased this PR onto current main (c245e2f0) and resolved the copy-runtime migration conflict without restoring the removed JavaScript worker: the containment boundary now lives in src/copy-containment.ts and is built/packaged with the TypeScript worker. The follow-up at a15df4a also shares worker error inspection so the introduced-change clone gate passes.

Validated on the current head:

• npm run typecheck and the legacy runtime/lib builds
• 22 passing in tests/isolation-copy-containment.test.js
• package smoke test
• Prettier and ESLint (0 errors; repository warnings only)
• Opcore introduced-change validation, including clone.duplication

The branch is mergeable again and fresh CI is running.

[tomdps]

Reviewed against #939 and current main. The shared pinned-root boundary is enforced across traversal, directory creation, synchronous copies, and worker copies; containment violations fail closed while ordinary unreadable/broken entries retain existing skip behavior. Source/destination symlink escapes, cycles, raw traversal, root replacement, worker error propagation, and in-root compatibility are covered. I also validated a conflict-free synthetic merge with current main: 22 focused containment tests, 12 existing isolation-manager integration tests, full TypeScript build/typecheck, and package smoke all pass. The documented same-user path-based TOCTOU/hard-link/mount-alias limitation is acceptable for this defense-in-depth scope.

[github-actions]

🎉 This PR is included in version 6.39.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀