@piagent/platform 1.6.0 → 1.7.1

package/docs/command-reference-vietnamese.md

@@ -42,6 +42,7 @@ Command ngắn của PiAgent dùng cho workflow và guard local:
 | `/usage` | Usage live/history/preflight/compact/logs/efficiency. |
 | `/context` | Smart index/rebuild/search/pack/impact/efficiency/preflight/compact. |
 | `/permission` | Permission mode của session. |
+| `/fast` | Xem/bật/tắt OpenAI Codex Fast service tier cho session; không đổi model/thinking và không gọi model khi chạy command. |
 | `/profile` | Profile và tech stack. |
 | `/memory` | Project memory policy. |
 | `/onboard` | Project onboarding/status/setup. |
@@ -90,7 +91,7 @@ Nếu chỉ scout/audit read-only:
 /workflow scout Scout payment FE mapping vs BE. Do not edit source.
 ```
 
-Nếu session đang nặng hoặc Pi báo context overflow, dùng fresh workflow:
+Nếu session đang nặng hoặc Pi báo context overflow, dùng fresh workflow. Ba lệnh dưới đây là ví dụ phổ biến; `/fresh help` liệt kê toàn bộ workflow canonical:
 
 ```text
 /fresh scout <read-only request>
@@ -112,7 +113,7 @@ Pi Agent dùng ít namespace nhưng mỗi namespace có subcommand/menu rõ:
 - `/workflow` là cửa chính cho task/scout/review/git/onboard workflow. Workflow cần agent turn là cố ý và được nói rõ.
 - `/usage` gom live usage, history/report hint, preflight, compact, logs, efficiency.
 - Pi native `/name` đặt tên session theo task; Piagent nhận rename event để Agent Watch/report map đúng việc.
-- `/fresh` mở session mới cho `task`, `scout`, hoặc `be-to-fe` khi phiên hiện tại đã nặng.
+- `/fresh` mở session mới cho mọi workflow canonical khi phiên hiện tại đã nặng; chạy `/fresh help` để xem catalog hiện hành.
 - `/context` gom architecture map, code index, search, context pack, test impact, efficiency, preflight và semantic compact.
 - `/permission` gom permission status/read-only/workspace-write/full-access.
 - `/profile` là namespace duy nhất cho profile và tech stack.
@@ -145,9 +146,10 @@ Các command này đến từ package `piagent-core`.
 | `/task-preflight` | Xem product preflight deterministic. | Intent/risk/scope/runtime/solver/phases/tools/helpers/backend/approval có schema/version. |
 | `/piagent-status` | Xem product live status deterministic. | Task/phase/checkpoint/resume/recovery/helper/terminal receipt từ persisted evidence. |
 | `/piagent-inspector` | Muốn xem Piagent đang làm gì, sửa file nào, diff bao nhiêu dòng, command nào fail/block và context còn bao nhiêu. | Mở menu `summary/files/commands/security/context/toggle`; read-only, không gọi model. |
-| `/fresh task|scout|be-to-fe <request>` | Phiên hiện tại đã nặng hoặc muốn tách việc. | Mở session mới có tên và replay workflow prompt gọn. |
+| `/fresh <workflow> <request>` | Phiên hiện tại đã nặng hoặc muốn tách việc; nhận mọi workflow canonical. | Mở session mới có tên và replay workflow prompt gọn; `/fresh help` liệt kê lựa chọn. |
 | `/context` | Xem index/search/pack/impact/efficiency/preflight/compact. | Menu context, không gọi model. |
 | `/permission` | Xem/đổi quyền runtime. | Menu status/read-only/workspace-write/full-access. |
+| `/fast status\|on\|off` | Xem/bật/tắt Fast service tier cho session OpenAI Codex. | Chạy ngay, 0 model token; giữ nguyên model/thinking. Session trống mặc định tắt, environment override hoặc state đã lưu khi resume có thể được ưu tiên. |
 | `/memory` hoặc `/memory-policy` | Xem memory policy. | Chạy ngay, không gọi model. |
 | `/model-options` | Xem hướng dẫn model/thinking. | Chạy ngay; chọn model vẫn dùng `/model` hoặc `Ctrl+L`. |
 | `/piagent-mcp` | Xem/quản trị MCP trong Pi. | Menu MCP, không gọi model. |
@@ -325,7 +327,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 +344,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 +360,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 +368,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 +378,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 +412,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 +439,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 +473,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
@@ -501,9 +494,9 @@ 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.6.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.6.0` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1` | Cài Pi CLI tương thích với release hiện tại. |
+| `npm install -g --ignore-scripts @piagent/platform@1.7.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.7.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. |
@@ -552,7 +545,9 @@ Các lệnh này chạy ngoài Pi.
 | `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 bốn 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. Digest S0 loại private vault/stage-window identity nên lượt paid và mọi resume dùng lại đúng receipt khi semantic không đổi. |
+| `npm run benchmark:production-v2 -- --dry-run` | Validate ma trận 108 session Luna/medium Fast-vs-Fast; khóa Fast execution configuration bằng Piagent outbound telemetry và Codex identity-bound effective thread settings, upper-95 family `<=0.60` và pooled all-attempt net ratio `<=0.65`, chưa dùng 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ư. |
@@ -576,7 +571,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

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 <workflow>` vẫn là đường phục hồi
+tường minh cho mọi workflow canonical khi preflight xác định input quá lớn hoặc
+working set không thể rút gọn an toàn; `/fresh help` liệt kê catalog hiện hành.
 
 ## 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.6.0` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.7.1` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.6.0` |
+| Registry distribution | `npm:@piagent/platform@1.7.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.6.0` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.7.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.6.0
+pi install git:github.com/Vt-mmm/piagent@v1.7.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.
@@ -65,13 +65,13 @@ 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.6.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
+npm install -g --ignore-scripts @piagent/platform@1.7.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.6.0` 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.0`.
+`pi install git:github.com/Vt-mmm/piagent@v1.7.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.7.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.6.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.7.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -216,7 +216,7 @@ piagent-update --version X.Y.Z --project /path/to/project
 Sequence thủ công tương đương:
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
 npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable

package/docs/en/architecture.md

@@ -94,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
@@ -111,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.
 
@@ -127,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
@@ -166,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:

package/docs/languages.json

@@ -21,8 +21,8 @@
       "en": "README.md",
       "vi": "README.vi.md",
       "consistentAt": {
-        "en": "c2b6f830977bff9eff7ebdc97f1aa15502ce3e2c",
-        "vi": "a6533b41f285b3dc05a594e21cc208ca28b5569b"
+        "en": "e4dd46221efb318f9f89438c9b7a074ed4a3452e",
+        "vi": "2fbafba52e00ce7ee46051498b6f89c023030923"
       }
     },
     {
@@ -39,8 +39,8 @@
       "en": "docs/en/architecture.md",
       "vi": "docs/vi/architecture.md",
       "consistentAt": {
-        "en": "7902186a3bf9cc8c344bd27ea352cf4a6d5eae2a",
-        "vi": "64575dc18be0167324bfba396d7162c74af28048"
+        "en": "6a8a6f73bd6b0bde3fad00f0996426eaa101a8a9",
+        "vi": "580addecc766aa7317c3c49d9d740bc05f1bb43d"
       }
     },
     {

package/docs/operator-manual-vietnamese.md

@@ -18,13 +18,13 @@ 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.84.1
-npm install -g --ignore-scripts @piagent/platform@1.6.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
+npm install -g --ignore-scripts @piagent/platform@1.7.1
 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.6.0`. 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.7.1`. 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:
 
@@ -38,7 +38,7 @@ bash scripts/install-global.sh --stable
 Full update phải đồng bộ exact Pi host trước, rồi npm-global helper và Pi package matching:
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
 npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
@@ -99,8 +99,8 @@ install package once
 ### Cài Pi và package platform
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.6.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
+npm install -g --ignore-scripts @piagent/platform@1.7.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -283,7 +283,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.6.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.7.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -334,7 +334,7 @@ Use `/workflow scout` cho payment/auth/data/contract mapping khi mục tiêu là
 
 ### Task mới khi session đã nặng
 
-Nếu `/usage` cho thấy context cao, hoặc Pi báo context overflow, dùng fresh workflow:
+Nếu `/usage` cho thấy context cao, hoặc Pi báo context overflow, dùng fresh workflow. Đây là ba ví dụ thường dùng; `/fresh help` liệt kê đầy đủ catalog canonical:
 
 ```text
 /fresh scout Scout payment FE mapping vs BE contract. Backend read-only. Do not edit source.
@@ -924,13 +924,13 @@ Default safe config:
 
 - `toolDescriptionMode: compact`;
 - `asyncByDefault: false`;
-- `parallel.concurrency: 3`;
-- `parallel.maxTasks: 6`;
+- `parallel.concurrency: 1`;
+- `parallel.maxTasks: 1`;
 - `maxSubagentDepth: 1`;
-- `maxSubagentSpawnsPerSession: 32`;
+- `maxSubagentSpawnsPerSession: 1`;
 - scheduled runs off;
 - worktree base stable;
-- intercom bridge on.
+- wait/intercom bridge off; builtin và worker disabled.
 
 ### Piagent agents
 
@@ -938,13 +938,13 @@ Default safe config:
 |---|---|---|
 | `piagent-scout` | Map source/spec read-only. | No write. |
 | `piagent-planner` | Plan implementation + verify gates. | No write. |
-| `piagent-worker` | Implement approved bounded task. | Write in scope. |
+| `piagent-worker` | Compatibility metadata only; Piagent config disables it. | Không được dispatch. |
 | `piagent-reviewer` | Review diff/tests/scope. | Review-first. |
 | `piagent-oracle` | Risk/architecture challenge. | No write. |
 
 ### Auto-delegation
 
-Với `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, `/workflow review`, parent agent dùng solo-first orchestration: lập task tree/review lenses trước, rồi chỉ spawn subagent khi có phần việc độc lập và đáng token. Alias cũ như `/task` vẫn giữ cùng policy.
+Với `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, `/workflow review`, parent agent tự suy luận và implement. Helper mặc định tắt. Khi operator bật rõ, runtime chỉ được dispatch một helper read-only, context fresh, nếu có ít nhất hai lane độc lập và projected net token saving từ 30% sau handoff/merge. Worker, retry, nested và parallel helper đều tắt. Alias cũ như `/task` giữ cùng policy.
 
 Kiểm tra nhanh policy:
 
@@ -954,13 +954,12 @@ Kiểm tra nhanh policy:
 
 Không cần tự gọi `/run` cho task bình thường. Chỉ dùng `/run` khi muốn ép rõ role hoặc debug.
 
-Parent nên spawn khi:
+Helper chỉ đủ điều kiện khi đồng thời:
 
-- cần scout codebase rộng;
-- cần map BE/spec read-only trước khi FE implement;
-- cần reviewer độc lập;
-- cần context builder cho task lớn;
-- cần oracle/risk challenge.
+- operator đã opt-in;
+- có ít nhất hai workstream độc lập và helper không phụ thuộc output tiếp theo của parent;
+- context chuyển giao fresh, tối đa 2.048 token và không inherit history;
+- tổng token parent + helper + handoff + merge được dự báo thấp hơn solo ít nhất 30%.
 
 Không nên spawn khi:
 
@@ -975,27 +974,15 @@ Không nên spawn khi:
 ```text
 /run piagent-scout "Map listing page state flow. Read-only."
 /run piagent-planner "Plan FE implementation from this backend contract."
-/run piagent-worker "Implement the approved plan. Do not touch backend."
 /run piagent-reviewer "Review current diff for correctness, tests, and scope drift."
 /run piagent-oracle "Challenge this architecture decision before implementation."
 ```
 
-Parallel read-only review:
-
-```text
-/parallel piagent-reviewer "Review correctness" -> piagent-reviewer "Review tests" -> piagent-reviewer "Review scope drift"
-```
-
-Chain:
-
-```text
-/chain piagent-scout "Scout target area" -> piagent-planner "Plan from {previous}" -> piagent-worker "Implement from {previous}" -> piagent-reviewer "Review implementation"
-```
+`/parallel`, `/chain` và writer role là capability upstream của package `pi-subagents`, nhưng Piagent config chủ động chặn các surface đó để tránh nhân context và token.
 
 Background:
 
 ```text
-/run piagent-scout "Map this module" --bg
 /subagents-fleet
 ```
 
@@ -1007,26 +994,19 @@ subagent({ action: "status", view: "fleet" })
 subagent({ action: "status", id: "<run-id>", view: "transcript" })
 subagent({ action: "steer", id: "<run-id>", message: "Focus only on tests." })
 subagent({ action: "stop", id: "<run-id>" })
-subagent({ action: "resume", id: "<run-id>", message: "Continue after this clarification." })
 ```
 
 Output file mode để giảm parent context:
 
 ```text
 /run scout[output=context.md,outputMode=file-only] "Map target area"
-/chain scout[output=context.md,as=context] "Scan" -> planner[reads=context.md] "Plan from {outputs.context}"
 ```
 
 ### Worktree isolation
 
-Chỉ bật writer parallel/worktree khi:
-
-- repo là Git repo;
-- worktree clean;
-- write sets không overlap;
-- parent review/merge outputs.
+Piagent không bật writer parallel/worktree; parent là writer duy nhất.
 
-Default solo/internal: một `piagent-worker`, parallel read-only reviewers/scouts.
+Default: parent là writer duy nhất; không worker, không parallel helper.
 
 ### Watchdog
 
@@ -1044,8 +1024,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.6.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.6.0` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.7.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.7.1` | 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. |
@@ -1120,7 +1100,7 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 | `/usage` | Snapshot context/session. |
 | `/usage logs` | Xem capture output dài đã compact. |
 | `/name` | Đặt/đổi tên session theo task để report dễ map. |
-| `/fresh` | Mở session mới cho task/scout/be-to-fe khi phiên hiện tại nặng. |
+| `/fresh` | Mở session mới cho mọi workflow canonical khi phiên hiện tại nặng; xem lựa chọn bằng `/fresh help`. |
 | `/name <name>` | Đổi tên session cho resume/report. |
 | `/session` | Pi native session stats/info. |
 | `/mcp` / `/mcp tools` | Check MCP. |
@@ -1157,7 +1137,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.6.0
+npm install -g --ignore-scripts @piagent/platform@1.7.1
 command -v piagent-install
 ```