fix(harness): resolve workspace-rooted absolute paths in ProjectAwareOverlay

[chcodex]

Fixes #2514

Problem

With projectWritable(true), ProjectAwareOverlay misroutes paths when the agent uses an absolute path under the workspace root (e.g. /your/workspace/src/Foo.java). isWorkspacePath() classified any workspace-rooted absolute path as workspace metadata purely by prefix, and read/search operations passed absolute paths straight to the overlay where the lower project filesystem (SANDBOXED) re-rooted them under the project root — so reads could not fall back to project/src/Foo.java.

Changes

ProjectAwareOverlay.java

• isWorkspacePath() now relativizes workspace-rooted absolute paths and classifies the relative part with the same WORKSPACE_PREFIXES logic used for relative paths.
• Added toWorkspaceRelativePath() (renamed from toProjectTargetPath()), which rewrites a workspace-rooted absolute path to its workspace-relative form so the lower SANDBOXED project filesystem resolves it against the project root instead of re-rooting it. Without this, ROOTED mode would re-resolve the absolute path back into the workspace because the workspace is listed in the project FS PathPolicy.
• Write routing: write, edit, delete, uploadFiles use the rewritten target for the project branch.
• Read/search routing: read, exists, downloadFiles, ls, grep, glob, move now relativize workspace-rooted absolute paths before delegating to overlay semantics (upper workspace first, lower project fallback).

ProjectAwareOverlayTest.java

• Fixed isWorkspacePath_absoluteUnderWorkspace_returnsTrue (used a non-metadata file, which is no longer a workspace path).
• Added coverage for absolute paths: source write lands in project dir, metadata write lands in workspace, read falls back to project dir, upper read precedence, exists project fallback, ls/glob/grep find project files, and move semantics match relative paths.

Verification

• mvn -pl agentscope-harness -am test -Dtest=ProjectAwareOverlayTest — 26 tests, 0 failures.
• mvn -pl agentscope-harness test — 709 tests, 0 failures.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[chcodex]

The failing test HarnessAgentSubagentStreamEventsTest.streamEvents_childAgentStartAndEndEmittedWithSource is unrelated to this PR (only ProjectAwareOverlay.java and its test are touched here).

Verified:

• ProjectAwareOverlayTest passes: 19/19.
• HarnessAgentSubagentStreamEventsTest passes locally and on 3 repeated runs (4/4 each), so the CI failure is a flaky async timing issue (child AGENT_END event missing from the collected stream), not a regression from this change.

Re-running CI to confirm.

[codecov]

Codecov Report

❌ Patch coverage is 79.41176% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../harness/agent/filesystem/ProjectAwareOverlay.java	79.41%	3 Missing and 4 partials ⚠️

📢 Thoughts on this report? Let us know!