@piagent/platform 1.5.5 → 1.6.1

package/docs/release-install-policy.md

@@ -11,7 +11,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.84.1`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.5.5 | Rollout guidance |
+| Surface | Status for v1.6.1 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -106,7 +106,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.5.5` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.6.1` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -126,7 +126,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.5.5
+npm install -g --ignore-scripts @piagent/platform@1.6.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -134,8 +134,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.5.5 (helper package version)
-tag: v1.5.5
+currentRelease: v1.6.1 (helper package version)
+tag: v1.6.1
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -152,7 +152,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.5.5
+pi install git:github.com/Vt-mmm/piagent@v1.6.1
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -385,9 +385,10 @@ Re-running the workflow from a branch instead skips publishing, because the publ
    category bands và 95% token-ratio confidence nên là model-quota gate có xác
    nhận riêng, không chạy ngầm trong CI. Không claim token/cost nếu report không
    cho phép `tokenClaimAllowed` hoặc `productionGate.passed` khác `true`.
-   Zero-usage process failure có thể retry tối đa hai lần với backoff và phải xuất hiện trong
-   infrastructure ledger; timeout hay task failure không được retry để né điểm
-   reliability.
+   Release run yêu cầu zero infrastructure retry và zero unknown provider-attempt
+   usage. Diagnostic retry override phải xuất hiện trong infrastructure ledger
+   và làm production claim fail; timeout hay task failure không được retry để né
+   điểm reliability.
 
 3. Push the release-candidate branch, open a pull request to `main`, and wait for both Ubuntu/macOS verify jobs and both CodeQL matrix jobs to pass. Record the exact PR-head commit SHA that passed; do not merge it into the Vercel production branch yet, and do not tag a later unverified edit.
 4. Create an annotated, reviewed tag on that exact verified commit and push the tag. Pushing the tag starts `publish.yml`, which runs the full verify matrix as a dependency and only then publishes, so a failure on any supported runtime stops the release before it reaches the registry:

package/docs/runtime-harness-standard.md

@@ -111,15 +111,15 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
 
 4. Implement
    - tool-call hook checks shell, capabilities and external actions automatically
-   - edit only in scope
+   - follow repository evidence across packages/child repositories; task scope is an initial focus
    - avoid protected paths
-   - block direct and shell writes outside scope
+   - block protected/read-only paths and unbounded opaque shell writes
 
 5. Verify
    - run every exact mapped verify command
    - tool-result hook records exact observed evidence after task start
    - bind passing evidence to the current working-tree digest
-   - reconcile changed files against baseline and scope
+   - reconcile every changed file against the baseline; report focus expansion without blocking
    - if verify unavailable: not DONE
 
 6. Trace

package/docs/runtime-policy-design.md

@@ -51,7 +51,7 @@ Profiles define:
 - `rootMarkers`
 - `protectedPaths`
 - `shellProtectedPaths` — shell-only deny list for bash/exec parsing.
-- `readOnlyPaths` — path tools may read, but write/edit and shell access are denied.
+- `readOnlyPaths` — path tools may read, but `write`/`edit`/`apply_patch` and shell access are denied.
 - `requiredContext`
 - `verifyCommands`
 - `mcpCapabilities`
@@ -60,9 +60,9 @@ Profiles define:
 
 The same platform can operate as `web-frontend`, `backend-api`, `fullstack`, `be-readonly-fe`, `data`, `devops`, `docs`, `python`, `node-typescript`, or `mobile` by switching profile.
 
-`protectedPaths` blocks read/write path-tool access and is also used for shell matching when `shellProtectedPaths` is omitted. `readOnlyPaths` is for contracts such as `be-readonly-fe`: path tools may inspect these files with `read`, `grep`, `find`, and `ls`, but write/edit and shell access are blocked automatically.
+`protectedPaths` blocks `read`/`write`/`edit`/`apply_patch` access and is also used for shell matching when `shellProtectedPaths` is omitted. `readOnlyPaths` is for contracts such as `be-readonly-fe`: path tools may inspect these files with `read`, `grep`, `find`, and `ls`, but `write`/`edit`/`apply_patch` and shell access are blocked automatically.
 
-`shellProtectedPaths` is intentionally shell-only. A path declared only there blocks `bash`/`exec` access, but does not block `read`, `write`, or `edit` path tools. `profile-doctor` and `team-doctor` warn on shell-only entries so older custom profiles can migrate write-sensitive paths to `protectedPaths` or `readOnlyPaths`.
+`shellProtectedPaths` is intentionally shell-only. A path declared only there blocks `bash`/`exec` access, but does not block `read`, `write`, `edit`, or `apply_patch`. `profile-doctor` and `team-doctor` warn on shell-only entries so older custom profiles can migrate write-sensitive paths to `protectedPaths` or `readOnlyPaths`.
 
 ## Permission profiles
 
@@ -70,7 +70,7 @@ The runtime separates the active autonomy profile from the project profile:
 
 | Profile | Meaning |
 |---|---|
-| `read-only` | Allows source inspection through `read`, `grep`, `find`, `ls`, plus piagent state tools. Blocks shell, write/edit, and unknown non-piagent tools before execution. |
+| `read-only` | Allows source inspection through `read`, `grep`, `find`, `ls`, plus piagent state tools. Blocks shell, `write`/`edit`/`apply_patch`, and unknown non-piagent tools before execution. |
 | `workspace-write` | Default governed implementation mode. Existing protected-path, shell, capability, context, verify, and final gates remain active. |
 | `trusted-full-access` | Trusted automation mode for known repos. It can relax tool-registry blocks and capability filesystem scopes inside the guard, but protected paths, secret redaction, capability-lock integrity, and destructive/external confirmation still apply. |
 

package/docs/runtime-quality-baseline.md

@@ -27,7 +27,7 @@ piagent_permission_status
 
 Runtime behavior:
 
-- `read-only` chặn shell, write/edit, và unknown non-piagent tools;
+- `read-only` chặn shell, `write`/`edit`/`apply_patch`, và unknown non-piagent tools;
 - `workspace-write` là default cho implementation có guard;
 - `trusted-full-access` nới tool/scope autonomy trong môi trường trusted nhưng không tắt protected paths, redaction, capability lock, hoặc human gate cho destructive/external action.
 - `/permission full-access <task>` bật `trusted-full-access` cho session hiện tại rồi gửi phần task còn lại cho agent; `/permission status` hiển thị mode và boundary đang active. Alias `/full-access <task>` và `/permission-status` vẫn chạy.
@@ -45,7 +45,7 @@ Runtime behavior:
 - phân tích shell command trước khi chạy lệnh rủi ro;
 - block destructive patterns;
 - đệ quy vào shell wrapper phổ biến như `sudo`, `env`, `bash -c`, subshell, command substitution, và backtick;
-- check `shellProtectedPaths` cho bash, mặc định bảo vệ `.git`, `auth.json`, `.env`, `.env.*`; path chỉ nằm trong `shellProtectedPaths` là shell-only và không chặn write/edit;
+- check `shellProtectedPaths` cho bash, mặc định bảo vệ `.git`, `auth.json`, `.env`, `.env.*`; path chỉ nằm trong `shellProtectedPaths` là shell-only và không chặn `write`/`edit`/`apply_patch`;
 - kiểm tra cả bare filename, partial glob (`*`, `?`, character class, brace), symbolic-link alias đã canonicalize, và redirect shell có hoặc không có khoảng trắng;
 - redact sensitive text trong text result và JSON-like result details trước khi output được trả về model; non-text media block được giữ nguyên;
 - cảnh báo broad command prefix như `bash`, `python`, `node`, `git`, `sudo`;
@@ -230,7 +230,13 @@ chỉ lưu histogram tên tool. Chỉ claim chất lượng/token/cost khi các
 - 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.
+  cùng fixed-workload usage đủ confidence; production yêu cầu cận trên 95% của
+  primary fresh-token ratio `<=0.60`, exact accepted/failed-attempt usage và
+  complete evidence cho đủ 18/18 family, causal context receipt đầy đủ cho mọi
+  Piagent run, full suite và zero infrastructure retry/unknown usage. Tỷ lệ token
+  theo band/family, API-equivalent text-token cost và duration đều là diagnostic,
+  không chặn claim token-focused. Deep-logic vẫn là capability gate riêng với
+  token upper95 `<=0.80` và duration upper95 `<=1.10`.
 
 `piagent-benchmark <project> --record ...` vẫn route tới recorder cũ cho task
 project-specific, nhưng không thay thế automatic release benchmark.
@@ -238,10 +244,11 @@ project-specific, nhưng không thay thế automatic release benchmark.
 `core-v1` là smoke gate 24 session. Release/model claim diện rộng dùng
 `production-v1`: 18 scenario family x 3 generated variant x 2 surface = 108
 session, phủ sáu domain, nhiều profile và cold/steady lifecycle. Production gate
-chấm thêm từng category và cận trên 95% của paired token ratio; repeat được
+chấm thêm từng category và cận trên 95% của fixed-workload family token ratio;
+duration chỉ được report để chẩn đoán. Repeat được
 cluster theo scenario family nên không bị tính như bằng chứng độc lập. Runner
-chỉ retry lỗi process trước khi có usage, ghi retry vào ledger riêng; timeout và
-task failure vẫn được chấm reliability. Chi tiết và quy trình private held-out
+không retry trong release run; override retry được ghi vào ledger riêng và làm
+claim fail. Timeout và task failure vẫn được chấm reliability. Chi tiết và quy trình private held-out
 suite nằm trong `docs/quality-benchmark.md`.
 
 ## Runtime policy trong profile

package/docs/security-threat-model.md

@@ -25,7 +25,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.5.5, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.6.1, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes
@@ -54,7 +54,7 @@ The final category is outside the containment capability of the Piagent guard. I
 | Malicious project profile or relaxed capability lock | Trust-aware profile loading, deterministic lock digest, base-policy/source integrity, protected self-state, and fail-closed verification | An already trusted malicious repository can execute code through mechanisms outside the guard. |
 | 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. |
+| 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`, and `apply_patch` 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. |

package/docs/subagent-orchestration-capabilities.md

@@ -10,25 +10,25 @@ Package used:
 
 ## Kết luận
 
-Pi Agent Platform uses `pi-subagents` for child sessions, parallel read-only work, review loops, and structured handoffs. The platform keeps a safe default configuration and documents advanced commands separately so daily users can still start with `/workflow task`.
+Pi Agent Platform keeps `pi-subagents` installed for one exceptional fresh read-only helper. Daily work remains parent-direct. The package's broader parallel/worker features are not enabled by Piagent's governed baseline.
 
 Core decisions:
 
-1. natural-language delegation is preferred over requiring users to remember `/run`;
-2. parent agent should decide whether independent read-only work deserves subagents;
-3. piagent roles remain narrow and policy-aware;
-4. background, watchdog, scheduled, and parallel-writer behavior stays opt-in;
-5. long child output should use file handoff when possible.
+1. no helper is the default and missing runtime cost evidence means `skip`;
+2. dispatch requires two independent lanes and at least 30% projected total token saving;
+3. one task run has an absolute ceiling of one fresh read-only helper, zero retries, and zero helper workers;
+4. the parent owns planning, mutation, verification, and final review;
+5. UI/telemetry records dispatch/skip reasons and projected saving.
 
 ## Capabilities
 
 | Capability | Meaning | Platform decision |
 |---|---|---|
 | Natural language delegation | User can ask for scout/review/planning without exact syntax. | Covered by auto-delegation policy and workflow prompts. |
-| Builtin agents | General roles such as researcher, planner, reviewer, and context-builder. | Use when they fit the task and installed tools are available. |
-| Piagent agents | `piagent-scout`, `piagent-planner`, `piagent-worker`, `piagent-reviewer`, `piagent-oracle`. | Default roles for governed project work. |
-| Prompt shortcuts | `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`. | Documented for explicit orchestration. |
-| Supervisor channel | Child can ask parent for a decision. | Allowed for blocked or high-context child work. |
+| Builtin agents | General upstream roles. | Disabled by the Piagent baseline. |
+| Piagent agents | Read-only `piagent-scout`, `piagent-planner`, `piagent-reviewer`, `piagent-oracle`; compatibility `piagent-worker`. | At most one read-only role; worker disabled. |
+| Prompt shortcuts | Upstream `/parallel-*` and worker/reviewer loops. | Outside the governed default and cannot widen the one-helper ceiling. |
+| Supervisor channel | Child can ask parent for a decision. | Disabled; a blocked helper returns once and is not retried. |
 | Output controls | `output`, `outputMode=file-only`, `reads`, `outputSchema`, `acceptance`. | Recommended for large reports and handoff context. |
 | Worktree isolation | Separate checkout for parallel writer agents. | Non-default; use only with explicit scope and disjoint write sets. |
 | Watchdog | Additional opt-in review at session end. | Off by default to control token/cost. |
@@ -37,15 +37,16 @@ Core decisions:
 ## Applied in platform
 
 - `scripts/configure-subagents.sh`
-  - `waitTool.enabled: true`
-  - `intercomBridge.mode: always`
+  - `waitTool.enabled: false`
+  - `intercomBridge.mode: off`
   - stable `defaultSessionDir`, `singleRunOutputBaseDir`, `worktreeBaseDir`
   - `scheduledRuns.enabled: false`
-  - bounded `maxSubagentDepth`, spawn cap, and parallel concurrency
+  - `maxSubagentDepth: 1`, `maxSubagentSpawnsPerSession: 1`, global/parallel concurrency `1`
+  - builtin agents disabled and worker overrides disabled
 - `scripts/setup.sh` / `scripts/install-global.sh`
   - install `npm:pi-web-access@0.17.0` by default for web/docs research; `--no-web-access` opts out
 - Workflow prompts
-  - `/workflow task`, `/workflow plan`, `/workflow review`, `/workflow be-to-fe`, `/workflow platform-improve` instruct the parent to auto-delegate when work is independent and bounded
+  - parent works directly; one fresh read-only helper requires runtime-projected saving of at least 30%
 - Docs
   - command reference lists prompt shortcuts, watchdog/profile commands, supervisor control, output/fork/worktree options
 
@@ -56,7 +57,9 @@ Core decisions:
 | Watchdog always-on | Extra review can increase token/cost. |
 | `asyncByDefault: true` | Background work can surprise interactive users. |
 | Scheduled subagents | Useful for monitoring, unrelated to normal implementation. |
-| Parallel writers | Correct only with clean repo, worktree isolation, and non-overlapping files. |
+| Parallel writers | Disabled; parent is the only writer. |
+| Parallel read-only helpers | Extra model turns/context cost; absolute governed cap is one. |
+| Forked child context | Replays parent history and defeats the token-saving gate. |
 | Research agent without web tooling | It needs appropriate web/search/fetch tools installed. |
 
 ## Recommended usage
@@ -67,39 +70,4 @@ Daily implementation:
 /workflow task Implement <task>.
 ```
 
-Review until clean:
-
-```text
-/review-loop current diff max 3 rounds
-```
-
-Parallel review:
-
-```text
-/parallel-review current diff
-```
-
-Research-heavy task:
-
-```bash
-pi install npm:pi-web-access@0.17.0
-```
-
-```text
-/parallel-research Compare available implementation options for <topic>.
-```
-
-Context handoff before a large implementation:
-
-```text
-/parallel-context-build Build context for <large task>.
-/parallel-handoff-plan Build implementation handoff plan for <large task>.
-```
-
-Watchdog for a high-risk session:
-
-```text
-/subagents-watchdog recommend-model
-/subagents-watchdog session model recommended
-/subagents-watchdog on
-```
+The parent performs review, research, planning, implementation, and verification directly. A helper dispatch must expose its runtime estimate and fresh read-only contract; otherwise the telemetry outcome is `skip`.

package/docs/subagents-and-multiagent.md

@@ -19,7 +19,7 @@ Pi core không có subagents built-in. Theo design của Pi, subagents là exten
 
 Từ `v0.3.7`, `scripts/setup.sh` mặc định cài `pi-subagents` và chạy config preset `safe`.
 
-Workflow prompts của platform dùng **solo-first orchestration policy**: khi anh chạy `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, hoặc `/workflow review`, parent agent đọc `piagent_orchestration_policy`, lập task tree/review lenses, rồi mới cân nhắc subagent cho phần việc độc lập. Anh không bắt buộc phải gọi `/run` nếu chỉ muốn task hoàn chỉnh, và platform cũng không spawn swarm khi task nhỏ. Alias cũ như `/task` vẫn giữ cùng policy.
+Workflow prompts của platform dùng **parent-direct orchestration policy**: parent model tự đọc, suy luận và implement. Helper mặc định tắt. Chỉ khi operator bật `PIAGENT_HELPERS_MODE=on`, runtime mới được phép cân nhắc đúng một helper read-only có context fresh; việc dispatch còn phải chứng minh ít nhất hai lane độc lập và tối thiểu 30% projected net token saving sau cả chi phí handoff/merge. Worker, parallel, nested helper và retry đều bị tắt. Alias cũ như `/task` giữ cùng policy.
 
 Kiểm tra nhanh policy trong Pi:
 
@@ -27,22 +27,21 @@ Kiểm tra nhanh policy trong Pi:
 /piagent-orchestration
 ```
 
-Runtime policy dùng `RolePolicy v1` và `HelperRequest v1` để bind objective,
+Runtime policy dùng `RolePolicy v1` và `HelperRequest v2` để 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_HELPERS_MODE=recommend  # opt-in quan sát/recommend; không spawn
+PIAGENT_HELPERS_MODE=on         # opt-in; vẫn phải qua evidence gate 30%
 ```
 
-`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
+`piagent-worker` bị disable trong Piagent config và không được delegate.
+CAP-14 mặc định `off`; chỉ environment opt-in mới có thể bật. Lower-level
+helper budget là trần tuyệt đối: tối đa 1 read-only helper concurrent và tổng,
+0 writer, 0 retry, 8 calls, context handoff tối đa 2.048 token; 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à
@@ -50,7 +49,7 @@ không merge output. Khi thành công, parent chỉ nhận bounded redacted summ
 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.
+Guard extension vẫn load trong helper process. Piagent helper chỉ đọc nên không tạo verifier hay source-change authority; parent vẫn là owner duy nhất của implementation và exact verifier cuối.
 
 Xem chi tiết: `docs/auto-delegation-policy.md`.
 
@@ -96,15 +95,15 @@ Nội dung chính:
 
 - `toolDescriptionMode: compact` để giảm prompt/token;
 - `asyncByDefault: false` để không tự chạy background nếu không yêu cầu;
-- `waitTool.enabled: true` để parent có thể đợi async runs khi workflow cần kết quả;
-- `intercomBridge.mode: always` để child có thể hỏi parent qua `contact_supervisor`;
+- `waitTool.enabled: false` để không tạo continuation chờ helper;
+- `intercomBridge.mode: off` để child không mở thêm vòng hỏi/đáp;
 - `singleRunOutputBaseDir` và `defaultSessionDir` stable trong `~/.pi/agent`;
 - `worktreeBaseDir` stable cho parallel writer khi được explicit bật;
 - `scheduledRuns.enabled: false` để không lộ surface schedule nếu user không yêu cầu;
-- `parallel.concurrency: 3`;
-- `parallel.maxTasks: 6`;
+- `parallel.concurrency: 1` và `parallel.maxTasks: 1` (compatibility surface, không phải parallel dispatch);
 - `maxSubagentDepth: 1`;
-- `maxSubagentSpawnsPerSession: 32`;
+- `maxSubagentSpawnsPerSession: 1`;
+- builtin agents và `piagent-worker` bị disable; chỉ custom read-only role có thể được operator bật rõ;
 - async completion batching bật.
 
 Không ép `subagents.modelScope` mặc định. Anh chọn model parent bằng `/model`; builtin subagents sẽ inherit model nếu không override. Nếu muốn ép chỉ provider:
@@ -276,40 +275,15 @@ Platform package exposes these package-level agents:
 |---|---|---|
 | `piagent-scout` | bounded repo mapping | no |
 | `piagent-planner` | implementation plan + verify gates | no |
-| `piagent-worker` | single-writer implementation | yes |
+| `piagent-worker` | compatibility metadata; disabled by config | unavailable |
 | `piagent-reviewer` | review diff/policy/tests/scope | no |
 | `piagent-oracle` | second opinion/risk challenge | no |
 
-Default rule:
-
-- Use `piagent-scout` before touching unfamiliar code.
-- Use `piagent-planner` before medium/high-risk changes.
-- Use `piagent-worker` only for approved, bounded write tasks.
-- Use `piagent-reviewer` before final handoff.
-- Use `piagent-oracle` when architecture/product/risk is uncertain.
+Default rule: parent tự làm. Khi operator opt-in, runtime có thể chọn đúng một trong các read-only role phía trên sau khi qua evidence gate 30%; không role nào được retry hay spawn tiếp.
 
 ## Worktree isolation
 
-Parallel implementation writers can clobber each other in one checkout. Only use `worktree: true` when:
-
-- current repo is a Git repo;
-- working tree is clean;
-- write sets do not overlap;
-- parent will review/merge outputs.
-
-Example:
-
-```text
-subagent({
-  tasks: [
-    { agent: "piagent-worker", task: "Implement feature A" },
-    { agent: "piagent-worker", task: "Implement feature B" }
-  ],
-  worktree: true
-})
-```
-
-For normal solo/internal workflow, prefer one `piagent-worker` plus parallel read-only reviewers.
+Piagent không cấp writer helper và không bật worktree/parallel orchestration. Nếu operator cần các capability upstream này thì đó là một runtime khác ngoài policy/budget/claim của Piagent.
 
 ## Watchdog opt-in
 
@@ -356,10 +330,10 @@ Recommended token policy:
 
 - default `safe` preset;
 - do not set `asyncByDefault` unless anh intentionally wants background-heavy workflow;
-- keep `/piagent-orchestration` at `solo-first` unless team has a measured reason to change it;
-- one writer at a time;
-- parallel reviewers/scouts are OK;
-- use `piagent-scout`/`piagent-planner` to compress context before handing off to `piagent-worker`;
+- giữ parent-direct và `PIAGENT_HELPERS_MODE=off` mặc định;
+- parent là writer duy nhất;
+- không parallel, nested, forked-history hay retry helper;
+- chỉ opt-in một read-only helper khi projected net saving từ 30%;
 - run `/subagents-fleet` to inspect background runs instead of asking parent model to recall everything.
 
 ## Nguồn

package/docs/task-implementation-contract.md

@@ -24,7 +24,7 @@ Agent Watch/report hien ten task ma operator da dat.
 | Mode | `changeMode` | `source-change` hoac `read-only`. |
 | Retry | `attempt`, `maxAttempts`, `previousAttempts` | Tran lay tu attempt dau, khong duoc nang o retry sau. |
 | Intent | `summary`, `riskLane`, `expectedOutput`, `acceptanceCriteria` | Chot truoc khi implementation. |
-| Scope | `scope`, `outOfScope`, `protectedPaths` | Direct write bi chan ngoai scope; final gate doi chieu Git. |
+| Focus va bao ve | `scope`, `outOfScope`, `protectedPaths` | `scope` dinh huong retrieval/review; protected/read-only policy moi la bien ghi bat buoc. Final gate doi chieu Git va report moi file da doi. |
 | Context | `requiredContext`, `contextManifest`, `memoryCitations`, `mcpCapabilities` | Citation co path va reason. |
 | Verify | `verifyGroup`, `verifyCommands`, `verifyEvidence` | Moi command phai observed, exact-match va pass. |
 | Plan | `workPlan`, `reviewLenses`, `orchestration` | Toi da 12 step, dependency DAG, single writer. |
@@ -89,7 +89,7 @@ Vi vay:
 - file dirty truoc task nhung bi sua tiep se duoc tinh;
 - file da duoc sua roi revert ve baseline chi nam trong audit history, khong pass gate;
 - claim file khong co evidence bi tu choi;
-- thay doi ngoai `scope` bi tu choi;
+- thay doi ngoai `scope` van duoc phep khi can de hoan thanh yeu cau; runtime ghi nhan day la focus expansion de review;
 - delete/missing co digest rieng;
 - staged rename ghi ca old path va new path.
 
@@ -137,7 +137,7 @@ nguyen grant cua project va chi re-pin core khi release moi khong mo rong quyen.
 | Lop | Enforcement |
 |---|---|
 | Prompt/workflow | Huong dan dung tool theo thu tu. |
-| Tool-call guard | Protected path, scope, read-only, destructive/external confirmation. |
+| Tool-call guard | Protected/read-only path, opaque mutation target, destructive/external confirmation. Task `scope` khong chan ghi file. |
 | Tool-result observer | Changed-file va bash evidence tu su kien that. |
 | Persisted contract | Session binding, retry, plan, context, verify, trace. |
 | Completion hook | Chan completion claim khi gate chua pass. |

package/docs/task-lifecycle-vietnamese.md

@@ -73,13 +73,13 @@ 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
+nhat checkpoint; `edit`/`write`/`apply_patch` va `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:
+`write`/`edit`/`apply_patch` 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;
@@ -105,7 +105,7 @@ Gate completed yeu cau dong thoi:
 - moi verify command co observed result `exitCode=0` va exact match;
 - work plan khong con `pending`, `in-progress` hoac `failed`;
 - declared changed files khop final digest sau baseline; file da revert khong tinh;
-- khong co file ngoai `scope`;
+- moi file thay doi deu co evidence; file ngoai focus `scope` duoc report de review nhung khong block;
 - final trace la `completed`.
 
 `true`, `echo ok`, `npm test || true` hoac command gan giong khong thay the lenh

package/docs/team-onboarding.md

@@ -10,7 +10,7 @@ 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.84.1
-npm install -g --ignore-scripts @piagent/platform@1.5.5
+npm install -g --ignore-scripts @piagent/platform@1.6.1
 piagent-install --stable
 cd /path/to/project
 pi
@@ -44,7 +44,7 @@ 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.84.1
-npm install -g --ignore-scripts @piagent/platform@1.5.5
+npm install -g --ignore-scripts @piagent/platform@1.6.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

package/docs/usage-observability.md

@@ -57,6 +57,9 @@ piagent_context_preflight
 `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. Nếu
+evidence của bất kỳ lane có trọng số nào chưa đầy đủ, score chính là `null` và
+UI ghi `unavailable`; `contextWasteScoreEstimate` chỉ là chẩn đoán partial, không
+được diễn giải thành “không có waste”. 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
@@ -169,8 +172,10 @@ Alias ngắn `/setname ABC-123 Short task name` vẫn chạy. Nếu tắt nhầm
 
 Task Contract v2 lưu cả `sessionId`, `sessionName`, `taskId` và `taskRunId`, nên
 Agent Watch/report có thể map usage vào đúng attempt kể cả session đã resume hoặc
-được đổi tên sau khi bắt đầu. Một session không được tái sử dụng cho task khác;
-retry dùng session mới và giữ liên kết qua cùng `taskId`.
+được đổi tên sau khi bắt đầu. Người dùng có thể giao việc khác ngay trong cùng
+session; runtime kết thúc partition cũ và tạo `taskRunId` mới thay vì khóa session
+vào một workflow. Retry có thể dùng session mới và vẫn giữ liên kết qua cùng
+`taskId`.
 
 Mặc định history mode **bao gồm subagent session files** vì đó là usage thật của máy. Dùng `--no-subagents` khi chỉ muốn parent/main sessions.
 

package/docs/vi/architecture.md

@@ -44,6 +44,7 @@ Rule máy đọc nằm tại `architecture/layers.json`; chạy `npm run archite
 | Security foundation | `packages/piagent-core/security/` | Sensitive-data primitive | Workflow behavior |
 | Benchmark | `packages/piagent-core/benchmark/`, `benchmarks/` | Suite validation, scoring, evidence | Runtime enforcement |
 | WebUI contracts | `packages/piagent-webui/contracts/` | Wire type dùng chung giữa browser và server | Mọi hành vi runtime; layer này không phụ thuộc gì |
+| WebUI shared | `packages/piagent-webui/shared/` | Helper xác định, không có dependency, dùng chung cho browser, server và gateway | Browser state, transport, truy cập filesystem hoặc runtime policy |
 | WebUI client | `packages/piagent-webui/client/` | View trên browser, view model, UI preference | Server state, filesystem, Pi API |
 | WebUI server | `packages/piagent-webui/server/` | HTTP/WS endpoint, đọc session, dựng diff | Render phía browser; không được import client |
 | WebUI extension | `packages/piagent-webui/extension/` | Lệnh `/piagent-webui` chạy trong Pi | Wire type mà client cũng cần |
@@ -93,10 +94,23 @@ 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.
 
+Gateway bind mỗi lần browser gửi vào đúng một operation lifecycle dùng chung
+giữa stream và supervisor. Runtime chỉ cho tối đa một provider retry còn
+pristine trong khoảng delay 8 giây, và từ chối replay sau khi đã có assistant
+output nhìn thấy hoặc bất kỳ tool call nào. Compaction có phase riêng, terminal
+settlement chỉ phát một lần và event đến muộn không thể đưa UI trở lại
+`Working`. Bounded emission guard cục bộ bỏ activity/reviewer note lặp hoặc câu
+filler; final assistant message luôn đi ngoài guard này.
+
+Exact edit và local patch còn có thể bind vào full-file digest của lần read
+thành công gần nhất trong cùng task run. Concurrent drift đã được chứng minh sẽ
+block toàn bộ mutation trước hunk đầu tiên và yêu cầu một fresh read; file chưa
+có snapshot vẫn dùng exact-anchor behavior bình thường của host.
+
 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;
+Chỉ failure có evidence chứng minh thuộc ownership của source 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
+source-mutation authority. Environment, permission, protected-path policy 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,
@@ -110,7 +124,7 @@ Semantic specialist review là đường CAP-13 riêng cho `strict-high-risk`, k
 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.
+stale, không xác định được target, 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
@@ -123,9 +137,9 @@ 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ó
+đóng, target hint theo initial focus, 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
+ưu tiên context theo focus relevance 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
@@ -164,16 +178,16 @@ automatic dispatch của mọi capability bị chặn ở một đơn vị cho m
 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
+Helper do Piagent sở hữu dùng RolePolicy v1 và HelperRequest v2. Request bind
+hashed session/task identity, bounded objective, read-only 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
+không thể nhận mutation tool và worker dispatch bị tắt.
+`PIAGENT_HELPERS_MODE=off|recommend|on` mặc định là `off`; `on` là opt-in rõ ràng
+nhưng runtime vẫn phải chứng minh hai lane độc lập và projected net token saving
+từ 30%. CAP-14 cùng owner budget chặn tuyệt đối ở một helper read-only fresh tổng
+và concurrent, 0 writer, 0 retry, 8 calls và tối đa 2.048 context token chuyển giao.
+Failure/reservation hết hạn vẫn dùng hết slot duy nhất, và runtime 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,