@piagent/platform 1.2.10 → 1.2.12

package/docs/distribution-standard.md

@@ -14,9 +14,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.10` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.12` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.10` |
+| Registry distribution | `npm:@piagent/platform@1.2.12` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.10` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.12` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.10
+pi install git:github.com/Vt-mmm/piagent@v1.2.12
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -65,12 +65,12 @@ Team nên install global package một lần:
 ```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.10
+npm install -g --ignore-scripts @piagent/platform@1.2.12
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.2.10` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.10`.
+`pi install git:github.com/Vt-mmm/piagent@v1.2.12` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.12`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -120,7 +120,7 @@ Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap
 ```bash
 bash scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.10 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.12 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -201,7 +201,10 @@ Máy chưa có helper dùng bootstrap all-in-one:
 npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force
 ```
 
-Máy bị khóa npm global ở `/usr/local` không cần `sudo`: updater sẽ dùng prefix user-local `~/.pi/npm-global` hoặc maintainer có thể truyền `--npm-prefix <path>`.
+Updater ưu tiên prefix đang chứa chính command `piagent-update` nếu prefix đó
+có quyền ghi, kể cả khi `npm config` trỏ sang nơi khác. Nếu cả prefix đang chạy
+và npm global mặc định đều bị khóa, updater mới dùng `~/.pi/npm-global`; không
+cần `sudo`. Maintainer vẫn có thể ép vị trí bằng `--npm-prefix <path>`.
 
 Project migration/doctor là bước kiểm tra sau global update, chỉ chạy cho repo cần xác minh:
 

package/docs/mcp-and-tools.md

@@ -453,13 +453,18 @@ Search/list channels cũng được kiểm:
 
 ## Built-in platform tools
 
+The registry below is the full capability surface. Dynamic activation exposes
+only the small subset needed now. Routine tasks use task start/progress while
+lifecycle hooks handle policy and evidence; status/evidence/gate entries are
+operator diagnostics or recovery tools.
+
 | Tool | Intent |
 |---|---|
 | `piagent_context` | Active profile/context/verify/MCP/memory overview. |
-| `piagent_exec_policy_check` | Evaluate shell command before running. |
-| `piagent_context_budget` | Check candidate context files against hard caps. |
-| `piagent_tool_policy_check` | Check tool capability registration. |
-| `piagent_task_gate_check` | Check task readiness before final DONE. |
+| `piagent_exec_policy_check` | Explain the shell-policy verdict already enforced by the hook. |
+| `piagent_context_budget` | Diagnose candidate context files against hard caps. |
+| `piagent_tool_policy_check` | Diagnose tool capability registration. |
+| `piagent_task_gate_check` | Diagnose missing final proof during recovery. |
 | `piagent_memory_status` | Project memory policy/files/rules. |
 | `piagent_memory_search` | Keyword search `.pi/memory` markdown. |
 | `piagent_memory_note` | Append explicit durable memory note. |
@@ -473,9 +478,10 @@ Search/list channels cũng được kiểm:
 | `piagent_profile_tech_apply` | Apply profile + selected role tech stack and Context7 placeholders. |
 | `piagent_profile_tech_context_record` | Record a concise Context7 evidence snapshot for a selected tech. |
 | `piagent_task_start` | Create Task Implementation Contract. |
-| `piagent_context_record` | Record context manifest for task. |
-| `piagent_verify_record` | Record verify evidence only when it matches an observed Pi bash result after task start. Passing gate also requires exact match with `task.verifyCommands`. |
-| `piagent_trace_record` | Record handoff/final trace. |
+| `piagent_task_progress` | Complete the normal review step or explicit custom/high-risk checkpoints. |
+| `piagent_context_record` | Recovery fallback for context manifest evidence. |
+| `piagent_verify_record` | Recovery fallback for an exact observed Pi bash result bound to the current tree. |
+| `piagent_trace_record` | Recovery/high-risk fallback for handoff or blocker state. |
 
 ## Core capabilities
 

package/docs/model-options.md

@@ -146,20 +146,17 @@ piagent-model-scope --preset full --default-model anthropic/claude-sonnet-5:xhig
 
 ## Benchmark rule
 
-Không claim “Pi + provider X tiết kiệm hơn provider Y” bằng cảm giác. Chạy cùng scenario rồi ghi bằng:
+Không claim “Pi + provider X tiết kiệm hơn provider Y” bằng cảm giác. Pin model
+và thinking rồi chạy automatic paired benchmark:
 
 ```bash
-piagent-usage /path/to/project
-bash scripts/quality-benchmark.sh /path/to/project --record \
-  --scenario bounded-source-fix \
-  --surface pi \
-  --result pass \
-  --tokens <total> \
-  --cost <cost> \
-  --verify "<verify-command>" \
-  --notes "provider/model/thinking=<provider/model:thinking>"
+piagent-benchmark --dry-run --model <provider/model> --thinking high
+piagent-benchmark --model <provider/model> --thinking high
 ```
 
+Runner đọc model/thinking/token/cost từ Pi session và chỉ kết luận efficiency
+khi quality/safety gates vẫn đạt. Dùng một report riêng cho mỗi model preset.
+
 So sánh tối thiểu:
 
 - Pi + model Codex ở fast/balanced/deep;

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.10
+npm install -g --ignore-scripts @piagent/platform@1.2.12
 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.10`. 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.12`. 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.10
+npm install -g --ignore-scripts @piagent/platform@1.2.12
 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.10 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.12 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -416,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:
@@ -588,19 +600,63 @@ 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
+piagent-benchmark --production --dry-run
+```
+
+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
+đạt `10/10`, workflow đạt ngưỡng của suite (`10/10` cho smoke, ít nhất `9/10`
+cho production), 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`.
+
+Lệnh không flag là smoke suite 24 session. Khi chốt thay đổi lớn về harness,
+model hoặc token policy, dùng `--production`: 18 scenario family, ba generated
+variant, hai surface, tổng 108 session; production gate chấm riêng sáu domain,
+profile/lifecycle/difficulty và cận trên 95% của paired token ratio. Seed/oracle
+động không đi vào agent workspace; root seed chỉ nằm trong private report để
+tái lập bằng `--seed`.
+
+Production runner mặc định retry tối đa hai lần, cách nhau 60 giây, chỉ khi process chết trước
+khi ghi usage. Timeout hoặc task đã tiêu token rồi fail vẫn là reliability failure thật,
+không được retry. Report hiện số retry và giữ chi tiết local trong
+`infrastructure-attempts.jsonl`. Dùng `--scenarios <id,id> --repeats 1` để debug
+rubric; subset không thể vượt production release gate.
+
+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
+```
+
+Chế độ mặc định là `controlled`: Codex chạy ephemeral, chỉ được ghi trong
+workspace benchmark, dùng `CODEX_HOME` tạm mới cho từng session/retry để 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 /path/to/piagent/scripts/quality-benchmark.sh /path/to/project --record \
+```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`;
@@ -671,6 +727,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 |
@@ -910,8 +971,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.10` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.10` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.12` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.12` | 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. |
@@ -944,7 +1005,11 @@ 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` | Chạy và chấm paired smoke benchmark 24 session. |
+| `piagent-benchmark --dry-run` | Xem execution plan, không dùng model quota. |
+| `piagent-benchmark --production --dry-run` | Xem production plan 108 session, 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
 
@@ -1018,7 +1083,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.10
+npm install -g --ignore-scripts @piagent/platform@1.2.12
 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

@@ -63,6 +63,10 @@ pi install /path/to/piagent
 - `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