@piagent/platform 1.2.9 → 1.2.11

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.82.0`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.2.9 | Rollout guidance |
+| Surface | Status for v1.2.11 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.9` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.11` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.9
+npm install -g --ignore-scripts @piagent/platform@1.2.11
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.2.9 (helper package version)
-tag: v1.2.9
+currentRelease: v1.2.11 (helper package version)
+tag: v1.2.11
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.9
+pi install git:github.com/Vt-mmm/piagent@v1.2.11
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -104,7 +104,34 @@ piagent-update --version X.Y.Z --project /path/to/project
 
 With `--project`, the updater migrates legacy project state if needed and runs `piagent-doctor --strict-share`; use `--no-migrate` only when debugging a migration.
 
-If the machine's default npm global prefix is locked by the OS, for example `/usr/local/lib/node_modules`, the updater uses `~/.pi/npm-global` for this rollout and prints the `PATH` line to add later. Do not run project update/doctor as root, because that can leave project files owned by root. Maintainers can force a specific prefix with `--npm-prefix <path>`.
+From `v1.2.11`, project migration also previews and upgrades Task Contract v1
+state to session-bound v2. It fails before changing project files when any task
+state is unreadable, writes v2 atomically, and archives v1 only after the new
+contract exists. Opening the project with the new Pi package also performs the
+same idempotent task-state migration for resumed sessions.
+
+The `v1.2.11` migrator also upgrades the exact generated `v1.2.10` `AGENTS.md`
+and future `<!-- piagent-managed:* -->` blocks while preserving project text
+outside that block. A global-only update is still effective immediately: the
+runtime replaces the exact legacy checklist in the model's in-memory system
+prompt without editing the project file. Running `--project` makes the cleanup
+durable and lets doctor verify it.
+
+A project already onboarded does not need onboarding again after a global
+update. Its profile still extends the newly installed adapter and its capability
+lock re-pins only when the release does not widen the project's grants. Daily
+source work must start a new v2 task in a Git working tree with a configured
+verify command; read-only scout remains available without a source verifier.
+
+The updater first identifies the npm prefix that owns the active
+`piagent-update` command. If that prefix is writable, host and helper stay there
+even when `npm config get prefix` points somewhere else, such as an active
+`/opt/homebrew` install with npm configured for `/usr/local`. This prevents two
+same-version helpers with different source from shadowing one another. If both
+the active prefix and the configured global prefix are locked, the updater uses
+`~/.pi/npm-global` and prints the `PATH` line to add later. Do not run project
+update/doctor as root, because that can leave project files owned by root.
+Maintainers can force a specific prefix with `--npm-prefix <path>`.
 
 For a fresh machine that does not have `piagent-update` yet, bootstrap the same all-in-one flow without opening Pi:
 
@@ -260,6 +287,13 @@ Re-running the workflow from a branch instead skips publishing, because the publ
    bash scripts/setup.sh --global-only --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z --dry-run
    ```
 
+   Nếu release thay đổi harness, context budget, tool loading hoặc logic tính
+   token, maintainer còn phải chạy `piagent-benchmark --dry-run`, sau đó chạy
+   `piagent-benchmark --model <provider/model> --thinking <level>` trên đúng
+   release candidate và lưu report. Đây là model-quota gate có xác nhận riêng,
+   không chạy ngầm trong CI. Không claim token/cost nếu report không cho phép
+   `tokenClaimAllowed`.
+
 3. Push the release-candidate branch, open a pull request to `main`, and wait for both Ubuntu/macOS verify jobs and both CodeQL matrix jobs to pass. Record the exact PR-head commit SHA that passed; do not merge it into the Vercel production branch yet, and do not tag a later unverified edit.
 4. Create an annotated, reviewed tag on that exact verified commit and push the tag. Pushing the tag starts `publish.yml`, which runs the full verify matrix as a dependency and only then publishes, so a failure on any supported runtime stops the release before it reaches the registry:
 

package/docs/runtime-harness-standard.md

@@ -6,14 +6,15 @@ Runtime harness là “máy vận hành task” dùng chung cho nhiều project:
 
 ```text
 User request
-  -> project profile
-  -> intake/risk lane
+  -> Pi session name / task identity
+  -> resolved project profile + capability lock
+  -> intake/risk lane/change mode
   -> required context manifest
-  -> plan / task contract
+  -> session-bound task contract v2 + work-plan DAG
   -> guarded tool calls
-  -> implementation
-  -> observed verify evidence
-  -> trace / handoff
+  -> baseline-aware changed-file evidence
+  -> all-command observed verification
+  -> immutable trace / retry handoff
 ```
 
 Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecycle, policy, verification, và documentation flow.
@@ -23,10 +24,12 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
 | Module | Pi Agent Platform target | Lý do |
 |---|---|---|
 | Risk lane | `riskLane` + profile `hardGates` | Chặn auth, release, provider config, destructive action, database migration. |
-| Intake | `piagent_task_start` | Mỗi task có scope, output, acceptance criteria trước khi edit. |
+| Intake | runtime automatic intake; fallback `piagent_task_start` | Mỗi attempt có identity/session/scope/output/acceptance criteria trước model work; bounded tasks không tốn management turn. |
 | Context rules | `/onboard run`, Pi Context Engine, `.pi/project-context.md`, `requiredContext`, context manifest | Giảm token và tránh đọc toàn repo. |
-| Test matrix | `verifyCommands` + observed verify evidence | DONE phải có exact verify command thực chạy qua Pi bash hoặc `N/A` rõ lý do. |
-| Trace | `piagent_trace_record`, `.pi/piagent-state/traces.jsonl`, session entry | Có audit trail cho task. |
+| Test matrix | `verifyCommands` + observed verify evidence | Source DONE phải có mọi exact verify command thực chạy và pass qua Pi bash. |
+| Trace | completion hook, `.pi/piagent-state/traces.jsonl`, session entry | Runtime tự ghi audit trail; tool thủ công chỉ dùng recovery. |
+| Retry | `attempt`, `maxAttempts`, `previousAttempts`, failed step state | Lần sau giữ failure/ruled-out evidence và không loop vô hạn. |
+| Change truth | Git baseline/final digests + tool-result observation | Không nhận file dirty cũ hoặc claim không có evidence là thay đổi của task. |
 | Protected paths | `protectedPaths` trong profile + extension guard | Mỗi project có vùng cấm riêng. |
 | Tool registry | `mcpCapabilities` + `.mcp.json` | Không tự đoán tool/MCP. |
 | Domain contract | Project docs/profile | Chỉ project cần UX/form/data strict mới bật. |
@@ -57,6 +60,9 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
 
 ```text
 1. Intake
+   - one Pi session per task
+   - runtime auto-start for bounded source changes; manual fallback for broad/high-risk/ambiguous scope
+   - source-change or read-only
    - risk lane
    - expected output
    - acceptance criteria
@@ -64,41 +70,46 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
    - protected paths
 
 2. Context
-   - load concise piagent_context once
-   - use one token-budgeted Context Engine pack for unfamiliar/cross-module work
-   - read only targeted requiredContext
-   - check only large/unfamiliar files with piagent_context_budget
-   - record context manifest
+   - runtime injects one bounded Context Engine navigation pack when useful
+   - read only targeted current files
+   - successful reads become context manifest evidence automatically
+   - no routine context/status/index tool calls
 
 3. Plan
    - exact touchpoints
    - verify command
    - rollback/handoff if high-risk
+   - dependency DAG with one write owner
 
 4. Implement
-   - check complex/risky shell with piagent_exec_policy_check
-   - check non-piagent tools only when capability is unclear
+   - tool-call hook checks shell, capabilities and external actions automatically
    - edit only in scope
    - avoid protected paths
+   - block direct and shell writes outside scope
 
 5. Verify
-   - run exact mapped verify command
-   - store evidence
+   - run every exact mapped verify command
+   - tool-result hook records exact observed evidence after task start
+   - bind passing evidence to the current working-tree digest
+   - reconcile changed files against baseline and scope
    - if verify unavailable: not DONE
 
 6. Trace
-   - changed files
-   - commands
-   - result
-   - friction
-   - next step
-   - piagent_task_gate_check before DONE
+   - completion hook projects the final contract and runs the gate
+   - runtime persists changed files, commands, result and final trace
+   - one bounded continuation repairs missing evidence; it never loops
+   - freeze the contract after a terminal outcome
+
+7. Retry when needed
+   - start a fresh Pi session with the same taskId
+   - carry forward failedAt, reason, ruledOut, and prior outcome
+   - refuse attempts beyond the first attempt's maxAttempts
 ```
 
 | Lane | Extra context/orchestration |
 |---|---|
-| `tiny` | Core lifecycle only; parent agent, targeted reads, exact verify. |
-| `normal` | Index/memory only for unfamiliar areas; bounded read-only delegation when it saves context. |
+| `tiny` | Automatic lifecycle; parent agent, targeted reads, exact verify, no progress/evidence calls. |
+| `normal` | Automatic objective evidence plus one explicit final review step. |
 | `high-risk` | Relevant index/memory/vendor evidence plus explicit security/data/release review. |
 
 ## Maturity phases
@@ -108,20 +119,27 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
 | P0 | package core + profile + docs + protected path guard | Chỉ đủ pilot/read-only. |
 | P1 | schema + task contract + doctor + verify-local + lean prompts | Dùng được cho task nhỏ có review. |
 | P2 | extension tools for task/context/verify/trace + session entries | Dùng được cho source task có guard rõ. |
-| P3 | exec policy + context budget + tool registry + task gate + benchmark recorder | Dùng được cho guarded project workflows. |
-| P4 | stronger worktree/sandbox/team governance | Cần project-specific dry run trước khi làm default. |
+| P3 | exec policy + context budget + tool registry + task gate + automatic paired benchmark | Dùng được cho guarded project workflows. |
+| P4 | session-bound v2 state, Git change truth, retry, completion hook, bounded secure local state | Sẵn sàng rollout có kiểm soát; OS/MDM governance vẫn ngoài core. |
 
 ## Chuẩn DONE
 
 Một Pi task chỉ DONE khi có đủ:
 
 - profile loaded;
+- task is bound to the current Pi session;
 - lane classified;
 - protected paths known;
 - context manifest exists;
 - plan exists for source write;
 - changed files listed;
-- exact verify command ran and passed, hoặc explicitly `N/A` với reason;
+- every exact source verify command ran and passed;
+- declared changed files are evidenced, in scope, and different from baseline;
+- work plan has no pending/in-progress/failed step;
 - trace/handoff recorded;
 - no secrets touched;
 - no protected path writes.
+
+Read-only task có thể hoàn tất không cần source verifier nhưng phải giữ working
+tree không đổi. Source task không có Git hoặc meaningful verifier bị từ chối từ
+đầu, không đợi tới cuối mới báo thiếu evidence.

package/docs/runtime-policy-design.md

@@ -20,14 +20,14 @@ Runtime policy là lớp kiểm soát cách agent đọc context, gọi tool, s
 | Project context | `piagent_context` | Load profile, settings, policy, and local state summary. |
 | Context index | `piagent_context_index_status/search/record` | Maintain a compact advisory node/edge/citation map for profile/project/tech/task navigation. |
 | Permission profile | `piagent_permission_status` | Show active `read-only`, `workspace-write`, or `trusted-full-access` boundary. |
-| Exec policy | `piagent_exec_policy_check` | Evaluate shell command risk before execution. |
-| Context budget | `piagent_context_budget` | Enforce size/count limits for context files. |
-| Tool registry | `piagent_tool_policy_check` | Check external tool capability against profile. |
-| Task contract | `piagent_task_start` | Persist scope, acceptance criteria, risk lane, and verify plan. |
-| Context manifest | `piagent_context_record` | Record files read for a task. |
-| Verify evidence | `piagent_verify_record` | Record command result only after matching an observed Pi `bash` tool result after task start. |
-| Final gate | `piagent_task_gate_check` | Validate readiness before final handoff. |
-| Trace | `piagent_trace_record` | Persist changed files, outcome, and handoff state. |
+| Exec policy | `tool_call` hook; diagnostic `piagent_exec_policy_check` | Evaluate shell command risk before execution. |
+| Context budget | lifecycle hooks; diagnostic `piagent_context_budget` | Enforce size/count limits for context files. |
+| Tool registry | `tool_call` hook; diagnostic `piagent_tool_policy_check` | Check external tool capability against profile. |
+| Task contract | automatic intake; fallback `piagent_task_start` | Persist scope, acceptance criteria, risk lane, intake mode, and verify plan before model work. |
+| Context manifest | `tool_result` hook; recovery `piagent_context_record` | Record successful targeted reads for a task. |
+| Verify evidence | `tool_result` hook; recovery `piagent_verify_record` | Bind an exact observed Pi `bash` result to the current working tree. |
+| Final gate | `message_end` hook; diagnostic `piagent_task_gate_check` | Validate projected readiness before final handoff. |
+| Trace | completion hook; recovery `piagent_trace_record` | Persist changed files, outcome, and handoff state. |
 | Usage | `piagent_usage_snapshot` | Show session/context/token usage when available. |
 
 ## Policy precedence
@@ -78,7 +78,7 @@ The runtime separates the active autonomy profile from the project profile:
 ## Task lifecycle
 
 ```text
-intake
+runtime/manual intake
   -> profile/context
   -> task contract
   -> context manifest
@@ -90,7 +90,9 @@ intake
   -> handoff
 ```
 
-This lifecycle is intentionally explicit. It makes task quality auditable and avoids relying on a long prompt as the only control layer.
+This lifecycle is intentionally explicit in persisted state but passive in the
+routine model flow. Hooks make task quality auditable without turning the state
+machine into a long sequence of model tool calls.
 
 ## Verify evidence ledger
 
@@ -100,7 +102,10 @@ Pi `bash` results are observed through the runtime `tool_result` hook and append
 .pi/piagent-state/observed-bash.jsonl
 ```
 
-The ledger stores cwd, timestamp, status, a hash of the normalized command, and redacted command text for audit. It does not need the raw command text to validate a later `piagent_verify_record` call.
+The ledger stores cwd, timestamp, status, a hash of the normalized command, and
+redacted command text for audit. Runtime uses it directly; a recovery
+`piagent_verify_record` call can also validate against it without raw command
+storage.
 
 This file-based ledger is intentionally shared by parent and subagent processes that run in the same project cwd. If a worker subagent runs `npm test`, the parent can later record that exact verify command without depending on process-local memory.
 
@@ -129,4 +134,10 @@ Ad-hoc commands can still be recorded for traceability, but they do not satisfy
 
 ## Benchmark discipline
 
-Quality/token/cost claims must be recorded through `scripts/quality-benchmark.sh` or equivalent project evidence. The benchmark unit is a real task scenario with the same acceptance criteria and verification command.
+Release-level quality/token/cost claims must use `piagent-benchmark`: paired clean
+workspaces, the same prompt/model/thinking, hidden acceptance checks, exact Pi
+usage, scope checks and Piagent workflow evidence. A token-saving verdict also
+requires quality/reliability at least `9/10`, perfect safety/workflow,
+non-inferior quality and at least three same-model paired runs with exact usage.
+`scripts/quality-benchmark.sh` remains only as a legacy recorder for
+project-specific evidence.

package/docs/runtime-quality-baseline.md

@@ -133,7 +133,18 @@ Runtime behavior:
 - yêu cầu observed passing verify khớp exact `task.verifyCommands` khi task có source changes;
 - block `piagent_trace_record completed` nếu final gate đang enforce và proof chưa đủ.
 
-Agent vẫn phải gọi `piagent_task_gate_check` trước final handoff.
+Agent không phải gọi các tool evidence/trace/gate trong task thường. Hook
+`tool_result` tự ghi targeted reads, changed files và exact verifier; hook
+`message_end` dựng final contract, chạy gate rồi ghi terminal trace khi đủ proof.
+Các tool thủ công vẫn tồn tại cho diagnostics/recovery và high-risk/custom plan.
+
+Passing evidence còn phải khớp `workingTreeDigest` hiện tại. Bất kỳ mutation nào
+sau verify làm evidence cũ stale. Việc chạm một file rồi revert về đúng digest
+baseline chỉ được giữ trong audit history, không được tính là final source diff.
+
+Automatic/assisted plan được phép một `followUp` correction turn khi projected
+gate fail. Lượt này nhận đúng missing reasons, không tự lặp; rollback bằng
+`PIAGENT_AUTO_RECOVERY=off`.
 
 `piagent_verify_record` không còn tin `exitCode` tự khai báo. Lệnh verify phải khớp một bash tool result đã quan sát sau `task.createdAt`, và claimed `exitCode` phải khớp trạng thái `isError` của Pi. Observed result được ghi vào `.pi/piagent-state/observed-bash.jsonl` để parent/subagent process có thể share evidence trong cùng project cwd.
 
@@ -158,7 +169,7 @@ Guard state tự bảo vệ:
 - mọi text block trong `tool_result` và string leaf trong JSON-like `details` có thêm shared sensitive-data redaction; key như `password`, `token`, `credential` được dùng làm context phát hiện;
 - `npm run benchmark:redaction` gate contextual recall, benign preservation, structured objects/arrays, và large-output correctness bằng synthetic data; opaque entropy không có credential context được báo riêng và không gate release;
 - bash evidence chỉ giữ command text đã redact ở memory/disk; raw command hash vẫn dùng để exact-match verify evidence;
-- `piagent_task_start`, `piagent_verify_record`, và `tool_result` hook vẫn ghi state được qua internal extension path.
+- `piagent_task_start`, lifecycle hooks và các recovery tools vẫn ghi state được qua internal extension path.
 
 ## 5. Local verification
 
@@ -188,34 +199,37 @@ pi list --approve
 
 ## 6. Quality benchmark
 
-Script:
+Automatic paired benchmark:
 
 ```bash
-bash scripts/quality-benchmark.sh <project-path> --init
-bash scripts/quality-benchmark.sh <project-path> --record \
-  --scenario bounded-source-fix \
-  --surface pi \
-  --result pass \
-  --tokens 12345 \
-  --cost 0.12 \
-  --verify "npm test" \
-  --notes "verify passed; no manual correction"
+piagent-benchmark --dry-run
+piagent-benchmark
 ```
 
 Output:
 
 ```text
-<project>/.pi/benchmarks/quality-scenarios.md
-<project>/.pi/benchmarks/quality-runs.jsonl
+~/.pi/agent/benchmarks/piagent/<run-id>/report.json
+~/.pi/agent/benchmarks/piagent/<run-id>/report.html
+~/.pi/agent/benchmarks/piagent/<run-id>/summary.txt
+~/.pi/agent/benchmarks/piagent/<run-id>/runs.jsonl
 ```
 
-Chỉ claim chất lượng/token/cost khi cùng scenario có:
+Runner dùng clean Git fixture, hidden grader và exact Pi session usage. Piagent
+fixture được init/onboard và build context trước measured run để benchmark task
+steady-state; mọi context/index mutation sau Git baseline vẫn bị scope gate bắt.
+Report tách hidden correctness khỏi scope/reliability, hiện usage của mọi run và
+chỉ lưu histogram tên tool. Chỉ claim chất lượng/token/cost khi các paired run có:
 
 - cùng task prompt/spec;
 - cùng acceptance criteria;
 - verify command rõ;
-- token/cost/duration được ghi lại;
-- quality notes và số vòng sửa lại.
+- token/cost/duration được runtime ghi lại;
+- quality/reliability đạt ít nhất `9/10`, safety/workflow đạt `10/10`, quality
+  không giảm và ít nhất ba cặp cùng model có exact usage.
+
+`piagent-benchmark <project> --record ...` vẫn route tới recorder cũ cho task
+project-specific, nhưng không thay thế automatic release benchmark.
 
 ## Runtime policy trong profile
 

package/docs/security-threat-model.md

@@ -14,6 +14,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - protected guard, profile, settings, capability-lock, and evidence files;
 - external GitHub, HTTP, MCP, and provider resources that can be mutated;
 - release identity, installer sources, dependency pins, and package contents;
+- source bodies and retrieval metadata stored in the local Context Engine index;
 - observed verification evidence used to approve task completion.
 
 ## Trust assumptions
@@ -21,7 +22,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.9, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.11, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes
@@ -42,11 +43,15 @@ The final category is outside the containment capability of the Piagent guard. I
 | Direct or nested path-like tool input | Bounded recursive input inspection, protected-path precedence, repository boundary checks, filesystem capability scopes, and read-only profile paths | A new carrier or field name must be classified before it can be treated as controlled. Unknown/ambiguous tools fail closed where policy requires confirmation. |
 | Shell glob reaching a protected file | Glob candidates are read from the same expanded, resolved word list as every other check and matched against examples of each protected pattern, so a pattern assembled by an expansion (`{cat,.env*}`, `cat $({echo,.env*})`, `{bash,} -c 'cat .env*'`, `echo .env* | xargs cat`) is seen. This is the only check that can answer for a pattern at all, since `.env*` matches no protected literal. Whether a word is matched against filenames is decided per character, so a quoted metacharacter names a file instead (`{".env*",x}`). A redirection is read by the rule the shell uses — it opens its target only where that target expands to exactly one word, and is refused as an ambiguous redirect otherwise (`> "{.env,}"{,}`, `> {.env,other}`), while a word that can still disappear, an unset variable or a pattern under `nullglob`, leaves the count unknowable and keeps every candidate | Matching is against generated examples of each protected pattern, not against the filesystem, so a protected pattern whose examples do not represent every real name it covers can leave a matching file unnamed. Bounded expansion refuses rather than enumerates when a glob is too broad to expand. |
 | Encoding, case variation, traversal, or symbolic-link alias | Single percent decode, case-insensitive protected matching, canonical resolution for existing paths, traversal/repository escape rejection | Filesystem races and code executing outside observed tool paths require an OS boundary. |
-| Context index built with weaker or stale path rules | CLI and runtime share one resolved exclusion policy covering base policy, adapter inheritance, protected, shell-protected, and read-only paths. Content APIs require an explicit exclusion list and fail closed when it is omitted. A versioned exclusion digest forces incremental rebuild on policy drift; search/pack filter candidates again at read time, and source-shaped symlinks or canonical paths outside the project are refused. | Context Engine remains an application-level local cache. An explicit empty exclusion list is still available to intentional low-level callers; filesystem races and a process with direct OS access require an OS boundary. |
+| Local image path introduced through chat or extension input | Auto-attachment resolves the canonical target through the same project and `additionalReadRoots` grants as document intake, checks both the requested symlink location and resolved target against protected paths, preserves capability read scope, sniffs image bytes, and opens the inspected device/inode with no-follow semantics before attaching | A deliberately broad `additionalReadRoots` grant exposes every supported image under that root. Processes running as the same OS account and files modified in place remain outside this application-level boundary. |
+| Context index built with weaker or stale path rules | CLI and runtime share one resolved exclusion policy covering base policy, adapter inheritance, protected, shell-protected, and read-only paths. Every index API, including status, requires an explicit exclusion list and fails closed when it is omitted. A versioned exclusion digest forces rebuild on policy drift; search/pack filter candidates again at read time, and source-shaped symlinks or canonical paths outside the project are refused. Policy drift also rebuilds FTS, checkpoints WAL, and vacuums the database before clearing a retryable `purgePending` marker. | An explicit empty exclusion list remains available to intentional low-level callers. A policy migration may temporarily require roughly twice the database size in free space; interruption leaves the marker pending and retries on the next ensure. |
+| Source residue or cross-account access to the local context index | Context Engine directory mode is `0700`; SQLite database, WAL, and SHM are `0600`. SQLite core and FTS5 secure-delete are both enabled for ordinary updates, while policy migrations rebuild FTS and vacuum legacy free pages. | Context Engine is still an application-level cache, not an OS sandbox. A process running as the same OS account, filesystem races, backups, snapshots, or storage below the filesystem layer require separate OS/device controls. |
 | Shell glob, brace, redirection, wrapper, assignment, or command composition | Static Bash operand/action analysis with bounded expansion and regression cases; protected input is denied and external mutation is confirmation-gated. A path the analysis cannot resolve — literal text concatenated with a substitution, as in `.en$(echo v)` — is refused rather than matched on its literal half | Runtime-generated interpreter payloads cannot be fully understood by static parsing. Sensitive output redaction is a backstop, not containment. |
 | Secret returned in tool output | Shared contextual redaction across guarded text/results and synthetic recall benchmark | High-entropy, novel secret formats, or transformed output such as base64-encoded content can evade pattern-based redaction. Never intentionally print real secrets. |
 | Malicious project profile or relaxed capability lock | Trust-aware profile loading, deterministic lock digest, base-policy/source integrity, protected self-state, and fail-closed verification | An already trusted malicious repository can execute code through mechanisms outside the guard. |
 | External GitHub/HTTP/MCP/provider mutation | Direct and proxied action classification plus explicit operator confirmation, including guarded shell carriers | Provider semantics and new tool schemas can change; new integrations require policy and regression review. |
+| Repository MCP direct tool loses server attribution | Guard and doctor share the merged MCP view. Both session-level and effective per-server `directTools` selections fail closed when `toolPrefix: "none"` removes server identity; approved direct tools remain usable with `server` or `short` prefixes | A future adapter naming mode or config layer must be added to the shared MCP resolver before rollout. |
+| Read-only subagent receives mutation-capable tools | Packaged read-only roles carry explicit `read`, `grep`, `find`, `ls` allowlists; CI checks every `acceptanceRole: read-only` manifest, while all shell/edit/write capability remains on the explicit writer role | User/project overrides and a compromised external subagent runtime can replace the packaged contract; inspect effective runtime configuration when accepting third-party roles. |
 | Destructive local action | Exec-policy classification and explicit confirmation; protected paths remain denied in every permission profile. A target written as a command substitution is evaluated only where its body is one plain command with literal operands and a format this renderer reproduces exactly, and confirmed otherwise — a separator, a nested substitution, a redirection, a variable, quoting, an escape, a `printf` option, or a `printf` conversion whose result this does not reproduce (`*`, `%q`, `%b`, the numeric conversions, `%%`) all make the body unreadable here. A constant width or precision and format reuse are reproduced, so a target built from those is refused rather than confirmed, and the rendered output is read as a path candidate as well as the format's literal text and its arguments — a name assembled across a conversion (`.e%.1sv nv` is `.env`) appears in none of the pieces. Brace expansion, ranges included, is performed once per segment before anything reads it, so the rules, the legacy patterns, the nested-interpreter scan, the pipeline producers and the destructive checks all see the word list the shell would build rather than the text as typed; the expansion produces a token stream, so a command and its arguments assembled from one brace word (`{cat,.env}`) are read as both; quoting is tracked per character, so a word holding a quoted group beside an expanding one (`"{.env,}"{,}`) expands exactly as far as the shell expands it — and a target that is nothing but an unresolved parameter expansion is confirmed rather than permitted, since it can hold any value including root. The same holds for reads: a word that is only an unresolved parameter expansion is confirmed wherever the command opens files (`cat ${HOME:+.env}`), including across a pipe into an `xargs` that opens them (`echo $F \| xargs cat`), while a command substitution in that position is left to the nested scan that classifies the command inside it, and two expansions with nothing between them count as a name being assembled just as literal text beside one does. Brace expansion, parameter expansion and command substitution are performed once per segment, in the order a shell performs them, and every reader takes that one word list — so a name assembled by an expansion (`r$(printf %s m) -rf /`, `xa$(printf %s rgs)`, `$(printf %s ba)$(echo -n sh) -c '...'`) is the command it becomes rather than the text it was typed as. A name that still cannot be resolved is treated as an unknown command rather than a known-harmless one: it is enough to bring the destructive checks, the interpreter scan and the file-operand net into play, since `${X:+r}m -rf /` and `${X:+cat} ${X:+.env}` are those commands whenever the variable is set. Differential cases are generated rather than enumerated, over the cross product the defects live in — expansion form, position in the command, and reader — with each spelling placed in the command name, the operand, a flag's argument, a redirection target, a pipeline producer, an `xargs` consumer and an interpreter payload; the corpus fails if any generated spelling produced no word list, so a batch that dies early cannot pass as coverage, and it asserts in both directions so a check that answers for everything fails too | Confirmation is not isolation. A trusted process outside the observed tool path retains OS authority. A target produced by any other command is knowable only at run time, so it is gated by confirmation rather than refused. |
 | Forged verification result | Observed Bash result ledger, command hash, task-start ordering, exit-code and verify-command matching | Compromise of the trusted Pi/process environment is outside this evidence model. |
 | Mutable or substituted release source | Exact team tags, stable tag-to-commit resolution, release-commit binding in tag CI, annotated-tag requirement, add-on integrity checks, and documented tag ruleset requirement | Bootstrap helper installation still relies on GitHub tag immutability; repository administrators must prevent tag update/deletion. Signed provenance remains future work. |

package/docs/subagents-and-multiagent.md

@@ -253,7 +253,7 @@ Platform package exposes these package-level agents:
 | `piagent-scout` | bounded repo mapping | no |
 | `piagent-planner` | implementation plan + verify gates | no |
 | `piagent-worker` | single-writer implementation | yes |
-| `piagent-reviewer` | review diff/policy/tests/scope | review-first, edit only if asked |
+| `piagent-reviewer` | review diff/policy/tests/scope | no |
 | `piagent-oracle` | second opinion/risk challenge | no |
 
 Default rule: