@piagent/platform 1.5.5 → 1.6.1

package/docs/auto-delegation-policy.md

@@ -1,7 +1,7 @@
 # Solo-first orchestration policy
 <!-- language: vi; english-index: docs-site/content/en/workflows.html -->
 
-Mục tiêu: user không phải nhớ `/run`, `/parallel`, `/chain` cho workflow hằng ngày, nhưng platform cũng không tự biến mọi task thành swarm tốn token. Khi anh gõ `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, hoặc `/workflow review`, parent agent đọc `piagent_orchestration_policy`, giữ mặc định **solo-first**, rồi chỉ dùng subagents nếu việc đó giúp giảm nhiễu context, tăng tốc read-heavy work, hoặc tăng chất lượng review. Alias cũ như `/task` vẫn giữ cùng policy.
+Mục tiêu: parent model tự làm trọn task với đầy đủ năng lực. Helper không còn là phase mặc định để scout/plan/review; nó chỉ là một tối ưu token ngoại lệ. Piagent chỉ cho tối đa **một helper read-only, context fresh** khi runtime chứng minh có ít nhất hai lane độc lập và tổng token dự kiến sau handoff/merge giảm tối thiểu **30%**. Alias cũ như `/task` giữ cùng policy.
 
 Kiểm tra policy hiện tại trong Pi:
 
@@ -15,11 +15,11 @@ Slash command này chỉ hiện status compact, không gửi follow-up cho model
 
 Subagent không nên hiểu là “luôn tự sinh khi task lớn”. Hành vi đúng là:
 
-1. Parent agent đánh giá task có phần việc độc lập không.
-2. Nếu có và `pi-subagents`/subagent tool khả dụng, parent có thể tự spawn subagent.
-3. Nếu không có tool/package, parent tiếp tục single-agent và ghi rõ `Subagents: unavailable/not used`.
-4. User vẫn có thể gọi command trực tiếp khi muốn ép orchestration cụ thể.
-5. Parallel read-only có thể dùng cho scout/review; parallel writers không phải default và cần approval + isolation.
+1. Parent làm trực tiếp nếu runtime chưa có bằng chứng định lượng.
+2. Helper chỉ đủ điều kiện khi có ít nhất hai workstream độc lập, helper không chờ output tiếp theo của parent, context transfer không quá 2.048 token, không inherit transcript, và tổng dự kiến tiết kiệm ít nhất 30%.
+3. Mỗi task run chỉ có một lần thử helper. Lỗi runtime/scope xác định không được relaunch.
+4. Helper luôn read-only; worker/writer helper bị tắt. Parent giữ toàn bộ mutation và quyết định.
+5. UI/telemetry phải ghi `dispatch` hoặc `skip`, reason codes, và projected net saving; không có số liệu thì `skip`.
 
 Nếu bundled skill `pi-subagents` có trong skill list của parent, parent nên dùng skill đó cho orchestration patterns thay vì tự đoán syntax. Skill này là parent-only; child subagents không nhận nó.
 
@@ -28,43 +28,45 @@ Nếu bundled skill `pi-subagents` có trong skill list của parent, parent nê
 | Setting | Default |
 |---|---|
 | Mode | `solo-first` |
-| Max concurrent subagents | `2` |
+| Helper budget | `1` read-only total; concurrent `1`; retry `0`; worker `0` |
+| Minimum projected net saving | `30%` |
+| Context transfer | fresh/isolated; tối đa `2.048` token; không inherit parent history |
 | Review lenses | `correctness`, `tests`, `scope` |
 | Field Guide | `.pi/memory/MEMORY.md`, advisory, explicit-write only |
-| Writer policy | Một writer cho một write set. |
+| Writer policy | Parent model là writer duy nhất. |
 
 Model role guidance:
 
 - planner: model mạnh nhất hợp lý cho decomposition, architecture, risk, acceptance criteria;
-- worker: model nhanh/ổn định cho bounded implementation đã có plan;
-- reviewer: model/thinking decorrelated với worker khi review quan trọng;
-- watchdog/oracle: model mạnh chỉ cho final risk/security/release/high-impact.
+- worker: disabled; parent model implement trực tiếp;
+- reviewer/oracle: role read-only ngoại lệ; không tự chạy chỉ vì review quan trọng;
+- builtin agents và watchdog: disabled trong baseline Piagent.
 
 ## Khi nào parent nên tự spawn
 
-Parent nên tự spawn subagents khi có ít nhất một điều kiện:
+Chỉ spawn khi **đồng thời** thỏa tất cả điều kiện:
 
-- cần scout nhiều vùng source độc lập;
-- cần map BE contract read-only trong khi FE implementation là write target;
-- cần đọc external source docs/repo và repo hiện tại song song;
-- cần external research có nguồn dẫn, và `pi-web-access`/web tools đang available;
-- cần tạo context handoff trước task lớn (`context-builder`);
-- cần review nhiều góc độc lập: correctness, tests, security, scope drift;
-- task có từ 3 touchpoint trở lên;
-- task medium/high-risk nhưng có phần audit read-only trước khi edit;
-- context có nguy cơ phình to nếu parent tự đọc toàn bộ log/spec/source.
+- runtime xác định ít nhất hai workstream thật sự độc lập;
+- helper có thể hoàn tất mà không chờ output tiếp theo của parent;
+- helper chỉ cần read/grep/find/ls;
+- request dùng fresh isolated context, seed không quá 2.048 token;
+- estimate gồm parent + helper + transfer + merge thấp hơn solo ít nhất 30%;
+- task run chưa từng launch helper và không retry một lỗi runtime/scope xác định.
 
 ## Khi nào không nên tự spawn
 
 Không spawn nếu:
 
 - task nhỏ, một file, verify đơn giản;
+- không có runtime estimate hoặc projected saving dưới 30%;
 - requirement chưa rõ và cần hỏi user trước;
 - chỉ có một write target nhỏ;
 - subagent tool/package chưa available;
 - repo dirty hoặc write set có nguy cơ overlap mà chưa phân tách được;
 - task high-risk cần human gate trước khi edit;
-- muốn spawn nhiều writer song song nhưng không có worktree isolation/approval.
+- cần bất kỳ mutation nào từ child;
+- muốn planner/reviewer chỉ để “tăng chất lượng” nhưng không giảm tổng token;
+- đã có một helper attempt, kể cả attempt failed/orphaned.
 
 ## Default agent mapping
 
@@ -72,13 +74,10 @@ Không spawn nếu:
 |---|---|---|
 | Map unfamiliar repo/module/spec | `piagent-scout` | read-only |
 | Build implementation plan | `piagent-planner` | read-only |
-| Implement approved bounded change | `piagent-worker` | single writer |
 | Review current diff | `piagent-reviewer` | review-first |
 | Challenge architecture/risk | `piagent-oracle` | read-only |
-| External docs/web research | builtin `researcher` | read-only; requires web tools |
-| Large context handoff | builtin `context-builder` or `piagent-scout` | writes handoff artifact only |
 
-Default rule: parallel read-only is OK; parallel writers are not default.
+Default rule: parent direct. Tối đa một role read-only ở bảng trên; không parallel và không worker.
 
 ## Workflow policy
 
@@ -89,42 +88,26 @@ Parent should:
 1. load piagent context/profile/memory/project context;
 2. load `piagent_orchestration_policy`;
 3. create a compact task tree/workPlan and review lenses in `piagent_task_start`;
-4. decide whether subagents are useful enough to justify extra token cost;
-5. if useful, spawn bounded read-only scout/planner/reviewer before or after implementation;
-6. keep implementation single-writer unless user explicitly approves otherwise;
+4. runtime tính projected total tokens; thiếu estimate hoặc saving dưới 30% thì skip;
+5. nếu đủ điều kiện, spawn đúng một helper fresh/read-only;
+6. parent tự implement và review;
 7. summarize subagent outputs into task contract/context manifest/final response.
 
 ### `/workflow be-to-fe`
 
-Recommended auto-delegation:
-
-- `piagent-scout`: map backend contract read-only;
-- `piagent-scout`: map frontend touchpoints read-only;
-- `piagent-planner`: produce FE implementation plan;
-- parent or `piagent-worker`: implement FE only;
-- `piagent-reviewer`: review diff and verify coverage.
+Parent map BE contract, map FE touchpoints, implement và review. Runtime chỉ được chọn **một** trong hai lane mapping cho `piagent-scout` nếu estimate toàn task đạt ngưỡng 30%; lane còn lại vẫn do parent làm.
 
 ### `/workflow platform-improve`
 
-Recommended auto-delegation:
-
-- `piagent-scout`: inspect current platform source/docs;
-- builtin `researcher`: inspect official docs/web evidence when `pi-web-access` is installed;
-- builtin `context-builder`: create handoff context/meta-prompt for large platform changes;
-- `piagent-scout`: inspect official docs/external source repo targeted evidence;
-- `piagent-planner`: produce implementation matrix;
-- parent or `piagent-worker`: implement bounded changes;
-- `piagent-reviewer`: review docs/runtime behavior.
+Parent inspect, research, plan, implement và review. Một fresh read-only helper chỉ được map một lane độc lập khi runtime estimate tổng token đạt ngưỡng; không dùng chain scout → planner → worker → reviewer.
 
 ### `/review`
 
-Recommended auto-delegation:
+Parent-owned review:
 
 - select explicit review lenses first;
-- optional parallel `piagent-reviewer` for correctness;
-- optional parallel `piagent-reviewer` for tests/verification;
-- optional parallel `piagent-reviewer` for scope/protected-path drift;
-- optional `piagent-oracle` for architecture/high-risk concerns.
+- parent cover các lens trong cùng context;
+- chỉ dùng một fresh read-only reviewer/oracle nếu nó thay thế một lane độc lập và estimate tiết kiệm ít nhất 30%.
 
 If the user explicitly asks for a review loop, use `/review-loop` or an equivalent parent-controlled loop with max rounds. Do not blindly apply all reviewer suggestions.
 
@@ -136,17 +119,7 @@ Single scout:
 Use piagent-scout to map the target module read-only. Return files, ownership, invariants, and likely change points only.
 ```
 
-Parallel scout:
-
-```text
-Run parallel piagent-scout agents: one maps backend contract read-only, one maps frontend touchpoints read-only. Wait for both and summarize the contract-to-FE map.
-```
-
-Parallel review:
-
-```text
-Run parallel piagent-reviewer agents for correctness, tests/verification, and scope/protected-path drift. Wait for all and summarize findings by severity.
-```
+The parent must attach runtime evidence equivalent to: `independent lanes >= 2`, `context=fresh`, `inheritedParentTokens=0`, and `projectedNetSaving>=30%`. Without it, do not call the helper tool.
 
 Tool syntax fallback:
 
@@ -159,7 +132,7 @@ subagent({ agent: "piagent-scout", task: "Map target area read-only. Return conc
 Final response should include one line:
 
 ```text
-Subagents: <not used / unavailable / used: piagent-scout, piagent-reviewer>
+Helper: <skip reason=<code> projectedSaving=<unknown|N%> / dispatch role=<role> projectedSaving=N%>
 ```
 
 If not used, give the reason briefly:
@@ -172,19 +145,11 @@ If not used, give the reason briefly:
 
 ## Token rule
 
-Subagents can reduce parent context pollution, but total token usage can increase because each child does its own model/tool work. Use them for parallelizable read-heavy work and review quality, not as a blanket token-saving switch.
+Projected saving phải so sánh **tổng parent + child + handoff + merge**, không so child với một đoạn parent context riêng lẻ. Ngưỡng 30% là dispatch gate, không phải bằng chứng rằng Piagent đã rẻ hơn `codex-cli` 30–40%; kết luận đó chỉ được đưa ra từ paired benchmark Piagent/`codex-cli` cùng model, thinking, task và success gate.
 
-## Package shortcuts worth using
+## Package shortcuts
 
-| Shortcut | Use when |
-|---|---|
-| `/parallel-review` | Need distinct review angles; add `autofix` only when user permits fixes. |
-| `/review-loop` | Need worker/reviewer/fix loop until clean or capped. |
-| `/parallel-research` | Need external evidence + local code context. |
-| `/parallel-context-build` | Need context/meta-prompt handoff before a large plan. |
-| `/parallel-handoff-plan` | Need research + context-builder + implementation handoff. |
-| `/gather-context-and-clarify` | Need scout/research first, then ask only meaningful questions. |
-| `/parallel-cleanup` | Need post-implementation cleanup review. |
+Các shortcut `/parallel-*`, worker/reviewer loop và grant-spawn-budget thuộc package upstream nhưng không nằm trong Piagent governed default. Absolute Piagent budget vẫn là một read-only helper total; daily workflow không dùng các shortcut này.
 
 See `docs/subagent-orchestration-capabilities.md`.
 

package/docs/command-reference-vietnamese.md

@@ -325,7 +325,7 @@ Các command này thuộc Pi core hoặc package Pi chính. Tên/availability c
 
 Các command này đến từ package `pi-subagents`. Tên hơi “package terminology”, nên bảng dưới dịch ra nghĩa thực tế.
 
-Quan trọng: daily flow không bắt anh phải nhớ các lệnh này. Các workflow `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, `/workflow review` dùng solo-first orchestration: parent agent lập task tree/review lenses trước, rồi chỉ spawn subagent khi task có phần việc độc lập và đáng token. Slash command dưới đây dùng khi anh muốn ép orchestration cụ thể hoặc debug.
+Quan trọng: Piagent mặc định parent-direct và helpers `off`. Các lệnh dưới đây phần lớn là capability upstream để inspect/debug. Piagent config chặn builtin, worker, parallel, nested và retry; operator chỉ có thể opt-in một helper read-only context fresh, và runtime vẫn yêu cầu hai lane độc lập cùng projected net saving từ 30%.
 
 | Command | Dịch nghĩa dễ hiểu | Dùng khi nào | Kết quả mong đợi |
 |---|---|---|---|
@@ -342,16 +342,10 @@ Quan trọng: daily flow không bắt anh phải nhớ các lệnh này. Các wo
 | `/subagents-generate-profiles <provider>` | Sinh quota/quality profiles | Khi muốn profile model theo quota/chất lượng. | Tạo profile cho provider. |
 | `/subagents-check-profile <name>` | Check profile | Khi profile/model có thể stale. | Re-check model availability/auth. |
 | `/run <agent> "<task>"` | Chạy 1 subagent | Khi cần 1 scout/reviewer/planner riêng context. | Child session chạy task rồi trả summary về parent. |
-| `/run <agent> "<task>" --bg` | Chạy background | Khi muốn agent chạy nền rồi mình xem sau. | Dùng `/subagents-fleet` để follow. |
-| `/run <agent> "<task>" --fork` | Chạy từ forked session | Khi child cần inherited conversation/context branch. | Fork thật từ parent leaf; dùng fresh nếu không cần history. |
-| `/parallel ...` | Chạy nhiều agent song song | Khi các việc độc lập, nhất là read-only review/scout/test analysis. | Parent đợi hoặc gom kết quả tùy flow. |
-| `/chain ...` | Chạy tuần tự | Khi output agent trước là input agent sau. | Dùng `{previous}` để truyền summary trước đó. |
-| `/run-chain <name>` | Chạy chain đã lưu | Khi có workflow lặp lại. | Package chạy recipe chain đã định nghĩa. |
-| `/parallel-review` | Review song song | Khi cần nhiều reviewer theo góc nhìn độc lập. | Có thể thêm `autofix` nếu đã cho phép sửa. |
-| `/review-loop` | Worker/reviewer/fix loop | Khi muốn review đến khi sạch hoặc hết vòng. | Nên set max rounds, thường dùng tối đa 3 vòng. |
-| `/parallel-research` | Research song song | Khi cần external evidence + local scout. | Builtin `researcher` cần `pi-web-access`. |
-| `/parallel-context-build` | Build context handoff | Khi task lớn cần `context.md`/meta-prompt trước planning. | Dùng `context-builder` agents. |
-| `/parallel-handoff-plan` | Research + context + plan | Khi muốn handoff plan đầy đủ cho implementation. | Tốt cho architecture hoặc platform change lớn. |
+| `/run <agent> "<task>" --bg` | Capability upstream | Piagent không bật async mặc định. | Không dùng trong governed default. |
+| `/run <agent> "<task>" --fork` | Capability upstream | Inherit history trái policy context fresh. | Piagent từ chối. |
+| `/parallel ...`, `/chain ...`, `/run-chain ...` | Capability upstream | Nhân số turn/context. | Piagent config giới hạn 1 và không dispatch parallel/chain. |
+| `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan` | Capability upstream | Tạo nhiều helper hoặc retry loop. | Piagent config không cho dùng. |
 | `/gather-context-and-clarify` | Scout rồi hỏi đúng câu | Khi requirement chưa rõ nhưng cần đọc trước. | Trả clarification questions có evidence. |
 | `/parallel-cleanup` | Cleanup review sau implement | Khi muốn rà cleanup đáng làm. | Có thể thêm `autofix`. |
 
@@ -364,7 +358,7 @@ Glossary:
 | `fleet` | “Đội” child sessions đang chạy hoặc vừa chạy xong. |
 | `scout` | Agent đọc/map code read-only. |
 | `planner` | Agent lập plan và verify gate, không sửa code. |
-| `worker` | Agent sửa code theo plan. |
+| `worker` | Metadata compatibility; bị Piagent disable. |
 | `reviewer` | Agent review diff/test/scope. |
 | `oracle` | Agent phản biện/risk challenge. |
 | `researcher` | Builtin agent nghiên cứu web/docs có nguồn; cần `pi-web-access`. |
@@ -372,7 +366,7 @@ Glossary:
 | `chain` | Làm A rồi dùng kết quả A để làm B. |
 | `parallel` | Làm nhiều nhánh độc lập cùng lúc. |
 | `bg` | Background run, không block parent ngay. |
-| `fork` | Child bắt đầu từ nhánh session hiện tại thay vì context fresh. |
+| `fork` | Capability upstream; Piagent cấm vì helper phải context fresh. |
 | `watchdog` | Opt-in adversarial reviewer ở cuối turn; không phải `reviewer` subagent. |
 | `worktree` | Checkout riêng cho parallel writers để tránh đè file nhau. |
 
@@ -382,7 +376,7 @@ Piagent subagents:
 |---|---|---|
 | `piagent-scout` | Map repo/module/spec trước khi sửa. | Read-only. |
 | `piagent-planner` | Lập implementation plan. | Read-only. |
-| `piagent-worker` | Implement task đã rõ/đã approve. | Có thể write trong scope. |
+| `piagent-worker` | Compatibility metadata; bị Piagent config disable. | Không dispatch. |
 | `piagent-reviewer` | Review diff, verify coverage, scope drift. | Review-first. |
 | `piagent-oracle` | Challenge architecture/risk. | Read-only. |
 
@@ -416,24 +410,21 @@ Một số option hữu ích:
 ```text
 /run reviewer[model=anthropic/claude-sonnet-5:high] "Review this diff"
 /run scout[output=context.md,outputMode=file-only] "Map auth flow"
-/chain scout[output=context.md,as=context] "Scan" -> planner[reads=context.md] "Plan from {outputs.context}"
 subagent({ action: "status", view: "fleet" })
 subagent({ action: "status", id: "<run-id>", view: "transcript", lines: 120 })
-subagent({ action: "grant-spawn-budget", additional: 10 })
 ```
 
 `outputMode=file-only` hữu ích khi child tạo report dài: parent chỉ nhận đường dẫn file, không bị nhồi full report vào context.
 
 ## Khi nào nên spawn subagent
 
-Theo provider docs, subagent tốt nhất cho việc độc lập và bounded:
+Trong Piagent, helper chỉ được dispatch khi tất cả điều kiện sau đúng:
 
-- codebase exploration;
-- map contract/API/schema;
-- đọc docs/spec dài rồi tóm tắt;
-- review correctness/security/tests/scope drift theo nhiều góc nhìn;
-- chạy/test analysis không cần sửa cùng file;
-- compress context trước khi parent/worker implement.
+- operator đã bật `PIAGENT_HELPERS_MODE=on`;
+- runtime chứng minh ít nhất hai lane độc lập;
+- helper không cần chờ output tiếp theo của parent;
+- handoff context fresh, không inherit history, tối đa 2.048 token;
+- projected tổng token sau cả handoff/merge tiết kiệm ít nhất 30%.
 
 Không nên spawn bừa khi:
 
@@ -446,11 +437,11 @@ Không nên spawn bừa khi:
 Default của platform là an toàn:
 
 - `maxSubagentDepth: 1`: parent spawn child, child không fan-out tiếp.
-- `parallel.concurrency: 3`: không mở quá nhiều child cùng lúc.
+- `parallel.concurrency: 1`: compatibility ceiling, không chạy song song.
 - `asyncByDefault: false`: không tự chạy background nếu anh không yêu cầu.
-- Một `piagent-worker` tại một thời điểm; parallel chủ yếu dùng cho scout/reviewer.
+- Tổng 1 read-only helper, 0 worker, 0 retry.
 
-Nếu anh không gọi gì thêm, `/workflow task` vẫn chạy solo-first và chỉ tự dùng subagent theo `docs/auto-delegation-policy.md` khi có scout/planning/review độc lập đáng làm. Alias `/task` giữ cùng policy.
+Nếu anh không bật gì thêm, `/workflow task` chạy parent-direct và không tạo model turn phụ. Alias `/task` giữ cùng policy.
 
 ## Prompt mẫu cho bài toán thật
 
@@ -480,7 +471,7 @@ Use piagent-reviewer before final.
 Nếu muốn parallel read-only:
 
 ```text
-Run parallel piagent-scout agents: one maps backend contract read-only, one maps frontend route/state usage. Wait for both, then plan FE implementation.
+Keep the parent direct. If helper mode was explicitly enabled and the runtime proves at least 30% net saving, run one fresh read-only piagent-scout for the single highest-value independent lane.
 ```
 
 ### Review trước khi ship
@@ -502,8 +493,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.84.1` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.5.5` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.5.5` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.6.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.6.1` | 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. |
@@ -547,17 +538,18 @@ 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` | Chạy smoke suite `core-v1`: paired Raw Pi/Piagent, 24 session, hidden grader + scope + workflow + exact usage. |
+| `piagent-benchmark` | Chạy smoke suite `core-v1`: paired Piagent/controlled `codex-cli` bằng Luna/medium, 24 session, hidden grader + scope + workflow + exact usage. |
 | `piagent-benchmark --dry-run` | Validate suite và xem số model session, không gọi model. |
-| `npm run benchmark:deep -- --dry-run` | Validate `deep-logic-v1`: 6 family difficulty large x 2 repeat x Piagent/`codex-cli` = 24 session, pin Luna/medium và chưa dùng quota. |
-| `npm run benchmark:deep` | Chạy paired deep-logic benchmark Luna/medium cho event/state, scheduler, policy, context graph, stream recovery và transactional config. |
+| `npm run benchmark:deep -- --dry-run` | Validate `deep-logic-v1`: 7 family difficulty large × 3 repeat × Piagent/`codex-cli` = 42 session, khóa Luna/medium và chưa dùng quota. |
+| `npm run benchmark:deep` | Chạy paired deep-logic benchmark Luna/medium cho event/state, scheduler, policy, context graph, stream recovery, transactional config và temporal usage billing chính xác. |
 | `piagent-benchmark --production --dry-run` | Xem ma trận production 18 family x 3 variant x 2 surface = 108 session, chưa dùng quota. |
-| `piagent-benchmark --production --surfaces piagent,codex-cli --model <provider/model> --thinking high --piagent-treatment candidate` | Chạy production release gate đa domain/profile/lifecycle với controlled Codex, treatment Piagent đã pin, paired outcome và 95% token-ratio confidence. |
+| `piagent-benchmark --production --preflight-only` | Trước lượt trả phí, tự chạy/cache ba lane provider-free cùng exact source/tree/config/runner binding; lần đầu có long-horizon tối thiểu 30 phút, 0 provider call/model token. |
+| `piagent-benchmark --production --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-luna --thinking medium --piagent-treatment candidate` | Chạy production release gate đa domain/profile/lifecycle với controlled Codex; S12/S36/S72 chặn pooled fresh ratio >1.10, observed family >1.25 hoặc subagent vượt 1 attempt/5% traffic; S108 dùng upper-95 <=0.60. |
 | `piagent-benchmark --piagent-treatment release-defaults\|local-safe\|candidate\|feature-off ...` | Pin treatment Piagent; chỉ surface `piagent` nhận feature env, manifest/resume/replay/report giữ nguyên treatment. |
 | `piagent-benchmark --codex-mode native ...` | Đo UX Codex theo cấu hình operator; protocol gate fail closed nên report không được claim tiết kiệm token. |
 | `piagent-benchmark --production --seed <value> ...` | Tái lập đúng generated variant của một production report riêng tư. |
 | `piagent-benchmark --production --scenarios <id,id> --repeats 1 ...` | Chẩn đoán family/rubric đã chọn; không đủ điều kiện nhận production verdict. |
-| `piagent-benchmark --production --infrastructure-retries 2 ...` | Retry đúng lỗi process chết trước usage; timeout/task failure không retry và vẫn chấm reliability. |
+| `piagent-benchmark --production --infrastructure-retries 2 ...` | Diagnostic recovery run; retry chỉ áp lỗi process chết trước usage, được report đầy đủ và làm production claim fail. |
 | `piagent-benchmark --production --retry-delay 60 ...` | Đặt backoff trước infrastructure retry; production mặc định 60 giây. |
 | `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. |
@@ -576,7 +568,7 @@ Khi đang develop chính repo `piagent`, có thể dùng npm scripts tương ứ
 | `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 -- ...` | `node scripts/benchmark-runner.mjs ...` |
-| `npm run benchmark:webui-parity` | Gate provider-free cho 10 workflow, 32 Project Controls, contract/security, Chromium flow và ba cỡ performance stress. |
+| `npm run benchmark:webui-parity` | Gate provider-free cho 10 workflow, 32 Project Controls, contract/security, bảy deterministic UI-stability suite, Chromium flow và ba cỡ performance stress. |
 | `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` |

package/docs/context-engine.md

@@ -21,9 +21,11 @@ task
 
 ## P0: runtime context controls
 
-- 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.
+- Piagent tools được chia thành `governance`, `policy`, `retrieval`, `source`,
+  `knowledge`, `onboarding`, và `usage`. URL GitHub/GitLab/Bitbucket do operator
+  cung cấp chỉ bật schema `source`; code retrieval không tự kéo theo memory,
+  document intake hoặc orchestration. Checkout được cấp quyền đọc đúng session
+  qua `read`/`grep`/`find`/`ls`, còn shared cache không mở cho shell hay mutation.
 - 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
@@ -46,6 +48,10 @@ task
 - 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.
+- Mỗi telemetry row có provenance envelope do writer đóng sau payload; event
+  không thể ghi đè schema/provenance. Nếu source snapshot phải redact, receipt
+  chỉ giữ `sanitizedContentDigest` và `fileContentHash` trên nội dung đã sanitize;
+  raw-content digest không được tính hoặc lưu.
 
 Bốn cơ chế `PIAGENT_DYNAMIC_TOOLS`, `PIAGENT_AUTO_CONTEXT`,
 `PIAGENT_CONTEXT_TELEMETRY` và `PIAGENT_AUTO_RECOVERY` đều **bật mặc định**.
@@ -180,7 +186,9 @@ không bị trừ điểm. `contextSelections`, `contextSelectionsUsed` và
 ranking. Runtime chỉ đọc phần đuôi telemetry có giới hạn khi tính report hoặc
 feedback, nên lịch sử dài không làm chậm từng prompt theo thời gian.
 
-`contextWasteScore` nằm trong khoảng `0..100`, thấp hơn là tốt hơn:
+Khi toàn bộ evidence lane đầy đủ, `contextWasteScore` nằm trong khoảng `0..100`,
+thấp hơn là tốt hơn. Nếu coverage chưa đầy đủ, score chính là `null` và chỉ
+`contextWasteScoreEstimate` được giữ như chẩn đoán partial:
 
 ```text
 30% duplicate read rate

package/docs/context-window-policy.md

@@ -36,7 +36,11 @@ Trước task lớn/risk cao trong Pi TUI:
 /context compact
 ```
 
-Nếu recommendation là `fresh-session`, dùng `/fresh task`, `/fresh scout`, hoặc `/fresh be-to-fe` thay vì tiếp tục nhồi context vào session hiện tại.
+Với task/phase tiếp theo trong cùng phiên hiển thị, runtime tự tạo working set
+gọn trước mỗi provider call; người dùng không phải mở session mới chỉ để đổi từ
+scout sang plan, implement hay verify. `/fresh task`, `/fresh scout` và
+`/fresh be-to-fe` vẫn là đường phục hồi tường minh khi preflight xác định input
+quá lớn hoặc working set không thể rút gọn an toàn.
 
 ## Context manifest
 
@@ -68,6 +72,38 @@ Pi settings template dùng:
 }
 ```
 
+Host compaction trên chỉ là overflow guard. Adaptive context governor của
+Piagent chạy sớm hơn và không đổi model/thinking:
+
+- phát hiện ranh giới task/phase, context pressure, số tool round, read-output
+  cũ và kết quả lặp;
+- giữ yêu cầu/quyết định gần nhất của người dùng, Task Contract, acceptance
+  criteria, changed files, verifier và lỗi chưa giải quyết;
+- bỏ raw read/test log cũ khỏi provider working set nhưng giữ nguyên transcript
+  hiển thị và audit source;
+- giữ nguyên nhóm assistant tool-call/tool-result để không tạo orphan protocol;
+- giữ nguyên tối thiểu 6 nhóm ranh giới gần nhất; nếu transcript hoặc projected
+  candidate đã có orphan tool message thì fail closed và không thay context;
+- chỉ project khi ước tính tiết kiệm đạt ngưỡng thích ứng: ít nhất 8K token,
+  15% transcript occupancy và không đòi quá 20K; không đạt thì no-op thay vì gọi
+  thêm một model summarizer có phí;
+- chỉ ghi durable compaction sau khi agent đã settled; coding task dùng summary
+  deterministic từ state/file-backed evidence để không tốn thêm model call;
+- trước khi lặp exact verifier, dùng current-tree gate: một durable pass trên
+  cùng working-tree digest được tái sử dụng bằng receipt nhỏ thay vì chạy lại.
+  Code đổi, pass thiếu/stale, test từng fail, hoặc operator yêu cầu chạy lại thì
+  verifier thật vẫn chạy;
+- giữ model summarizer cho thảo luận không có Task Contract và ít tool evidence,
+  nơi sắc thái hội thoại quan trọng hơn tiết kiệm tuyệt đối.
+
+Telemetry tách `contextOccupancy` (working set ước tính/được provider báo) khỏi
+`billedTraffic` (input/output/cache thực sự đo được). Vì context hook không có
+usage hóa đơn theo lần gọi, runtime không được suy diễn hai con số này là một.
+
+Mốc vận hành hiện tại bắt đầu tạo áp lực ở khoảng 160K token, giữ provider prompt
+dưới 240K khi có thể và chủ động tránh vùng pricing 272K+. Đây là giới hạn
+working set, không phải giới hạn năng lực hay context window của model.
+
 ## Rule
 
 - Nếu task là read-only, không mở write-capable prompt.

package/docs/distribution-standard.md

@@ -15,9 +15,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.5.5` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.6.1` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.5.5` |
+| Registry distribution | `npm:@piagent/platform@1.6.1` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -27,7 +27,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.5.5` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.6.1` | 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. |
@@ -54,7 +54,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.5.5
+pi install git:github.com/Vt-mmm/piagent@v1.6.1
 ```
 
 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.
@@ -66,12 +66,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.84.1
-npm install -g --ignore-scripts @piagent/platform@1.5.5
+npm install -g --ignore-scripts @piagent/platform@1.6.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.5.5` 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.5.5`.
+`pi install git:github.com/Vt-mmm/piagent@v1.6.1` 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.6.1`.
 
 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).
 
@@ -121,7 +121,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.5.5 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.6.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/en/architecture.md

@@ -44,6 +44,7 @@ The machine-readable rule is `architecture/layers.json`; `npm run architecture:c
 | Security foundation | `packages/piagent-core/security/` | Sensitive-data primitives | Workflow behavior |
 | Benchmark | `packages/piagent-core/benchmark/`, `benchmarks/` | Suite validation, scoring, evidence | Runtime enforcement |
 | WebUI contracts | `packages/piagent-webui/contracts/` | Wire types shared by browser and server | Any runtime behavior; it depends on nothing |
+| WebUI shared | `packages/piagent-webui/shared/` | Dependency-free deterministic helpers shared by browser, server, and gateway | Browser state, transport, filesystem access, or runtime policy |
 | WebUI client | `packages/piagent-webui/client/` | Browser views, view models, UI preferences | Server state, filesystem, Pi APIs |
 | WebUI server | `packages/piagent-webui/server/` | HTTP/WS endpoints, session reads, diff assembly | Browser rendering; it may not import the client |
 | WebUI extension | `packages/piagent-webui/extension/` | The in-Pi `/piagent-webui` command surface | Wire types the client also needs |
@@ -93,10 +94,23 @@ the verified journal second; corruption blocks automatic resume for review.
 The journal hash chain and acceptance receipts are same-runtime operational
 evidence, not independent attestation or a separate audit authority.
 
+The Gateway binds each browser send to one operation lifecycle shared by the
+stream and supervisor. It permits at most one pristine provider retry within an
+8-second delay, and refuses replay after any visible assistant output or tool
+call. Compaction has a separate phase, terminal settlement is emitted once, and
+post-settlement events cannot put the UI back into `Working`. A bounded local
+emission guard removes repeated/filler activity or reviewer notes, while final
+assistant messages always bypass that guard.
+
+Exact edits and local patches may also bind to the full-file digest from the
+latest successful read in the same task run. Proven concurrent drift blocks the
+whole mutation before the first hunk and requires one fresh read; an unobserved
+file retains the host's normal exact-anchor behavior.
+
 Recovery is classification-driven and bounded across task attempts. Only an
-in-scope source-owned failure may receive one repair pass; transient verifier or
+evidence-backed source-owned failure may receive one repair pass; transient verifier or
 provider failures receive at most one exact retry and never source-mutation
-authority. Environment, permission, policy, scope, and unknown failures stay
+authority. Environment, permission, protected-path policy, and unknown failures stay
 non-mutating. `PIAGENT_AUTO_RECOVERY=off` restores ordinary P3 handoff behavior
 without migrating state. Every final path writes a redacted Handoff v1
 projection from operational truth. Resume binds task/session identity, journal
@@ -110,7 +124,7 @@ Semantic specialist review is a separate strict-high-risk CAP-13 path, not a
 universal parser-driven recovery path. It is pinned to one shared continuation,
 one current-tree diff, two targeted reads, exact eligible source/test paths, and
 the configured verifier after any mutation. Denied, failed, no-op, stale,
-out-of-scope, unsupported, or exhausted work locks the opportunity and hands
+target-unresolved, unsupported, or exhausted work locks the opportunity and hands
 off. Broad-default observation/advice never schedules this review or blocks a
 tool call.
 
@@ -126,7 +140,7 @@ Task Contract v2 also carries an additive Criterion Graph v1 planning
 projection. It maps every operator criterion exactly once to a closed planning
 kind, scoped target hints, proof kinds, and dependency order. The graph has no
 `satisfied` state and cannot override acceptance or exact-verifier truth. It
-selects relevant in-scope context before older observations, survives
+selects relevant focus-ranked context before older observations, survives
 compaction/resume by digest, and adds no tool-schema change or provider follow-up
 turn. `PIAGENT_INTELLIGENCE_ENGINE=off` selects the mechanical control for
 causal tests and emergency rollback; new tasks otherwise use the criterion
@@ -165,17 +179,17 @@ authority, and combined automatic dispatch authority is capped at one unit per
 task. These interaction checks are snapshot-bound and cannot change the
 provider-visible tool schema.
 
-Piagent-owned helpers use RolePolicy v1 and HelperRequest v1. The request binds
-a hashed session/task identity, bounded objective, read/write scope, exact tool
+Piagent-owned helpers use RolePolicy v1 and HelperRequest v2. The request binds
+a hashed session/task identity, bounded objective, read-only scope, exact tool
 allowlist, authenticated model/effort source, context/time/call ceilings, output
 schema, stopping rule, approval restrictions, and deduplication key. Read-only
-roles cannot receive mutation tools. Worker remains disabled by default and
-requires an explicit single-writer lease. `PIAGENT_HELPERS_MODE=off|recommend|on`
-defaults to `recommend`; `on` permits only read-only dispatch through an
-installed provider adapter. CAP-14 permits at most one automatic helper dispatch
-per task/run; the lower-level owner budget still caps two concurrent and three
-total explicitly owned helper reservations, deduplicates equivalent work, recovers
-expired reservations without adding budget, and cancels late work when the
+roles cannot receive mutation tools, and worker dispatch is disabled.
+`PIAGENT_HELPERS_MODE=off|recommend|on` defaults to `off`; `on` is explicit
+opt-in but still requires two independent lanes and at least 30% projected net
+token saving. CAP-14 and the lower-level owner budget enforce one fresh read-only
+helper total and concurrent, zero writers, zero retries, eight calls, and at most
+2,048 transferred context tokens. Failed or expired work consumes the only slot,
+and late work is cancelled when the
 parent Task Contract becomes terminal. It does not claim control over unrelated
 Pi sessions or account usage, and never changes the user-pinned parent model.
 Dispatch enforces the request's time, call, and token ceilings at result merge: