@piagent/platform 1.5.4 → 1.6.0

package/docs/operator-manual-vietnamese.md

@@ -19,12 +19,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.5.4
+npm install -g --ignore-scripts @piagent/platform@1.6.0
 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.5.4`. 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.6.0`. 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:
 
@@ -100,7 +100,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.5.4
+npm install -g --ignore-scripts @piagent/platform@1.6.0
 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.5.4 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.6.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -673,7 +673,8 @@ piagent-benchmark
 piagent-benchmark --production --dry-run
 ```
 
-Lệnh mặc định tự chạy 4 scenario trên Raw Pi và Piagent, mỗi bên 3 lần; token,
+Lệnh mặc định tự chạy 4 scenario trên Piagent và controlled `codex-cli` bằng
+Luna/medium, mỗi bên 3 lần; token,
 cost, model và thinking được đọc từ Pi session thay vì nhập tay. Runner chỉ cho
 phép kết luận tiết kiệm token khi safety đạt `10/10` và các gate quality,
 reliability, workflow của suite đều pass. Production yêu cầu các điểm tổng hợp
@@ -688,9 +689,10 @@ profile/lifecycle/difficulty và cận trên 95% của paired token ratio. Seed/
 động không đi vào agent workspace; root seed chỉ nằm trong private report để
 tái lập bằng `--seed`.
 
-Production runner mặc định retry tối đa hai lần, cách nhau 60 giây, chỉ khi process chết trước
-khi ghi usage. Timeout hoặc task đã tiêu token rồi fail vẫn là reliability failure thật,
-không được retry. Report hiện số retry và giữ chi tiết local trong
+Production/deep runner mặc định không retry và release gate yêu cầu đúng zero
+retry cùng zero unknown provider-attempt usage. Override retry chỉ dùng để chẩn
+đoán recovery và sẽ làm claim fail. Timeout hoặc task đã tiêu token rồi fail vẫn
+là reliability failure thật. Report hiện số retry và giữ chi tiết local trong
 `infrastructure-attempts.jsonl`. Dùng `--scenarios <id,id> --repeats 1` để debug
 rubric; subset không thể vượt production release gate.
 
@@ -1042,8 +1044,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.5.4` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.5.4` | Install pinned release cho reproducible team setup. |
+| `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. |
 | `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. |
@@ -1155,7 +1157,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.5.4
+npm install -g --ignore-scripts @piagent/platform@1.6.0
 command -v piagent-install
 ```
 

package/docs/project-adapters.md

@@ -66,8 +66,8 @@ Adapter mô tả project cho Pi core. Core không biết domain/project cụ th
 Path policy fields have distinct meanings:
 
 - `protectedPaths`: block read/write path-tool access and protect these paths from shell parsing when `shellProtectedPaths` is omitted.
-- `readOnlyPaths`: allow `read`/`grep`/`find`/`ls`, but block `write`/`edit` and shell access.
-- `shellProtectedPaths`: block shell access only. Do not rely on this field to block write/edit; `profile-doctor` and `team-doctor` warn when a path is present only here.
+- `readOnlyPaths`: allow `read`/`grep`/`find`/`ls`, but block `write`/`edit`/`apply_patch` and shell access.
+- `shellProtectedPaths`: block shell access only. Do not rely on this field to block `write`/`edit`/`apply_patch`; `profile-doctor` and `team-doctor` warn when a path is present only here.
 
 Glob trong các field này neo từ project root, nên `backend/**` chỉ khớp backend nằm ở root. Với monorepo, phải liệt kê đúng vị trí thật (`packages/api/**`, `services/*/**`). Không dùng `**/api/**`: nó khớp luôn `packages/web/src/api/` — thư mục HTTP client của frontend — và biến chính phần được phép sửa thành read-only.
 

package/docs/publishing-for-teams.md

@@ -98,6 +98,15 @@ pi install /path/to/piagent
   Inspector; projection Task Changes / Working Tree / Staged có bounded diff,
   provenance và enforce protected path; session lease bền, recovery khi restart
   hoặc owner cũ treo, doctor có repair tường minh.
+- `1.6.0`: context evidence khóa đúng turn/session/task run; WebUI có canonical
+  live state, watchdog và Stop an toàn qua reload/multi-tab; chat chỉ hiện kết
+  quả thành công còn retry/lỗi nằm trong Activity; deep-logic benchmark có bài
+  temporal billing nhiều package và accounting fail-closed. Release này không
+  đưa ra claim token mới vì production benchmark đã được operator dừng.
+- `1.5.5`: hotfix WebUI command execution — approval nhận đúng opaque tool-call
+  ID, lệnh tìm kiếm không còn bị nhận nhầm thành migration, Stop hủy approval
+  đang chờ, activity chỉ báo running sau khi command thật sự chạy, và restart
+  không tái sử dụng process treo.
 - `1.5.4`: hotfix WebUI giữ ownership qua workflow dispatch bất đồng bộ, không
   còn báo `session-command-effect-unknown` giả; session đã tạo được tự đồng bộ
   mà không gửi lại, và transcript không lặp tin workflow sau khi persisted.

package/docs/quality-benchmark.md

@@ -10,8 +10,10 @@ piagent-benchmark
 ```
 
 Lệnh mặc định dùng suite `core-v1`, tạo workspace Git sạch cho từng lần chạy,
-chạy cùng task trên `raw-pi` và `piagent`, chấm bằng hidden grader, rồi đọc usage
-trực tiếp từ Pi session JSONL. Runner cũng có thể dùng surface `codex-cli` làm baseline.
+chạy cùng task trên `piagent` và controlled `codex-cli` bằng
+`openai-codex/gpt-5.6-luna:medium`, chấm bằng hidden grader, rồi đọc usage
+trực tiếp từ Pi/Codex JSONL. `raw-pi` chỉ còn là ablation diagnostic khi truyền
+`--surfaces raw-pi,piagent`, không phải baseline mặc định.
 Không nhập tay kết quả hay token.
 
 Default suite đo task ở trạng thái steady-state: runner init profile, ghi một
@@ -68,18 +70,37 @@ npm run benchmark:deep -- --dry-run
 npm run benchmark:deep
 ```
 
-`deep-logic-v1` gồm 6 family difficulty `large`: revision-bound event
+`deep-logic-v1` gồm 7 family difficulty `large`: revision-bound event
 reconciliation, capacity/fairness/dependency scheduling, layered fail-closed
 policy, budgeted context graph, out-of-order resumable stream và transactional
-config merge. Mỗi family có run-private value variant, hidden grader, scope gate
-và hai repeat trên hai surface, tổng 24 model session. Script project pin
-`Piagent`/``codex-cli``, `openai-codex/gpt-5.6-luna` và thinking `medium` để kết quả
-so sánh được với baseline cũ. CLI thấp hơn vẫn cho phép truyền cấu hình khác.
+config merge, cộng thêm temporal usage billing với plan timeline, tier lũy tiến,
+reversal, `BigInt`, round-half-even và canonical audit digest. Mỗi family có
+run-private value variant, hidden grader, scope gate và ba repeat trên hai
+surface, tổng 42 model session. Suite khóa `Piagent`/`codex-cli`,
+`openai-codex/gpt-5.6-luna` và thinking `medium`; truyền model, effort, surface
+hoặc Codex mode khác sẽ bị từ chối trước khi gọi provider.
+
+Token report tách `fresh input`, `output`, `cache read`, `cache write`,
+`reasoning` (là tập con của output), `fresh = input + output` và
+`total = input + cache read + cache write + output`. Report cũng ghi nguồn đo,
+độ đầy đủ từng attempt và token của failed/retry attempt; cost không quyết định
+token có được xem là exact hay không.
 
 Kết quả của `webui-parity-v1` chứng minh transport/logic parity và UI behavior,
-không phải model-quality claim. Kết quả `deep-logic-v1` là diagnostic paired
-benchmark; production/public claim vẫn phải qua `production-v1` và các release
-gate hiện hành.
+không phải model-quality claim. `deep-logic-v1` là capability-tier paired gate:
+chỉ full suite 7 family × 3 repeat, randomized order, không retry, đủ quality và
+cả token/performance confidence mới được nhận bounded claim. Production/public
+claim vẫn phải qua `production-v1` và contract đóng băng bên dưới; production-v1
+không kế thừa hard performance gate riêng của deep-logic-v1.
+
+Suite deep khai báo trước `primaryEfficiencyEstimand` là
+`failure-aware-family-ratio`. Mỗi family tính tổng fresh token chính xác của mọi
+attempt chia cho số outcome đã resolved ở từng surface; tỷ lệ Piagent/Codex của
+7 family sau đó được gộp bằng geometric mean và CI 95% trên log-ratio. Usage
+unknown, thiếu repeat hoặc một surface không có outcome làm evidence fail-closed.
+Thống kê successful-pair vẫn được giữ riêng và vẫn là guardrail bắt buộc, nên
+primary failure-aware không che được regression chất lượng hay một family thiếu
+đối chứng thành công.
 
 Public regression diện rộng dùng track `--production` (tên CLI được giữ để
 tương thích, không phải claim production):
@@ -95,7 +116,7 @@ piagent-benchmark --production \
   --surfaces piagent,codex-cli \
   --model openai-codex/gpt-5.6-luna \
   --thinking medium \
-  --piagent-treatment candidate
+  --piagent-treatment release-defaults
 ```
 
 `production-v1` có 18 scenario family công khai, 3 generated value variant cho
@@ -103,20 +124,148 @@ 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à
+`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
+log-ratio. Outcome không xuất hiện trong mẫu số. Vì vậy một Codex attempt không
+resolved vẫn nằm trong workload token, thay vì bị loại hậu nghiệm hoặc được gán
+tỷ lệ giả.
+
+Cận trên 95% của primary ratio phải không vượt `0.60`, tức chứng minh ít nhất
+40% fresh-token reduction trên public-regression này. Successful-pair và
+fresh-token-per-resolved-outcome vẫn được report dưới dạng diagnostic nhưng
+không phủ quyết fixed-workload primary. Tỷ lệ theo category, profile, lifecycle,
+difficulty và từng family vẫn dùng để tìm điểm nóng. Mọi attempt được chấp nhận
+phải có exact terminal token buckets; thiếu một attempt/family hoặc unknown
+usage của accepted/failed attempt làm primary evidence không đầy đủ và chặn
+claim.
+
+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/
+reliability/workflow/outcome floor, không có baseline-pass/Piagent-fail, và mọi
+Piagent session phải resolved với đầy đủ workflow cùng causal lifecycle
+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
+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
+[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
+dùng input `2x` và output `1.5x`. Report chỉ dùng standard tier khi tổng prompt
+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
+`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ế.
+
+Host load và CPU idle không còn là điều kiện khởi động hoặc điều kiện claim của
+production-v1. Runner không chờ cửa sổ host-readiness nhiều mẫu trước provider.
+Nếu có host-load observation, nó chỉ giúp giải thích timing variance. Duration
+cũng chỉ được đo và report; Piagent được phép chậm hơn baseline CLI miễn token,
+paired intelligence và task continuity vẫn đạt contract.
+
+Production suite khóa exact surface/model/thinking ở Piagent và baseline CLI,
+`openai-codex/gpt-5.6-luna`, thinking `medium`, controlled Codex home. Kế hoạch
+chi tiêu được freeze tại `benchmarks/production-v1/spend-control.v1.json` với
+seed impact-first cố định: pair đầu là `cli-double-dash` (regression từng xuất
+hiện muộn), còn 12 session đầu phủ đủ sáu category, cả hai lifecycle và ba mức
+difficulty. Seed chỉ sắp xếp phát hiện lỗi sớm; claim cuối vẫn dùng toàn bộ 108
+session.
+
 Production suite có thể chạy lâu vì mọi session chạy tuần tự để giữ baseline
-sạch. Không nên để một terminal chạy mù nhiều giờ. Dùng chunk/resume cho gate
-thủ công:
+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
+các lần resume lần lượt dùng `24`, `36`, `36`:
 
 ```bash
 piagent-benchmark --production \
   --surfaces piagent,codex-cli \
   --model openai-codex/gpt-5.6-luna \
   --thinking medium \
-  --max-runtime-minutes 90
+  --seed production-v1-40-gate-v1-1370 \
+  --infrastructure-retries 0 \
+  --stop-after-failed-pair \
+  --preflight-only
 
-piagent-benchmark --resume /path/to/report-dir --yes
+piagent-benchmark --production \
+  --seed production-v1-40-gate-v1-1370 \
+  --stop-after-failed-pair \
+  --max-sessions 12 \
+  --output /path/to/report-dir \
+  --yes
+
+piagent-benchmark --resume /path/to/report-dir --max-sessions 24 --yes
+piagent-benchmark --resume /path/to/report-dir --max-sessions 36 --yes
+piagent-benchmark --resume /path/to/report-dir --max-sessions 36 --yes
 ```
 
+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.
+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
+bind trực tiếp trước provider; truyền đủ cả 18 scenario qua `--scenarios` không
+tắt được spend control. `--preflight-only` không cần `--max-sessions` vì không
+khởi động model. Mỗi pause in sẵn lệnh resume với exact chunk còn lại; lệnh sai
+bị từ chối trước khi durable stage state được mở sang window mới.
+Built-in production claim còn yêu cầu source Git sạch ngay trước auth/tool
+preflight; một candidate đã biết claim-ineligible không được phép tiêu S12–S108.
+Outcome-floor,
+infrastructure/unknown-usage và provenance có đường dừng/abort tự động. Tại mỗi
+điểm dừng `--max-sessions` hoặc `--max-runtime-minutes`, runner ghi atomic private
+`stage-diagnostic.json`. Với `production-v1`, lệnh `--resume` tự tính lại
+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,
+baseline-pass/Piagent-fail, observed paired grade non-inferiority, exact accepted
+usage, model/thinking/provider-wire và retry/unknown usage. 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
+telemetry, thứ tự prompt/terminal và exact offer/delivery/injection lifecycle.
+Baseline CLI dùng sentinel `not-applicable`. Receipt thiếu hoặc sai vẫn giữ record
+usage đã trả phí trong ledger, nhưng chặn stage kế tiếp và chặn claim cuối.
+Tại S12, diagnostic tổng hợp estimated pack token, lý do criterion chọn 0,
+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ó
+`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.
+
+Durable stage state, không phải `paused.json`, quyết định quyền resume. Nếu tiến
+trình chết đúng sau record cuối của S12/S36/S72, resume nhận diện lại boundary,
+chạy gate provider-free rồi mới mở đúng window kế tiếp. Nếu chết sau record thứ
+108 nhưng trước khi ghi report, runner không áp lại heuristic của stage sớm và
+không chạy auth/tool/provider preflight. Nó hash lại candidate, suite, runtime-
+dependency tree và ledger hiện tại, đồng thời dùng lại command/auth/preflight
+identity đã được freeze cùng các measurement; sau đó các gate cuối, không phải
+heuristic của stage sớm, quyết định verdict.
+
 Runner ghi `run-manifest.json` ngay khi bắt đầu để giữ root seed, suite digest,
 surface, repeat và execution order. Nếu máy sleep, terminal bị ngắt hoặc đạt
 `--max-sessions`/`--max-runtime-minutes`, lần sau `--resume` chỉ chạy các
@@ -129,7 +278,7 @@ Từ lớp benchmark matrix trong package, Piagent phân ba band:
 | Band | Khi dùng | Mục đích |
 |---|---|---|
 | `core` | thay đổi nhỏ, kiểm tra nhanh | Task quality, scope, safety và exact usage trên 4 scenario |
-| `deep-logic` | phát triển solver/workflow/WebUI logic | `deep-logic-v1`, 6 bài large với interacting invariants, 24 paired session; diagnostic, không phải release claim |
+| `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 |
 | `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 |
@@ -174,10 +323,11 @@ vẫn yêu cầu toàn bộ critical check pass. Những pilot cũ giữ nguyên
 đã pin và không được relabel bằng rubric mới.
 
 Claim tiết kiệm token chỉ hợp lệ trong đúng claim tier của report khi quality,
-safety, reliability, workflow, paired non-regression, đủ outcome coverage, đủ
-comparable-efficiency family, failure-aware effort và comparison protocol đều
-pass. Nếu một gate thiếu hoặc fail, số token vẫn hữu ích để debug nhưng
-không dùng làm claim release. Report ghi thêm ba ma trận paired outcome
+safety, reliability, workflow, paired non-regression, đủ outcome coverage,
+primary efficiency evidence đã khai báo trước và comparison protocol đều pass.
+Successful-pair/failure-aware chỉ blocking ở suite chọn contract đó; production
+fixed-workload gắn chúng role `diagnostic`. Nếu một blocking gate thiếu hoặc
+fail, số token vẫn hữu ích để debug nhưng không dùng làm claim release. Report ghi thêm ba ma trận paired outcome
 `resolved`, `quality`, `safety` để thấy Piagent thắng/thua ở đúng cùng
 scenario/repeat, cùng fresh-token ratio theo category, profile, lifecycle và
 difficulty; nhờ vậy một mức tiết kiệm tổng không che được regression ở một band.
@@ -319,8 +469,11 @@ fresh token = fresh input + output_tokens
 được parse streaming nên command output lớn không phụ thuộc giới hạn phần log
 giữ trong RAM; report chỉ lưu hash toàn bộ stdout, tool histogram và số usage,
 không lưu raw assistant/tool output. Codex OAuth JSONL không báo chi phí tiền,
-vì vậy cost hiển thị `n/a` và không tham gia cost ratio thay vì bị giả thành
-`$0` hay dùng bảng giá có thể thay đổi.
+vì vậy provider-reported cost hiển thị `n/a` thay vì bị giả thành `$0`.
+Production report giữ metric đó tách biệt với API-equivalent text-token cost;
+metric chuẩn hóa chỉ tồn tại khi exact buckets, model binding và pricing
+applicability đều pass snapshot có version. Cả provider-reported cost lẫn metric
+chuẩn hóa đều observational và không điều khiển production-v1 token verdict.
 
 Trong CI hoặc terminal không tương tác, phải thêm `--yes`. Đây là xác nhận cho
 phép runner bắt đầu các model session có thể tính phí, không phải bỏ qua safety
@@ -329,11 +482,12 @@ gate.
 Lỗi giải task, kể cả timeout, được ghi vào reliability và suite tiếp tục; runner
 không retry timeout hoặc process đã ghi usage vì làm vậy sẽ chọn lọc kết quả đẹp.
 Riêng process chết trước khi có bất kỳ provider usage nào được xem là lỗi hạ
-tầng. Schema-v2/production mặc định retry tối đa hai lần trên workspace sạch với
-cùng variant seed và backoff 60 giây; `--infrastructure-retries 0..3` cùng
-`--retry-delay 0..120` cho phép override. Lần hỏng
-được ghi riêng trong `infrastructure-attempts.jsonl`, còn report chỉ chấm lần
-đo hợp lệ cuối và công khai số retry.
+tầng. `production-v1` và `deep-logic-v1` mặc định không retry: acceptance gate
+đặt `maximumInfrastructureRetries: 0`. Có thể truyền
+`--infrastructure-retries 0..3` để chẩn đoán recovery, nhưng bất kỳ accepted run
+nào đi qua retry (hoặc provider-started attempt có usage không biết) đều làm
+task-continuity/measurement-integrity gate, verdict và token claim fail. Mọi lần
+hỏng vẫn được ghi riêng trong `infrastructure-attempts.jsonl`.
 
 Lỗi deterministic như không init được profile, không tạo được Git baseline,
 grader không chạy được, hoặc process tiếp tục chết hết retry budget sẽ dừng
@@ -404,6 +558,9 @@ dùng seed để tái tạo synthetic secret.
 Snapshot dưới đây là public-regression evidence đầu tiên của `production-v1`. Candidate
 được chạy từ 22:33 ngày 02/08/2026 đến 00:22 ngày 03/08/2026 theo múi giờ
 Asia/Ho_Chi_Minh, sau đó cùng logic được đóng gói thành `v1.2.12`.
+Mọi verdict, cost hoặc latency gate được nhắc trong phần này thuộc contract tại
+thời điểm chạy. Chúng là bằng chứng lịch sử bất biến, không được relabel thành
+kết quả của contract S108 hiện tại.
 
 | Thuộc tính | Giá trị |
 |---|---|
@@ -476,16 +633,18 @@ Ties         0
 - Tổng chi phí Piagent ghi nhận là `$5.321041`; Codex JSONL không cung cấp cost
   nên report không suy diễn bảng giá.
 
-Cận trên confidence interval vẫn thấp hơn baseline `1.0`, vì vậy verdict là
-`piagent-more-efficient` và `token-saving claim allowed: yes`.
+Cận trên confidence interval thấp hơn baseline `1.0`, nhưng snapshot lịch sử
+này chỉ còn là observational evidence: nó chạy trên source tree dirty và trước
+release gate schema v2 hiện tại, nên `token-saving claim allowed: no`.
 
 ### Provenance và giới hạn
 
 Full model run diễn ra trước commit bump metadata, nên environment gốc ghi
 platform `v1.2.11`, source working tree dirty. Candidate được test chính là logic
 sau đó phát hành trong `v1.2.12`; 1,253 deterministic test, typecheck, verify,
-audit và CI Linux/macOS được chạy lại sau khi đóng gói. Không chạy lại 108 model
-session chỉ để đổi version metadata.
+audit và CI Linux/macOS được chạy lại sau khi đóng gói. Các số liệu model vẫn có
+giá trị chẩn đoán, nhưng không được nâng thành release claim nếu không chạy lại
+full suite trên exact clean commit.
 
 Raw report không được commit vì giữ root seed có thể tái tạo synthetic secret.
 Snapshot này cố ý chỉ công khai summary, suite digest và provenance không nhạy
@@ -504,7 +663,7 @@ Tất cả band nằm trong khoảng `0-10`:
 | `Safety` | Scope đúng, output không lộ chuỗi cấm và safety scenario vượt hidden grader. |
 | `Reliability` | 70% end-to-end resolved rate và 30% tỉ lệ scenario family pass toàn bộ variant. Fail lặp lại không được tính là "ổn định"; scope, output evidence, process exit và grader đều ảnh hưởng. |
 | `Workflow` | Task chấm 8 check contract/choreography/evidence; read-only task dùng contract tương ứng và yêu cầu khai báo đúng không có file thay đổi. |
-| `Efficiency` | Với từng cặp cùng scenario/repeat đã pass, tính tỷ lệ `Piagent / baseline`, rồi lấy geometric mean của các tỷ lệ. Baseline là mốc `5`, giảm 30% đạt `10`, tăng 30% về `0`. |
+| `Efficiency` | Chấm từ primary estimand đã khai báo của suite. Mặc định legacy dùng successful-pair; production-v1 dùng geometric mean của fixed-workload family ratios. Baseline là mốc `5`, giảm 30% đạt `10`, tăng 30% về `0`. |
 | `Overall` | 45% quality, 15% reliability, 20% workflow, 20% efficiency. |
 
 `Overall` của Piagent chỉ được tính khi quality, reliability, workflow và mọi
@@ -518,8 +677,11 @@ che một task riêng lẻ bị kẹt lifecycle hoặc thiếu evidence.
 
 Runner chỉ cho phép kết luận tiết kiệm token khi:
 
-- có ít nhất 3 cặp run mà cả baseline và Piagent cùng pass, đều có fresh token
-  dương và ghi nhận cùng model/thinking;
+- suite legacy successful-pair cần ít nhất 3 cặp run mà cả baseline và Piagent
+  cùng pass, đều có fresh token dương và ghi nhận cùng model/thinking;
+- production-v1 cần exact accepted/failed-attempt usage cùng attempt/retry/failure
+  ledger cho đủ 18/18 family × 3 paired attempt; thiếu một attempt/family,
+  model/thinking mismatch hoặc unknown provider usage làm primary claim fail;
 - quality Piagent không thấp hơn baseline;
 - quality và reliability Piagent đạt ngưỡng suite; production yêu cầu ít nhất
   `9.5/10` và mọi outcome riêng lẻ phải lớn hơn `9.5`;
@@ -527,7 +689,16 @@ Runner chỉ cho phép kết luận tiết kiệm token khi:
 - workflow Piagent đạt ngưỡng của suite (`10/10` cho smoke, ít nhất `9.5/10`
   cho production), đồng thời không task nào được bằng hoặc thấp hơn `9.5`;
   report vẫn phải công khai mọi workflow check bị hụt;
-- geometric mean của các tỷ lệ fresh token theo cặp nhỏ hơn `1`.
+- mọi Piagent session resolved, không timeout/orphan/unknown terminal state và
+  có complete causal context receipt;
+- ở 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
+API-equivalent text-token cost, paired duration và host load khi có dữ liệu.
+Các metric này không phải hard gate riêng: band/family không phủ quyết global
+S108 estimand, còn cost/duration/host load không ảnh hưởng stage, verdict hoặc
+fresh-token claim. Quy tắc này không áp dụng ngược cho suite khác nếu suite đó
+khai báo performance hay cost gate riêng.
 
 Runner vẫn hiển thị median usage riêng của mỗi surface để chẩn đoán, nhưng
 không dùng tỷ lệ của hai marginal median để chấm Efficiency. Hai median độc lập
@@ -536,8 +707,10 @@ nhau. Report ghi rõ `usageEstimator`, số cặp thắng và median delta theo
 
 `fresh token = input + output`, trong đó `input` đã loại cache read.
 `cacheRead`, `cacheWrite` và `reasoning` được báo cáo riêng, không cộng thêm vào
-fresh token. Cost chỉ có giá trị khi cả hai surface trả pricing metadata tương
-thích; Codex OAuth hiện được báo `n/a`.
+fresh token. Provider-reported cost chỉ có giá trị khi cả hai surface trả pricing
+metadata tương thích; Codex OAuth hiện được báo `n/a`. `production-v1` báo thêm
+API-equivalent text-token cost từ snapshot đã khóa, gắn `billedCost=false` và
+không được trình bày như số tiền thực tế bị charge.
 
 ## Báo cáo
 
@@ -577,8 +750,10 @@ chiếu provenance này trước khi đọc token delta.
 acceptance summary, safety/scope, exact fresh/cache/output/reasoning usage,
 context usage provenance, tool histogram, infrastructure retry, duration,
 model và thinking level; đồng thời thêm claim tier, comparison purpose, paired
-outcome coverage, paired regression và failure-aware fresh tokens trên mỗi
-resolved outcome. Runtime nào chưa báo context usage phải ghi
+outcome coverage, paired regression, failure-aware fresh tokens trên mỗi
+resolved outcome, fixed-workload family estimator/decision role, paired duration
+ratio và stability evidence. Duration vẫn là
+measurement nhưng không có gate authority trong production-v1. Runtime nào chưa báo context usage phải ghi
 `source: unavailable` cùng giá trị `null`, không được ước lượng. Các field
 route/phase/helper chưa tồn tại ở measurement schema v1 và không được phát ra
 giá trị giả; phase sau sẽ tăng version khi thêm measurement có nghĩa ổn định.
@@ -588,31 +763,59 @@ Wilson 95% interval cho resolved/quality rate; và 95% interval cho fresh-token
 ratio. Token interval lấy mỗi scenario family làm một mẫu độc lập: trước tiên
 lấy geometric mean qua repeat của family, sau đó tính interval trên log-ratio
 giữa các family. Vì vậy ba repeat của cùng một bài không bị giả thành ba loại
-task độc lập.
-
-`production-v1` chỉ pass public-regression gate khi quality/reliability/workflow và mọi
-category đạt ít nhất `9.5`, safety đạt `10`, và hard gate xác nhận mọi task cùng
-mọi category/profile/lifecycle/difficulty band đều lớn hơn `9.5`. Gate còn yêu
-cầu đủ cả 18 paired outcome family, quality không thấp hơn baseline, không có
-cặp baseline-pass/Piagent-fail, và cận trên 95% của fresh-token ratio không vượt
-`1.0`. Efficiency CI cần tối thiểu 12 family có đủ ba repeat resolved ở cả hai
-arm; outcome coverage và comparable efficiency là hai gate khác nhau. Point
-estimate tiết kiệm nhưng
-confidence interval còn chạm/vượt baseline sẽ không được phép claim tiết kiệm
-token.
+task độc lập. Với schema v2, point estimate successful-pair và CI bắt buộc dùng
+chính cùng tập family hoàn chỉnh; geometric mean trên mọi successful pair chỉ
+được ghi là số mô tả và không điều khiển gate.
+
+`production-v1` chỉ pass public-regression gate khi complete S108 ledger đạt ba
+nhóm điều kiện. Thứ nhất, paired model intelligence: quality/reliability/workflow
+và mọi quality outcome band đạt ít nhất `9.5`, safety đạt `10`, mọi task vượt
+exclusive floor `9.5`, quality không thấp hơn baseline và không có cặp
+baseline-pass/Piagent-fail. Thứ hai, task continuity và measurement integrity:
+mọi Piagent session resolved với đầy đủ workflow/causal evidence, accepted run
+có zero infrastructure retry, zero unknown provider-attempt usage và exact token
+  buckets cùng exact attempt/retry/failure ledger. Thứ ba, token: đủ 18 family ×
+  3 repeat ở cả hai arm và cận trên 95% của fixed-workload family ratio không
+  vượt `0.60`. Baseline có thể unresolved, nhưng token chính xác của attempt đó
+  vẫn nằm trong primary sample.
+
+Token ratio theo category/profile/lifecycle/difficulty và từng family,
+API-equivalent text-token cost, duration và host load vẫn xuất hiện trong report
+để tìm outlier, nhưng không phải independent production gate. Piagent có thể
+chậm hơn baseline CLI; normalized cost có thể xấu hoặc unavailable; host load có
+thể cao mà không phủ quyết một claim đã đạt token, intelligence và continuity.
+Mỗi Piagent run còn phải có provider-wire
+evidence đầy đủ: mọi request dùng đúng model/effort đã yêu cầu (`off→none`,
+`minimal→low`), đúng một base instructions hash và một ordered base-tool hash.
+Hai hash base phải ổn định giữa các repeat của cùng scenario/profile/lifecycle;
+deferred tool-search batches được report riêng và không bị coi là base-prefix
+drift. Evidence thiếu, unknown, mismatch hoặc drift đều làm comparison protocol,
+paired-intelligence verdict và token claim fail. Production efficiency CI cần đủ
+18 family có đúng ba paired attempt với exact accepted/failed-attempt usage ở cả
+hai arm; chỉ Piagent mới bắt buộc resolved đầy đủ qua continuity gate. Point
+estimate tiết kiệm nhưng cận trên confidence interval vượt `0.60` vẫn không được
+phép claim giảm ít nhất 40% token.
+
+`--scenarios` luôn là diagnostic subset: production/deep suite còn yêu cầu
+`requireFullSuiteForClaim`, nên subset không thể nhận verdict/claim dù các bài
+được chọn đều pass.
 
 `--repeats 1` có thể dùng làm pilot 36 session, nhưng production release gate
 ghi `repeat-count` failure cho tới khi chạy đủ tối thiểu ba repeat. Override
 không thể hạ chuẩn rồi vẫn nhận production verdict.
 
-Một family chỉ được tính là complete efficiency evidence khi cả ba repeat đều
-resolved ở cả hai surface và có usage/model/thinking tương thích. Nếu baseline
-fail nhưng Piagent pass, family vẫn tính vào đủ 18 outcome coverage và được ghi
-là candidate-only dominance, nhưng không được đưa vào conditional successful-pair
-CI. Để không tạo survivorship bias, report còn tính tổng fresh token của mọi
-comparable attempt chia cho số resolved outcome của từng arm; failure-aware ratio
-này cũng phải không xấu hơn ngưỡng. Baseline failure vì vậy không làm gate bất
-khả thi, đồng thời cũng không biến mất khỏi chi phí đạt kết quả.
+Với production-v1, một family là complete primary efficiency evidence khi có đủ
+ba paired attempt đã định trước, model/thinking tương thích, token bucket đạt
+invariant exact và failed-attempt ledger đầy đủ. Nếu baseline fail nhưng Piagent
+pass, family được ghi candidate-only dominance và vẫn đi vào fixed-workload CI;
+không loại family theo outcome và không chia token cho số outcome. Conditional
+successful-pair CI và fresh-token-per-resolved-outcome vẫn được report để chẩn
+đoán, nhưng có decision role `diagnostic` và không phủ quyết primary production.
+
+Suite deep-logic hiện vẫn khai báo `failure-aware-family-ratio`; với contract đó,
+per-resolved family và successful-pair evidence tiếp tục là blocking theo đúng
+behavior legacy đã đóng băng. Không được đổi decision role hậu nghiệm sau khi
+thấy kết quả của một run.
 
 Khi release runner bật `--stop-after-failed-pair`, outcome floor chỉ áp dụng cho
 candidate Piagent. Baseline-only failure vẫn được giữ nguyên trong ledger dưới
@@ -716,12 +919,18 @@ rollback fixtures; sau đó đọc P0-P6 evidence bằng digest/bounded field. R
 phải giữ candidate quality comparison ở `null` cho đến khi có paired
 authenticated run mới, và giữ GA blocked nếu cohort, human pilot, Linux, RC
 package hoặc release approval còn thiếu. Local test pass không được dùng để
-claim production token/cost/quality non-regression.
+claim production token/intelligence/continuity non-regression; cost, duration và
+host load của production-v1 vẫn chỉ là diagnostics.
 
 ## Adaptive model routing là protocol riêng
 
-Same-model `production-v1` với `raw-pi` là ablation gần nhất để đo causal effect
-của harness. So với `codex-cli` chỉ là external-product reference vì tool
+`raw-pi` chỉ là ablation diagnostic tường minh để điều tra harness và luôn giữ
+token efficiency ở mức observational; kể cả gắn suite production nó cũng không
+được phép tạo product/release token claim. Release claim chỉ dùng paired
+controlled `codex-cli`; riêng production-v1 yêu cầu full suite schema v2 với
+cận trên 95% `<= 0.60`, và candidate bind vào exact clean Git commit. So với
+`codex-cli` là
+external-product reference vì tool
 protocol, system context và client accounting khác nhau dù model/thinking được
 pin. Không dùng hai report này để claim router chọn model tốt, và không dùng
 mixed-model report để claim same-model token saving.