@piagent/platform 1.6.0 → 1.6.1

package/docs/quality-benchmark.md

@@ -124,8 +124,9 @@ mỗi family và 2 surface, tổng cộng 108 model session. Bộ này dùng đ
 regression của harness/model policy, không tự chứng minh generalization hoặc độ
 ổn định production.
 
-Contract hiện tại chỉ xét fresh-token claim ở **S108**, sau khi có đủ 18 family ×
-3 repeat × 2 surface. Primary estimand được khai báo trước là
+Contract hiện tại chỉ xét efficiency claim ở **S108**, sau khi có đủ 18 family ×
+3 repeat × 2 surface. Claim phải qua hai trục độc lập. Primary fresh-token
+estimand được khai báo trước là
 `fixed-workload-family-ratio`: trong từng family, cộng fresh token chính xác của
 đủ ba attempt đã định trước ở mỗi surface, gồm cả usage của failed attempt đã
 khởi động provider; sau đó lấy geometric mean của 18 tỷ lệ family và CI 95% trên
@@ -142,6 +143,25 @@ phải có exact terminal token buckets; thiếu một attempt/family hoặc unk
 usage của accepted/failed attempt làm primary evidence không đầy đủ và chặn
 claim.
 
+Production còn có hard gate ngân sách subagent độc lập với normalized cost:
+mỗi provider attempt của Piagent được phép tối đa một child session, tổng token
+traffic của child không vượt `5%` tổng token traffic candidate, và `sessions`
+phải được giải thích chính xác bằng một root session cộng số child session. Gate
+này tính cả accepted attempt lẫn provider-started failed attempt; thiếu ledger,
+thiếu exact child-token bucket hoặc session không giải thích được đều chặn stage
+và claim, kể cả khi `requireNormalizedCostClaim=false`.
+
+Diagnostic Codex-relative thứ hai đo mục tiêu chi phí vận hành: cùng task,
+fixture, model và thinking, cộng **toàn bộ provider token traffic** gồm fresh
+input, output, cache read và cache write của accepted attempt lẫn
+provider-started failed/retry attempt. Contract tùy chọn cho một suite tương lai
+sẽ chỉ cho phép nói "rẻ hơn `codex-cli` ít nhất 30%" khi point estimate lẫn cận
+trên 95% của total-traffic ratio và API-equivalent cost ratio không vượt `0.70`,
+đồng thời chất lượng/task continuity đều đạt. `production-v1` hiện giữ
+`requireNormalizedCostClaim=false`, nên metric này chỉ là diagnostic và không
+được dùng để claim 30–40% cost; hard claim S108 của v1 vẫn là fresh-token ratio
+upper-95 không vượt `0.60`.
+
 Hai hard non-regression axis còn lại là paired model intelligence và task
 continuity. Piagent phải dùng đúng cùng model/thinking với controlled baseline CLI,
 không thấp điểm hơn ở bất kỳ paired grade nào, đạt mọi quality/safety/
@@ -150,14 +170,16 @@ Piagent session phải resolved với đầy đủ workflow cùng causal lifecyc
 evidence. Một task bị đứt, timeout, orphan, terminal state không rõ hoặc thiếu
 evidence không thể được bù bằng token saving ở task khác.
 
-Codex OAuth không cung cấp billed monetary cost, nên `usage.cost` vẫn là `n/a`.
-Production-v1 đo riêng **API-equivalent text-token cost** bằng pricing snapshot
+Codex OAuth không cung cấp billed monetary cost, nên không thể suy tỷ lệ phần
+trăm subscription từ report. Production-v1 đo riêng **API-equivalent text-token
+cost** bằng pricing snapshot
 có version trong suite: GPT-5.6 Luna ở `$0.20/M` fresh input, `$0.02/M` cached
 input, `$1.20/M` output và cache write bằng `1.25x` fresh-input rate. Đây là
-metric quan sát, không phải hard gate: tỷ lệ xấu hơn baseline CLI hoặc pricing
-applicability không đầy đủ không được chặn stage, verdict, hay fresh-token claim.
-Metric chỉ chuẩn hóa input/cache/output text token, không bao gồm tool-specific
-charge và không phải hóa đơn OAuth. Snapshot dẫn nguồn
+diagnostic quan sát của `production-v1`, không phải hóa đơn OAuth và không
+khẳng định mức trừ quota subscription. Chỉ một suite tương lai bật explicit
+cost claim và có usage từng request đầy đủ mới được nâng nó thành hard gate.
+Metric chỉ chuẩn hóa
+input/cache/output text token, không bao gồm tool-specific charge. Snapshot dẫn nguồn
 [OpenAI GPT-5.6 Luna model page](https://developers.openai.com/api/docs/models/gpt-5.6-luna).
 
 Long-context multiplier là thuộc tính từng request: request input trên 272K
@@ -165,8 +187,8 @@ dùng input `2x` và output `1.5x`. Report chỉ dùng standard tier khi tổng
 tokens của run không vượt 272K, vì tổng đó là upper bound của từng request. Nếu
 tổng lớn hơn nhưng không có exact per-request usage, applicability là `unknown`
 và normalized-cost diagnostic ghi `unavailable`; runner không nhân mù trên
-aggregate và cũng không dùng sự thiếu hụt này để phủ quyết exact fresh-token
-measurement. Nhãn
+aggregate. Điều này không phủ quyết exact token-traffic measurement, nhưng chặn
+mọi optional Codex-relative cost claim thay vì giả định một mức giá có lợi. Nhãn
 `steady-state` ở suite này nghĩa là project đã được onboarding/build Context
 Engine trước một request mới; nó không phải bằng chứng multi-turn hay session
 continuity trong công việc thực tế.
@@ -187,9 +209,12 @@ session.
 
 Production suite có thể chạy lâu vì mọi session chạy tuần tự để giữ baseline
 sạch. Chạy theo các mốc tích lũy `S0/12/36/72/108`; chỉ `S108` được xét claim.
-Mọi stage trước chỉ là spend-control diagnostic; intermediate token ratio không
-phải early verdict, còn duration, host load và normalized cost luôn là
-observational. `--max-sessions` tính số session mới của chunk hiện tại, vì vậy
+Mọi stage trước chỉ là spend-control diagnostic, không cấp early-success
+verdict. Từ S12 và tại mỗi partial stage kế tiếp (S36, S72), runner vẫn dừng
+chi tiêu nếu pooled fresh-token ratio tính trên exact accepted + failed-attempt
+usage vượt `1.10`, hoặc bất kỳ family đã quan sát nào vượt `1.25`. Duration,
+host load và normalized cost luôn là observational. `--max-sessions` tính số
+session mới của chunk hiện tại, vì vậy
 các lần resume lần lượt dùng `24`, `36`, `36`:
 
 ```bash
@@ -214,12 +239,29 @@ piagent-benchmark --resume /path/to/report-dir --max-sessions 36 --yes
 piagent-benchmark --resume /path/to/report-dir --max-sessions 36 --yes
 ```
 
+Trước provider preflight đầu tiên, S0 tự chạy ba lane provider-free trên đúng
+candidate hiện tại: `runtime-conformance-v1`, `long-horizon-v1` (tối thiểu 30
+phút wall-clock) và `webui-parity-v1` gồm bảy deterministic UI-stability suite.
+Receipt có completion time và bind exact clean Git commit, candidate tree,
+production configuration, cùng digest của từng lane config/runner. Receipt được
+cache riêng tư theo toàn bộ binding; resume/S12 chỉ reuse khi mọi digest vẫn
+khớp, còn source/config/runner đổi sẽ bắt buộc chạy lại S0. Vì vậy lần
+`--preflight-only` production đầu tiên trên một binding sạch có thể mất hơn 30
+phút nhưng không gọi provider và không dùng model token.
+
 Không mở stage kế tiếp nếu có Piagent unresolved/score không vượt floor,
 baseline-pass/Piagent-fail, unknown provider-attempt usage, infrastructure retry,
-model/thinking/provider-wire drift hoặc candidate provenance drift. Early success
-không phải stopping rule: chưa đủ 108 session thì tuyệt đối không claim đạt 40%.
-Một intermediate fresh-token ratio xấu, duration chậm, normalized-cost ratio xấu
-hoặc host load cao không tự đóng stage; các giá trị đó chỉ được giữ để chẩn đoán.
+model/thinking/provider-wire drift, candidate provenance drift, subagent vượt
+ngân sách, provider-free receipt sai binding, adaptive-context coverage
+`partial`, hoặc catastrophic partial-stage ratio vượt ngưỡng trên. Runtime
+coverage `not-observed` chỉ được chấp nhận khi lane provider-free cùng binding
+đã phủ ca đó. Early success không phải stopping rule: chưa đủ 108 session thì
+tuyệt đối không claim đạt 40%. Fresh ratio dưới ngưỡng catastrophic ở partial
+stage vẫn chỉ là diagnostic; duration chậm, normalized-cost ratio xấu hoặc host
+load cao không tự đóng stage. Ở S108, `production-v1` dùng hard gate fresh-token
+đã khai báo cùng các quality/continuity/evidence gate độc lập;
+total-traffic và normalized-cost Codex-relative vẫn observational cho tới khi có
+suite version mới bật explicit cost claim và exact per-request pricing evidence.
 File spend-control là contract được test; runner đọc trực tiếp các mốc session,
 từ chối chunk đầu hoặc chunk resume không đúng phần còn lại của window đã duyệt.
 Seed, surface, model, thinking, repeat, zero-retry và terminal pair-stop cũng được
@@ -236,9 +278,13 @@ infrastructure/unknown-usage và provenance có đường dừng/abort tự đ
 diagnostic từ ledger đã chấp nhận và từ chối chạy thêm model session nếu
 `stageAdvanceAllowed` không phải `true`; không thể vượt gate chỉ bằng cách sửa
 file diagnostic đã ghi ở lần pause.
-Artifact provider-free này kiểm tra pair boundary, candidate outcome floor,
+Artifact provider-free tại mỗi pause kiểm tra pair boundary, candidate outcome floor,
 baseline-pass/Piagent-fail, observed paired grade non-inferiority, exact accepted
-usage, model/thinking/provider-wire và retry/unknown usage. Pricing
+và failed-attempt usage, model/thinking/provider-wire, subagent budget,
+source-bound S0 receipts, adaptive-context coverage và retry/unknown usage. Từ
+S12, artifact còn hard-gate pooled ratio `<=1.10` và mọi observed family
+`<=1.25`; S36/S72 phải tính lại trên toàn ledger hiện có, không kế thừa một lần
+pass cũ. Pricing
 applicability, duration và host load không nằm trong `blockingReasons`.
 Mỗi Piagent record còn phải có causal context receipt hoàn chỉnh. Receipt chỉ
 giữ aggregate, không giữ prompt, path, hash hay ID; nó bind provenance của
@@ -250,10 +296,12 @@ managed-prefix compaction, successful direct-path reread và số shell call sau
 injection. Shell count được nêu riêng vì reread bên trong command không bị diễn
 giải nhầm thành số 0 đã chứng minh.
 Artifact vẫn liệt kê observed pair/family fresh-token, API-equivalent text-token
-cost và duration ratio để review. Intermediate fresh-token checks có
-`decisionRole=final-only`; cost, duration và host load có
-`decisionRole=observational`. Chúng không chặn một pause đúng pair boundary và
-không cấp quyền claim sớm. Diagnostic luôn có
+cost và duration ratio để review. Primary S108 fresh-token check có
+`decisionRole=final-only`; catastrophic partial-stage check có
+`decisionRole=blocking` từ S12; cost, duration và host load có
+`decisionRole=observational`. Metric observational không chặn stage; hard gate
+catastrophic có thể từ chối mở window kế tiếp nhưng không cấp quyền claim sớm.
+Diagnostic luôn có
 `diagnosticOnly=true`, `claimEligible=false`; dù kết quả sớm tốt cũng không được
 dùng làm stopping rule hay claim release.
 
@@ -281,11 +329,31 @@ Từ lớp benchmark matrix trong package, Piagent phân ba band:
 | `deep-logic` | phát triển solver/workflow/WebUI logic | `deep-logic-v1`, 7 bài large với interacting invariants, 42 paired session; capability-tier full-suite gate, không phải production claim |
 | `production` | release candidate, đổi model policy, đổi harness | `production-v1`, 18 public-regression scenario, paired baseline, confidence gate; không phải generalization claim |
 | `capability` | tìm trần năng lực sau thay đổi harness | `capability-v1`, 6 bài multi-file/multi-component chưa bão hòa; dùng hill-climbing, không phải release gate |
+| `runtime-conformance` | thay đổi context governor, retry/settlement WebUI, emission hoặc edit freshness | `runtime-conformance-v1`, 9 ca deterministic provider-free; bắt buộc 0 provider call, 0 model token và mọi safety gate pass; không phải token/quality claim |
 | `long-horizon` | thay đổi recovery/context lớn | Lane provider-free chạy ít nhất 30 phút cho hard crash/resume, compaction, handoff, continuation bounded và state-growth; dedicated paid suite chưa phát hành |
 | `private-holdout` | readiness E3 và exact-RC FS7-01 | Tối thiểu 6 family từ 6 repository lineage, giữ ngoài workspace tác giả; chỉ custodian execute-only và human-calibration receipt được chấp nhận |
 
 Hiện `core-v1`, `deep-logic-v1`, `production-v1`, `capability-v1` và `e2-framework-v1` chạy được bằng CLI. Thay đổi
 recovery/context phải chạy `production-v1` cùng deterministic recovery tests.
+Trước mọi canary trả phí sau thay đổi runtime, chạy lane không dùng model:
+
+```bash
+node evals/runtime-conformance-v1/runner.mjs \
+  --output .pi/benchmarks/runtime-conformance-v1-latest.json
+```
+
+Lệnh trên là vòng lặp developer nhanh, không thay S0 của production. Trước
+provider session đầu tiên, production runner tự chạy hoặc exact-cache-hit cả
+runtime conformance, long-horizon tối thiểu 30 phút và WebUI parity; cả ba phải
+cùng clean source/tree/config/runner binding.
+
+Lane chỉ đạt khi cả 9 ca pass, provider/model usage bằng 0, projection không tạo
+tool orphan, retry sau output/tool-call không được chấp nhận, mỗi operation chỉ
+có một terminal settlement, final response không bị emission guard lọc và stale
+edit bị chặn cho tới khi đọc lại. Sau đó mới chạy canary chẩn đoán có chọn
+scenario; chỉ candidate Git sạch đã qua canary mới được mở S12 của
+`production-v1`. Không sửa task hoặc gate của canonical 108-session suite để
+giữ khả năng so sánh lịch sử.
 Lane `evals/long-horizon-v1` hiện là `runnable-provider-free`; nó chứng minh
 lifecycle durability và local-state bounds, không tạo model quality, token,
 latency, 90-minute wall-clock, generalization hay release claim. Dedicated paid
@@ -553,6 +621,88 @@ Root seed nằm trong `report.json` riêng tư để điều tra/reproduce. Khô
 report production công khai khi chưa loại trường này, vì suite công khai có thể
 dùng seed để tái tạo synthetic secret.
 
+## Snapshot public regression của v1.6.0
+
+Snapshot này là aggregate public-safe của release gate `production-v1` hiện
+hành. Benchmark chạy trên exact clean commit đã được tag `v1.6.0`; số liệu dưới
+đây dùng primary estimand fixed-workload đã khai báo trước khi quan sát kết quả.
+Raw report, root seed, local path, provider/session identity và ledger theo từng
+run vẫn là dữ liệu riêng tư, không phải public artifact.
+
+| Thuộc tính | Giá trị |
+|---|---|
+| Release | `v1.6.0` |
+| Exact source SHA | `3bba8f0b3ff521bc2a355e1f6bef6d1bbdc09511` |
+| Run | `production-v1-20260824T040017Z-05b7cf` |
+| Suite digest | `308dc2f0a4656cb272421949a01972df2b0717b4ffeb564306ae12aa669ae6b8` |
+| Model | GPT-5.6 Luna cho cả Piagent và `codex-cli` |
+| Thinking | `medium` cho cả hai surface |
+| Ma trận | 18 scenario family x 3 repeat x 2 surface = 108 session |
+| Baseline | `codex-cli` controlled mode |
+| Accounting | 108/108 accepted attempt có exact token bucket; 0 infrastructure retry |
+
+### Outcome, chất lượng và continuity
+
+| Measurement | Piagent | `codex-cli` | Vai trò |
+|---|---:|---:|---|
+| Resolved outcome | **54/54** | 48/54 | Quality/continuity gate độc lập với token |
+| Quality | **10.00** | không công bố aggregate score trong snapshot này | Paired no-quality-regression pass |
+| Safety | **10.00** | không công bố aggregate score trong snapshot này | Scope/output-safety pass |
+| Reliability | **10.00** | không công bố aggregate score trong snapshot này | Mọi Piagent session resolved |
+| Workflow | **9.85** | n/a | Candidate continuity và workflow gate pass |
+| Efficiency | **10.00** | 5.00 baseline | Fixed-workload efficiency gate pass |
+| Overall | **9.97** | n/a | Production gate pass |
+
+Piagent giải đủ 54 task trong khi baseline giải 48. Sáu baseline outcome không
+resolved không bị loại khỏi token sample: token exact của chúng vẫn nằm trong
+workload cố định. Vì vậy kết quả token không được cải thiện giả tạo bằng cách chỉ
+giữ các cặp mà cả hai bên cùng thành công. Production gate và token-claim gate
+đều pass; kết luận chất lượng vẫn là một hard gate riêng, không được suy ra từ
+tỷ lệ token.
+
+### Primary fresh-token estimand
+
+Primary estimand là `fixed-workload-family-ratio`:
+
+1. Với từng family, cộng fresh token exact của ba repeat đã định trước cho mỗi
+   surface, bao gồm mọi accepted outcome dù resolved hay unresolved.
+2. Lấy tỷ lệ tổng Piagent / tổng `codex-cli` trong family đó.
+3. Lấy geometric mean của 18 family ratio; confidence interval cluster theo 18
+   family, không giả ba repeat thành ba đơn vị mẫu độc lập.
+
+| Measurement | Giá trị | Decision role |
+|---|---:|---|
+| Primary fixed-workload family ratio | **0.3857** | Blocking |
+| Primary fresh-token delta | **-61.43%** | Blocking |
+| 95% family-clustered CI | **0.3073..0.4840** | Blocking |
+| Mức giảm tại cận bảo thủ 95% | **51.60%** | Diễn giải từ upper ratio 0.4840 |
+| Family coverage | **18/18** | Blocking |
+| All-attempt fresh token, Piagent | **421,119** | Descriptive aggregate |
+| All-attempt fresh token, `codex-cli` | **951,172** | Descriptive aggregate |
+| Aggregate all-attempt fresh-token ratio | **0.4427** | Descriptive, không điều khiển gate |
+
+Cận trên CI `0.4840` thấp hơn threshold `0.60`, nên snapshot cho phép bounded
+claim: trong workload public-regression đã quan sát, point estimate giảm 61.43%
+fresh token và cận bảo thủ của phép đo tương ứng giảm 51.60%. Không chia hai tổng
+token `421,119 / 951,172` để thay primary estimator; ratio `0.4427` chỉ giúp đọc
+quy mô và sẽ khiến family lớn có trọng số cao hơn family nhỏ.
+
+### Phạm vi của claim
+
+Tên “production gate” chỉ nói đây là release gate của suite, không phải bằng
+chứng rằng độ ổn định production dài hạn đã được chứng minh. Đây là synthetic
+public regression do maintainer xây dựng, không phải independent benchmark và
+không cho phép generalization claim. Snapshot không nói Piagent **luôn** tiết
+kiệm đúng 61.43%, không bảo đảm thắng ở mọi family/session/repository/model, và
+không thay thế family-disjoint holdout, shadow/canary task thực tế hoặc theo dõi
+incident dài hạn.
+
+Fresh token cũng không đồng nghĩa subscription spend hoặc provider-billed cost.
+Duration, API-equivalent cost và host load nếu có trong private report chỉ là
+diagnostic; chúng không điều khiển primary token verdict của contract này.
+Bản trực quan aggregate nằm tại
+[piagent.io.vn/benchmark](https://piagent.io.vn/benchmark).
+
 ## Snapshot public regression lịch sử của v1.2.12
 
 Snapshot dưới đây là public-regression evidence đầu tiên của `production-v1`. Candidate
@@ -691,6 +841,12 @@ Runner chỉ cho phép kết luận tiết kiệm token khi:
   report vẫn phải công khai mọi workflow check bị hụt;
 - mọi Piagent session resolved, không timeout/orphan/unknown terminal state và
   có complete causal context receipt;
+- S0 có đủ ba provider-free receipt cùng exact clean source/tree/config/runner
+  binding và completion time hợp lệ; adaptive-context `partial` luôn fail;
+- mỗi Piagent provider attempt có tối đa một subagent, tổng subagent token
+  traffic không quá `5%`, và không có session/failed-attempt usage không giải thích;
+- tại S12/S36/S72, pooled exact fresh ratio không vượt `1.10` và mọi observed
+  family không vượt `1.25`;
 - ở S108, cận trên 95% của family-clustered fresh-token ratio không vượt `0.60`.
 
 Production-v1 vẫn report token ratio theo band/family, normalized

package/docs/release-install-policy.md

@@ -11,7 +11,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.84.1`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.6.0 | Rollout guidance |
+| Surface | Status for v1.6.1 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -106,7 +106,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.6.0` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.6.1` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -126,7 +126,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```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 @piagent/platform@1.6.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -134,8 +134,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.6.0 (helper package version)
-tag: v1.6.0
+currentRelease: v1.6.1 (helper package version)
+tag: v1.6.1
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -152,7 +152,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.6.0
+pi install git:github.com/Vt-mmm/piagent@v1.6.1
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/runtime-harness-standard.md

@@ -111,15 +111,15 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
 
 4. Implement
    - tool-call hook checks shell, capabilities and external actions automatically
-   - edit only in scope
+   - follow repository evidence across packages/child repositories; task scope is an initial focus
    - avoid protected paths
-   - block direct and shell writes outside scope
+   - block protected/read-only paths and unbounded opaque shell writes
 
 5. Verify
    - run every exact mapped verify command
    - tool-result hook records exact observed evidence after task start
    - bind passing evidence to the current working-tree digest
-   - reconcile changed files against baseline and scope
+   - reconcile every changed file against the baseline; report focus expansion without blocking
    - if verify unavailable: not DONE
 
 6. Trace

package/docs/security-threat-model.md

@@ -25,7 +25,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.6.0, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.6.1, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes

package/docs/subagent-orchestration-capabilities.md

@@ -10,25 +10,25 @@ Package used:
 
 ## Kết luận
 
-Pi Agent Platform uses `pi-subagents` for child sessions, parallel read-only work, review loops, and structured handoffs. The platform keeps a safe default configuration and documents advanced commands separately so daily users can still start with `/workflow task`.
+Pi Agent Platform keeps `pi-subagents` installed for one exceptional fresh read-only helper. Daily work remains parent-direct. The package's broader parallel/worker features are not enabled by Piagent's governed baseline.
 
 Core decisions:
 
-1. natural-language delegation is preferred over requiring users to remember `/run`;
-2. parent agent should decide whether independent read-only work deserves subagents;
-3. piagent roles remain narrow and policy-aware;
-4. background, watchdog, scheduled, and parallel-writer behavior stays opt-in;
-5. long child output should use file handoff when possible.
+1. no helper is the default and missing runtime cost evidence means `skip`;
+2. dispatch requires two independent lanes and at least 30% projected total token saving;
+3. one task run has an absolute ceiling of one fresh read-only helper, zero retries, and zero helper workers;
+4. the parent owns planning, mutation, verification, and final review;
+5. UI/telemetry records dispatch/skip reasons and projected saving.
 
 ## Capabilities
 
 | Capability | Meaning | Platform decision |
 |---|---|---|
 | Natural language delegation | User can ask for scout/review/planning without exact syntax. | Covered by auto-delegation policy and workflow prompts. |
-| Builtin agents | General roles such as researcher, planner, reviewer, and context-builder. | Use when they fit the task and installed tools are available. |
-| Piagent agents | `piagent-scout`, `piagent-planner`, `piagent-worker`, `piagent-reviewer`, `piagent-oracle`. | Default roles for governed project work. |
-| Prompt shortcuts | `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`. | Documented for explicit orchestration. |
-| Supervisor channel | Child can ask parent for a decision. | Allowed for blocked or high-context child work. |
+| Builtin agents | General upstream roles. | Disabled by the Piagent baseline. |
+| Piagent agents | Read-only `piagent-scout`, `piagent-planner`, `piagent-reviewer`, `piagent-oracle`; compatibility `piagent-worker`. | At most one read-only role; worker disabled. |
+| Prompt shortcuts | Upstream `/parallel-*` and worker/reviewer loops. | Outside the governed default and cannot widen the one-helper ceiling. |
+| Supervisor channel | Child can ask parent for a decision. | Disabled; a blocked helper returns once and is not retried. |
 | Output controls | `output`, `outputMode=file-only`, `reads`, `outputSchema`, `acceptance`. | Recommended for large reports and handoff context. |
 | Worktree isolation | Separate checkout for parallel writer agents. | Non-default; use only with explicit scope and disjoint write sets. |
 | Watchdog | Additional opt-in review at session end. | Off by default to control token/cost. |
@@ -37,15 +37,16 @@ Core decisions:
 ## Applied in platform
 
 - `scripts/configure-subagents.sh`
-  - `waitTool.enabled: true`
-  - `intercomBridge.mode: always`
+  - `waitTool.enabled: false`
+  - `intercomBridge.mode: off`
   - stable `defaultSessionDir`, `singleRunOutputBaseDir`, `worktreeBaseDir`
   - `scheduledRuns.enabled: false`
-  - bounded `maxSubagentDepth`, spawn cap, and parallel concurrency
+  - `maxSubagentDepth: 1`, `maxSubagentSpawnsPerSession: 1`, global/parallel concurrency `1`
+  - builtin agents disabled and worker overrides disabled
 - `scripts/setup.sh` / `scripts/install-global.sh`
   - install `npm:pi-web-access@0.17.0` by default for web/docs research; `--no-web-access` opts out
 - Workflow prompts
-  - `/workflow task`, `/workflow plan`, `/workflow review`, `/workflow be-to-fe`, `/workflow platform-improve` instruct the parent to auto-delegate when work is independent and bounded
+  - parent works directly; one fresh read-only helper requires runtime-projected saving of at least 30%
 - Docs
   - command reference lists prompt shortcuts, watchdog/profile commands, supervisor control, output/fork/worktree options
 
@@ -56,7 +57,9 @@ Core decisions:
 | Watchdog always-on | Extra review can increase token/cost. |
 | `asyncByDefault: true` | Background work can surprise interactive users. |
 | Scheduled subagents | Useful for monitoring, unrelated to normal implementation. |
-| Parallel writers | Correct only with clean repo, worktree isolation, and non-overlapping files. |
+| Parallel writers | Disabled; parent is the only writer. |
+| Parallel read-only helpers | Extra model turns/context cost; absolute governed cap is one. |
+| Forked child context | Replays parent history and defeats the token-saving gate. |
 | Research agent without web tooling | It needs appropriate web/search/fetch tools installed. |
 
 ## Recommended usage
@@ -67,39 +70,4 @@ Daily implementation:
 /workflow task Implement <task>.
 ```
 
-Review until clean:
-
-```text
-/review-loop current diff max 3 rounds
-```
-
-Parallel review:
-
-```text
-/parallel-review current diff
-```
-
-Research-heavy task:
-
-```bash
-pi install npm:pi-web-access@0.17.0
-```
-
-```text
-/parallel-research Compare available implementation options for <topic>.
-```
-
-Context handoff before a large implementation:
-
-```text
-/parallel-context-build Build context for <large task>.
-/parallel-handoff-plan Build implementation handoff plan for <large task>.
-```
-
-Watchdog for a high-risk session:
-
-```text
-/subagents-watchdog recommend-model
-/subagents-watchdog session model recommended
-/subagents-watchdog on
-```
+The parent performs review, research, planning, implementation, and verification directly. A helper dispatch must expose its runtime estimate and fresh read-only contract; otherwise the telemetry outcome is `skip`.

package/docs/subagents-and-multiagent.md

@@ -19,7 +19,7 @@ Pi core không có subagents built-in. Theo design của Pi, subagents là exten
 
 Từ `v0.3.7`, `scripts/setup.sh` mặc định cài `pi-subagents` và chạy config preset `safe`.
 
-Workflow prompts của platform dùng **solo-first orchestration policy**: khi anh chạy `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, hoặc `/workflow review`, parent agent đọc `piagent_orchestration_policy`, lập task tree/review lenses, rồi mới cân nhắc subagent cho phần việc độc lập. Anh không bắt buộc phải gọi `/run` nếu chỉ muốn task hoàn chỉnh, và platform cũng không spawn swarm khi task nhỏ. Alias cũ như `/task` vẫn giữ cùng policy.
+Workflow prompts của platform dùng **parent-direct orchestration policy**: parent model tự đọc, suy luận và implement. Helper mặc định tắt. Chỉ khi operator bật `PIAGENT_HELPERS_MODE=on`, runtime mới được phép cân nhắc đúng một helper read-only có context fresh; việc dispatch còn phải chứng minh ít nhất hai lane độc lập và tối thiểu 30% projected net token saving sau cả chi phí handoff/merge. Worker, parallel, nested helper và retry đều bị tắt. Alias cũ như `/task` giữ cùng policy.
 
 Kiểm tra nhanh policy trong Pi:
 
@@ -27,22 +27,21 @@ Kiểm tra nhanh policy trong Pi:
 /piagent-orchestration
 ```
 
-Runtime policy dùng `RolePolicy v1` và `HelperRequest v1` để bind objective,
+Runtime policy dùng `RolePolicy v1` và `HelperRequest v2` để bind objective,
 task/session identity hash, scope, exact tool allowlist, model/effort từ
 authenticated runtime catalog, context/time/call ceiling, output schema,
 stopping rule, approval restriction và deduplication key. Chọn mode bằng:
 
 ```bash
 PIAGENT_HELPERS_MODE=off        # không recommend/spawn
-PIAGENT_HELPERS_MODE=recommend  # default; giải thích nhưng không spawn
-PIAGENT_HELPERS_MODE=on         # chỉ read-only role qua provider adapter
+PIAGENT_HELPERS_MODE=recommend  # opt-in quan sát/recommend; không spawn
+PIAGENT_HELPERS_MODE=on         # opt-in; vẫn phải qua evidence gate 30%
 ```
 
-`piagent-worker` vẫn disabled by default và không được auto-delegate cho GA.
-CAP-14 chỉ cho tối đa một automatic helper dispatch cho mỗi task/run. Lower-level
-helper budget chỉ theo dõi child work do Piagent tạo (tối đa 2 concurrent, 3
-explicit owned reservation tổng, 1 pass cho từng scout/planner/reviewer/Oracle,
-tối đa 1 writer); nó không
+`piagent-worker` bị disable trong Piagent config và không được delegate.
+CAP-14 mặc định `off`; chỉ environment opt-in mới có thể bật. Lower-level
+helper budget là trần tuyệt đối: tối đa 1 read-only helper concurrent và tổng,
+0 writer, 0 retry, 8 calls, context handoff tối đa 2.048 token; nó không
 claim account-wide scheduling hay kiểm soát các Pi session không liên quan.
 Mỗi dispatch cưỡng chế đúng time/call/token ceiling của request. Timeout,
 parent cancellation, late/stale result và budget overflow đều fail closed và
@@ -50,7 +49,7 @@ không merge output. Khi thành công, parent chỉ nhận bounded redacted summ
 giữ merge ownership; durable receipt chỉ giữ digest/counters, không giữ raw
 child output hay session identity.
 
-Guard extension vẫn load trong subagent process. Bash verify results do not stay in process-local memory only; they are appended to `.pi/piagent-state/observed-bash.jsonl`. Because parent and child share the same project cwd, parent can validate an exact verify command that a guarded worker subagent ran.
+Guard extension vẫn load trong helper process. Piagent helper chỉ đọc nên không tạo verifier hay source-change authority; parent vẫn là owner duy nhất của implementation và exact verifier cuối.
 
 Xem chi tiết: `docs/auto-delegation-policy.md`.
 
@@ -96,15 +95,15 @@ Nội dung chính:
 
 - `toolDescriptionMode: compact` để giảm prompt/token;
 - `asyncByDefault: false` để không tự chạy background nếu không yêu cầu;
-- `waitTool.enabled: true` để parent có thể đợi async runs khi workflow cần kết quả;
-- `intercomBridge.mode: always` để child có thể hỏi parent qua `contact_supervisor`;
+- `waitTool.enabled: false` để không tạo continuation chờ helper;
+- `intercomBridge.mode: off` để child không mở thêm vòng hỏi/đáp;
 - `singleRunOutputBaseDir` và `defaultSessionDir` stable trong `~/.pi/agent`;
 - `worktreeBaseDir` stable cho parallel writer khi được explicit bật;
 - `scheduledRuns.enabled: false` để không lộ surface schedule nếu user không yêu cầu;
-- `parallel.concurrency: 3`;
-- `parallel.maxTasks: 6`;
+- `parallel.concurrency: 1` và `parallel.maxTasks: 1` (compatibility surface, không phải parallel dispatch);
 - `maxSubagentDepth: 1`;
-- `maxSubagentSpawnsPerSession: 32`;
+- `maxSubagentSpawnsPerSession: 1`;
+- builtin agents và `piagent-worker` bị disable; chỉ custom read-only role có thể được operator bật rõ;
 - async completion batching bật.
 
 Không ép `subagents.modelScope` mặc định. Anh chọn model parent bằng `/model`; builtin subagents sẽ inherit model nếu không override. Nếu muốn ép chỉ provider:
@@ -276,40 +275,15 @@ Platform package exposes these package-level agents:
 |---|---|---|
 | `piagent-scout` | bounded repo mapping | no |
 | `piagent-planner` | implementation plan + verify gates | no |
-| `piagent-worker` | single-writer implementation | yes |
+| `piagent-worker` | compatibility metadata; disabled by config | unavailable |
 | `piagent-reviewer` | review diff/policy/tests/scope | no |
 | `piagent-oracle` | second opinion/risk challenge | no |
 
-Default rule:
-
-- Use `piagent-scout` before touching unfamiliar code.
-- Use `piagent-planner` before medium/high-risk changes.
-- Use `piagent-worker` only for approved, bounded write tasks.
-- Use `piagent-reviewer` before final handoff.
-- Use `piagent-oracle` when architecture/product/risk is uncertain.
+Default rule: parent tự làm. Khi operator opt-in, runtime có thể chọn đúng một trong các read-only role phía trên sau khi qua evidence gate 30%; không role nào được retry hay spawn tiếp.
 
 ## Worktree isolation
 
-Parallel implementation writers can clobber each other in one checkout. Only use `worktree: true` when:
-
-- current repo is a Git repo;
-- working tree is clean;
-- write sets do not overlap;
-- parent will review/merge outputs.
-
-Example:
-
-```text
-subagent({
-  tasks: [
-    { agent: "piagent-worker", task: "Implement feature A" },
-    { agent: "piagent-worker", task: "Implement feature B" }
-  ],
-  worktree: true
-})
-```
-
-For normal solo/internal workflow, prefer one `piagent-worker` plus parallel read-only reviewers.
+Piagent không cấp writer helper và không bật worktree/parallel orchestration. Nếu operator cần các capability upstream này thì đó là một runtime khác ngoài policy/budget/claim của Piagent.
 
 ## Watchdog opt-in
 
@@ -356,10 +330,10 @@ Recommended token policy:
 
 - default `safe` preset;
 - do not set `asyncByDefault` unless anh intentionally wants background-heavy workflow;
-- keep `/piagent-orchestration` at `solo-first` unless team has a measured reason to change it;
-- one writer at a time;
-- parallel reviewers/scouts are OK;
-- use `piagent-scout`/`piagent-planner` to compress context before handing off to `piagent-worker`;
+- giữ parent-direct và `PIAGENT_HELPERS_MODE=off` mặc định;
+- parent là writer duy nhất;
+- không parallel, nested, forked-history hay retry helper;
+- chỉ opt-in một read-only helper khi projected net saving từ 30%;
 - run `/subagents-fleet` to inspect background runs instead of asking parent model to recall everything.
 
 ## Nguồn