@piagent/platform 1.2.10 → 1.2.11

package/catalog/capabilities.json

@@ -12,8 +12,8 @@
       },
       "artifacts": [
         {
-          "byteSize": 1901,
-          "digest": "sha256:4cf593f5ae8d2806d5d1262ea31f7814e087b0d599e66fc064467b8c22a6a075",
+          "byteSize": 1913,
+          "digest": "sha256:fc10abbe00bb05e64e43662550b9a92e95b7441c3da000a5e2e244c5afb0eccc",
           "id": "generic",
           "kind": "adapters",
           "path": "adapters/generic/profile.json"
@@ -26,8 +26,8 @@
           "path": "evals/scenarios/capability-resolution.json"
         },
         {
-          "byteSize": 6201,
-          "digest": "sha256:35398d414c6fd57f63c81990881410ad4286074c2c63fbf53a808b6cfb27b343",
+          "byteSize": 6232,
+          "digest": "sha256:a2c44a910a440e972579c2a2ec372ee15cfb73b63b27d01c1e3a053c176d11bf",
           "id": "base-policy",
           "kind": "policies",
           "path": "packages/piagent-core/policies/base-policy.json"
@@ -54,15 +54,15 @@
           "path": "packages/piagent-core/prompts/pr.md"
         },
         {
-          "byteSize": 1749,
-          "digest": "sha256:160bf204e632293068bba0d457f0abb0c5a76af3ed452b0647746e9e7071d773",
+          "byteSize": 1314,
+          "digest": "sha256:e1e9caf68957748bebf6ac2d6294905226b298b2734434db8341b35664794388",
           "id": "review",
           "kind": "prompts",
           "path": "packages/piagent-core/prompts/review.md"
         },
         {
-          "byteSize": 3452,
-          "digest": "sha256:d06f189c7cf6484cc60d79c200e85ff60f543651264b9233cb23686145cc35d8",
+          "byteSize": 2371,
+          "digest": "sha256:bfe8374f15e06d410eec7ab2c82f85ef011fc7d514a92f23720179b497910a44",
           "id": "task",
           "kind": "prompts",
           "path": "packages/piagent-core/prompts/task.md"
@@ -75,8 +75,8 @@
           "path": "packs/engineering-base/recipes/bounded-change.json"
         },
         {
-          "byteSize": 1356,
-          "digest": "sha256:8ee63773b66386fb1e278e178842d4bd2a725b73d60e1114529df4aa3bc628f4",
+          "byteSize": 1832,
+          "digest": "sha256:a1c21e7d1c3ab12fff8516bbac2922526e35b37a6852eaa9f5a7d98a102b830e",
           "id": "piagent-ops",
           "kind": "skills",
           "path": "packages/piagent-core/skills/piagent-ops/SKILL.md"

package/docs/command-reference-vietnamese.md

@@ -468,8 +468,8 @@ Các lệnh này chạy ngoài Pi.
 | Command | Dùng khi nào |
 |---|---|
 | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `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` | Cài pinned release khi cần 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` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
 | `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
 | `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |
@@ -511,11 +511,12 @@ Các lệnh này chạy ngoài Pi.
 | `piagent-uninstall --apply` | Gỡ Pi package của platform khỏi Pi settings global. |
 | `piagent-uninstall --apply --with-addons --with-host` | Gỡ thêm pi-mcp-adapter, pi-subagents, pi-web-access và Pi host. |
 | `piagent-uninstall --apply --project /path/to/project` | Gỡ thêm state của platform trong project: profile, lock, `piagent-state/`. |
-| `piagent-benchmark ...` | Ghi quality benchmark bằng package bin. |
+| `piagent-benchmark` | Tự chạy paired Raw Pi/Piagent ở steady-state đã onboard, chấm riêng hidden grader + scope + workflow và đọc exact token/tool histogram từ session. |
+| `piagent-benchmark --dry-run` | Validate suite và xem số model session, không gọi model. |
 | `bash scripts/verify-local.sh` | Verify repo platform trước khi commit/tag. |
 | `bash scripts/verify-local.sh --offline` | Verify trong CI/máy sạch, bỏ qua local Pi model catalog. |
 | `bash scripts/setup.sh <project> ...` | Preseed setup project; không bắt buộc cho daily flow. |
-| `bash scripts/quality-benchmark.sh ...` | Ghi quality benchmark theo scenario thật. |
+| `bash scripts/quality-benchmark.sh ...` | Legacy: ghi tay benchmark cho scenario project-specific. |
 
 Trong output `piagent-install`, `currentRelease` là version của terminal helper đang chạy, không phải lời xác nhận rằng npm-global helper vừa được update. Checklist đầy đủ nằm tại [release/install policy](release-install-policy.md).
 
@@ -528,7 +529,7 @@ Khi đang develop chính repo `piagent`, có thể dùng npm scripts tương ứ
 | `npm run install-global` | `bash scripts/install-global.sh` |
 | `npm run init-project -- <project>` | `bash scripts/init-project.sh <project>` |
 | `npm run doctor -- <project> --strict-share` | `bash scripts/team-doctor.sh <project> --strict-share` |
-| `npm run benchmark -- ...` | `bash scripts/quality-benchmark.sh ...` |
+| `npm run benchmark -- ...` | `node scripts/benchmark-runner.mjs ...` |
 | `npm run usage -- <project>` | `bash scripts/pi-session-stats.sh <project>` |
 | `npm run usage -- --history <project> --days 7` | `bash scripts/pi-session-stats.sh --history <project> --days 7` |
 | `npm run models` | `bash scripts/pi-model-catalog.sh` |
@@ -570,7 +571,10 @@ export GITHUB_PERSONAL_ACCESS_TOKEN=<github-token>
 | Subagents tốn bao nhiêu? | `/subagent-cost` |
 | Có nên compact chưa? | Xem `contextUsage.percent`; trên 75% mới cân nhắc `/compact`. |
 
-Không claim tiết kiệm token/cost nếu chưa có số liệu cùng scenario. Dùng benchmark script để ghi lại.
+Không claim tiết kiệm token/cost nếu chưa có paired evidence cùng scenario. Dùng
+`piagent-benchmark`; runner chỉ cho phép verdict tiết kiệm khi
+quality/reliability đạt ít nhất `9/10`, safety/workflow đạt tuyệt đối, quality
+không giảm và có ít nhất ba cặp cùng model với exact usage.
 
 ## Source rule cho subagent/custom agent
 

package/docs/context-engine.md

@@ -12,7 +12,7 @@ task
   -> dynamic tool groups
   -> explicit path + FTS5 + symbol/import graph + git/test signals
   -> Reciprocal Rank Fusion + personalized PageRank
-  -> token-budgeted context pack
+  -> token-budgeted navigation pack or current-turn source snapshot
   -> selected parent model
   -> delta tool results + semantic compaction
   -> local telemetry for Agent Watch
@@ -23,19 +23,32 @@ task
 - Piagent tools được chia thành `governance`, `policy`, `retrieval`,
   `knowledge`, `onboarding`, và `usage`. Code retrieval không tự kéo theo
   memory, document intake, source checkout hoặc orchestration.
-- Session bắt đầu với loader nhỏ. Input hook bật nhóm cần cho task trước khi
-  system prompt được tạo.
-- `piagent_tools` chỉ mở thêm nhóm được yêu cầu; runtime guard vẫn chạy kể cả
-  khi policy tool không hiện với model.
+- Session bắt đầu không mang schema quản trị Piagent. Input hook bật thẳng nhóm
+  tối thiểu cần cho task trước khi system prompt được tạo.
+- `piagent_tools` chỉ xuất hiện khi operator yêu cầu rõ tool loader; runtime
+  guard vẫn chạy kể cả khi policy tool không hiện với model.
 - Tool order cố định để giữ prompt prefix ổn định cho provider có prompt cache.
 - Read/grep/find/ls lặp lại với cùng input và cùng output trả delta marker thay
   vì chèn lại toàn bộ kết quả.
+- Auto-context được cache theo `cwd + sessionId + promptHash`. Cùng prompt trong
+  cùng session chỉ inject một lần; session khác vẫn có pack riêng. Gọi manual
+  pack với cùng query trả reuse marker ngắn trừ khi `refresh=true`.
+- Auto pack dùng 500 token cho `tiny`, 900 cho `normal`, 1.200 cho `high-risk`;
+  manual pack mặc định 2.400 token. Model và thinking level không bị hạ.
+- Task source bounded do runtime intake quản lý có thể nhận current-turn snapshot
+  tối đa 900 token trước action đầu. Snapshot chỉ lấy file dưới source/test root,
+  đọc nội dung hiện tại sau freshness/protected-path/symlink checks và bị bỏ qua
+  khi index stale hoặc retrieval confidence thấp. Model dùng snapshot cho edit
+  đầu tiên, chỉ re-read khi thiếu region hoặc edit báo mismatch.
+- Token estimator tính ASCII và UTF-8 riêng, bảo thủ hơn cho tiếng Việt/CJK/emoji
+  để pack không vượt budget chỉ vì một ký tự dùng nhiều byte.
 - Telemetry không lưu prompt hoặc tool output thô. Nó lưu hash, kích thước, tool,
   model, thinking, active-tool count, usage, retrieval confidence và đường dẫn
   tương đối đã được guard redaction.
 
-Ba cơ chế `PIAGENT_DYNAMIC_TOOLS`, `PIAGENT_AUTO_CONTEXT` và
-`PIAGENT_CONTEXT_TELEMETRY` đều **bật mặc định** từ `v1.2.6`. Telemetry chỉ ghi
+Bốn cơ chế `PIAGENT_DYNAMIC_TOOLS`, `PIAGENT_AUTO_CONTEXT`,
+`PIAGENT_CONTEXT_TELEMETRY` và `PIAGENT_AUTO_RECOVERY` đều **bật mặc định**.
+Ba cờ đầu có từ `v1.2.6`; bounded recovery có từ `v1.2.11`. Telemetry chỉ ghi
 operational metadata/hash như mô tả dưới đây, không ghi prompt hoặc tool output
 thô. Tắt riêng từng cơ chế cho một lần chạy bằng:
 
@@ -43,6 +56,7 @@ thô. Tắt riêng từng cơ chế cho một lần chạy bằng:
 PIAGENT_DYNAMIC_TOOLS=off pi
 PIAGENT_AUTO_CONTEXT=off pi
 PIAGENT_CONTEXT_TELEMETRY=off pi
+PIAGENT_AUTO_RECOVERY=off pi
 ```
 
 ## P1: code index và retrieval
@@ -101,8 +115,10 @@ score(file) = sum(weight(source) / (60 + rank(source, file)))
 ```
 
 Context pack tách repo map và source snippets, sau đó dừng cứng tại token
-budget. Index chỉ là navigation evidence; model phải đọc file hiện tại trước
-khi edit.
+budget. Manual/read-only pack vẫn chỉ là navigation evidence và model phải đọc
+file hiện tại trước khi edit. Riêng current-turn snapshot của automatic bounded
+task đọc lại file hiện tại sau freshness check; edit exact-text sẽ fail nếu file
+đổi sau snapshot, khi đó model phải re-read thay vì đoán.
 
 Tất cả API chạm context index (`build`, `status`, `ensure`, `search`, `pack`,
 `impact`) bắt buộc caller truyền `excludePatterns` tường minh và fail-closed
@@ -146,8 +162,14 @@ Mỗi event có:
 ```
 
 Agent Watch có thể join event với Pi session JSONL bằng `sessionId` và
-`sessionName`. Không cần polling realtime; import lúc mở app hoặc lúc xuất
-report vẫn thấy đủ event đã ghi.
+`sessionName`, và với task contract bằng `taskId`/`taskRunId`. Không cần polling
+realtime; import lúc mở app hoặc lúc xuất report vẫn thấy event đã ghi.
+
+Telemetry, trace, observed-bash và capture dùng bounded JSONL owner-only, có
+cross-process rotation lock. Giới hạn mặc định: context telemetry 32 MiB, task
+trace 8 MiB, capture index 4 MiB; tool-result captures tối đa 500 file, 128 MiB
+và 30 ngày. Record đơn lẻ vượt trần được thay bằng audit marker thay vì làm file
+phình. Mọi writer từ chối `.pi` hoặc ancestor symlink ra ngoài project.
 
 Feedback không phải model học ngầm. Khi một context pack chọn file và chính
 session đó sau đó thực sự đọc hoặc sửa file, file nhận một boost nhỏ ở những

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.11` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.10` |
+| Registry distribution | `npm:@piagent/platform@1.2.11` |
 | 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.11` | 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.11
 ```
 
 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.11
 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.11` 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.11`.
 
 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.11 \
   --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.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.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.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.10
+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.10 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.11 \
   --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,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
+```
 
-bash /path/to/piagent/scripts/quality-benchmark.sh /path/to/project --record \
+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
+```
+
+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`;
@@ -671,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 |
@@ -910,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.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.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. |
@@ -944,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
 
@@ -1018,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.10
+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

@@ -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