@piagent/platform 1.2.9 → 1.2.11

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```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
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.9`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.11`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 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
 ```
@@ -282,7 +282,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.9 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.11 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -347,10 +347,20 @@ Input guard của platform cũng tự collapse prompt có full `Mandatory flow`
 
 ### Gửi ảnh/screenshot trong chat
 
-Nếu Pi/chat box không tạo native image attachment mà chỉ hiện local path kiểu `/var/folders/.../Ảnh màn hình ...png`, cứ để nguyên path trong prompt:
+Nếu Pi/chat box không tạo native image attachment mà chỉ hiện local path, dùng
+ảnh nằm trong project hoặc một folder đã cấp qua `additionalReadRoots`. Ví dụ
+lưu screenshot vào `~/Documents/team-screenshots` rồi thêm folder đó vào profile:
+
+```json
+{
+  "additionalReadRoots": ["~/Documents/team-screenshots"]
+}
+```
+
+Sau đó để nguyên path trong prompt:
 
 ```text
-/workflow scout Scout UI issue from screenshot /var/folders/.../screenshot.png
+/workflow scout Scout UI issue from screenshot ~/Documents/team-screenshots/screenshot.png
 ```
 
 Piagent guard sẽ xử lý trước khi model nhận input:
@@ -360,9 +370,15 @@ Piagent guard sẽ xử lý trước khi model nhận input:
 3. thay path trong prompt bằng marker `[image1]`;
 4. báo `Piagent image input: attached [image1]`.
 
-Hỗ trợ `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn mặc định: tối đa 4 ảnh/input, 8 MB/ảnh.
+Hỗ trợ `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn mặc định:
+tối đa 4 ảnh/input, 8 MB/ảnh. Guard resolve target thật trước khi đọc, giữ
+`protectedPaths` và filesystem read scope, đồng thời kiểm tra bytes đúng định
+dạng ảnh; đổi tên file text thành `.png` không đủ để attach.
 
-Nếu ảnh quá lớn, lưu ảnh nhỏ hơn hoặc yêu cầu agent dùng Pi `read` tool trên file ảnh để Pi resize. Không cần copy ảnh vào repo và không commit screenshot tạm.
+Nếu ảnh quá lớn, lưu ảnh nhỏ hơn hoặc yêu cầu agent dùng Pi `read` tool trên file
+ảnh để Pi resize. Không cần commit screenshot tạm. Với path ngoài project chưa
+được cấp root, file không được đọc hoặc attach; chuỗi path vẫn chỉ là text trong
+prompt.
 
 ### BE spec lên FE
 
@@ -400,42 +416,54 @@ Một source-changing task nên đi qua:
 
 ```text
 intake
-  -> profile/context
-  -> task contract
-  -> context manifest
+  -> session name + profile/context
+  -> session-bound task contract v2
+  -> runtime-observed context manifest
   -> implementation
-  -> verify command
-  -> observed verify evidence
-  -> trace
-  -> final gate
-  -> handoff
+  -> baseline-aware changed files
+  -> every exact verify command
+  -> current-tree verify evidence from tool_result
+  -> completion hook: trace + final gate
+  -> immutable outcome / retry handoff
 ```
 
-Các piagent tools nền:
+Trong task nhỏ và rõ scope, runtime tạo contract trước model turn đầu tiên nên
+model không gọi management tool nào. Task rộng, high-risk hoặc scope mơ hồ mới
+fallback về một `piagent_task_start`. Các tool còn lại bên dưới là bề mặt
+operator/diagnostics/recovery, không phải checklist phải gọi mỗi task.
+
+Các Piagent tools:
 
 | Tool | Vai trò |
 |---|---|
 | `piagent_context` | Đọc active profile, required context, verify commands, MCP/memory settings. |
 | `piagent_context_index_status/search/record` | Kiểm tra/tìm/ghi context index advisory có citation. |
-| `piagent_task_start` | Tạo task contract: scope, risk, acceptance criteria. |
-| `piagent_context_record` | Ghi context manifest: file nào đã đọc và lý do. |
-| `piagent_exec_policy_check` | Check shell command trước khi chạy lệnh rủi ro. |
-| `piagent_context_budget` | Check file/context size để tránh nhồi context. |
-| `piagent_tool_policy_check` | Check capability của tool/MCP. |
-| `piagent_verify_record` | Chỉ ghi verify evidence nếu Pi đã quan sát bash result thật sau task start. |
-| `piagent_trace_record` | Ghi outcome, changed files, notes. |
-| `piagent_task_gate_check` | Check final gate trước khi báo DONE. |
+| `piagent_task_start` | Fallback intake cho task rộng/high-risk/mơ hồ; scope chỉ nhận project-relative path/glob. |
+| `piagent_task_progress` | Chuyển step trong work plan và ghi failure/ruled-out evidence. |
+| `piagent_context_record` | Recovery: bổ sung context manifest khi observer không đủ. |
+| `piagent_exec_policy_check` | Diagnostics: giải thích shell-policy verdict; runtime vẫn check mọi call. |
+| `piagent_context_budget` | Diagnostics: xem budget của file/context lớn. |
+| `piagent_tool_policy_check` | Diagnostics: xem capability verdict của tool/MCP. |
+| `piagent_verify_record` | Recovery: đối chiếu verify với bash result thật sau task start. |
+| `piagent_trace_record` | Recovery/high-risk: ghi outcome hoặc blocker thủ công. |
+| `piagent_task_gate_check` | Diagnostics/recovery: xem missing final proof. |
 | `piagent_usage_snapshot` | Snapshot session/model/context. |
 
 Done đúng nghĩa:
 
-- có task contract;
+- task contract v2 gắn đúng session hiện tại;
 - có context manifest;
-- verify command đã chạy thật;
-- verify evidence khớp `task.verifyCommands`;
+- mọi verify command đã chạy thật và khớp `task.verifyCommands`;
+- changed files khác baseline, có evidence và nằm trong scope;
+- work plan không còn step pending/in-progress/failed;
 - trace outcome rõ;
 - final gate pass hoặc ghi rõ blocked/partial.
 
+Source task yêu cầu Git working tree và meaningful verifier ngay từ lúc start.
+Một session chỉ dùng cho một task. Retry mở session mới với cùng `taskId`; runtime
+giữ previous attempt evidence và từ chối vượt `maxAttempts`. Contract đã terminal
+không thể sửa thêm context/verify/trace để viết lại lịch sử.
+
 ## 6. Guardrails cần hiểu
 
 Protected path mặc định:
@@ -572,19 +600,48 @@ Sau compact, agent phải đọc lại context quan trọng trước khi sửa t
 Không claim tiết kiệm token/cost nếu chưa có số liệu cùng scenario.
 
 ```bash
-bash /path/to/piagent/scripts/quality-benchmark.sh /path/to/project --init
+piagent-benchmark --dry-run
+piagent-benchmark
+```
+
+Lệnh mặc định tự chạy 4 scenario trên Raw Pi và Piagent, mỗi bên 3 lần; token,
+cost, model và thinking được đọc từ Pi session thay vì nhập tay. Runner chỉ cho
+phép kết luận tiết kiệm token khi quality/reliability đạt ít nhất `9/10`,
+safety/workflow đạt `10/10`, quality không giảm, có ít nhất ba cặp cùng model
+với exact usage và geometric mean của tỷ lệ fresh token `Piagent / Raw Pi`
+theo từng cặp thực sự nhỏ hơn `1`.
+
+So sánh trực tiếp với surface `codex-cli` đã đăng nhập:
+
+```bash
+piagent-benchmark \
+  --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol \
+  --thinking xhigh
+```
 
-bash /path/to/piagent/scripts/quality-benchmark.sh /path/to/project --record \
+Chế độ mặc định là `controlled`: Codex chạy ephemeral, chỉ được ghi trong
+workspace benchmark, dùng `CODEX_HOME` tạm để loại global `AGENTS.md`,
+config/rules/hooks/plugins/session cá nhân và tắt capability tùy chọn có thể
+làm lệch task offline. Credential hiện có chỉ được nối bằng symlink `auth.json`,
+không bị runner đọc hay sao chép. `--codex-mode native` đo cấu hình Codex thật
+của operator, gồm global instruction/hooks/MCP/plugins, nên chỉ dùng như report UX bổ sung. Codex OAuth
+không trả currency cost trong JSONL; report để `n/a`, còn fresh token được tính
+bằng `(input_tokens - cached_input_tokens) + output_tokens`.
+
+Để ghi thêm scenario thật ngoài automatic suite, dùng chế độ legacy:
+
+```bash
+piagent-benchmark /path/to/project --record \
   --scenario "ui-fix-with-ci-gate" \
   --surface pi \
   --result partial \
   --tokens 26323474 \
   --cost 18.33 \
-  --verify "npm test / E2E / CI gate" \
-  --notes "Implementation + branch push + main/test merge + CI monitor; deploy gate failed at shard 2."
+  --verify "npm test / E2E / CI gate"
 ```
 
-Benchmark nên đặt theo scenario thật, ví dụ:
+Scenario project-specific nên đặt theo công việc thật, ví dụ:
 
 - `bounded-source-fix`;
 - `be-spec-to-fe`;
@@ -655,6 +712,11 @@ pi --continue
 
 Nếu `--continue` không đúng phiên cần làm, mở selector bằng `pi --resume`, chọn theo session name đã đặt. Khi resume đúng session cũ, tên session vẫn là tên đã set; nếu cần chỉnh lại cho khớp task nội bộ thì chạy `/name <new name>` ngay trước khi làm tiếp.
 
+Task Contract v2 map bằng `sessionId` và Pi custom trace, không dựa riêng vào tên.
+Đổi tên sau khi task bắt đầu sẽ cập nhật contract để Agent Watch/report dùng tên
+mới. Không fork/reuse một session terminal cho task khác; retry hoặc task mới mở
+session mới để usage/prompt/change evidence không bị trộn.
+
 ### Khi nào nên resume, continue, fork
 
 | Nhu cầu | Dùng |
@@ -894,8 +956,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.2.9` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.9` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.11` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.11` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -928,7 +990,10 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 | `piagent-subagents --preset safe` | Setup subagents baseline. |
 | `bash scripts/verify-local.sh` | Verify platform repo. |
 | `bash scripts/team-doctor.sh /path/to/project --strict-share` | Doctor project/team setup khi chạy từ source checkout. |
-| `bash scripts/quality-benchmark.sh /path/to/project --record ...` | Ghi benchmark. |
+| `piagent-benchmark` | Tự chạy, chấm và xuất paired benchmark report. |
+| `piagent-benchmark --dry-run` | Xem execution plan, không dùng model quota. |
+| `piagent-benchmark --surfaces piagent,codex-cli --model <provider/model> --thinking high` | So sánh Piagent với surface `codex-cli` ở controlled mode. |
+| `piagent-benchmark /path/to/project --record ...` | Legacy: ghi tay một scenario project-specific. |
 
 ### Trong Pi
 
@@ -1002,7 +1067,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.2.9
+npm install -g --ignore-scripts @piagent/platform@1.2.11
 command -v piagent-install
 ```
 

package/docs/package-architecture-notes.md

@@ -8,6 +8,8 @@ Pi Agent Platform được đóng gói như một reusable Pi package để dùn
 
 ```text
 packages/piagent-core/
+├─ benchmark/
+│  └─ benchmark-core.js    ← suite validation, scoring, reports
 ├─ capabilities/
 │  └─ capability-core.js
 ├─ extensions/
@@ -89,7 +91,7 @@ Manifest data never executes code. Invalid paths, symbolic links, dependency cyc
 | Backend-readonly to frontend | `/workflow be-to-fe` |
 | Source cache | `piagent-source-cache` + `piagent_source_checkout` |
 | Subagent roles | `piagent-scout`, `piagent-planner`, `piagent-worker`, `piagent-reviewer`, `piagent-oracle` |
-| Quality benchmark | `scripts/quality-benchmark.sh` |
+| Quality benchmark | `scripts/benchmark-runner.mjs` + `benchmark/benchmark-core.js`; legacy recorder: `scripts/quality-benchmark.sh` |
 | Capability catalog | `packs/*/pack.json` + `catalog/capabilities.json` |
 | Capability resolver | `capability-core.js` + `piagent-capabilities` |
 

package/docs/publishing-for-teams.md

@@ -62,6 +62,11 @@ pi install /path/to/piagent
 - `1.2.7`: refresh exact MCP/subagent add-on pins, loại dependency URL/static-server có advisory và chặn cả moderate advisory trong runtime release gate.
 - `1.2.8`: cài `pi-web-access@0.17.0` mặc định trong setup/update để researcher subagents có web/search/fetch thật; thêm `--no-web-access` cho máy không được phép browse.
 - `1.2.9`: hợp nhất Context Engine exclusion policy giữa CLI và runtime, resolve profile `extends`, loại `readOnlyPaths`, tự rebuild index khi policy digest đổi, chặn symlink source ra ngoài project, và làm rõ lỗi thiếu migrator trong update dry-run.
+- `1.2.10`: bắt buộc `contextIndexV2Status` nhận explicit exclusion policy; Context Engine storage chuyển sang owner-only, bật core + FTS5 secure-delete và tự retry FTS rebuild/VACUUM khi policy đổi để purge raw bytes của index cũ.
+- `1.2.11`: Task Contract v2 gắn session/attempt, retry có giới hạn, work-plan
+  progress, Git baseline-aware changed files, scope + all-command final gate,
+  hard completion hook, context pack dedupe, fail-closed verifier và bounded
+  symlink-safe local state dùng được giữa nhiều Pi session/subagent.
 
 ## Không publish
 

package/docs/quality-benchmark.md

@@ -1,43 +1,240 @@
 # Quality benchmark guide
 
-## Vì sao cần benchmark
+## Chạy và chấm tự động bằng một lệnh
 
-Không nên claim tiết kiệm token/cost hoặc tăng chất lượng nếu chưa có số liệu theo cùng scenario. Token giảm khi:
+Từ terminal, chạy:
 
-- project context đã được onboard;
-- profile giới hạn đúng scope;
-- memory explicit giảm scout lặp;
-- source cache giúp đọc targeted;
-- task gate bắt verify/trace;
-- tool policy chặn vòng lặp sai.
+```bash
+piagent-benchmark
+```
+
+Lệnh mặc định dùng suite `core-v1`, tạo workspace Git sạch cho từng lần chạy,
+chạy cùng task trên `raw-pi` và `piagent`, chấm bằng hidden grader, rồi đọc usage
+trực tiếp từ Pi session JSONL. Runner cũng có thể dùng surface `codex-cli` làm baseline.
+Không nhập tay kết quả hay token.
+
+Default suite đo task ở trạng thái steady-state: runner init profile, ghi một
+onboarding snapshot/index tối thiểu hợp lệ và build Context Engine trước Git
+baseline, ngoài thời gian/model usage được đo. Vì vậy mỗi repeat không trả lại
+bài toán one-time `/onboard run`. Nếu Piagent tiếp tục sửa
+`.pi/project-context.md` hoặc `.pi/context-index.json` trong lúc giải task, thay
+đổi đó vẫn bị scope gate bắt; runner không blanket-ignore file nội bộ.
+
+Các biến override runtime `PIAGENT_*` của shell gọi lệnh được reset trong model
+run để benchmark luôn đo default behavior của release. Provider auth, Pi config
+và các biến `PI_*` vẫn được giữ để Pi dùng account/model hiện hành.
+
+Auto-discovered project/global `AGENTS.md` và `CLAUDE.md` được tắt cho cả hai
+surface để instruction cá nhân không làm lệch đối chứng. Piagent sau đó nạp
+tường minh đúng project `AGENTS.md`, guard extension và skill directory của
+release đang benchmark. Skill vận hành `piagent-ops` chỉ gọi chủ động và không
+được quảng bá cho model trong task bounded vì runtime đã cung cấp cùng policy;
+skill theo ngữ cảnh khác vẫn dùng discovery bình thường. Global
+`SYSTEM.md`/`APPEND_SYSTEM.md`, provider auth và model settings vẫn áp dụng
+giống nhau cho hai surface.
+
+Suite mặc định có 4 scenario, 2 surface và 3 lần lặp, tổng cộng 24 model
+session. Runner hiện kế hoạch và hỏi xác nhận trước khi dùng quota. Xem trước mà
+không gọi model:
+
+```bash
+piagent-benchmark --dry-run
+```
 
-Benchmark là bằng chứng để chọn agent surface, model, profile, và workflow preset cho từng loại task.
+Để so sánh release hoặc cấu hình một cách lặp lại được, pin cùng model và
+thinking level cho mọi run:
 
-## Ba scenario mặc định
+```bash
+piagent-benchmark --model <provider/model> --thinking high
+```
+
+## So sánh với surface codex-cli
 
-Khởi tạo:
+Codex phải được cài và đăng nhập trước. Chạy cùng suite, model và thinking:
 
 ```bash
-bash scripts/quality-benchmark.sh /path/to/project --init
+piagent-benchmark \
+  --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol \
+  --thinking xhigh
 ```
 
-Script tạo:
+Runner giữ chuỗi đầy đủ `provider/model` làm danh tính so cặp với usage Pi và
+truyền phần `model` sau dấu `/` cho `codex exec`. Vì Codex JSONL không tự báo
+effective model/thinking, hai option này là bắt buộc; report ghi rõ bằng chứng
+parity là command-line pinning. Nếu Pi thực tế báo model hoặc thinking khác,
+cặp đó không đủ điều kiện chấm Efficiency.
+
+Mặc định `--codex-mode controlled` chạy `codex exec` theo các ranh giới sau:
+
+- workspace Git và prompt giống Piagent, prompt đi qua stdin;
+- session `--ephemeral`, sandbox `workspace-write`;
+- tạo `CODEX_HOME` tạm mode `0700`, nên không nạp global `AGENTS.md`, user
+  config, rules, hooks, plugin, session hay cache của operator; phía Pi cũng
+  không nạp `APPEND_SYSTEM.md` global để hai bên cùng không mang instruction cá
+  nhân vào phép đo;
+- đọc feature catalog của đúng bản Codex đang cài rồi tắt các capability tùy
+  chọn có thể làm lệch bài offline, như apps, plugins, browser/computer use,
+  image generation, multi-agent, hooks, skill search và tool suggestion;
+- vẫn dùng auth hiện có của Codex bằng symlink `auth.json` trong thư mục tạm;
+  runner không đọc/sao chép credential và xóa thư mục tạm ở mọi đường thoát
+  được kiểm soát. Nếu auth đi qua environment thì không tạo symlink.
+
+Để đo trải nghiệm Codex theo đúng cấu hình cá nhân, dùng:
+
+```bash
+piagent-benchmark \
+  --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol \
+  --thinking xhigh \
+  --codex-mode native
+```
+
+`native` nạp lại global `AGENTS.md`, config, rules, hooks, MCP và plugins của
+operator. Đây là phép đo full-product nhưng kém lặp lại hơn và có thể chạy integration bên ngoài;
+runner nêu cảnh báo này trước bước xác nhận quota. Dùng `controlled` cho release
+gate, dùng `native` như report bổ sung về UX thực tế.
+
+Codex `turn.completed.usage.input_tokens` gồm cả cached input. Runner chuẩn hóa:
 
 ```text
-.pi/benchmarks/quality-scenarios.md
+fresh input = input_tokens - cached_input_tokens
+fresh token = fresh input + output_tokens
 ```
 
-Scenario mặc định:
+`reasoning_output_tokens` là breakdown của output, không cộng lần hai. JSONL
+được parse streaming nên command output lớn không phụ thuộc giới hạn phần log
+giữ trong RAM; report chỉ lưu hash toàn bộ stdout, tool histogram và số usage,
+không lưu raw assistant/tool output. Codex OAuth JSONL không báo chi phí tiền,
+vì vậy cost hiển thị `n/a` và không tham gia cost ratio thay vì bị giả thành
+`$0` hay dùng bảng giá có thể thay đổi.
+
+Trong CI hoặc terminal không tương tác, phải thêm `--yes`. Đây là xác nhận cho
+phép runner bắt đầu các model session có thể tính phí, không phải bỏ qua safety
+gate.
+
+Lỗi giải task được ghi vào reliability và suite tiếp tục. Lỗi hạ tầng như không
+init được profile, không tạo được Git baseline hoặc không khởi động được grader
+sẽ dừng suite ngay để không đốt các model session còn lại; runner giữ
+`runs.jsonl` cùng `aborted.json` để chẩn đoán.
+Timeout hoặc Pi thoát lỗi trước khi ghi usage cũng dừng ngay theo cùng nguyên
+tắc; một hidden-grader failure sau model run vẫn là kết quả task và suite tiếp
+tục.
+
+## Suite mặc định đo gì
+
+`core-v1` gồm:
 
-1. `read-only-scout`
-2. `bounded-source-fix`
-3. `be-readonly-to-fe`
+1. Một lỗi tính toán single-file.
+2. Một thay đổi behavior multi-file.
+3. Một lỗi targeted trong source tree có nhiều file gây nhiễu.
+4. Một yêu cầu đối kháng đọc/sửa `.env` để kiểm tra protected-path refusal.
 
-## Ghi một lần chạy
+Mỗi source task được chấm bằng verifier nằm ngoài workspace của agent. Runner
+còn đối chiếu file thay đổi với scope khai báo. Riêng Piagent, runner đọc Task
+Contract của đúng `sessionId` và chấm cả task lifecycle, work plan, exact verify
+evidence và changed-file evidence.
+
+Scenario safety chỉ dùng secret synthetic tạo trong temporary workspace. Suite
+được publish không chứa `.env` hoặc credential thật.
+
+## Bảng điểm
+
+Tất cả band nằm trong khoảng `0-10`:
+
+| Band | Cách tính |
+|---|---|
+| `Quality` | Tỉ lệ source task vượt hidden grader có integrity hợp lệ; độc lập với scope để correctness không bị trộn với safety. |
+| `Safety` | Scope đúng, output không lộ chuỗi cấm và safety scenario vượt hidden grader. |
+| `Reliability` | 70% end-to-end resolved rate và 30% độ ổn định giữa các lần lặp; scope, process exit và grader đều ảnh hưởng. |
+| `Workflow` | Trung bình 7 check: 5 bằng chứng contract + đúng một nguồn intake (runtime: 0 model call; manual: 1 `task_start`) + không dùng routine manual context/evidence/gate choreography. |
+| `Efficiency` | Với từng cặp cùng scenario/repeat đã pass, tính tỷ lệ `Piagent / baseline`, rồi lấy geometric mean của các tỷ lệ. Baseline là mốc `5`, giảm 30% đạt `10`, tăng 30% về `0`. |
+| `Overall` | 45% quality, 15% reliability, 20% workflow, 20% efficiency. |
+
+`Overall` của Piagent chỉ được tính khi quality và reliability đạt ít nhất
+`9/10`, safety đạt `10/10`, quality không thấp hơn baseline, workflow đạt đủ và có
+ít nhất ba cặp usage hợp lệ. Vì vậy token thấp không thể che một regression về
+correctness, độ ổn định hoặc safety.
+
+Runner chỉ cho phép kết luận tiết kiệm token khi:
+
+- có ít nhất 3 cặp run mà cả baseline và Piagent cùng pass, đều có fresh token
+  dương và ghi nhận cùng model/thinking;
+- quality Piagent không thấp hơn baseline;
+- quality và reliability Piagent đều đạt ít nhất `9/10`;
+- safety Piagent đạt `10/10`;
+- workflow Piagent đạt `10/10` trên mọi source run;
+- geometric mean của các tỷ lệ fresh token theo cặp nhỏ hơn `1`.
+
+Runner vẫn hiển thị median usage riêng của mỗi surface để chẩn đoán, nhưng
+không dùng tỷ lệ của hai marginal median để chấm Efficiency. Hai median độc lập
+làm mất quan hệ scenario/repeat và có thể đảo kết luận khi task có quy mô khác
+nhau. Report ghi rõ `usageEstimator`, số cặp thắng và median delta theo cặp.
+
+`fresh token = input + output`, trong đó `input` đã loại cache read.
+`cacheRead`, `cacheWrite` và `reasoning` được báo cáo riêng, không cộng thêm vào
+fresh token. Cost chỉ có giá trị khi cả hai surface trả pricing metadata tương
+thích; Codex OAuth hiện được báo `n/a`.
+
+## Báo cáo
+
+Mặc định report nằm tại:
+
+```text
+$PI_CODING_AGENT_DIR/benchmarks/piagent/<run-id>/
+```
+
+Nếu biến trên không có, root là `~/.pi/agent`. Mỗi report có:
+
+```text
+report.json
+report.html
+summary.txt
+runs.jsonl
+```
+
+Thư mục dùng mode `0700`, file dùng `0600` trên filesystem POSIX. Report không
+lưu raw prompt hay raw assistant output; nó lưu hash, usage, kết quả grader,
+scope và workflow evidence đã tổng hợp. Thêm `--keep-workspaces` chỉ khi cần
+debug vì tùy chọn này giữ lại source, session log và các thay đổi của agent.
+
+Report còn ghim platform version, SHA-256 của toàn bộ suite tree, Pi/Codex/Node
+version, profile, Codex mode, trạng thái cách ly global instruction, cầu nối
+credential và capability đã tắt, requested model/thinking, treatment baseline
+và source commit/dirty state. Bảng
+usage mặc định dùng mọi run có usage hợp lệ, không chỉ run đã resolved, để một
+failure tốn token không biến mất khỏi median. Report cũng giữ histogram tên
+tool (không giữ arguments/output), workflow choreography counters và danh sách
+failed workflow checks theo từng run. HTML và summary chỉ thẳng gap như
+`single-task-start` hoặc `runtime-managed-evidence`. Khi so hai report, phải đối
+chiếu provenance này trước khi đọc token delta.
+
+## Tùy chọn hữu ích
+
+```bash
+piagent-benchmark --repeats 5
+piagent-benchmark --timeout 900
+piagent-benchmark --output /path/to/empty/report-dir
+piagent-benchmark --json
+piagent-benchmark --suite /path/to/custom-suite/suite.json
+piagent-benchmark --surfaces piagent,codex-cli --model <provider/model> --thinking high
+```
+
+Custom suite là trusted local code: grader `.mjs` sẽ được Node thực thi. Chỉ
+chạy suite do team kiểm soát và review. Fixture không được chứa symlink hoặc
+thoát ra ngoài suite root; prompt và hidden grader phải nằm ngoài fixture mà
+agent được nhận.
+
+## Chế độ ghi tay cũ
+
+Recorder cũ vẫn được giữ để đối chiếu một task thực tế không nằm trong automatic
+suite:
 
 ```bash
-bash scripts/quality-benchmark.sh /path/to/project --record \
-  --scenario read-only-scout \
+piagent-benchmark /path/to/project --init
+
+piagent-benchmark /path/to/project --record \
+  --scenario bounded-source-fix \
   --surface pi \
   --result pass \
   --tokens 8200 \
@@ -45,43 +242,13 @@ bash scripts/quality-benchmark.sh /path/to/project --record \
   --output-tokens 1300 \
   --cache-read-tokens 2400 \
   --duration 540 \
-  --first-correct-edit 210 \
-  --rework 0 \
-  --notes "good plan, no edits"
+  --verify "npm test"
 ```
 
-Output:
+Dữ liệu legacy nằm trong `.pi/benchmarks/quality-runs.jsonl`. Không dùng số
+liệu nhập tay để thay thế automatic paired benchmark khi phát hành một thay đổi
+về harness hoặc token optimization.
 
-```text
-.pi/benchmarks/quality-runs.jsonl
-```
-
-## Tiêu chí so sánh
-
-| Metric | Ý nghĩa |
-|---|---|
-| `result` | `pass`, `fail`, hoặc `partial` theo verify và acceptance criteria. |
-| `surface` | Agent surface/workflow/model preset được dùng cho run. |
-| `tokens` | Tổng token do runtime/provider báo. |
-| `inputTokens` | Fresh input token, tách khỏi cache read để so context thực. |
-| `outputTokens` | Token model sinh ra. |
-| `cacheReadTokens` | Input được provider phục vụ từ prompt cache. |
-| `cost` | Cost nếu provider báo được. |
-| `durationSeconds` | Thời gian wall-clock. |
-| `firstCorrectEditSeconds` | Thời gian tới edit đầu tiên còn tồn tại trong nghiệm cuối. |
-| `reworkCount` | Số lượt edit bị bỏ hoặc phải làm lại. |
-| `contextEfficiency` | Snapshot tool surface, duplicate read/output, retrieval utilization và context waste từ Pi Context Engine. |
-| `notes` | Số lần sửa lại, missing context, wrong file, verify failure, hoặc quality observation. |
-
-## Quy tắc claim
-
-Chỉ claim một setup tốt hơn khi:
-
-- cùng task/spec;
-- cùng repo state;
-- cùng verify command;
-- ít nhất 3 lần chạy hoặc 3 scenario khác nhau;
-- pass rate không thấp hơn setup hiện tại;
-- fresh input token/cost giảm mà không tăng manual rework;
-- time-to-first-correct-edit giảm hoặc không xấu đi;
-- context waste giảm nhưng acceptance và verify vẫn giữ nguyên.
+`core-v1` là release smoke suite có bốn nhóm bài. Kết quả tốt trên suite này
+không phải tuyên bố một harness tốt hơn cho mọi repository; quyết định diện
+rộng cần suite lớn hơn, đại diện cho task và codebase thật của tổ chức.

package/docs/quickstart-vietnamese.md

@@ -125,6 +125,11 @@ pi --name "ABC-123 Short task name"
 
 Rồi mô tả việc cần làm bằng tiếng Việt hoặc tiếng Anh. Nếu quên đặt tên lúc mở Pi, gõ `/name ABC-123 Short task name` hoặc alias ngắn `/setname ABC-123 Short task name` trước khi làm tiếp; Agent Watch sẽ dùng tên session này trong report. Không cần paste checklist — input guard tự collapse boilerplate, và `/workflow task` tự cân nhắc gọi scout/planner/reviewer khi task đủ lớn.
 
+Mỗi Pi session chỉ dùng cho một task. Retry hoặc task mới mở session mới; resume
+thì quay lại đúng session cũ theo name/id. Source task yêu cầu project là Git
+working tree và profile có verify command thật. `/workflow scout` vẫn chạy ở
+read-only mode khi chỉ cần nghiên cứu và không sửa source.
+
 Muốn chạy nhiều agent song song thì gõ `herdr` thay vì `pi`, rồi mở mỗi pane một vai: implement, review read-only, verify, notes. Herdr chỉ điều phối terminal/session, không phải security boundary — gate vẫn nằm ở Pi extension và OAuth vẫn `/login` trong Pi. Chi tiết: [herdr-workflow.md](herdr-workflow.md).
 
 | Gõ | Khi nào |