@piagent/platform 1.5.5 → 1.6.1

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,196 @@ 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 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
+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.
+
+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/
+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 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à
+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
+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. Đ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ế.
+
+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, 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
 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
 ```
 
+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, 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
+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 tại mỗi pause kiểm tra pair boundary, candidate outcome floor,
+baseline-pass/Piagent-fail, observed paired grade non-inferiority, exact accepted
+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
+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. 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.
+
+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,14 +326,34 @@ 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 |
+| `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
@@ -174,10 +391,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 +537,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 +550,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
@@ -399,11 +621,96 @@ 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
 đượ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 +783,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 +813,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 +827,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 +839,22 @@ 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;
+- 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
+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 +863,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 +906,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 +919,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 +1075,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.