@piagent/platform 1.6.0 → 1.7.1

package/docs/research/harness-next-evidence-review.md

@@ -0,0 +1,113 @@
+# Harness Next: evidence review
+
+Research date: 2026-08-30. Status: research and implementation in progress, not a release claim.
+
+## The problem being solved
+
+Piagent must distinguish an implementation defect, an incomplete test suite, a verifier limitation, and an execution failure. These require different recovery actions. A source recognizer that cannot understand a valid program must not tell the model to rewrite that program without a concrete failing behavior.
+
+The retained v6 campaign stopped after six sessions. Pi's expiry implementation received hidden grade 10/10, but its completion receipt remained pending and workflow score was 8.48. A separate, read-only diagnostic passed 480,061 assertions, including 120,000 year/month boundaries. These checks support a verifier-coverage false negative; they do not establish universal correctness or change the failed campaign result.
+
+The v6 admission check requires two single-parameter helpers. The actual implementation uses a shared three-parameter normalizer, mutable locals, UTC setter/round-trip calendar validation, numeric separators, and fraction padding. Directly invoking the dataflow layer beneath the admission check still rejects syntax. Adding one more source pattern is therefore not the architectural repair.
+
+## Primary sources and transferable mechanisms
+
+Numbers below are the authors' reported results under their own models, datasets, budgets, and dates. They are not comparable leaderboard rows and are not predicted Piagent gains.
+
+| Source | Evidence or mechanism | What Piagent can transfer; limitation |
+| --- | --- | --- |
+| [SWE-agent, NeurIPS 2024, v3](https://arxiv.org/abs/2405.15793v3) | A purpose-built agent-computer interface; reported pass@1 of 12.5% on SWE-bench and 87.7% on HumanEvalFix. | Treat tool feedback and interface design as measurable interventions. Do not assume its 2024 interface or scores transfer to another model. |
+| [Agentless, 2024, v2](https://arxiv.org/abs/2407.01489v2) | Localization, repair, and validation as separate phases; reported 32.00% (96 fixes) on SWE-bench Lite at $0.70 per problem. | Keep control flow inspectable and compare against a simpler baseline. More orchestration is not inherently better. Different benchmark from SWE-agent's full SWE-bench result. |
+| [EvalPlus, 2023, v3](https://arxiv.org/abs/2305.01210v3) | Mutation- and LLM-generated test inputs; HumanEval+ expands tests 80-fold. Across 26 models, the paper reports pass@k reductions up to 19.3–28.9% and changed rankings. | Strengthen independent tests and measure false acceptance, not merely acceptance rate. More cases are useful only with a trustworthy oracle and relevant partitions. |
+| [CEGAR, Clarke et al., 2000](https://web.stanford.edu/class/cs357/cegar.pdf) | Distinguish real counterexamples from artifacts of an abstraction; refine the abstraction for spurious traces. | Preserve `unknown` and route verifier limitations away from blind source repair. The paper's guarantees concern its finite-state model/specification setting, not arbitrary JavaScript or finite random tests. |
+| [fast-check model-based testing](https://fast-check.dev/docs/advanced/model-based-testing/) | Generate stateful command sequences, compare with a simpler model, shrink failures, replay with seed/path. | Exercise verification/recovery histories and save minimal counterexamples. The reference model must not copy the implementation's logic. |
+| [Anthropic agent eval guidance, 2026-01-09](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) | Separate transcript from final environment outcome, calibrate graders, validate tasks with reference solutions, distinguish pass@k from all-trial consistency. | Audit both false positives and false negatives; retain outcome and process metrics separately. This is engineering guidance, not a controlled estimate of Piagent improvement. |
+| [AgentLens, 2026, v3](https://arxiv.org/abs/2605.12925v3) | 2,614 trajectories, eight model backends, 60 SWE-bench Verified tasks; a 1,815-trajectory subset over 47 tasks. Among passing trajectories in that subset, 10.7% were classified as Lucky Passes. | Measure blind retries, regression cycles, and verification ordering in addition to final pass rate. This is a recent preprint; its labels are not proof that a specific Piagent run is bad. |
+| [Pi source README](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) | Minimal extensible harness; default read/write/edit/bash tools, extension-based workflow customization. | Keep reusable enforcement in the extension while letting the model choose implementation structure. Minimalism does not replace project authorization or verification. |
+| [mini-SWE-agent](https://mini-swe-agent.com/latest/) | Bash-only actions, linear message history, independent subprocess execution. | Use an observable lean baseline and avoid hidden recovery state. Do not transplant unrestricted shell access into Piagent's protected-path policy. |
+| [OpenHands architecture](https://docs.openhands.dev/sdk/arch/overview), [SDK paper v2](https://arxiv.org/abs/2511.03690v2) | Separate SDK, tools, workspaces, and server; immutable/stateless components and portable execution. | Separate assessment from execution and UI projection; keep backend failures distinct from model failures. No numerical reduction is inferred from the abstract's qualitative production claim. |
+| [LangGraph persistence](https://docs.langchain.com/oss/javascript/langgraph/persistence) | Checkpoints and pending writes preserve completed steps; replay after a checkpoint can re-execute external calls. | Store verification receipts and resume only valid bound work. Replay is not automatically free or side-effect-free; preserve the single paid-attempt ledger. |
+| [OpenAI evaluation guidance](https://developers.openai.com/api/docs/guides/evaluation-best-practices) | Task-specific evaluations, production failure datasets, automated scoring calibrated against human judgment. | Maintain a labelled grader audit set and separate quality, safety, and tool-selection checks. Do not add model judges as an uncalibrated completion authority. |
+
+[OpenAI's lean-prompt guidance](https://developers.openai.com/api/docs/guides/latest-model#favor-leaner-prompts) reports an internal sample with roughly 10–15% higher eval scores, 41–66% fewer total tokens, and 33–67% lower cost. The page does not establish an equivalent Piagent workload or a fresh-token saving. This is a hypothesis for a later isolated ablation, not a reason to change prompts during a frozen benchmark or advertise those numbers.
+
+## Alternatives considered
+
+1. **Extend the current source-template proof.** Low initial cost, but another valid helper graph or expression can fail before semantics. Rejected as the primary fix; retained only as a conservative optional analysis lane.
+2. **Ask the model to judge its own answer.** Flexible but vulnerable to shared blind spots and unsupported confidence. Not a completion authority for executable contracts.
+3. **Use project test exit code alone.** Language-independent but can accept incomplete or manipulated tests. Not sufficient by itself.
+4. **General formal verification of arbitrary generated JavaScript.** Strong results are possible for specified subsets, but a complete practical verifier for unrestricted programs is not a credible scoped deliverable. Keep explicit supported domains and `unknown`.
+5. **Independent contract execution plus orthogonal safety/provenance gates.** Selected direction. Freeze task-derived obligations, run host-owned validators against exact source snapshots, retain counterexamples, and state bounded assurance accurately. This changes the verification mechanism and requires its own calibration; it is not an automatic relaxation of the completion gate.
+
+## Execution isolation review
+
+[Node's documentation](https://nodejs.org/api/vm.html) explicitly rules out treating `node:vm` as a security boundary. The existing syntax-only compilation is different from executing candidate code; do not turn it into an in-process execution sandbox.
+
+[QuickJS-WASM runtime documentation](https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/classes/QuickJSRuntime.md) provides separate runtimes/modules, memory/stack controls, interrupts, and module-loader control. It is a candidate for pure-JavaScript probes, not yet a selected production dependency. An [upstream report against a pinned QuickJS commit](https://github.com/bellard/quickjs/issues/545) alleges interrupt-bypass CPU denial of service; the issue is closed, and applicability to any chosen WASM build has not been established. This is a reason to require an independent process deadline and resource tests, not a claim that all QuickJS releases are vulnerable.
+
+Initial local discovery found Docker CLI but no running Docker daemon. During subsequent implementation, the existing Docker Desktop was started and a separate locked worker dependency directory was installed without lifecycle scripts; the platform's shared dependencies were not changed. The selected experimental backend combines QuickJS-WASM with a constrained local Docker container, an independent OS watchdog, and host-owned comparison. See the [executor checkpoint](../decisions/harness-next-executor-checkpoint.md) for actual tests and limitations. An unavailable backend produces `error/unknown`, never an unprotected host-execution fallback.
+
+The selected [QuickJS core variant interface](https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten-core/README.md) allows using only core, release-sync WASM, and FFI types, all pinned to 0.32.0 in a dedicated lockfile. The installed variant identifies its underlying QuickJS revision as `f1139494d18a2053630c5ed3384a42bb70db3c53`. [Docker's container runtime controls](https://docs.docker.com/engine/containers/run/) provide the outer process, filesystem, network, and resource boundary. These controls are complementary; neither upstream documentation nor a finite adversarial suite is a blanket security guarantee.
+
+## Chosen research hypotheses
+
+Persistence follow-up: [SQLite's atomic-commit design](https://sqlite.org/atomiccommit.html) documents journal-based all-or-none transactions, including recovery after interruption, with explicit filesystem/locking/flush assumptions. [Node 22.19.0's SQLite API](https://nodejs.org/download/release/v22.19.0/docs/api/sqlite.html) is available but experimental in that minimum supported runtime, so using it for verifier storage requires a compatibility and packaging decision. Transactional durability alone does not authenticate a receipt, establish an approved oracle, or protect against compromise of a same-user host authority. The subsequent [durable evidence checkpoint](../decisions/harness-next-durable-evidence-checkpoint.md) records the implemented store; the [admission checkpoint](../decisions/harness-next-authenticated-admission-checkpoint.md) records its later runtime integration and remaining limits.
+
+Local source inspection also established that the existing working-tree digest covers changes relative to HEAD. The new execution bridge therefore separately binds source bytes and repository revision. This evidence changes the persistence requirement: a cache must not key solely on the old dirty-tree digest, nor treat a public hash as authentication.
+
+- H1: Separating verifier abstention from concrete behavioral failure prevents unnecessary source rewrites while preserving rejection of known-bad programs.
+- H2: Independent contract probes accept implementation-equivalent solutions that the v6 recognizer rejects, without accepting the retained mutation corpus.
+- H3: Durable, exact-snapshot receipts eliminate repeated completed provider-free work; replay never drops or repeats paid attempts silently.
+- H4: A leaner recovery interface reduces repair attempts and fresh tokens at equal outcome quality. Test separately after correctness, not bundled with the acceptance experiment.
+
+The accompanying architecture decision and evaluation protocol define how these hypotheses can be falsified. No paper or passing finite suite supports a claim of zero possible edge cases. The release must instead state tested input partitions, remaining unsupported contracts, repeated-run reliability, and unresolved risks.
+
+## Follow-up: stateful recovery and replay after admission integration
+
+Primary documentation was rechecked on 2026-08-30. The current [LangGraph checkpointer guide](https://docs.langchain.com/oss/javascript/langgraph/checkpointers) distinguishes full step checkpoints from completed per-node writes, and explicitly states that replay after a selected checkpoint re-executes later model/API calls. It also distinguishes exit-only, asynchronous, and synchronous durability. Piagent therefore cannot infer “exactly once” from the presence of a checkpoint: completed evidence reuse, pending-attempt reconciliation, and paid-attempt accounting need separate tests. The former durable-execution documentation URL now redirects to the persistence overview; the detailed checkpoint URL above is the relevant source for these claims.
+
+The [fault-tolerance guide](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance) separates retry policy, per-attempt timeout, and exhausted-error handling. This supports keeping worker failure distinct from a source counterexample. It does not justify importing that library's default retry behavior or raising Piagent's existing ceilings. Our next recovery work must retain the actual executor/unsupported reason instead of collapsing every unavailable admission into a generic missing-proof diagnostic.
+
+[fast-check's model-based guide](https://fast-check.dev/docs/advanced/model-based-testing/) compares command histories against a simplified model and warns against reproducing the implementation as the oracle. It provides shrinking plus seed/path/replay-path reproduction. The transferable test design is a small abstract authority/attempt model exercised by histories such as reserve → host death → reopen → reconcile → retry, not merely isolated method assertions. No fast-check dependency or general stateful adapter was installed by this checkpoint.
+
+Piagent-specific next evidence requirements (design decisions, not claims from the sources):
+
+- A completed observation survives restart without another independent attempt, after actual current project verification is refreshed.
+- A pending attempt never launches a duplicate solely because the host restarted or a timeout elapsed.
+- Late completion, cancellation, shutdown, policy revocation, contract drift, and source drift are tested in different orders; the latest valid authority state wins.
+- Counterexamples drive bounded source repair; executor errors and unsupported domains drive diagnosis/unknown, with no invented source defect.
+- Stateful application adapters need a simpler independent behavioral model and held-out command histories. Passing the evidence-store protocol tests alone does not satisfy the required stateful-recovery domain.
+
+These requirements extend the existing evaluation protocol; they do not replace the full frozen release campaign or import any external project's performance numbers as Piagent results.
+
+## Follow-up: project source graphs and differential diagnostics
+
+[Wang, Pradel and Liu's PatchDiff study, v2 (2025-09-09)](https://arxiv.org/abs/2503.15223v2) reports that 7.8% of examined patches counted as correct nevertheless failed developer-written tests. Differential testing exposed behavioral differences in 29.6% of plausible patches; a difference from the reference was not automatically a proven defect. The transfer to Piagent is to combine independently declared obligations, project tests and targeted divergent variants, not require textual similarity to a reference or import these rates as Piagent measurements.
+
+Source inspection showed that the experimental backend could not execute an unchanged multi-file implementation because all imports were refused. [QuickJS's runtime interface](https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/classes/QuickJSRuntime.md) exposes a module loader plus normalizer, and a pending-job query distinct from synchronous execution. The installed 0.32.0 declarations were inspected as well. The resulting design loads only pre-captured, explicitly approved relative modules; it neither discovers permissions from candidate imports nor supplies host IO. Async execution remains a separate unsupported backend capability.
+
+The [module integration checkpoint](../decisions/harness-next-module-checkpoint.md) records actual unchanged production-source execution, dependency-only mutations, authenticated completion/repair and a reproduced observation-time microtask gap. These are development integration diagnostics. They are not independently held-out calibration, exhaustive redactor correctness, a general JavaScript equivalence result or a release campaign.
+
+## Follow-up: selecting independently specified contracts
+
+[PROGRESS, v1 (2026-07-29)](https://arxiv.org/abs/2607.27359v1) reports 328/562 current-version bugs detected across 25 Java systems and satisfied preconditions for 70/150 difficult properties, versus 18 with standalone jqwik. Its abstract distinguishes regression assertions derived from current behavior from independent semantic properties. It combines generated properties with evolutionary search; it is a recent preprint, not a Piagent result. The transferable requirement is oracle independence and explicit property/parameter binding, not adopting model-generated properties as completion authority or predicting those detection rates here.
+
+[Beginner's Luck, POPL 2017, extended v3](https://arxiv.org/abs/1607.05443v3) connects declarative predicates with input generation and distribution controls, with formal results for its own language semantics. [fast-check's property documentation](https://fast-check.dev/docs/core-blocks/properties/) separates generators, preconditions and predicates; [its model-based guide](https://fast-check.dev/docs/advanced/model-based-testing/) warns against duplicating the implementation in the model. Neither source supplies a generic oracle for arbitrary natural-language tasks.
+
+Piagent's implemented transfer is a bounded data-template library, typed parameter substitution, exact task-criterion binding, full preview and separate host approval. This is deliberately not a claim to have implemented Luck's solver, PROGRESS's search, random generation or shrinking. Expected observations are authored independently of candidate source/output; a library match establishes identity, not semantic completeness. [The selection checkpoint](../decisions/harness-next-selection-checkpoint.md) records concrete integration tests and remaining held-out/release requirements.
+
+## Follow-up: temporal contract semantics before correctness labels
+
+Normative sources checked on 2026-08-30: [ECMAScript's Date Time String Format and adjacent Date operations](https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-date-time-string-format) include literal four-digit and signed expanded years, date-only forms and `24:00`; MakeFullYear separately maps numeric years 0–99 to 1900–1999. TimeClip constrains Date values and truncates fractional milliseconds. These facts do not imply that every application should accept every Date.parse form or TimeClip an explicit numeric comparison argument.
+
+[RFC 3339 sections 5.6–5.7](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) instead require seconds, permit variable fractional digits and lowercase separators, restrict the hour to 00–23, and include conditional leap-second rules. Thus “ISO timestamp” is not enough to silently select either standard's whole grammar as an application's acceptance oracle.
+
+Piagent's new `iso-expiry-millisecond-profile` is an explicit application contract, not a new standards-conformance claim. It covers the original diagnostic's minute/second/fraction forms, Gregorian validation, offsets, small years, inclusive comparison and default-clock behavior, while stating its additional format decisions for operator review. It uses static independent data and real candidate execution; no hidden benchmark grader is imported. Source-independent epoch checks, equivalent implementations, deliberate defects and read-only retained-source replay calibrate different failure modes. The retained campaign remains immutable and these checks remain development evidence.
+
+## Follow-up: lifecycle-correct evaluation before performance claims
+
+The [Pi SDK guide](https://pi.dev/docs/latest/sdk) describes session-specific extension binding and re-binding after session replacement. Inspection of the installed pinned 0.84.1 SDK and print-mode implementations established that `createAgentSession` alone does not emit extension startup; `bindExtensions` does. Piagent's real-host test omitted that call. Its newer session-lifetime completion fence correctly rejected the uninitialized session. The test now exercises startup and graceful shutdown, with a separate negative case retaining rejection when startup is omitted. The fence was not weakened.
+
+A second, independent test-host problem surfaced when the fixture was made to produce a real assertion failure. [Node 24.11.1's test runner](https://github.com/nodejs/node/blob/v24.11.1/lib/internal/test_runner/runner.js) supplies `NODE_TEST_CONTEXT` to test children and refuses recursive process-isolated runs when that variable is present. The Pi bash child inherited it, printed a warning, skipped the project tests and returned success. The fixture now uses the unchanged native Pi bash definition with a spawn hook removing only that outer-runner variable. Every invoked project verifier must report a positive test count and zero skipped tests; the deliberately wrong authorization implementation must produce an actual assertion error. Earlier real-host passes alone were therefore insufficient evidence that those nested tests ran.
+
+Two product defects were exposed by the corrected lifecycle: repeated announcements of the same session name unnecessarily rewrote a pending task, and recovery guidance omitted the repository-revision binding when identifying missing verification evidence. Name handling is now idempotent; receipt and guidance projections share the same revision-selection logic. Stale baseline evidence remains rejected. Missing-proof diagnostics expose task-derived targets without edit instructions or mutation permission; only a concrete observed failure can enter the existing bounded repair path. These changes support evaluation validity, not a token-efficiency or production-release claim.

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/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.6.0, 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

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

@@ -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

@@ -9,8 +9,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.84.1
-npm install -g --ignore-scripts @piagent/platform@1.6.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
+npm install -g --ignore-scripts @piagent/platform@1.7.1
 piagent-install --stable
 cd /path/to/project
 pi
@@ -26,7 +26,7 @@ pi
 ## Prerequisites
 
 - Node.js >=22.19.0.
-- Pi Coding Agent `0.84.1`.
+- Pi Coding Agent `0.86.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;
@@ -43,8 +43,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.84.1
-npm install -g --ignore-scripts @piagent/platform@1.6.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
+npm install -g --ignore-scripts @piagent/platform@1.7.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -106,7 +106,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.84.1
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
 npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
@@ -118,7 +118,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.84.1
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
 pi install npm:@your-scope/platform@x.y.z
 ```
 

package/docs/third-party-neutrality.md

@@ -24,3 +24,10 @@ The neutrality gate scans active WebUI governance and client source. Historical
 records and implementation-specific integration documentation may retain an
 actual third-party name when it is necessary to explain compatibility or a
 security decision.
+
+Reviewed research records may name the tools whose primary sources they cite;
+source titles must stay accurate. The explicit record list in
+`scripts/check-public-wording.mjs` permits source names only. It does not permit
+promotional comparisons, ranking claims, copied branding, or new authority.
+Unlisted documents and all runtime/operator surfaces retain the full wording
+check. A document cannot opt itself out with a comment or metadata flag.

package/docs/usage-observability.md

@@ -278,7 +278,7 @@ Xem `contextUsage.percent`:
 - `< 50%`: bình thường.
 - `50–70%`: bắt đầu tránh đọc file lớn không cần thiết.
 - `70–82%`: chạy `/context compact` trước task dài tiếp theo.
-- `> 82%`: dùng `/fresh task`, `/fresh scout`, hoặc `/fresh be-to-fe` cho work mới.
+- `> 82%`: dùng `/fresh <workflow>` cho work mới; `/fresh help` liệt kê mọi workflow canonical.
 - Sau compaction, `contextUsage.tokens` có thể là `null` cho đến khi có assistant response mới.
 
 Nếu user paste full mandatory-flow boilerplate, platform input guard sẽ collapse về workflow command ngắn. Nếu prompt quá dài thật, platform có thể lưu intake vào `.pi/task-inbox/` local gitignored rồi replay bằng fresh workflow command.

package/docs/vi/architecture.md

@@ -94,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,
@@ -111,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
@@ -124,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
@@ -165,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,

package/docs-site/architecture.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.6.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.7.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/architecture" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/architecture" hreflang="en" lang="en">EN</a>