fix(agent-runtime): stop global AGENTS.md from starving project instructions

[xpeng5278-web]

Fixes #1490

Problem

~/.pi/agent/AGENTS.md and the project instruction chain shared one 32 KiB budget in project-instructions.ts. The global file was read first, so a global file of 32 KiB or more:

• was cut at 32,768 bytes with no marker, log, or warning, and
• used the whole budget, so every project AGENTS.md / CLAUDE.md was dropped (loadProjectInstructions broke out of its loop at once).

Change

• The global file and the project chain now have independent 32 KiB budgets. An oversized global file can no longer remove project instructions.
• A truncated file keeps whole UTF-8 characters and is followed by a visible notice:
  [PI-Desktop truncated <source>: loaded the first <n> of <total> bytes; the rest of this file is not in context.]
• Project files after a truncated one are still not loaded (same as before, without the 0–3 byte leftover a UTF-8 boundary could leave).
• ProjectInstruction / the project.instructions.resolve payload shape is unchanged; the notice is part of content.

This follows Codex: ~/.codex/AGENTS.md is loaded separately from the 32 KiB project_doc_max_bytes budget its project docs share. Unlike Codex, the global file keeps its own 32 KiB cap, so the worst case is 64 KiB, the same as the SYSTEM.md / APPEND_SYSTEM.md cap. Raising or configuring the caps (option 3 in the issue) is left for a separate discussion.

Before / after (repro from the issue: 64,992-byte global file + project AGENTS.md)

• Before: global silently ends at 32,768 bytes mid "# Section 152"; project entry missing.
• After: global = first 32,768 bytes + truncation notice; project AGENTS.md loaded in full.

Specs

ADR 0037 decision 4 and consequences, docs/spec/03-runtime/02-agent-runtime.md §7.3, and E2E-AGENTS-001 in 04-e2e-test-plan.md (plus the zh-CN copies) now describe the split budgets and the notice.

Verification (base origin/main 9f6aaa2)

• New tests failed on main first (4 failed), then pass: project-instructions.test.ts 16/16
• pnpm build:js, agent-runtime and desktop typecheck, pnpm lint, check-architecture, pnpm docs:check, pnpm check:pr-base: pass
• @pi-desktop/agent-runtime tests 1300/1300; host-runtime, pi-host, shared: pass
• pnpm test:e2e:hosted-search (fixture-backed sidecar scenario for E2E-AGENTS-001): PASS, 8/8
• NOT RUN: Electron-binary E2E and the Electron-based desktop tests (no Electron binary in my Linux environment). Remaining risk is low: the change is limited to the resolver, which the unit tests and the sidecar E2E above exercise directly. A few apps/desktop node tests (chat-error-message, jev-api-key-check, plugin-websocket) fail the same way on unmodified main in that environment.

[vastsa]

Thanks for the thorough root-cause fix and regression coverage. I merged this after refreshing the branch onto the latest main; the updated CI, docs, Rust, and Electron E2E checks all passed. The separate instruction budgets and visible UTF-8-safe truncation notice address the reported failure directly.

[muzimu217]

Verified locally on macOS (worktree off current main): project-instructions tests 16/16, full agent-runtime suite 94 files / 1300 tests pass.

The design is the right decomposition of #1490's two complaints:

• Independent budgets — MAX_GLOBAL_INSTRUCTION_BYTES and MAX_PROJECT_INSTRUCTION_BYTES (32 KiB each), so an oversized ~/.pi/agent/AGENTS.md can never starve project AGENTS.md/CLAUDE.md again. loadInstructionChain no longer subtracts the global file from the project budget, and the only external caller (launch-resolver.ts) consumes entries without assuming the old combined cap — I checked for other 32 KiB combined-budget assumptions and found none.
• Truncation is never silent — limitInstruction appends a notice naming the source and the loaded/total byte counts ([PI-Desktop truncated <source>: loaded the first <n> of <total> bytes; ...]), cut on a UTF-8 character boundary, with trimEnd before the notice so the marker reads cleanly.
• The chain break after a truncated file is explicit rather than implicit budget exhaustion, and the ADR 0037 amendment justifies the 64 KiB instruction-section ceiling with the Codex precedent (global AGENTS.md outside project_doc_max_bytes) — a good external anchor for the budget split.

Tests cover the four interesting shapes: UTF-8 boundary + exact notice text, budget exhaustion stopping later project files, both-full independent budgets, and oversized-global-with-project-present. Spec + e2e plan updated in both languages, ADR amended with an Updated: line.

Nothing blocking.