@piagent/platform 1.5.5 → 1.6.1

package/CHANGELOG.md

@@ -4,6 +4,172 @@ This file records release-facing changes for Pi Agent Platform. Copy the relevan
 
 ## Unreleased
 
+## v1.6.1 - 2026-08-26
+
+### Runtime continuity and truthful WebUI state
+
+- Kept queued same-session work under one operation identity and prevented a
+  pending durable task from emitting a completed message or a success bubble.
+  Final-looking drafts remain hidden until the task reaches a terminal state,
+  preserving user-message then assistant-response ordering without a stale
+  processing indicator.
+- Reconciled Activity from canonical tool evidence. Handled multi-target search
+  warnings finish normally, nested result envelopes are classified correctly,
+  and rejected or evidence-free helper calls remain visible as failures instead
+  of later replaying as passed.
+- Captured the latest real operator request for model-owned task startup while
+  bounding and redacting the durable copy, so attachments and workflow wrappers
+  no longer replace the user's actual intent.
+
+### Safe external source review
+
+- Detects GitHub, GitLab and Bitbucket references and activates only the minimal
+  source-checkout surface needed for a review. A successful checkout grants
+  session-scoped read access to that exact canonical tree, with an eight-source
+  bound and automatic cleanup at session end.
+- Preserved protections around shared caches, sibling paths, symlink escape,
+  credentials, `.env`, `.git` and all mutation paths. Read-only inspection may
+  use bounded `read`, `grep`, `find` and `ls` flows without widening the project
+  mutation contract.
+
+### Solo-first cost and context controls
+
+- Added direct subagent preflight with a one-helper ceiling, bounded calls,
+  turns and runtime, read-only role enforcement, no automatic retry/fork/worker
+  expansion, and truthful durable helper usage. Repeated helper results are
+  compacted without changing the model or thinking level.
+- Hardened adaptive context accounting, exact verifier reuse, task-evidence
+  refresh and bounded runtime emission so token-saving decisions fail closed
+  when evidence is incomplete and cannot be relabeled as a Codex-relative cost
+  claim.
+
+### Benchmark assurance
+
+- Added provider-free runtime-conformance and Codex-relative efficiency gates,
+  bound token/cost evidence to exact workload and provider attempts, and kept
+  the historical v1.6.0 production result explicitly separate from any new
+  subscription-spend or 30–40% cost claim.
+- Preserved the 108-session production gate as an operator-authorized quota
+  step; this release ships runtime and benchmark safeguards without claiming a
+  new provider-backed result.
+
+## v1.6.0 - 2026-08-24
+
+### Context efficiency and source safety
+
+- Replaced overlapping automatic discovery and criterion snapshots with one
+  criterion-aware initial pack. It prioritizes explicit targets and their
+  linked tests, excludes unrelated graph-only files, uses bounded snippets for
+  large files and records content/payload receipts for every injected item.
+- Corrected context-efficiency accounting so exact repeated reads are measured
+  only within a session/task/model/thinking partition, missing evidence remains
+  visible as unavailable, fallback rereads do not reward retrieval ranking, and
+  tool-schema share is reported against the complete system-plus-tool prefix.
+  Duplicate-output and retrieval-confidence rates now exclude unclassified
+  historical rows and expose their partial coverage instead of treating them
+  as zero waste. The aggregate context-waste score is now `null` unless every
+  weighted telemetry lane is complete; partial data is labeled only as a
+  diagnostic estimate.
+- Sanitized automatic source snapshots before provider injection while
+  preserving pure dynamic credential references. Sensitive literals, including
+  short values and numeric fallbacks, are redacted in common source syntax and
+  structured YAML, XML, HTML, CSS and Objective-C inputs with line-count-
+  preserving receipts. A redacted item retains only a digest of the sanitized
+  text; neither the raw-content digest nor another guessable verifier for the
+  original bytes is persisted. Sanitization of deeply nested calls is bounded.
+- Preserved one planned criterion source and its focused test when retrieval is
+  unavailable or stale, and retained complete per-item receipts for automatic,
+  command and tool-delivered context packs.
+- Cleared task identity, repeated-result state and pending context delivery at
+  terminal boundaries while preserving terminal-turn usage attribution. A new
+  request or workflow in the same session now starts clean, including after a
+  missing binding or terminal session restart.
+
+### Forty-percent benchmark contract and spend control
+
+- Raised the canonical production-v1 contract to require a fixed-workload,
+  family-clustered fresh-token upper-95 ratio at or below `0.60`. The estimator
+  includes all three predeclared attempts per surface in every family, including
+  exact provider-started failed-attempt usage, and does not condition token
+  measurement on task outcome. Every declared scenario/repeat must still have
+  an exact finite grade pair with no Piagent quality regression, and all Piagent
+  sessions must satisfy the independent continuity gates.
+- Added a separate GPT-5.6 Luna API-equivalent text-token cost diagnostic. It
+  prices exact text-token buckets, remains distinct from OAuth/provider billing,
+  and does not block the token-focused production claim.
+- Added duration comparison globally, by workload band and by family as
+  observational evidence. The canonical contract allows Piagent to be slower
+  when fresh-token, paired-intelligence and task-continuity gates still pass.
+- Froze production-v1 to Luna Medium and a ledger-bound S0/12/36/72/108 spend
+  sequence. Only S108 is claim-eligible; every earlier pause recomputes a
+  provider-free diagnostic and prints the exact bounded resume command.
+- Bound seed, surfaces, model, thinking, repeats, zero retries, paired terminal
+  stop and clean source identity before paid work. Reserved built-in suite IDs
+  cannot be impersonated by external suites, including through direct report
+  summarization.
+- Added a privacy-safe causal context receipt for every Piagent measurement.
+  The receipt binds telemetry provenance, current prompt/terminal order and the
+  exact offer/delivery/injection lifecycle before dropping paths, hashes and
+  identifiers. Missing, malformed, orphaned or mismatched evidence preserves
+  the paid ledger row but blocks S12 advancement and the final token claim.
+  S12 now reports aggregate pack tokens, zero-selection reasons, managed-prefix
+  compaction, successful direct fallback reads and shell-call exposure.
+- Reconstructs a missing terminal stop from the accepted ledger before any paid
+  resume, so a crash between the durable append and stop marker cannot spend the
+  rest of an authorized window.
+- Finalizes a complete ledger or valid final post-guard WAL without live auth,
+  provider preflight or installed Pi/Codex executables. Finalization rehashes the
+  current candidate, suite, runtime-dependency tree and ledger while reusing the
+  frozen command/auth/preflight identities bound to the accepted measurements.
+- Preserved the completed 108-session r3 ledger as observational evidence under
+  its original successful-pair contract. It is not retroactively promoted: only
+  a new provider run on the exact final candidate, after this estimand and suite
+  digest are frozen, can approve a 40% claim.
+
+### Runtime intelligence and context integrity
+
+- Bound context evidence to the exact turn, session and task run that observed
+  it. Planning selections no longer masquerade as delivered context, and stale
+  evidence cannot cross a task boundary or complete a later task.
+- Added bounded context-efficiency telemetry, delivery qualification, prefix
+  accounting and provider-wire fingerprints without exposing prompts,
+  credentials or raw provider payloads.
+- Preserved authenticated Codex model identifiers and supported reasoning
+  levels end to end. New installations default visibly to GPT-5.6 Sol with
+  High thinking while still allowing the user to choose another available
+  model for any message or session.
+- Added one fail-closed CAP-12 correction after a current exact verifier when
+  the model discovers an omission in a file it already authored in the same
+  task/run/session. The runtime opens repair only after an exact structured
+  mutation succeeds, permits no second source edit, and requires the exact
+  verifier again before completion.
+
+### WebUI continuity and operator clarity
+
+- Added a canonical live-state bootstrap and replay-gap recovery path so reloads
+  and multiple browser tabs agree on the running operation before reporting the
+  Gateway as live.
+- Added inactivity, absolute-runtime, termination and projection watchdogs.
+  Concurrent Stop requests share one termination, and uncertain ownership is
+  quarantined instead of being projected as an idle session.
+- Kept the conversation surface success-only: drafts, tool failures, retries,
+  completion-gate work in progress and abort details stay in Activity. Empty or
+  non-rendering provider output can no longer create a blank success bubble.
+- Made operation settlement first-terminal-wins and retained recent failures
+  independently from high-volume event traffic, preventing a retry or catalog
+  refresh from presenting contradictory outcomes.
+
+### Deeper benchmark and assurance contracts
+
+- Expanded the deep-logic benchmark with a multi-package temporal billing close
+  problem, stricter held-out variants, provider-wire checks, usage provenance,
+  statistical comparison gates and explicit Codex CLI controls.
+- Hardened benchmark accounting so unknown usage, infrastructure retries or an
+  unmatched provider attempt cannot support a token or production claim.
+- A provider-backed token-reduction claim is published only when a complete
+  zero-retry 108-session run passes on the exact clean tagged candidate. An
+  interrupted, historical or different-SHA run remains diagnostic evidence.
+
 ## v1.5.5 - 2026-08-21
 
 ### WebUI command execution hotfix

package/README.md

@@ -112,22 +112,26 @@ Removal targets what is registered in Pi's settings rather than what the current
   data, platform, reliability, and security. It compares Piagent with Raw Pi or
   controlled `codex-cli`, grades hidden acceptance/safety/workflow evidence,
   reports category/lifecycle/profile bands and 95% token-ratio confidence, and
-  reads exact JSONL usage plus privacy-safe tool histograms. Production runs
-  retry only zero-usage startup failures and disclose every retry separately.
-- `deep-logic-v1` adds six large, generated-variant families for interacting
-  state, orchestration, policy, context-graph, stream-recovery, and
-  transactional-config invariants. It keeps the current Pi model by default
-  and uses two repeats (24 paired sessions). A separate provider-free WebUI
+  reads exact JSONL usage plus privacy-safe tool histograms. Production claims
+  require zero retries; diagnostic retry overrides remain visible and fail the gate.
+- `deep-logic-v1` adds seven large, generated-variant families for interacting
+  state, orchestration, policy, context-graph, stream-recovery,
+  transactional-config, and exact temporal-billing invariants. It locks
+  Piagent/`codex-cli` to Luna/medium and uses three repeats (42 paired sessions) with token, duration,
+  full-suite, and zero-retry gates. A separate provider-free WebUI
   parity gate proves the 10 workflow and 32 runtime-control paths before any
   model quota is used.
-- The v1.2.12 production snapshot resolved 54/54 Piagent tasks, scored 10.00 for
-  quality/safety/reliability, 9.58 for workflow, 10.00 for efficiency, and 9.92
-  overall. Against controlled `codex-cli` on the same `gpt-5.6-sol`/`xhigh`
-  matrix, Piagent used 51.11% fewer paired fresh tokens with a 95% ratio interval
-  of `0.3809..0.6276`; see the [benchmark evidence](https://piagent.io.vn/benchmark)
-  and [methodology](docs/quality-benchmark.md). This is immutable historical
-  evidence; current production gates additionally require every task and score
-  band to exceed 9.5, so aggregate 9.58 alone is no longer sufficient.
+- The public `v1.6.0` production-v1 run
+  `production-v1-20260824T040017Z-05b7cf`, on exact commit
+  `3bba8f0b3ff521bc2a355e1f6bef6d1bbdc09511` with GPT-5.6 Luna Medium,
+  measured 108 sessions. Piagent resolved 54/54 tasks versus 48/54 for
+  `codex-cli`. Its primary fixed-workload family fresh-token ratio was `0.3857`
+  (61.43% lower), with a 95% interval of `0.3073..0.4840`; the upper bound
+  supports the conservative statement of at least 51.60% fewer fresh tokens on
+  this predeclared workload and exact release. Usage was exact for all 108
+  sessions and no retry occurred. See the
+  [benchmark evidence](https://piagent.io.vn/benchmark) and
+  [methodology](docs/quality-benchmark.md).
 - Built-in profiles for frontend, backend, fullstack, BE-readonly/FE-write, data, DevOps, mobile, docs, Python, and Node TypeScript.
 - Versioned capability packs with deterministic catalog, profile resolution, integrity lock, and permission checks.
 
@@ -137,7 +141,7 @@ Project profiles can declare a runtime `permissionProfile`:
 
 | Profile | Use when | Guard behavior |
 |---|---|---|
-| `read-only` | Scout, audit, review | Allows `read`, `grep`, `find`, `ls`, and piagent state tools; blocks shell, write/edit, and unknown tools. |
+| `read-only` | Scout, audit, review | Allows `read`, `grep`, `find`, `ls`, and piagent state tools; blocks shell, `write`/`edit`/`apply_patch`, and unknown tools. |
 | `workspace-write` | Normal implementation | Default profile. Keeps current protected-path, shell, capability, task, and verify gates. |
 | `trusted-full-access` | Trusted local automation | Expands workspace tool/scope autonomy, but still enforces protected paths, secret redaction, capability lock integrity, and destructive/external confirmation. |
 
@@ -156,9 +160,9 @@ Inside an active Pi session, use `/permission` for the menu or a session-local s
 
 Legacy aliases still work: `/permission-status`, `/read-only`, `/workspace-write`, and `/full-access`. Full-access also accepts a task after the command. The guard switches the current session to `trusted-full-access`, then forwards the remaining text as the next user request.
 
-## Solo-first orchestration
+## Parent-direct orchestration
 
-Pi Agent Platform supports subagents, but the default operating model is solo-first: one parent agent owns the task contract, uses explicit review lenses, and only calls bounded subagents when scout/planning/review work is independent enough to justify the extra token/tool cost.
+The parent model owns reasoning, implementation, and verification. Helpers are off by default. With explicit opt-in, runtime may dispatch one fresh read-only helper only when it proves two independent lanes and at least 30% projected net token saving after handoff and merge. Workers, retries, nested helpers, and parallel helpers remain disabled.
 
 Inside Pi:
 
@@ -166,7 +170,7 @@ Inside Pi:
 /piagent-orchestration
 ```
 
-This shows the active mode, max subagents, review lenses, Field Guide path, and writer policy without triggering a model follow-up.
+This shows the active mode, one-helper ceiling, review lenses, Field Guide path, writer policy, and dispatch/skip evidence without triggering a model follow-up.
 
 For bounded source work, runtime creates the session-bound contract before the
 model starts and injects its path scope plus concise verifier. Broad, high-risk,
@@ -267,9 +271,9 @@ Keep provider keys in environment variables, never in committed config. Switchin
 
 ## Subagents
 
-`piagent-setup` installs `pi-subagents` with the `safe` preset and `pi-web-access` for web-backed researcher runs unless disabled. Daily task prompts stay solo-first: they delegate bounded scout, planning, research, and review work only when it is independent enough to be worth the cost, and the final handoff states whether subagents were used and why.
+`piagent-setup` installs the optional `pi-subagents` compatibility runtime with a clamped `safe` preset. Daily tasks stay parent-direct; builtin agents and workers are disabled, and explicit helper mode still requires the measured 30% gate. The inspector states dispatch/skip reasons and projected saving.
 
-`/subagents-doctor` runs a health check; `/run piagent-scout "…"` and its planner, worker, and reviewer counterparts dispatch work. See [Subagents and multi-agent](docs/subagents-and-multiagent.md).
+`/subagents-doctor` runs a health check. See [Subagents and multi-agent](docs/subagents-and-multiagent.md) for the one read-only helper opt-in contract.
 
 ## Repository layout
 
@@ -359,7 +363,7 @@ This repository intentionally excludes:
 
 ## Maturity
 
-The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.5.5` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.6.1` or a reviewed commit.
 
 Ready for:
 

package/README.vi.md

@@ -29,6 +29,7 @@ Trong session Pi đầu tiên của project, chạy `/onboard`. Hằng ngày, d
 - Mỗi task dùng một session có tên rõ ràng.
 - Slash command chỉ chạy handler đã đăng ký; agent không phải scout lại command.
 - Prompt hướng dẫn model, còn policy quan trọng được enforce tại runtime.
+- Permission `read-only` chỉ cho phép kiểm tra; shell và các tool ghi `write`/`edit`/`apply_patch` đều bị chặn.
 - MCP config không chứa token hoặc OAuth credential.
 - Task source-changing cần scope, verify evidence và final gate.
 - Local state nằm trong `.pi/piagent-state/`, có owner-only permission và bounded retention.
@@ -46,6 +47,20 @@ chưa ship solver hoặc automatic parent routing. Host execution là mặc đ
 yêu cầu isolation backend chưa có adapter, mutation bị block thay vì âm thầm
 fallback về host.
 
+## Điều phối parent-direct
+
+Parent model tự sở hữu suy luận, implementation và verification. Helper mặc định
+tắt. Khi operator chủ động bật, runtime chỉ được dispatch tối đa một helper
+read-only dùng context fresh nếu chứng minh có hai lane độc lập và tổng token dự
+kiến sau handoff/merge giảm ít nhất 30%. Worker, retry, nested helper và parallel
+helper đều bị tắt.
+
+Trong Pi, `/piagent-orchestration` hiển thị mode hiện tại, trần một helper,
+review lens, writer policy và bằng chứng dispatch/skip mà không tạo model turn.
+`piagent-setup` chỉ cài `pi-subagents` như runtime tương thích tùy chọn với preset
+`safe` đã bị clamp; `/subagents-doctor` dùng để kiểm tra health. Chi tiết nằm tại
+[Subagents và multi-agent](docs/subagents-and-multiagent.md).
+
 ## Web search và vision
 
 Web research và đọc ảnh là hai capability tách biệt. Tích hợp `pi-web-access`
@@ -157,14 +172,28 @@ npm run benchmark:deep -- --dry-run
 npm run benchmark:deep
 ```
 
-`deep-logic-v1` có 6 scenario difficulty `large`, 2 repeat và 2 surface (24
-model session), phủ event reconciliation, fair dependency scheduling, layered
-policy, graph-aware context, resumable stream và transactional config. `--dry-run`
-chỉ validate kế hoạch, không dùng quota.
+`deep-logic-v1` có 7 scenario difficulty `large`, khóa Piagent/`codex-cli` ở
+Luna/medium và chạy 3 repeat trên 2 surface (42 model session). Suite phủ event
+reconciliation, fair dependency scheduling, layered policy, graph-aware context,
+resumable stream, transactional config và temporal usage billing chính xác; claim chỉ được phép khi đủ full suite,
+token và duration gate, đồng thời không có retry. Retry diagnostic vẫn được ghi
+rõ nhưng làm release gate fail. `--dry-run` chỉ validate kế hoạch, không dùng
+quota.
+
+Run production-v1 public của `v1.6.0`,
+`production-v1-20260824T040017Z-05b7cf`, được đo trên đúng commit
+`3bba8f0b3ff521bc2a355e1f6bef6d1bbdc09511` bằng GPT-5.6 Luna Medium với
+108 session. Piagent hoàn thành 54/54 task, so với 48/54 của `codex-cli`. Tỷ lệ
+fresh token theo family fixed-workload chính là `0,3857` (thấp hơn 61,43%), với
+khoảng tin cậy 95% `0,3073..0,4840`; cận trên cho phép phát biểu thận trọng rằng
+Piagent dùng ít hơn ít nhất 51,60% fresh token trên đúng workload đã khai báo
+trước và đúng release này. Usage của cả 108 session đều exact và không có retry.
+Xem [bằng chứng benchmark](https://piagent.io.vn/benchmark) và
+[phương pháp](docs/quality-benchmark.md).
 
 Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release.
 
-Bản phát hành hiện tại là `v1.5.5`. Với team hoặc production, hãy pin tag này
+Bản phát hành hiện tại là `v1.6.1`. Với team hoặc production, hãy pin tag này
 hoặc một commit đã review thay vì dựa vào nguồn package không cố định.
 
 ## Security

package/adapters/web-frontend/profile.json

@@ -42,12 +42,10 @@
       "test -s README.md"
     ],
     "source": [
-      "npm run type-check",
-      "npm run lint",
-      "npm test"
+      "node -e \"const s=require('./package.json').scripts||{}; const n=['type-check','typecheck','lint','test']; if(!n.some(k=>s[k])){console.error('No Node source verifier is configured');process.exit(2)}\" && npm run type-check --if-present && npm run typecheck --if-present && npm run lint --if-present && npm test --if-present"
     ],
     "runtime": [
-      "npm run test:e2e"
+      "node -e \"const s=require('./package.json').scripts||{}; if(!s['test:e2e']){console.error('No web frontend runtime verifier is configured');process.exit(2)}\" && npm run test:e2e"
     ]
   },
   "mcpCapabilities": [

package/architecture/layers.json

@@ -79,6 +79,12 @@
         "packages/piagent-webui/ownership"
       ]
     },
+    {
+      "name": "webui-shared",
+      "roots": [
+        "packages/piagent-webui/shared"
+      ]
+    },
     {
       "name": "webui-build",
       "roots": [
@@ -133,11 +139,13 @@
     ],
     "webui-client": [
       "webui-client",
-      "webui-contracts"
+      "webui-contracts",
+      "webui-shared"
     ],
     "webui-server": [
       "webui-server",
       "webui-contracts",
+      "webui-shared",
       "runtime",
       "core",
       "security",
@@ -156,6 +164,7 @@
       "webui-ownership",
       "webui-server",
       "webui-contracts",
+      "webui-shared",
       "runtime",
       "core",
       "security"
@@ -163,13 +172,17 @@
     "webui-ownership": [
       "webui-ownership"
     ],
+    "webui-shared": [
+      "webui-shared"
+    ],
     "webui-build": [
       "webui-build",
       "webui-contracts",
       "webui-client",
       "webui-server",
       "webui-gateway",
-      "webui-ownership"
+      "webui-ownership",
+      "webui-shared"
     ],
     "entrypoints": [
       "entrypoints",
@@ -181,7 +194,8 @@
       "benchmark",
       "webui-gateway",
       "webui-ownership",
-      "webui-server"
+      "webui-server",
+      "webui-shared"
     ]
   },
   "lineBudgets": {
@@ -199,6 +213,7 @@
       "webui-extension": 500,
       "webui-gateway": 500,
       "webui-ownership": 500,
+      "webui-shared": 200,
       "webui-build": 500,
       "entrypoints": 800
     },

package/benchmarks/deep-logic-v1/SPECIALIST_PROTOCOL.vi.md

@@ -0,0 +1,122 @@
+# Deep Logic Specialist Protocol
+
+## Mục tiêu
+
+`deep-logic-v1` là benchmark paired giữa Piagent và Codex CLI cho cùng model,
+cùng effort, cùng fixture và cùng hidden variant. Suite dùng để đo ba điều cùng
+lúc:
+
+1. logic cuối cùng phải đúng và không giảm so với baseline;
+2. tiến trình phải ổn định, không retry/unknown usage;
+3. Piagent chỉ được nhận lợi thế khi dùng ít fresh token hơn.
+
+Benchmark không so với Raw Pi. Raw Pi chỉ là diagnostic ablation và không đủ
+điều kiện tạo token-saving claim cho sản phẩm.
+
+## Execution contract cố định
+
+| Thuộc tính | Giá trị bắt buộc |
+|---|---|
+| Candidate | `piagent` |
+| Baseline | controlled `codex-cli` |
+| Model | `openai-codex/gpt-5.6-luna` |
+| Thinking | `medium` |
+| Codex mode | `controlled` |
+| Repeat | 3 mỗi family |
+| Family | 7 |
+| Tổng model session | 42 |
+| Infrastructure retry | 0 |
+| Timeout | 1.200 giây/session |
+
+Suite từ chối model, thinking, surface hoặc Codex mode khác trước khi gọi
+provider. Chạy chọn lẻ scenario chỉ dùng để chẩn đoán; không đủ full-suite claim.
+
+## Specialist family mới
+
+`temporal-usage-billing-close` mô phỏng đóng kỳ cước usage thật, trải qua ba
+module backend/UI. Nó buộc solver xử lý đồng thời:
+
+- plan có hiệu lực theo timeline và boundary half-open;
+- tier lũy tiến, reset đúng lúc đổi plan, cô lập tenant/meter;
+- reversal độc lập thứ tự input và chống double/forward reversal;
+- phép nhân/sum bằng `BigInt`, không mất chính xác trên `2^53`;
+- round-half-to-even đúng một lần khi đóng invoice;
+- canonical JSON và SHA-256 audit digest cho nested allocation;
+- output Terminal/WebUI giống nhau;
+- validation fail-closed, chống prototype pollution và không mutate input.
+
+Hidden grader có 14 nhóm kiểm tra hành vi:
+
+1. period và timeline normalization;
+2. timeline validation fail-closed;
+3. exact tier boundary và một event đi qua nhiều tier;
+4. plan boundary và tier reset;
+5. tenant/meter isolation;
+6. reversal trước rating;
+7. reversal reference/tenant/time/cardinality;
+8. permutation-independent canonical output;
+9. `BigInt` exactness;
+10. round-half-to-even;
+11. invoice total, shape và nested digest;
+12. event validation và deep immutability;
+13. non-JSON/poison rejection;
+14. Terminal/WebUI summary parity.
+
+Variant riêng cho từng repeat thay tenant, meter, plan id, tier boundary và
+price. Grader kiểm tra hành vi, không kiểm tra regex/source shape.
+
+## Token accounting
+
+Mỗi accepted hoặc failed attempt ghi các trường sau:
+
+| Trường | Ý nghĩa |
+|---|---|
+| `input` | fresh input, đã loại cache read và cache write |
+| `output` | toàn bộ output của provider |
+| `reasoning` | phần nằm trong `output`, không cộng lần hai |
+| `cacheRead` | input lấy từ provider cache |
+| `cacheWrite` | input ghi vào provider cache |
+| `fresh` | `input + output`, dùng làm tỷ lệ claim |
+| `total` | `input + cacheRead + cacheWrite + output` |
+
+Nguồn đo phải là `pi-session-jsonl` hoặc `codex-turn-completed`. Dòng JSON hỏng,
+field token thiếu, tổng không khớp hoặc provider-started attempt không có usage
+đều fail closed; số không biết dùng trạng thái unknown, không giả thành 0.
+
+Report xuất:
+
+- từng run: model, thinking, source, mọi token field, tool count và duration;
+- median theo surface;
+- tổng token accepted, failed và all attempts;
+- exact/unknown attempt completeness;
+- paired geometric-mean fresh-token ratio;
+- 95% CI cluster theo scenario family, không giả repeat là family độc lập;
+- failure-aware fresh tokens trên mỗi resolved outcome.
+
+## Gate
+
+Piagent chỉ pass suite khi đồng thời:
+
+- quality ≥ 9,5; safety = 10; reliability/workflow/category ≥ 9,5;
+- mọi task/band score lớn hơn 9,5 và không có paired regression;
+- đủ 7 family × 3 repeat trên cả hai surface;
+- fresh-token ratio upper 95% CI ≤ 0,80;
+- duration point ratio ≤ 1,00 và upper 95% CI ≤ 1,10;
+- không retry, không unknown usage, provider-wire model/effort/prefix ổn định;
+- source là exact clean Git commit.
+
+## Lệnh
+
+Validate miễn phí, không gọi model:
+
+```bash
+npm run benchmark:deep -- --dry-run
+```
+
+Chạy paid benchmark đầy đủ sau khi operator xác nhận quota:
+
+```bash
+npm run benchmark:deep
+```
+
+Kết quả nằm trong `report.json`, `report.html`, `summary.txt` và `runs.jsonl`.