@piagent/platform 1.2.17 → 1.3.0-ie.8

package/docs/runtime-harness-standard.md

@@ -12,6 +12,8 @@ User request
   -> required context manifest
   -> session-bound task contract v2 + work-plan DAG
   -> guarded tool calls
+  -> adaptive context plan receipt
+  -> hash-chained task journal / checkpoints
   -> baseline-aware changed-file evidence
   -> all-command observed verification
   -> immutable trace / retry handoff
@@ -26,8 +28,14 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
 | Risk lane | `riskLane` + profile `hardGates` | Chặn auth, release, provider config, destructive action, database migration. |
 | Intake | runtime automatic intake; fallback `piagent_task_start` | Mỗi attempt có identity/session/scope/output/acceptance criteria trước model work; bounded tasks không tốn management turn. |
 | Context rules | `/onboard run`, Pi Context Engine, `.pi/project-context.md`, `requiredContext`, context manifest | Giảm token và tránh đọc toàn repo. |
-| Test matrix | `verifyCommands` + observed verify evidence | Source DONE phải có mọi exact verify command thực chạy và pass qua Pi bash. |
+| Adaptive context | `runtime/context/adaptive-planner.ts` | Token budget theo phase/lane/model/thinking/context pressure; context pack có receipt. |
+| Parent model route | `runtime/model/model-route-*` | Capability/safety floor deterministic trước task; giữ explicit pin, exact catalog match, không đổi model giữa conversation. |
+| Retrieval route | `runtime/context/retrieval-route-policy.ts` | Local direct hoặc read-only retriever recommendation; chỉ `grep/find/read`, tối đa 8 nhánh × 4 vòng, không auto-dispatch. |
+| Repository memory | `.pi/piagent-state/repository-memory/facts.jsonl` | Fact có citation/expiry; chỉ inject trong token budget còn dư và luôn verify lại bằng current file. |
+| Test matrix | `verifyCommands` + verification intelligence + observed evidence | Chọn group theo task scope; source DONE phải có mọi exact verify command thực chạy và pass qua Pi bash. |
 | Trace | completion hook, `.pi/piagent-state/traces.jsonl`, session entry | Runtime tự ghi audit trail; tool thủ công chỉ dùng recovery. |
+| Journal/checkpoint | `.pi/piagent-state/task-journal/events.jsonl` | Hash-chain audit/replay; retention compaction lưu prefix/head anchor và contract vẫn là operational truth. |
+| Execution backend | host mặc định + fail-closed adapter contract | Không âm thầm chạy mutation trên host khi operator yêu cầu experimental isolation chưa có adapter. |
 | Retry | `attempt`, `maxAttempts`, `previousAttempts`, failed step state | Lần sau giữ failure/ruled-out evidence và không loop vô hạn. |
 | Change truth | Git baseline/final digests + tool-result observation | Không nhận file dirty cũ hoặc claim không có evidence là thay đổi của task. |
 | Protected paths | `protectedPaths` trong profile + extension guard | Mỗi project có vùng cấm riêng. |
@@ -53,6 +61,24 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
 - `/workflow discuss`: clarify before work.
 - `/workflow review`: review diff/source with evidence.
 
+## Parent routing và retrieval specialist
+
+Router chỉ đọc bounded `TaskFeatures`, selection provenance và authenticated
+catalog. Raw prompt/source không được ghi vào decision. `unknown` provenance,
+explicit user pin, unavailable model/effort, protected/external/destructive
+action, thiếu Git/verifier, hoặc host boundary không an toàn đều fail closed.
+
+Pi 0.84.1 có extension API đổi model nhưng path đó đồng thời cập nhật user
+default. Vì vậy Piagent không dùng nó để đổi model âm thầm. `auto` chỉ enforce ở
+prelaunch adapter do operator gọi bằng `piagent-route --execute --yes`; runtime
+extension vẫn chỉ shadow/recommend. Đây cũng là lý do model không bị đổi giữa
+conversation, tránh cache miss và context/harness discontinuity.
+
+Retrieval policy lấy cơ chế chuyên biệt hóa từ Fast Context nhưng giữ rollout
+bảo thủ: planner có thể đề nghị retriever read-only chạy nhiều hướng tìm kiếm có
+giới hạn, còn `automaticDispatch` luôn false cho đến khi provider-backed gate
+chứng minh quality, token và latency.
+
 ## Task lifecycle chuẩn
 
 Vòng đời thích nghi theo mức rủi ro. Runtime guard luôn hoạt động, nhưng các
@@ -70,7 +96,8 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
    - protected paths
 
 2. Context
-   - runtime injects one bounded Context Engine navigation pack when useful
+   - runtime planner decides whether a Context Engine navigation pack is useful
+   - budget is based on workflow phase, risk lane, explicit paths, model/thinking and context pressure
    - read only targeted current files
    - successful reads become context manifest evidence automatically
    - no routine context/status/index tool calls
@@ -98,14 +125,24 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
    - completion hook projects the final contract and runs the gate
    - runtime persists changed files, commands, result and final trace
    - one bounded continuation repairs missing evidence; it never loops
+   - strict specialist review is opt-in, uses one bounded diff plus two reads,
+     and limits repair to exact reviewed source/test paths
+   - denied, failed, no-op, stale, or exhausted review activity hands off; any
+     mutation requires the exact current-tree verifier before completion
    - freeze the contract after a terminal outcome
 
 7. Retry when needed
    - start a fresh Pi session with the same taskId
    - carry forward failedAt, reason, ruledOut, and prior outcome
    - refuse attempts beyond the first attempt's maxAttempts
+   - replay task journal checkpoints to see the latest phase before resuming
 ```
 
+Operator projection không tạo source of truth mới: `/task-preflight` chiếu fact
+và recommendation trước task, `/piagent-status` chiếu live persisted state, còn
+completion receipt chiếu final gate. Mọi view phải có schema/version, ghi
+`unknown`/`null` thay vì đoán, và luôn nói rõ host execution không phải sandbox.
+
 | Lane | Extra context/orchestration |
 |---|---|
 | `tiny` | Automatic lifecycle; parent agent, targeted reads, exact verify, no progress/evidence calls. |
@@ -121,6 +158,7 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
 | P2 | extension tools for task/context/verify/trace + session entries | Dùng được cho source task có guard rõ. |
 | P3 | exec policy + context budget + tool registry + task gate + automatic paired benchmark | Dùng được cho guarded project workflows. |
 | P4 | session-bound v2 state, Git change truth, retry, completion hook, bounded secure local state | Sẵn sàng rollout có kiểm soát; OS/MDM governance vẫn ngoài core. |
+| P5 | adaptive context planner, durable task journal, repository memory, model capability layer, verification intelligence | Sẵn sàng controlled recovery rollout; production benchmark bắt buộc, public long-horizon score chờ dedicated suite. |
 
 ## Chuẩn DONE
 

package/docs/runtime-policy-design.md

@@ -137,8 +137,9 @@ Ad-hoc commands can still be recorded for traceability, but they do not satisfy
 Release-level quality/token/cost claims must use `piagent-benchmark`: paired clean
 workspaces, the same prompt/model/thinking, hidden acceptance checks, exact Pi
 usage, scope checks and Piagent workflow evidence. A token-saving verdict also
-requires quality/reliability at least `9/10`, perfect safety, the suite's
-workflow threshold (`10/10` for smoke and at least `9/10` for production),
-non-inferior quality and at least three same-model paired runs with exact usage.
+requires perfect safety and the suite's quality/reliability/workflow gates.
+Production requires aggregate scores of at least `9.5/10` plus every task and
+category/profile/lifecycle/difficulty outcome strictly above `9.5`; it also
+requires non-inferior quality and paired same-model usage with confidence.
 `scripts/quality-benchmark.sh` remains only as a legacy recorder for
 project-specific evidence.

package/docs/runtime-quality-baseline.md

@@ -226,9 +226,10 @@ chỉ lưu histogram tên tool. Chỉ claim chất lượng/token/cost khi các
 - cùng acceptance criteria;
 - verify command rõ;
 - token/cost/duration được runtime ghi lại;
-- quality/reliability đạt ít nhất `9/10`, safety đạt `10/10`, workflow đạt ngưỡng
-  của suite (`10/10` cho smoke, ít nhất `9/10` cho production), quality không
-  giảm và ít nhất ba cặp cùng model có exact usage.
+- safety đạt `10/10` và các gate quality/reliability/workflow của suite pass;
+  production yêu cầu điểm tổng hợp ít nhất `9.5/10`, mọi task và mọi
+  category/profile/lifecycle/difficulty band lớn hơn `9.5`, quality không giảm,
+  cùng paired usage đủ confidence.
 
 `piagent-benchmark <project> --record ...` vẫn route tới recorder cũ cho task
 project-specific, nhưng không thay thế automatic release benchmark.

package/docs/security-threat-model.md

@@ -16,6 +16,8 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - release identity, installer sources, dependency pins, and package contents;
 - source bodies and retrieval metadata stored in the local Context Engine index;
 - observed verification evidence used to approve task completion.
+- solver, trajectory, recovery, helper-budget, and completion sidecars whose
+  integrity controls routing, resume, and one-writer decisions.
 
 ## Trust assumptions
 
@@ -52,6 +54,8 @@ The final category is outside the containment capability of the Piagent guard. I
 | External GitHub/HTTP/MCP/provider mutation | Direct and proxied action classification plus explicit operator confirmation, including guarded shell carriers | Provider semantics and new tool schemas can change; new integrations require policy and regression review. |
 | Repository MCP direct tool loses server attribution | Guard and doctor share the merged MCP view. Both session-level and effective per-server `directTools` selections fail closed when `toolPrefix: "none"` removes server identity; approved direct tools remain usable with `server` or `short` prefixes | A future adapter naming mode or config layer must be added to the shared MCP resolver before rollout. |
 | Read-only subagent receives mutation-capable tools | Packaged read-only roles carry explicit `read`, `grep`, `find`, `ls` allowlists; CI checks every `acceptanceRole: read-only` manifest, while all shell/edit/write capability remains on the explicit writer role | User/project overrides and a compromised external subagent runtime can replace the packaged contract; inspect effective runtime configuration when accepting third-party roles. |
+| Provider/model output or router attempts to widen solver/helper authority | Solver and model-route inputs are deterministic bounded facts; explicit model/thinking pins win; unknown provenance cannot enforce; exact authenticated catalog matching forbids silent substitution. RolePolicy and HelperRequest intersect parent scope/tools and never delegate approvals. Owner-only budgets enforce total/role/one-writer ceilings | Provider-backed execution remains external. Pi 0.84.1 extension `setModel` also updates user default state, so in-extension auto routing fails closed; only explicit prelaunch may enforce. Automatic workers and helper dispatch remain unpromoted pending controlled evidence. |
+| Corrupt, stale, symlinked, or partially written runtime sidecar | Closed validators, local-state canonicalization, atomic rename, bounded journals, task/session/tree identity, corrupt-state fail-closed behavior, and feature-off compatibility tests. Synthetic disk-full and permission-denied tests require no authoritative partial trajectory state | A process with the same OS account can still alter local state; application integrity is not OS isolation. Unexpected state must block mutation and route to doctor/handoff. |
 | Destructive local action | Exec-policy classification and explicit confirmation; protected paths remain denied in every permission profile. A target written as a command substitution is evaluated only where its body is one plain command with literal operands and a format this renderer reproduces exactly, and confirmed otherwise — a separator, a nested substitution, a redirection, a variable, quoting, an escape, a `printf` option, or a `printf` conversion whose result this does not reproduce (`*`, `%q`, `%b`, the numeric conversions, `%%`) all make the body unreadable here. A constant width or precision and format reuse are reproduced, so a target built from those is refused rather than confirmed, and the rendered output is read as a path candidate as well as the format's literal text and its arguments — a name assembled across a conversion (`.e%.1sv nv` is `.env`) appears in none of the pieces. Brace expansion, ranges included, is performed once per segment before anything reads it, so the rules, the legacy patterns, the nested-interpreter scan, the pipeline producers and the destructive checks all see the word list the shell would build rather than the text as typed; the expansion produces a token stream, so a command and its arguments assembled from one brace word (`{cat,.env}`) are read as both; quoting is tracked per character, so a word holding a quoted group beside an expanding one (`"{.env,}"{,}`) expands exactly as far as the shell expands it — and a target that is nothing but an unresolved parameter expansion is confirmed rather than permitted, since it can hold any value including root. The same holds for reads: a word that is only an unresolved parameter expansion is confirmed wherever the command opens files (`cat ${HOME:+.env}`), including across a pipe into an `xargs` that opens them (`echo $F \| xargs cat`), while a command substitution in that position is left to the nested scan that classifies the command inside it, and two expansions with nothing between them count as a name being assembled just as literal text beside one does. Brace expansion, parameter expansion and command substitution are performed once per segment, in the order a shell performs them, and every reader takes that one word list — so a name assembled by an expansion (`r$(printf %s m) -rf /`, `xa$(printf %s rgs)`, `$(printf %s ba)$(echo -n sh) -c '...'`) is the command it becomes rather than the text it was typed as. A name that still cannot be resolved is treated as an unknown command rather than a known-harmless one: it is enough to bring the destructive checks, the interpreter scan and the file-operand net into play, since `${X:+r}m -rf /` and `${X:+cat} ${X:+.env}` are those commands whenever the variable is set. Differential cases are generated rather than enumerated, over the cross product the defects live in — expansion form, position in the command, and reader — with each spelling placed in the command name, the operand, a flag's argument, a redirection target, a pipeline producer, an `xargs` consumer and an interpreter payload; the corpus fails if any generated spelling produced no word list, so a batch that dies early cannot pass as coverage, and it asserts in both directions so a check that answers for everything fails too | Confirmation is not isolation. A trusted process outside the observed tool path retains OS authority. A target produced by any other command is knowable only at run time, so it is gated by confirmation rather than refused. |
 | Forged verification result | Observed Bash result ledger, command hash, task-start ordering, exit-code and verify-command matching | Compromise of the trusted Pi/process environment is outside this evidence model. |
 | Mutable or substituted release source | Exact team tags, stable tag-to-commit resolution, release-commit binding in tag CI, annotated-tag requirement, add-on integrity checks, and documented tag ruleset requirement | Bootstrap helper installation still relies on GitHub tag immutability; repository administrators must prevent tag update/deletion. Signed provenance remains future work. |
@@ -76,6 +80,14 @@ Set `PIAGENT_NO_UPDATE_CHECK=1` to switch it off. Nothing else changes.
 
 Release gates include policy regression tests, TypeScript checking, runtime smoke tests, redaction benchmarks, package-content inspection, release-identity checks, installer tests, exact Pi host/add-on dependency audit, and CI on Linux x64 plus the current macOS runner. CodeQL covers JavaScript/TypeScript and GitHub Actions.
 
+The unreleased 1.3 candidate additionally scans solver/helper/recovery/usability
+reports for raw prompt, source, child-output, and credential fields; exercises
+cross-process helper reservations, stale locks, terminal late results,
+disk-full/permission failures, corrupt journals, and feature-off state; and
+measures deterministic routing and policy-core p95. Local success is not GA
+approval: an RC package, Linux candidate run, controlled cohorts, independent
+human pilot, candidate benchmark, and explicit release approval remain required.
+
 These are internal engineering controls, not an independent third-party audit. The project currently has no LTS promise. Stronger assurance still benefits from broader parser fuzzing, a larger OS/shell matrix, independent review, signed provenance, and continued adversarial testing.
 
 ## Reporting and disclosure

package/docs/subagents-and-multiagent.md

@@ -26,6 +26,29 @@ Kiểm tra nhanh policy trong Pi:
 /piagent-orchestration
 ```
 
+Runtime policy dùng `RolePolicy v1` và `HelperRequest v1` để bind objective,
+task/session identity hash, scope, exact tool allowlist, model/effort từ
+authenticated runtime catalog, context/time/call ceiling, output schema,
+stopping rule, approval restriction và deduplication key. Chọn mode bằng:
+
+```bash
+PIAGENT_HELPERS_MODE=off        # không recommend/spawn
+PIAGENT_HELPERS_MODE=recommend  # default; giải thích nhưng không spawn
+PIAGENT_HELPERS_MODE=on         # chỉ read-only role qua provider adapter
+```
+
+`piagent-worker` vẫn disabled by default và không được auto-delegate cho GA.
+CAP-14 chỉ cho tối đa một automatic helper dispatch cho mỗi task/run. Lower-level
+helper budget chỉ theo dõi child work do Piagent tạo (tối đa 2 concurrent, 3
+explicit owned reservation tổng, 1 pass cho từng scout/planner/reviewer/Oracle,
+tối đa 1 writer); nó không
+claim account-wide scheduling hay kiểm soát các Pi session không liên quan.
+Mỗi dispatch cưỡng chế đúng time/call/token ceiling của request. Timeout,
+parent cancellation, late/stale result và budget overflow đều fail closed và
+không merge output. Khi thành công, parent chỉ nhận bounded redacted summary và
+giữ merge ownership; durable receipt chỉ giữ digest/counters, không giữ raw
+child output hay session identity.
+
 Guard extension vẫn load trong subagent process. Bash verify results do not stay in process-local memory only; they are appended to `.pi/piagent-state/observed-bash.jsonl`. Because parent and child share the same project cwd, parent can validate an exact verify command that a guarded worker subagent ran.
 
 Xem chi tiết: `docs/auto-delegation-policy.md`.

package/docs/task-lifecycle-vietnamese.md

@@ -67,11 +67,21 @@ plan `scout`/`review`, khong con step `implement` mau thuan. Task high-risk/cust
 van giu checkpoint thu cong. Chi dung subagent cho scout, planning hoac review
 doc lap. Mot write set chi co mot owner.
 
+Trajectory khong suy dien quyen sua tu loi model noi. Automatic source task chi
+chuyen sang `execute` khi contract do runtime tao co bounded scope, exact
+verifier, acceptance receipt va mot step `single-writer` dang `in-progress` voi
+toan bo dependency da xong. Runtime ghi ro phase nao khong ton tai trong automatic
+plan neu can bo qua. Manual/high-risk task vao phase `plan` de doc, tim va cap
+nhat checkpoint; edit/write/bash ghi file van bi chan cho den khi plan/challenge
+hoan tat va step `single-writer` thuc su dependency-ready.
+
 ### 3. Execute
 
 Truoc khi co task contract, project da onboard chi cho inspection co gioi han;
 write/edit va shell command that su ghi file bi chan. Sau khi task bat dau:
 
+- phase `intake`, `scout` va `plan` chi cho discovery; `execute`/`repair` moi co
+  mutation tools, con read-only task khong bao gio nhan quyen mutation;
 - direct tool va MCP write phai nam trong `scope`;
 - read-only task chan moi project/external mutation;
 - protected path, secret redaction, destructive command va external confirmation

package/docs/team-onboarding.md

@@ -8,8 +8,8 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 
 ```bash
 node --version  # >= 22.19.0
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.17
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
+npm install -g --ignore-scripts @piagent/platform@1.3.0-ie.8
 piagent-install --stable
 cd /path/to/project
 pi
@@ -25,7 +25,7 @@ pi
 ## Prerequisites
 
 - Node.js >=22.19.0.
-- Pi Coding Agent `0.82.0`.
+- Pi Coding Agent `0.84.1`.
 - Runtime rollout:
   - verified: macOS Apple Silicon + Bash, Linux x64 + Bash;
   - supported target cần smoke trước khi rollout rộng: macOS Intel + Bash, Linux ARM64 + Bash;
@@ -42,8 +42,8 @@ Mặc định team dùng stable helper:
 
 ```bash
 node --version  # >= 22.19.0
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.17
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
+npm install -g --ignore-scripts @piagent/platform@1.3.0-ie.8
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -105,7 +105,7 @@ Version mới nhất được hỏi npm registry nhiều nhất một lần mỗ
 Sequence thủ công vẫn dùng được, và bắt buộc theo thứ tự này — `piagent-install` **fail** nếu Pi host lệch bản pin, nó không tự nâng host:
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
 npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
@@ -117,7 +117,7 @@ Full rollback dùng cùng sequence với `vPREVIOUS`, nhưng exact Pi host phả
 Nếu team publish npm private:
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
 pi install npm:@your-scope/platform@x.y.z
 ```
 
@@ -262,6 +262,14 @@ Project init tạo:
 
 Hai file memory ở trên là local/private mặc định theo `.pi/.gitignore`; chỉ commit nếu team opt-in sau review.
 
+Với luồng FE/BE tách repo nhưng để chung một folder làm việc, mở Pi tại folder cha và chọn `be-readonly-fe` cho chính folder cha đó. Ví dụ `Working/v-nexus-frontend/` và `Working/v-nexus-backend/` là hai Git repo riêng; `Working/.pi/piagent-profile.json` là profile của phiên Pi. Khi start task, scope ghi nên nằm trong FE repo:
+
+```text
+/workflow be-to-fe Scout BE changes read-only and create the FE remediation plan. Scope: v-nexus-frontend/plans/**, v-nexus-frontend/**. Backend repo is read-only.
+```
+
+Plan/report có thể ghi vào `v-nexus-frontend/plans/**` nếu muốn đi cùng FE repo, hoặc `Working/plans/**` nếu muốn lưu ở workspace cha. File ngoài repo con được theo dõi bằng bounded file-digest evidence, còn FE/BE repo con vẫn dùng Git evidence.
+
 ## Bước 4 — run trong Herdr
 
 ```bash

package/docs/usage-observability.md

@@ -19,6 +19,7 @@ Piagent package thêm command:
 /usage logs
 /usage live
 /usage efficiency
+/piagent-inspector
 ```
 
 Agent cũng có thể gọi tool:
@@ -54,7 +55,41 @@ piagent_context_preflight
 `/usage efficiency` đọc local Context Engine telemetry và hiện công thức
 `contextWasteScore`: duplicate reads, duplicate output, tool-schema share,
 low-confidence retrieval, và active-tool excess. Score này phải đi cùng task
-gate/verify result; nó không tự kết luận model hoặc nhân viên làm tốt/xấu.
+gate/verify result; nó không tự kết luận model hoặc nhân viên làm tốt/xấu. Nếu
+session có Task Contract, JSON detail còn có `taskEfficiency`: hashed
+session/task/run identity, solver route/mode/override, persisted phase duration,
+context/tool-group utilization, verify/repair/retry count, digest-only helper
+usage, outcome và acceptance. Raw task text/child output không được lưu. Parent
+token/cost, actual tool-call count, relevant-file time và correct-edit time giữ
+`null` hoặc `unavailable` nếu runtime không có exact fact; không dùng estimate.
+
+## Context Budget Inspector và activity panel
+
+`/piagent-inspector` là namespace duy nhất cho activity/diff review. Gõ không
+tham số để chọn `summary`, `files`, `commands`, `security`, `context`, `toggle`
+hoặc `help`. Panel live bốn dòng tự hiện sát phía trên footer native từ lúc mở
+session; `/piagent-inspector toggle` chỉ ẩn/hiện panel trong session hiện tại
+và không sửa profile.
+
+Màu panel mang nghĩa cố định: cyan/magenta phân biệt file và test, xanh lá cho
+addition/pass và context dưới 60%, vàng cho block hoặc context từ 60%, đỏ cho
+deletion/failure/safety hoặc context từ 80%. Màu có thể tắt bằng `NO_COLOR=1`.
+
+Inspector đọc các nguồn local đã có: Task Contract và baseline working tree,
+tool call/result, exact bash evidence, safety decision, trajectory/resume state,
+session messages và `ctx.getContextUsage()`. Vì vậy nó hiển thị được:
+
+- observed task files trên footer panel; exact task-baseline delta trong view `files`; toàn bộ dirty working tree khi không có task;
+- file/tool đang chạy và patch line vừa hoàn tất khi Pi cung cấp patch;
+- command requested, executed, passed, failed hoặc blocked;
+- verifier pass/fail, policy block, secret redaction và integrity warning;
+- context hiện tại, token/cost cộng theo session và usage của assistant turn mới nhất.
+
+Giới hạn được ghi rõ trong output: Pi gắn model usage vào assistant response/turn,
+không gắn exact token vào từng built-in tool call. Do đó inspector không chia token
+cho `read`, `edit`, `bash` bằng estimate. Nếu task đụng file đã dirty từ baseline,
+line scope là `mixed-working-tree`; dùng file list/task baseline để review, không
+coi toàn bộ `git diff HEAD` là công của task hiện tại.
 
 Giới hạn kỹ thuật: extension command context expose `ctx.getContextUsage()`, phù hợp để biết context window đang dùng bao nhiêu. Exact billed totals như `input`, `output`, `cacheRead`, `cacheWrite`, `cost` là API của Pi `/session` và RPC `get_session_stats`.
 

package/docs/vi/architecture.md

@@ -53,10 +53,160 @@ Folder `extensions/` vẫn chứa một số service module do lịch sử. Tên
 1. Pi load một extension entrypoint duy nhất.
 2. Composition resolve base policy, project profile, capability lock và local session state.
 3. Runtime hook normalize input và thu session evidence qua một session-scoped state owner.
-4. Core service quyết định path, shell, MCP, task, context và final-gate policy.
+4. Core service quyết định path, shell, MCP, task, context, recovery, memory, verification và final-gate policy.
 5. Runtime adapter register tool và slash command ngắn gọn.
 6. Owner-only local state ghi evidence; prompt chỉ là hướng dẫn, không phải enforcement boundary.
 
+## Adaptive durable runtime
+
+Runtime hiện tại có sáu lớp state operational/derived:
+
+| Layer | Source of truth | Derived state |
+|---|---|---|
+| Task contract | `.pi/piagent-state/tasks/*.json` | Session binding, final gate projection |
+| Task journal | `.pi/piagent-state/task-journal/events.jsonl` | Replay snapshot, checkpoint resume view |
+| Trajectory | Task Contract v2 cùng lifecycle/tool evidence đã quan sát | Current phase và bounded transition replay trong `.pi/piagent-state/trajectory/*.json` |
+| Recovery handoff | Contract, journal đã verify, trajectory, current tree và exact-verifier evidence | Bounded reconstruction projection trong `.pi/piagent-state/handoffs/*.json` |
+| Context index | Repository file + resolved exclusion policy digest | SQLite FTS/search pack, context efficiency report |
+| Repository memory | Fact/decision có citation, digest và expiry | Advisory retrieval hint |
+
+Task journal là owner-readable, có hash chain và sequence. Runtime ghi checkpoint
+cho task start/progress, mutation đã quan sát, verifier và completion. Giữa các
+lần retention compaction, journal là append-only; khi compact, chain giữ lại được
+hash lại và lưu anchor của prefix đã bỏ cùng prior head hash. Task contract vẫn là
+operational source of truth. Khi resume, runtime đọc work plan trong contract
+trước rồi mới dùng journal đã verify; journal corrupt sẽ chặn automatic resume để
+operator review.
+Hash chain của journal và acceptance receipt là operational evidence do cùng
+runtime tạo ra, không phải independent attestation hay một audit authority độc lập.
+
+Recovery dựa trên classification và bị giới hạn xuyên suốt các task attempt.
+Chỉ failure thuộc source và nằm trong scope mới có tối đa một repair pass;
+transient verifier/provider failure chỉ có tối đa một exact retry và không có
+source-mutation authority. Environment, permission, policy, scope và unknown
+failure luôn non-mutating. `PIAGENT_AUTO_RECOVERY=off` khôi phục ordinary P3
+handoff behavior mà không migrate state. Mọi final path ghi redacted Handoff v1
+projection từ operational truth. Khi resume, runtime bind task/session identity,
+journal integrity, trajectory phase, current-tree digest và exact verifier
+evidence; edit sau verify làm pass cũ stale, còn state corrupt hoặc
+symlink-unsafe sẽ block mutation. Acceptance criteria vẫn là completion truth;
+optional runtime-observed provenance chỉ phân biệt first-pass, repaired,
+blocked, partial và failed bằng bounded reference.
+
+Semantic specialist review là đường CAP-13 riêng cho `strict-high-risk`, không
+phải parser-driven recovery áp dụng phổ quát. Nó bị pin vào một shared
+continuation, một current-tree diff, hai targeted read, đúng source/test path đủ
+điều kiện và configured verifier sau mọi mutation. Call bị deny, fail, no-op,
+stale, ngoài scope, unsupported hoặc hết budget sẽ khóa cơ hội và handoff.
+Broad-default observe/advise không schedule review này và không block tool call.
+
+Adaptive Context Planner chạy trước khi runtime auto inject context. Nó dùng
+workflow phase, risk lane, explicit path, context pressure hiện tại, model
+identity Pi báo về và thinking level để chọn hard token budget cùng giới hạn số
+file. Planner không tự đổi model/provider. Hiện chưa ship local semantic
+reranker, nên plan luôn report `reranker: off` kể cả khi còn legacy environment
+flag. Mỗi context pack được inject có receipt để report giải thích vì sao path đó
+vào context.
+
+Task Contract v2 còn mang projection lập kế hoạch Criterion Graph v1 theo kiểu
+cộng thêm. Graph map đúng một lần từng criterion của operator sang planning kind
+đóng, target hint nằm trong scope, proof kind và dependency order. Graph không có
+state `satisfied`, nên không thể thay acceptance hay exact-verifier truth. Graph
+ưu tiên context liên quan trong scope trước observation cũ, giữ nguyên digest qua
+compaction/resume, không đổi tool schema và không tạo provider follow-up turn.
+`PIAGENT_INTELLIGENCE_ENGINE=off` chọn mechanical control cho causal test hoặc
+rollback khẩn cấp; task mới mặc định dùng criterion engine và pin mode/digest của
+nó trong Task Contract.
+
+Task đã complete có thể
+tạo retrieval fact ngắn hạn, có citation. Turn sau chỉ inject memory hint nếu còn
+chỗ trong token budget của context plan; repository file hiện tại vẫn là source
+of truth.
+
+Trajectory là phase evidence, không phải completion outcome thứ hai. Solver có
+thể recommend path, còn Task Contract và tool evidence đã quan sát sở hữu
+transition qua `intake`, `scout`, `plan`, `execute`, `verify`, `repair`,
+`review`, `handoff` và `terminal`. `/piagent-status` và `/task-preflight` hiển
+thị current phase. Trajectory state corrupt hoặc symlink-unsafe sẽ disable
+phase-tool enforcement và báo recovery thay vì đoán.
+
+`PIAGENT_PHASE_TOOLS=off|shadow|on` điều khiển phase enforcement. `shadow` là
+default và chỉ ghi intended difference, không đổi behavior; `on` giữ một tool
+schema provider-visible ổn định để tái sử dụng cache và enforce current phase
+tại tool-call guard; `off` tắt phase decision đó ngay cả khi sidecar đã tồn tại.
+Automatic source task chỉ vào `execute` khi runtime-owned contract có step
+`single-writer` đã dependency-ready, exact verifier, bounded scope và acceptance
+receipt. Manual và high-risk task chỉ được discovery trong suốt checkpoint
+plan/challenge. Tool visibility không phải authorization: scope, read-only,
+protected-path, destructive và external-action guard vẫn hoạt động ở mọi mode và
+trên mọi đường mutation. Piagent state/project mutator dùng native sequential
+execution metadata của Pi 0.84.1, pure read vẫn parallel-safe, và Pi giữ native
+per-file mutation queue. Authorization hook không acquire custom runtime lock.
+
+Acceptance assurance và semantic repair có kill switch off-only độc lập. Tắt
+acceptance assurance cũng tắt semantic repair phụ thuộc; chỉ tắt semantic repair
+thì phase, acceptance observation và recovery vẫn giữ nguyên. Semantic repair
+strict chỉ hợp lệ khi phase và recovery đều có enforcement authority, còn tổng
+automatic dispatch của mọi capability bị chặn ở một đơn vị cho mỗi task. Các
+interaction check này được bind vào snapshot và không đổi tool schema mà
+provider nhìn thấy.
+
+Helper do Piagent sở hữu dùng RolePolicy v1 và HelperRequest v1. Request bind
+hashed session/task identity, bounded objective, read/write scope, exact tool
+allowlist, authenticated model/effort source, context/time/call ceiling, output
+schema, stopping rule, approval restriction và deduplication key. Read-only role
+không thể nhận mutation tool. Worker default off và cần explicit single-writer
+lease. `PIAGENT_HELPERS_MODE=off|recommend|on` mặc định là `recommend`; `on` chỉ
+cho phép read-only dispatch qua provider adapter đã cài. CAP-14 chỉ cho tối đa
+một automatic helper dispatch cho mỗi task/run; lower-level owner budget vẫn
+giới hạn hai helper concurrent và ba explicit owned reservation tổng, deduplicate
+work tương đương, recover reservation hết hạn mà không tăng budget, và cancel
+late work khi parent Task Contract terminal. Controller không claim quyền kiểm
+soát Pi session/account usage không liên quan và không đổi user-pinned parent
+model. Dispatch cưỡng chế time/call/token ceiling khi merge result: timeout,
+overflow, cancellation hoặc stale result không thể đóng góp output. Helper thành
+công chỉ trả một summary đã redact và giới hạn, parent là merge owner duy nhất;
+raw child output chỉ được biểu diễn bằng digest trong durable usage evidence và
+không bao giờ auto-merge.
+
+Product-facing runtime view là projection deterministic từ chính các fact trên.
+`/task-preflight` tách observed runtime fact, solver recommendation, active
+policy mode, approval và blocker; nó không cấp implementation authority cho
+read-only, plan, review, protected, destructive hay external work.
+`/piagent-status` join Task Contract, journal, trajectory, resume, recovery,
+helper và runtime-model evidence mà không cần model turn. Terminal output nhúng
+completion receipt và task-efficiency view có giới hạn. Identity task/session/run
+được join bằng session id đã hash; raw task text và helper output không được lưu.
+Phase time chỉ đến từ persisted transition; edit timing, token total và cost
+không đo được phải giữ null. Same-runtime evidence là operational assurance,
+không phải independent audit.
+
+Cho đến khi controlled beta cohort cùng independent usability/platform gate
+complete, safe default được freeze là criterion engine `on`, solver `shadow`, phase tools `shadow`,
+recovery `on`, helpers `recommend`, parent routing `off`, automatic worker
+`off`, và host execution. Chỉ implement xong không đủ để promote mode.
+Feature-off vẫn đọc sidecar cũ mà không xóa state.
+
+Parent routing hiện có contract capability `low|medium|high|ultra` có version,
+selection provenance, exact authenticated-catalog matching và objective
+`intelligence|balance|cost`. Router phân loại trước model call của fresh task,
+không đổi model giữa conversation, giữ `/model` và CLI pin, đồng thời fail
+closed khi provenance hoặc host capability chưa rõ. Extension switch model của
+Pi 0.84.1 còn cập nhật user default, nên extension `auto` chỉ recommendation;
+chỉ explicit prelaunch adapter `piagent-route --execute --yes` được enforce.
+Default vẫn `off` cho đến khi authenticated G1/G2 pass mọi aggregate gate
+`>=9.5` và từng outcome riêng lẻ đều `>9.5`.
+
+Retrieval routing cũng giữ rollout bảo thủ: search broad hoặc confidence thấp có
+thể recommend retriever read-only chỉ dùng grep/find/read, tối đa hai nhánh song
+song trong hai vòng. Automatic dispatch vẫn false.
+
+Execution backend contract chạy fail-closed. Host là mặc định và Pi vẫn sở hữu
+OAuth/session credential. Nếu chọn docker, devcontainer hoặc sandbox nhưng chưa
+có adapter, mutation bị block thay vì âm thầm chạy bằng host. Task scope chạm cả
+frontend và backend sẽ chọn verify group tổng `source`; scope chạm docs cùng
+source sẽ combine hai verify group để không bỏ sót command.
+
 ## Ownership của state
 
 | State | Owner | Vị trí | Commit |
@@ -65,6 +215,11 @@ Folder `extensions/` vẫn chứa một số service module do lịch sử. Tên
 | Platform install config | Piagent installer | global Pi settings | Không |
 | Project profile và lock | Project | `.pi/piagent-profile*.json` | Có |
 | Task, trace, telemetry, capture | Runtime | `.pi/piagent-state/` | Không |
+| Task journal và checkpoint | Runtime audit | `.pi/piagent-state/task-journal/` | Không |
+| Trajectory phase/events | Runtime derived state | `.pi/piagent-state/trajectory/` | Không |
+| Recovery handoff projection | Runtime derived state | `.pi/piagent-state/handoffs/` | Không |
+| Piagent-owned helper budget | Runtime owned state | `.pi/piagent-state/helper-budgets/` | Không |
+| Repository memory fact | Runtime advisory memory | `.pi/piagent-state/repository-memory/` | Không |
 | Session history | Pi | Pi session store | Không |
 | Shared project instructions | Project | `AGENTS.md`, project docs | Có |
 

package/docs/vi/maintainer-guide.md

@@ -37,18 +37,31 @@ Không tạo folder `utils` để gom code không rõ ownership. Module phải m
 - `runtime/hooks/input-hook.ts`
 - `runtime/hooks/agent-start-hook.ts`
 - `runtime/hooks/completion-hook.ts`
+- `runtime/hooks/tool-call-hook.ts`
 - `runtime/hooks/tool-result-hook.ts`
+- `runtime/context/adaptive-planner.ts`
+- `runtime/context/retrieval-route-policy.ts`
+- `runtime/model/capabilities.ts`
+- `runtime/model/model-route-types.ts`
+- `runtime/model/model-route-policy.ts`
+- `runtime/model/model-route-runtime.ts`
+- `runtime/model/model-selection-provenance.ts`
 - `runtime/tools/tool-groups.ts`
 - `runtime/workflows/input-routing.ts`
 - `runtime/workflows/task-intake.ts`
 - `runtime/runtime-limits.ts`
+- `extensions/task-journal.js`
+- `extensions/task-runtime-audit.js`
+- `extensions/repository-memory.js`
+- `extensions/verification-intelligence.js`
+- `extensions/execution-backend.js`
 
 Những feature cần tách tiếp theo một khối trọn vẹn:
 
-1. `runtime/hooks/tool-call-hook.ts`: enforcement trước tool call cho capability, path, shell, external action, task scope và confirmation.
+1. Chuyển phần policy decision body đang được wire qua `runtime/hooks/tool-call-hook.ts` vào core service nhỏ.
 2. `runtime/tools/`: policy, task, context, memory, onboarding, profile, document và source tools.
 3. `runtime/commands/`: workflow, session, permission, context, MCP, profile, onboarding và compatibility alias.
-4. Tạo core service tập trung cho profile, memory, onboarding và source-cache algorithm vẫn còn nằm trong composition root.
+4. Tiếp tục đưa context, policy, onboarding, profile và source-cache call site về owning service; task audit và verifier selection đã đi qua focused service thay vì nằm trong composition root.
 
 Mục tiêu: composition root dưới 500 dòng, chỉ giữ registration order và một shared runtime state object nhỏ.
 
@@ -102,6 +115,26 @@ Tách `scripts/benchmark-runner.mjs` thành CLI mỏng và package module cho su
   code thực thi trước khi release được phép pass.
 - Mỗi filesystem write phải khai báo path, mode, retention và source of truth.
 - Mỗi derived metric phải nêu input và có unit test tính tay một ví dụ.
+- Thay đổi adaptive context phải ghi plan receipt, phase, lane, budget, model,
+  thinking level và confidence threshold vào telemetry.
+- Thay đổi task recovery phải giữ task contract là operational truth và task
+  journal là audit/replay truth; không được để checkpoint derived thay thế ngầm
+  một contract hợp lệ.
+- Recovery ceiling là invariant xuyên task attempt. Classifier mới không được
+  grant mutation; policy vẫn phải kiểm tra riêng source ownership, task scope và
+  hook authorization. Handoff/receipt state chỉ lưu bounded reference, không lưu
+  raw verifier log hay source.
+- Thay đổi resume phải so actual current tree với exact-verifier evidence và
+  fail closed khi identity, journal, trajectory, handoff hoặc symlink integrity
+  lỗi. Byte của terminal Task Contract phải immutable.
+- Thay đổi helper phải giữ pinned parent, one-writer invariant, strict
+  RolePolicy/HelperRequest scope intersection, cross-process owned budget và
+  digest-only usage receipt. Ở GA, `on` chỉ dispatch read-only role; automatic
+  worker delegation vẫn disabled.
+- Operator projection phải đọc persisted/observed truth, vẫn dùng được khi
+  sidecar cũ bị thiếu, hash session identity và giữ timing/token/cost fact không
+  có nguồn ở null. Thay đổi formatting phải giữ structured schema/version và
+  ranh giới host-không-phải-sandbox rõ ràng.
 
 ## Checklist khi thay đổi