@piagent/platform 1.2.17 → 1.3.0-ie.9

package/docs/en/architecture.md

@@ -53,10 +53,164 @@ The machine-readable rule is `architecture/layers.json`; `npm run architecture:c
 1. Pi loads the single extension entrypoint.
 2. Composition resolves base policy, project profile, capability lock, and local session state.
 3. Runtime hooks normalize input and collect session evidence through one session-scoped state owner.
-4. Core services decide path, shell, MCP, task, context, and final-gate policy.
+4. Core services decide path, shell, MCP, task, context, recovery, memory, verification, and final-gate policy.
 5. Runtime adapters register concise tools and slash commands.
 6. Owner-only local state records evidence; prompts remain guidance rather than the enforcement boundary.
 
+## Adaptive durable runtime
+
+The current runtime has six operational/derived state layers:
+
+| 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 plus observed lifecycle/tool evidence | `.pi/piagent-state/trajectory/*.json` current phase and bounded transition replay |
+| Recovery handoff | Contract, verified journal, trajectory, current tree, and exact-verifier evidence | `.pi/piagent-state/handoffs/*.json` bounded reconstruction projection |
+| Context index | Repository files plus resolved exclusion policy digest | SQLite FTS/search pack, context efficiency report |
+| Repository memory | Cited facts/decisions with file digests and expiry | Advisory retrieval hints only |
+
+The task journal is owner-readable, hash chained, and sequence numbered. Runtime
+records task start/progress, observed mutation, verifier, and completion
+checkpoints. Writes are append-only between bounded retention compactions; each
+compaction re-hashes the retained chain and stores the removed-prefix and prior
+head hashes as retention anchors. A normal task write does not trust the journal
+as operational state. Resume decisions use the current task contract first and
+the verified journal second; corruption blocks automatic resume for review.
+The journal hash chain and acceptance receipts are same-runtime operational
+evidence, not independent attestation or a separate audit authority.
+
+Recovery is classification-driven and bounded across task attempts. Only an
+in-scope source-owned failure may receive one repair pass; transient verifier or
+provider failures receive at most one exact retry and never source-mutation
+authority. Environment, permission, policy, scope, and unknown failures stay
+non-mutating. `PIAGENT_AUTO_RECOVERY=off` restores ordinary P3 handoff behavior
+without migrating state. Every final path writes a redacted Handoff v1
+projection from operational truth. Resume binds task/session identity, journal
+integrity, trajectory phase, current-tree digest, and exact verifier evidence;
+a post-verify edit invalidates the old pass, while corrupt or symlink-unsafe
+state blocks mutation. Acceptance criteria remain the completion truth; an
+optional runtime-observed provenance block only distinguishes first-pass,
+repaired, blocked, partial, and failed outcomes using bounded references.
+
+Semantic specialist review is a separate strict-high-risk CAP-13 path, not a
+universal parser-driven recovery path. It is pinned to one shared continuation,
+one current-tree diff, two targeted reads, exact eligible source/test paths, and
+the configured verifier after any mutation. Denied, failed, no-op, stale,
+out-of-scope, unsupported, or exhausted work locks the opportunity and hands
+off. Broad-default observation/advice never schedules this review or blocks a
+tool call.
+
+The Adaptive Context Planner runs before auto context injection. It uses the
+classified workflow phase, risk lane, explicit paths, current context pressure,
+Pi-reported model identity, and thinking level to choose a hard token budget and
+file limit. It never switches model/provider. No local semantic reranker is
+shipped yet, so the plan reports `reranker: off` even if a legacy environment
+flag is present. Each injected pack carries a receipt so reports can explain why
+those paths entered context.
+
+Task Contract v2 also carries an additive Criterion Graph v1 planning
+projection. It maps every operator criterion exactly once to a closed planning
+kind, scoped target hints, proof kinds, and dependency order. The graph has no
+`satisfied` state and cannot override acceptance or exact-verifier truth. It
+selects relevant in-scope context before older observations, survives
+compaction/resume by digest, and adds no tool-schema change or provider follow-up
+turn. `PIAGENT_INTELLIGENCE_ENGINE=off` selects the mechanical control for
+causal tests and emergency rollback; new tasks otherwise use the criterion
+engine and pin its mode/digest in the task contract.
+
+Completed tasks may add a short-lived, cited retrieval fact. A later turn can
+inject at most the memory hints that fit inside the context plan's unused token
+budget; current repository files remain authoritative.
+
+Trajectory is phase evidence, never a second completion outcome. The solver may
+recommend a path, while observed Task Contract and tool evidence own transitions
+through `intake`, `scout`, `plan`, `execute`, `verify`, `repair`, `review`,
+`handoff`, and `terminal`. `/piagent-status` and `/task-preflight` expose the
+current phase. Corrupt or symlink-unsafe trajectory state disables phase-tool
+enforcement and reports recovery instead of guessing.
+
+`PIAGENT_PHASE_TOOLS=off|shadow|on` controls phase enforcement. `shadow` is the
+default and records intended differences without changing behavior; `on` keeps
+one cache-stable provider-visible tool schema and enforces the current phase at
+the tool-call guard; `off` disables that phase decision even when sidecars
+exist. Automatic source tasks enter `execute` only when their runtime-owned
+contract has a dependency-ready `single-writer` step, exact verifier, bounded
+scope, and acceptance receipt. Manual and high-risk tasks remain discovery-only
+through their plan/challenge checkpoints. Tool visibility is not authorization:
+scope, read-only, protected-path, destructive, and external-action guards remain
+active in every mode and for every mutation path. Piagent state/project mutators
+use Pi 0.84.1 native sequential execution metadata, pure reads remain
+parallel-safe, and Pi retains its native per-file mutation queue. No custom
+runtime lock is acquired in authorization hooks.
+
+Acceptance assurance and semantic repair have independent off-only rollback
+switches. Turning acceptance assurance off also turns dependent semantic repair
+off; turning semantic repair off leaves phase, acceptance observation, and
+recovery intact. Strict semantic repair requires enforced phase and recovery
+authority, and combined automatic dispatch authority is capped at one unit per
+task. These interaction checks are snapshot-bound and cannot change the
+provider-visible tool schema.
+
+Piagent-owned helpers use RolePolicy v1 and HelperRequest v1. The request binds
+a hashed session/task identity, bounded objective, read/write scope, exact tool
+allowlist, authenticated model/effort source, context/time/call ceilings, output
+schema, stopping rule, approval restrictions, and deduplication key. Read-only
+roles cannot receive mutation tools. Worker remains disabled by default and
+requires an explicit single-writer lease. `PIAGENT_HELPERS_MODE=off|recommend|on`
+defaults to `recommend`; `on` permits only read-only dispatch through an
+installed provider adapter. CAP-14 permits at most one automatic helper dispatch
+per task/run; the lower-level owner budget still caps two concurrent and three
+total explicitly owned helper reservations, deduplicates equivalent work, recovers
+expired reservations without adding budget, and cancels late work when the
+parent Task Contract becomes terminal. It does not claim control over unrelated
+Pi sessions or account usage, and never changes the user-pinned parent model.
+Dispatch enforces the request's time, call, and token ceilings at result merge:
+timeout, overflow, cancellation, or stale results cannot contribute output.
+Successful helpers expose only a redacted bounded summary with the parent as
+the sole merge owner; raw child output is represented by a digest in durable
+usage evidence and is never merged automatically.
+
+The product-facing runtime view is a deterministic projection over these same
+facts. `/task-preflight` separates observed runtime facts, solver
+recommendations, active policy mode, approvals, and blockers; it never grants
+implementation authority to read-only, plan, review, protected, destructive,
+or external work. `/piagent-status` joins Task Contract, journal, trajectory,
+resume, recovery, helper, and runtime-model evidence without a model turn.
+Terminal output embeds a bounded completion receipt and task-efficiency view.
+Task/session/run identity is joinable through a hashed session id; raw task text
+and helper output are not retained. Phase time comes only from persisted
+transitions, while unmeasurable edit timing, token totals, and cost remain null.
+Same-runtime evidence is operational assurance, never an independent audit.
+
+Until controlled beta cohorts and the independent usability/platform gates are
+complete, the frozen safe defaults remain criterion engine `on`, solver `shadow`, phase tools
+`shadow`, recovery `on`, helpers `recommend`, parent routing `off`, automatic
+workers `off`, and host execution. Implementation completion alone cannot
+promote a mode. Feature-off reads existing sidecars without deleting them.
+
+Parent routing now has a versioned `low|medium|high|ultra` capability contract,
+selection provenance, exact authenticated-catalog matching, and
+`intelligence|balance|cost` objectives. It classifies before a fresh task call,
+never switches models mid-conversation, preserves `/model` and CLI pins, and
+fails closed when provenance or host capability is unknown. Pi 0.84.1's
+extension model switch also updates user default state, so extension `auto`
+remains recommendation-only; enforcement is limited to the explicit
+`piagent-route --execute --yes` prelaunch adapter. The default remains `off`
+until authenticated G1/G2 evidence passes every >=9.5 aggregate gate and every
+individual outcome is strictly above 9.5.
+
+Retrieval routing similarly remains conservative: a low-confidence or broad
+search can recommend a read-only retriever restricted to grep/find/read with at
+most two parallel searches over two rounds. Automatic dispatch stays false.
+
+The execution backend contract is fail-closed. Host execution remains the
+default and Pi owns OAuth/session credentials. Requesting docker, devcontainer,
+or sandbox without an installed adapter blocks mutation instead of silently
+falling back to host execution. Mixed frontend/backend task scope selects the
+comprehensive `source` verifier group; docs plus source scope combines both
+relevant verifier groups without dropping either command set.
+
 ## State ownership
 
 | State | Owner | Location | Commit |
@@ -65,6 +219,11 @@ The machine-readable rule is `architecture/layers.json`; `npm run architecture:c
 | Platform install config | Piagent installer | global Pi settings | No |
 | Project profile and lock | Project | `.pi/piagent-profile*.json` | Yes |
 | Task, trace, telemetry, captures | Runtime | `.pi/piagent-state/` | No |
+| Task journal and checkpoints | Runtime audit | `.pi/piagent-state/task-journal/` | No |
+| Trajectory phase/events | Runtime derived state | `.pi/piagent-state/trajectory/` | No |
+| Recovery handoff projections | Runtime derived state | `.pi/piagent-state/handoffs/` | No |
+| Piagent-owned helper budgets | Runtime owned state | `.pi/piagent-state/helper-budgets/` | No |
+| Repository memory facts | Runtime advisory memory | `.pi/piagent-state/repository-memory/` | No |
 | Session history | Pi | Pi session store | No |
 | Shared project instructions | Project | `AGENTS.md`, project docs | Yes |
 

package/docs/en/maintainer-guide.md

@@ -37,18 +37,31 @@ Already extracted:
 - `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`
 
 Next cohesive extractions:
 
-1. `runtime/hooks/tool-call-hook.ts`: pre-call capability, path, shell, external-action, task-scope, and confirmation enforcement.
+1. Move the policy decision body now wired through `runtime/hooks/tool-call-hook.ts` into focused core services.
 2. `runtime/tools/`: policy, task, context, memory, onboarding, profile, document, and source tools.
 3. `runtime/commands/`: workflow, session, permission, context, MCP, profile, onboarding, and compatibility aliases.
-4. Focused core services for the remaining profile, memory, onboarding, and source-cache algorithms still embedded in the composition root.
+4. Continue moving context, policy, onboarding, profile, and source-cache call sites behind their owning services; task audit and verifier selection already leave the composition root through focused services.
 
 Target: the composition root stays below 500 lines and contains registration order plus a small shared runtime state object.
 
@@ -102,6 +115,26 @@ Split `scripts/benchmark-runner.mjs` into a thin CLI plus package modules for su
   runtime code before a release can pass.
 - Every filesystem write declares path, mode, retention, and source of truth.
 - Every derived metric names its inputs and has a unit test with a hand-computed example.
+- Adaptive context changes must record the plan receipt, phase, lane, budget,
+  model, thinking level, and confidence threshold in telemetry.
+- Task recovery changes must keep task contract as operational truth and task
+  journal as audit/replay truth; never let a derived checkpoint silently replace
+  a valid contract.
+- Recovery ceilings are cross-attempt invariants. New classifiers cannot grant
+  mutation; policy must separately require source ownership, task scope, and
+  hook authorization. Handoff/receipt state stores bounded references, never
+  raw verifier logs or source.
+- Resume changes must compare the actual current tree with exact-verifier
+  evidence and fail closed on identity, journal, trajectory, handoff, or symlink
+  integrity errors. Terminal Task Contract bytes remain immutable.
+- Helper changes must preserve the pinned parent, one-writer invariant, strict
+  RolePolicy/HelperRequest scope intersection, cross-process owned budget, and
+  digest-only usage receipts. `on` may dispatch only read-only roles for GA;
+  automatic worker delegation remains disabled.
+- Operator projections must read persisted/observed truth, remain usable when
+  old sidecars are missing, hash session identity, and leave unavailable
+  timing/token/cost facts null. Formatting changes must preserve the structured
+  schema/version and the explicit host-not-a-sandbox boundary.
 
 ## Change checklist
 

package/docs/model-options.md

@@ -4,7 +4,35 @@ Pi Agent Platform không khóa vào một provider. Hai họ model dưới đây
 
 Lưu ý cách đọc: trong toàn bộ tài liệu này, "Codex" và "Claude" là **tên họ model** đứng sau các provider id ở trên. Chúng không phải tên CLI, và cũng không phải một agent nào khác — mọi thứ ở đây đều chạy trong Pi.
 
-Quan trọng: flow chính là user chọn model bằng native Pi selector, không phải hỏi agent recommend.
+Flow mặc định vẫn là user chọn model bằng native Pi selector. Adaptive routing
+chỉ hoạt động khi operator chọn mode tương ứng; `/model`, CLI `--model`, hoặc
+`--thinking` là hard pin và luôn thắng router.
+
+## Capability routing trước task
+
+Piagent có contract `low | medium | high | ultra`, tách khỏi tên model cụ thể.
+Mapping đánh giá OpenAI hiện tại là Luna/medium, Terra/medium, Sol/high và
+Sol/xhigh; authenticated catalog phải có đúng model/effort, nếu không decision
+trả `unavailable` thay vì substitute.
+
+```text
+PIAGENT_PARENT_ROUTING=off|shadow|recommend|auto
+PIAGENT_ROUTING_OBJECTIVE=intelligence|balance|cost
+```
+
+- `shadow`: tính và lưu decision đã redaction, không đổi model.
+- `recommend`: hiện band/model/effort và reason trong `/task-preflight`.
+- `auto`: extension hiện fail-closed về recommend. Task-boundary adapter an toàn
+  là lệnh prelaunch rõ ràng:
+
+```bash
+piagent-route --prompt "Fix src/parser.ts and run npm test" --json
+piagent-route --prompt-file /path/to/task.txt --execute --yes -- --approve
+```
+
+`--execute --yes` mới bắt đầu provider-backed task. Router từ chối explicit pin,
+task chưa qua preflight, catalog thiếu, hoặc decision không đủ điều kiện. Nó
+không đổi model giữa thread và không ghi raw prompt vào route evidence.
 
 ## Flow chuẩn sau OAuth
 
@@ -50,7 +78,12 @@ piagent-models --provider openai-codex
 piagent-models --provider anthropic
 ```
 
-Lưu ý: `--list-models` chỉ hiện model mà Pi xem là available với credential/provider hiện tại. Nếu chưa login Anthropic, các model Claude có thể chưa hiện dù model catalog local có metadata.
+Lưu ý: `--list-models` và `piagent-models` chỉ hiện model mà Pi xem là
+available với credential/provider hiện tại. `piagent-models --json` ghi rõ
+`authenticated`, `logged-out`, `offline` hoặc `unavailable`; nó không đọc public
+catalog rồi trình bày như quyền truy cập đã xác thực. Nếu một model đã seed vào
+scope nhưng chưa available, report giữ nguyên tên và cảnh báo, không substitute
+sang model khác.
 
 ## Thinking levels
 
@@ -80,9 +113,9 @@ pi --thinking medium
 | `openai-codex/gpt-5.4-mini` | fast/cheap | scout nhẹ, docs, simple fix |
 | `openai-codex/gpt-5.4` | balanced | task bình thường |
 | `openai-codex/gpt-5.5` | balanced/hard default | default mạnh cho implement |
-| `openai-codex/gpt-5.6-luna` | focused hard | debug/review/test khó, cần reasoning sâu nhưng scope hẹp |
-| `openai-codex/gpt-5.6-sol` | strategic/deep | architecture, large refactor, planning lớn |
-| `openai-codex/gpt-5.6-terra` | huge-context scout | đọc nhiều docs/source, tổng hợp repo lớn |
+| `openai-codex/gpt-5.6-luna` | cost-sensitive/high-volume | workload nhanh, nhiều lượt, ưu tiên latency và chi phí |
+| `openai-codex/gpt-5.6-terra` | balanced | công việc hằng ngày cần cân bằng capability, speed và cost |
+| `openai-codex/gpt-5.6-sol` | frontier/quality-first | task phức tạp, long-horizon hoặc cần chất lượng cao nhất |
 
 ### Họ model Claude (Anthropic)
 
@@ -102,15 +135,17 @@ Pi catalog có thể có thêm dated variants như `*-2025xxxx`. Dùng alias lat
 
 ## Recommended presets
 
-Preset dưới đây là cách mình seed `enabledModels`, không phải giới hạn hard. User vẫn có thể mở `/model` để chọn bất kỳ model available nào trong provider catalog.
+Preset dưới đây là benchmark seed cho `enabledModels`, không phải universal
+routing truth hay giới hạn hard. User vẫn có thể mở `/model` để chọn bất kỳ model
+available nào trong authenticated provider catalog.
 
 | Preset | Model OpenAI Codex | Model Claude (Anthropic) | Khi dùng |
 |---|---|---|---|
 | Fast scout | `openai-codex/gpt-5.4-mini:low` | `anthropic/claude-haiku-4-5:low` | đọc nhanh, hỏi đáp, grep/scout nhẹ |
 | Balanced implement | `openai-codex/gpt-5.5:medium` | `anthropic/claude-sonnet-5:medium` | task source bình thường |
-| Hard implement | `openai-codex/gpt-5.6-luna:xhigh` hoặc `openai-codex/gpt-5.5:xhigh` | `anthropic/claude-sonnet-5:xhigh` | task nhiều file, contract mapping, debug khó |
-| Strategic/deep | `openai-codex/gpt-5.6-sol:xhigh` | `anthropic/claude-opus-4-7:max` hoặc `anthropic/claude-opus-4-8:max` | architecture, large refactor, high-risk review |
-| Huge-context scout | `openai-codex/gpt-5.6-terra:xhigh` | `anthropic/claude-fable-5:max` | đọc nhiều docs/context, tổng hợp repo lớn |
+| Cost-sensitive volume | `openai-codex/gpt-5.6-luna:medium` | `anthropic/claude-haiku-4-5:low` | workload nhanh, nhiều lượt; đo quality gate trước khi promote |
+| Balanced implement | `openai-codex/gpt-5.6-terra:high` hoặc `openai-codex/gpt-5.5:high` | `anthropic/claude-sonnet-5:high` | task source hằng ngày, cân bằng capability/cost |
+| Frontier/quality-first | `openai-codex/gpt-5.6-sol:high` | `anthropic/claude-opus-4-7:xhigh` hoặc `anthropic/claude-opus-4-8:xhigh` | architecture, long-horizon, high-risk review |
 
 Tên model có thể đổi theo Pi model catalog. Khi không chắc, ưu tiên `/model` hoặc `pi --list-models`.
 
@@ -140,7 +175,7 @@ Shift+Tab
 Nếu muốn đặt default khác:
 
 ```bash
-piagent-model-scope --preset full --default-model openai-codex/gpt-5.6-sol:xhigh
+piagent-model-scope --preset full --default-model openai-codex/gpt-5.6-sol:high
 piagent-model-scope --preset full --default-model anthropic/claude-sonnet-5:xhigh
 ```
 
@@ -157,8 +192,19 @@ piagent-benchmark --model <provider/model> --thinking high
 Runner đọc model/thinking/token/cost từ Pi session và chỉ kết luận efficiency
 khi quality/safety gates vẫn đạt. Dùng một report riêng cho mỗi model preset.
 
+Khi migrate model family, giữ effort hiện tại làm baseline rồi chạy cùng effort
+và đúng một level thấp hơn trên representative tasks. Ví dụ baseline `high` thì
+so `high` với `medium`; không đặt `xhigh` hay `max` làm mặc định chung chỉ vì
+model hỗ trợ level đó. Promote seed chỉ khi paired report giữ quality, safety,
+reliability và workflow gate.
+
 So sánh tối thiểu:
 
 - Pi + model Codex ở fast/balanced/deep;
 - Pi + model Claude ở fast/balanced/deep;
 - any other approved setup nếu team muốn so sánh bằng số liệu.
+
+`/task-preflight` và `/piagent-status` chỉ report model/effort/context có
+provenance từ Pi runtime hoặc authenticated catalog. Solver/helper không tự đổi
+parent model đã pin. Nếu fact chưa có ngoài Pi session, UI ghi `unknown`; không
+substitute model và không ước lượng token/cost.

package/docs/operator-manual-vietnamese.md

@@ -13,17 +13,17 @@ Từ đó Pi có thể login provider, chọn model, onboard project, chạy tas
 
 Runtime team nên pin release tag hoặc commit đã review. Latest chỉ dùng cho máy cá nhân/sandbox khi chấp nhận cập nhật nhanh.
 
-Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy `piagent-doctor` + smoke test trước khi rollout rộng; native Windows chưa phải target rollout team; WSL2 experimental/chưa release-gate. Node.js tối thiểu là `22.19.0`, Pi Coding Agent là `0.82.0`.
+Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy `piagent-doctor` + smoke test trước khi rollout rộng; native Windows chưa phải target rollout team; WSL2 experimental/chưa release-gate. Node.js tối thiểu là `22.19.0`, Pi Coding Agent là `0.84.1`.
 
 ```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.9
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.17`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.3.0-ie.9`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -37,7 +37,7 @@ bash scripts/install-global.sh --stable
 Full update phải đồng bộ exact Pi host trước, rồi npm-global helper và Pi package matching:
 
 ```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
@@ -98,8 +98,8 @@ install package once
 ### Cài Pi và package platform
 
 ```bash
-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.9
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -282,7 +282,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.17 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.3.0-ie.9 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -410,6 +410,73 @@ Git trong Pi Agent là capability + guard, không có namespace `/git-*`. Khi mu
 
 `/workflow commit` inspect status/diff, stage đúng scope, verify phù hợp, rồi commit local; không push. `/workflow pr` inspect branch/diff/commit rồi hỏi xác nhận trước khi `git push` hoặc tạo/cập nhật GitHub PR. Alias `/commit` và `/pr` vẫn chạy cho power user. Các lệnh stage rộng như `git add .`, `git add -A`, `git add --all`, `git add -- .`, `git add :/` cũng phải qua confirmation.
 
+### Preflight, live status và receipt
+
+Trước task hoặc khi cần kiểm tra deterministic state, dùng:
+
+```text
+/task-preflight
+/piagent-status
+/piagent-inspector
+/usage efficiency
+```
+
+Preflight phân biệt rõ mode `shadow`, `assist`, `enforce`; runtime fact chưa có
+được ghi là `unknown`. Nó hiển thị intent/risk/scope, model và effort provenance,
+solver route, phase, context/tool/helper budget, backend, approval và blocker.
+Read-only/plan/review không bao giờ hiện implementation authorization. Dòng
+`host execution is not a sandbox` là boundary thật: Piagent policy giảm lỗi thao
+tác nhưng không cô lập code khỏi account của operator.
+
+`/piagent-status` đọc Task Contract, checkpoint, trajectory, verifier, recovery,
+helper và resume state đã lưu, không hỏi model nhớ lại. Khi terminal, JSON detail
+có completion receipt: outcome, acceptance, changed-tree identity, exact verify,
+review/helper/recovery, remaining risk và handoff. Receipt chỉ gọi là complete
+khi hard completion gate trên working tree hiện tại pass, trace terminal là
+`completed`, và mọi acceptance criterion đều satisfied. Thiếu gate evidence phải
+fail closed thay vì suy đoán từ state cũ; evidence cùng runtime không được
+gọi là independent audit. Tắt từng lớp bằng `PIAGENT_SOLVER_MODE=off`,
+`PIAGENT_PHASE_TOOLS=off`, `PIAGENT_AUTO_RECOVERY=off`, hoặc
+`PIAGENT_HELPERS_MODE=off`. Hai lớp semantic có kill switch độc lập:
+`PIAGENT_ACCEPTANCE_ASSURANCE=off` tắt assurance và semantic repair phụ thuộc,
+còn `PIAGENT_SEMANTIC_REPAIR=off` chỉ tắt repair/review. Các biến này chỉ được
+hạ authority, không được dùng để nâng mode ngoài profile đã pin; state cũ được
+giữ để có thể tạo attempt mới có provenance rõ ràng.
+
+`/piagent-inspector` là một namespace read-only, không sinh thêm command rời.
+Gõ không tham số để chọn `summary`, `files`, `commands`, `security`, `context`
+hoặc `toggle`. Panel bốn dòng tự hiện sát phía trên footer native từ lúc mở session:
+phase và việc hiện tại; task file/test, `+/-`, command pass/fail/block, safety và
+context budget. Nó dùng extension-status API nên không thay footer native của
+Pi và không thêm bước bắt buộc vào workflow. Dòng status dùng file task đã quan
+sát để phản hồi nhanh; view `files` tính exact snapshot delta. Task đụng file dirty từ trước được
+đánh dấu mixed baseline; token theo từng built-in tool luôn unavailable vì Pi
+chỉ cung cấp usage exact theo response/turn.
+
+Known unsupported/unpromoted surfaces của candidate hiện tại: parent routing
+đã có `off|shadow|recommend|auto`, nhưng extension `auto` fail-closed về
+recommend; chỉ `piagent-route --execute --yes` là explicit prelaunch boundary.
+Authenticated G1/G2 chưa chạy nên default vẫn `off`. Helper không tự đổi parent model; automatic worker và
+multi-writer luôn off; helper `on` chưa phải default; docker/devcontainer/
+sandbox không chạy nếu chưa có adapter và không âm thầm fallback; native Windows
+không nằm trong rollout matrix. Local scripted pilot không thay thế năm người
+độc lập, và same-process receipt không thay thế security audit.
+
+Kiểm tra decision trước khi chạy:
+
+```bash
+piagent-route --prompt "Fix src/parser.ts and run npm test" --json
+```
+
+Chỉ khi muốn router thực sự mở một fresh Pi process mới dùng:
+
+```bash
+piagent-route --prompt-file /path/to/task.txt --execute --yes -- --approve
+```
+
+Lệnh này dùng authenticated `pi --list-models`, không đọc credential store,
+không ghi raw task vào route sidecar, giữ hard pin, và từ chối task bị blocked.
+
 ## 5. Control flow của một task chuẩn
 
 Một source-changing task nên đi qua:
@@ -607,11 +674,11 @@ piagent-benchmark --production --dry-run
 
 Lệnh mặc định tự chạy 4 scenario trên Raw Pi và Piagent, mỗi bên 3 lần; token,
 cost, model và thinking được đọc từ Pi session thay vì nhập tay. Runner chỉ cho
-phép kết luận tiết kiệm token khi 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, có ít nhất ba cặp cùng model với exact
-usage và geometric mean của tỷ lệ fresh token `Piagent / Raw Pi` theo từng cặp
-thực sự nhỏ hơn `1`.
+phép kết luận tiết kiệm token khi safety đạt `10/10` và các gate quality,
+reliability, workflow của suite đều pass. Production yêu cầu các điểm tổng hợp
+ít nhất `9.5/10`, đồng thời từng task và từng category/profile/lifecycle/
+difficulty band phải lớn hơn `9.5`; quality không giảm và paired usage cùng
+model phải vượt confidence gate.
 
 Lệnh không flag là smoke suite 24 session. Khi chốt thay đổi lớn về harness,
 model hoặc token policy, dùng `--production`: 18 scenario family, ba generated
@@ -631,8 +698,9 @@ So sánh trực tiếp với surface `codex-cli` đã đăng nhập:
 ```bash
 piagent-benchmark \
   --surfaces piagent,codex-cli \
-  --model openai-codex/gpt-5.6-sol \
-  --thinking xhigh
+  --model openai-codex/gpt-5.6-luna \
+  --thinking medium \
+  --piagent-treatment candidate
 ```
 
 Chế độ mặc định là `controlled`: Codex chạy ephemeral, chỉ được ghi trong
@@ -971,8 +1039,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.2.17` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.17` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.3.0-ie.9` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.3.0-ie.9` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -1020,6 +1088,7 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 | `Ctrl+P` | Cycle scoped models. |
 | `Shift+Tab` | Cycle thinking level. |
 | `/commands` | Menu/help command runtime theo topic. |
+| `/piagent-inspector` | Menu read-only cho task diff/file test/line, command, safety và context; `toggle` ẩn/hiện panel bốn dòng trong session. |
 | `/workflow` | Menu task/scout/review/git/onboard workflow. |
 | `/permission` | Menu permission status/read-only/workspace-write/full-access. |
 | `/permission status` | Xem permission profile hiện tại. |
@@ -1083,7 +1152,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.2.17
+npm install -g --ignore-scripts @piagent/platform@1.3.0-ie.9
 command -v piagent-install
 ```
 

package/docs/project-adapters.md

@@ -95,7 +95,9 @@ Quy tắc:
 
 ## Monorepo và workspace
 
-Một project = một thư mục mở `pi`. Guard đọc profile tại `<cwd>/.pi/piagent-profile.json` và không đi ngược lên tìm, nên mở `pi` ở thư mục cha chứa nhiều project sẽ bỏ qua profile của từng project con và chạy unprofiled.
+Một project = một thư mục mở `pi`. Guard đọc profile tại `<cwd>/.pi/piagent-profile.json` và không đi ngược lên tìm, nên nếu mở `pi` ở thư mục cha thì thư mục cha đó cũng phải có `.pi/piagent-profile.json`.
+
+Workspace cha chứa nhiều Git repo riêng được hỗ trợ cho luồng BE-to-FE nội bộ: ví dụ mở `pi` tại `Working/`, bên trong có `v-nexus-frontend/` và `v-nexus-backend/`, mỗi thư mục con vẫn là Git repo riêng. Source-change task dùng Git evidence từ các repo con trực tiếp và prefix file bằng tên repo (`v-nexus-frontend/src/...`). File nằm ở workspace cha nhưng không thuộc repo con, ví dụ `Working/plans/**`, dùng bounded file-digest evidence. Scope ghi nên trỏ rõ vào vùng được phép, ví dụ `v-nexus-frontend/**` và `plans/**`.
 
 Detect FE/BE đọc theo thứ tự:
 
@@ -123,10 +125,11 @@ Rule nằm ở `packages/piagent-core/extensions/project-shape.js`. Cả `piagen
 | `mobile` | React Native/Flutter | npm test / flutter test nếu tool có |
 | `docs` | Docs portal/manual | markdown diff check + test nếu project có |
 
-`be-readonly-fe` giữ read-only cho backend ở root (`backend`, `server`, `api`), ở một cấp dưới `apps/` và `packages/` (`api`, `server`, `backend`), toàn bộ `services/*`, và mọi `**/migrations/**`. Profile built-in là điểm khởi đầu, không phải danh sách đầy đủ — sửa `readOnlyPaths` **và** `shellProtectedPaths` trong `.pi/piagent-profile.json` cho đúng repo:
+`be-readonly-fe` giữ read-only cho backend ở root (`backend`, `server`, `api`), repo con trực tiếp có tên chứa `backend` như `v-nexus-backend`, ở một cấp dưới `apps/` và `packages/` (`api`, `server`, `backend`), toàn bộ `services/*`, và mọi `**/migrations/**`. Profile built-in là điểm khởi đầu, không phải danh sách đầy đủ — sửa `readOnlyPaths` **và** `shellProtectedPaths` trong `.pi/piagent-profile.json` cho đúng repo:
 
 - backend đặt tên khác (`apps/gateway`, `packages/core-service`): thêm path vào cả hai field.
 - frontend nằm trong `services/` (ví dụ `services/web`): `services/*/**` sẽ khoá nhầm nó. Thay pattern đó bằng danh sách service backend cụ thể. Triệu chứng là một write bị chặn kèm lý do trỏ tới `readOnlyPaths`, không phải lỗi im lặng.
+- FE và BE là hai repo ngang hàng: tạo profile ở workspace cha và dùng scope ghi kiểu `v-nexus-frontend/**` hoặc `plans/**`. BE repo có tên chứa `backend` được read-only tự động; nếu BE tên khác thì thêm đúng tên repo, ví dụ `v-nexus-api/**`, vào cả `readOnlyPaths` và `shellProtectedPaths`.
 
 ## Runtime profile selection