fix(agent-runtime): keep project instructions for out-of-root paths

[525300887039]

Problem

In a project-bound Desktop session, a Read / Write / Edit / BrowserPreview call on an attachment or another path outside the project root resolves to an empty project instruction chain. The runtime then replaces the active chain with that result, silently removing the project's AGENTS.md from the system prompt. Passing the project root itself as a path has the same effect.

Fix

Resolve out-of-root targets and the root path itself to the project's root instruction chain. In-project paths still receive their root-to-nested chain; instruction files outside the project are never read. No-project and empty-root behavior remain unchanged, and the runtime still applies genuinely empty results rather than retaining stale nested instructions.

Add resolver tests and a Read regression that connects the real resolver to the runtime: after a nested read and an out-of-project read, the prompt keeps root rules but not the previous nested rules. Update the English and Chinese runtime specification and E2E-AGENTS-001 expectations.

Verification

Task candidate: 6ab074e9a702868efea984613852a34ebafc9f53
Base main: e23cc9362f574e3c7eeafa46416ee1b041177994

• pnpm check:pr-base — passed; current origin/main is an ancestor.
• pnpm --filter @pi-desktop/shared build — passed.
• pnpm --filter @pi-desktop/agent-runtime build and typecheck — passed.
• pnpm --filter @pi-desktop/agent-runtime test — 1,288 passed across 93 files.
• Resolver/runtime targeted tests — 296 passed across 2 files.
• pnpm test:e2e:hosted-search — 8/8 passed. The new fixture scenario runs the production instruction resolver through the real sidecar Read flow: a nested read adds nested rules; reading an attachment outside the project restores the root chain and never loads an outside AGENTS.md. It uses a deterministic local provider and temporary files; artifact SHA-256: 9b81d968e5f4177df3c75fd5f3908aab786035a2e92d2f7f02cf88f221e86eb4.
• pnpm lint, pnpm docs:check (557 pages, 85 English/Chinese pairs), and git diff --check — passed.

Limitations

• The targeted sidecar E2E does not launch the full Electron UI. No Electron, IPC, or RPC contract changes are part of this fix; the broader provider/UI journey remains marked Draft in E2E-AGENTS-001.
• No real provider credentials or paid services were used.

Fixes #968

[muzimu217]

This matches the root cause chain documented in #968 and my review there: an out-of-root tool target made loadProjectInstructions return undefined, and the runtime replaced the active chain with that empty result — silently dropping the project's AGENTS.md for the rest of the turn. Your fix implements exactly the fallback shape suggested back then (out-of-root keeps the root's own chain instead of dropping everything), and since it lands inside loadProjectInstructions it covers both call sites (the agent sidecar path and the host app path) at once.

The logic reads correctly to me: targetDirectory is either root itself (out-of-root or the root path, whose parent lies outside) or a dirname already verified within-root, so dropping the in-loop isWithinRoot check is safe — the walk can only terminate at root. Outside-instruction files are never read, in-project paths keep the root-to-nested chain, and the runtime still honors genuinely empty results rather than retaining stale nested rules.

Correction (edited): an earlier version of this comment described the empty-chain overwrite as something I had validated locally — that was overstated; the behavior is from the #968 root-cause analysis and code reading, not a fresh run on my machine. I was not able to assemble this branch's toolchain locally, so verification rests on your resolver and runtime regressions (and CI once a maintainer triggers the workflows). My contribution here is the #968 linkage and the code review above.

One observation, not a blocker: isWithinRoot resolves paths lexically, so a symlink inside the project pointing outside would still count as within-root for the instruction walk — same as before this change, and consistent with how tool-path resolution treats symlinks elsewhere. Fine to leave as-is.

[vastsa]

Thanks for the focused fix. I verified the reported failure against the current implementation: resolving an out-of-root target can yield an empty chain, which replaces the active project instructions. The root fallback closes that path without reading instruction files outside the project. On an isolated candidate based on 8906c88, the resolver/runtime tests passed (278/278) and agent-runtime typecheck passed.

I’m holding the merge because E2E-AGENTS-001 is still Draft. The hosted-search E2E is adjacent and does not exercise out-of-root instruction resolution; the Electron → main → sidecar user journey for this change remains unverified. Please add or run a relevant fixture-backed user-path E2E on a candidate containing the latest main. Thanks for documenting the behavior and its boundaries clearly.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[vastsa]

Thanks for fixing this. The linked issue is confirmed: an out-of-project target and the project root itself could resolve to a successful empty chain, which replaced the active project rules. The resolver now falls back to the root chain while continuing to read instruction files only inside that root; no-project and genuinely empty-root behavior remain unchanged.

I added fixture-backed coverage that runs the production resolver through the real sidecar Read flow. It verifies a nested read adds nested rules and a following attachment read restores the root rules without loading an outside AGENTS.md. The PR candidate integration tree matches the tested task candidate.

Validation passed: agent-runtime tests 1,288/1,288, targeted tests 296/296, pnpm test:e2e:hosted-search 8/8, package build/typecheck, lint, docs checks, and pnpm check:pr-base against e23cc93. GitHub reports no configured checks for this branch. The broader Desktop UI journey remains Draft, but this fix does not change Electron or IPC behavior and its sidecar/resolver path is now exercised. Approving and merging.