@caupulican/pi-adaptative 0.85.0 → 0.85.4

package/docs/providers.md

@@ -201,6 +201,9 @@ export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o
 
 ### Amazon Bedrock
 
+Amazon Bedrock requires an explicit verified region scope. A region from `~/.aws/config` is not
+enough: Pi persists and sends `AWS_REGION` explicitly so discovery and runtime requests cannot drift.
+
 ```bash
 # Option 1: AWS Profile (recommended for IAM Identity Center / SSO)
 export AWS_PROFILE=your-profile
@@ -212,31 +215,48 @@ export AWS_SECRET_ACCESS_KEY=...
 # Option 3: Bearer Token
 export AWS_BEARER_TOKEN_BEDROCK=...
 
-# Optional region (defaults to us-east-1)
-export AWS_REGION=us-west-2
+# Required AWS scope. US inference profiles in Ohio use us-east-2.
+export AWS_REGION=us-east-2
 ```
 
 For an SSO profile, AWS CLI v2 is required and the modern `sso-session` profile format is recommended.
-Start Pi with `AWS_PROFILE` set, or run `/login amazon-bedrock` and enter the profile name for the
-current Pi process. Pi runs `aws sso login --profile <profile>` without a shell. The AWS SDK refreshes
-ordinary role credentials; if the underlying SSO session later expires, Pi performs one foreground
-login and replays the Bedrock request once, only before a response has started. Background and worker
-requests never open a browser and instead return an authentication-required error to the owning
-session.
+Run `/login amazon-bedrock`, select SSO, and enter the exact profile and region. For IAM keys, bearer
+tokens, ECS roles, or IRSA, select the ambient-credentials option and enter the exact region. Pi then:
+
+1. verifies the selected profile and region with STS;
+2. paginates region-scoped system inference profiles;
+3. selects the current US/EU/APAC/global Claude candidate for each available tier;
+4. runs a bounded one-token runtime probe for every candidate; and
+5. persists the exact profile, region, verified model IDs, verification mode, and timestamp in the
+   user settings file.
+
+Bearer tokens skip STS and control-plane discovery because that auth mode cannot reliably use them;
+Pi instead probes the bounded region-derived candidates directly. A credential alone exposes no
+Bedrock models. If `AWS_PROFILE` or `AWS_REGION` later differs from the saved scope, the saved model
+evidence is rejected until `/login amazon-bedrock` verifies the new scope. Direct Anthropic models are
+unaffected.
+
+Pi runs `aws sso login --profile <profile>` without a shell. The AWS SDK refreshes ordinary role
+credentials; if the underlying SSO session later expires, Pi performs one foreground login and
+replays the Bedrock request once, only before a response has started. Background and worker requests
+never open a browser and instead return an authentication-required error to the owning session.
 
 Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`).
 
 ```bash
-pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
+pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-5
 ```
 
 Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set `AWS_BEDROCK_FORCE_CACHE=1` to enable cache points:
 
 ```bash
 export AWS_BEDROCK_FORCE_CACHE=1
-pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123
+pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/abc123
 ```
 
+An explicitly configured application-inference-profile ARN remains selectable only when its ARN
+region matches the verified scope. It does not expand the discovered system-model allowlist.
+
 If you are connecting to a Bedrock API proxy, the following environment variables can be used:
 
 ```bash
@@ -250,6 +270,10 @@ export AWS_BEDROCK_SKIP_AUTH=1
 export AWS_BEDROCK_FORCE_HTTP1=1
 ```
 
+An explicit unauthenticated proxy (`AWS_BEDROCK_SKIP_AUTH=1` plus
+`AWS_ENDPOINT_URL_BEDROCK_RUNTIME`) is outside AWS account/region verification and retains its custom
+model surface.
+
 ### Cloudflare AI Gateway
 
 `CLOUDFLARE_API_KEY` can be set via `/login`. The account ID and gateway slug must be set as environment variables.

package/docs/settings.md

@@ -278,7 +278,7 @@ Worker writes use **review-after-apply** semantics: a grant-authorized direct `w
 
 Deterministic argument repair is built in and has no settings toggle; schema-valid calls still return unchanged without entering the repair layer. `PI_TOOL_REPAIR_DISABLED=1` remains only an emergency diagnostic kill switch.
 
-Text protocol precedence is: `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` kills it, then `toolRepair.textProtocol` force-enables or disables it globally, then per-model `textToolCallProtocol` applies, then a persisted `/toolprobe` text-protocol verdict applies to that exact model. Native provider tool calls still take precedence when the model emits them; the text protocol is the fallback lane for pure-text models. Failed calibration is stored per host/model and can be cleared with `/toolprotocol-reset <provider/model>`.
+Text protocol precedence is: `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` kills it; a persisted `/toolprobe` native verdict then keeps that exact model on native calls; otherwise `toolRepair.textProtocol` force-enables or disables globally, per-model `textToolCallProtocol` applies, and finally a persisted calibrated text-protocol verdict applies. The phone/text protocol is therefore a fallback lane for models without proven native calls, never a replacement for a proven native path. Failed calibration is stored per host/model and can be cleared with `/toolprotocol-reset <provider/model>`.
 
 Environment kill switches override their diagnostic layers: `PI_TOOL_REPAIR_DISABLED=1`, `PI_TOOL_REPAIR_TEACH_DISABLED=1`, and `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1`. See [Tool repair](tool-repair.md) for diagnostics, reset controls, and replay.
 

package/docs/tool-boundary-performance-roadmap-2026-08-02.md

@@ -7,8 +7,9 @@ not exercised.
 
 ## Required invariants
 
-1. Validate cheap authority, path, identity, availability, and collision facts before asking the model for a
-   large payload.
+1. Validate cheap authority, path, identity, availability, and collision facts at the earliest harness-owned
+   execution boundary, before payload processing or mutation. Never make the model coordinate preparation, and
+   recheck mutable facts inside the serialized mutation boundary immediately before the write.
 2. Keep coordinators, payload handles, mutable queues, and retry state session-owned unless cross-session
    coordination is the explicit invariant.
 3. Store large bytes once, outside the JavaScript heap where practical. Context and telemetry retain bounded
@@ -23,10 +24,10 @@ not exercised.
 
 | Boundary | Root cause | Fix | Evidence gate |
 | --- | --- | --- | --- |
-| Write collision | `write` accepted the full content before discovering an occupied destination and could overwrite it. | Two-phase `prepare`/`commit`, path-only collision and parent checks, single-use session intent, and final `wx` no-clobber create. | `test/file-mutation-preflight.test.ts`; `test/file-encoding-policy.test.ts` |
-| Missing/stale edit | `edit` accepted replacement payloads before existence checks and could apply a plan prepared against older bytes. | Path-only preparation records file identity; commit consumes the intent and rejects a missing or changed target. | `test/file-mutation-preflight.test.ts`; `test/file-mutation-queue.test.ts` |
+| Write collision | `write` accepted the full content before discovering an occupied destination and could overwrite it. | One semantic model call; the harness preflights collision and parent access, rechecks inside the path queue, and finishes with atomic no-clobber creation. When the generated payload is valid and only the name collides, its exact bytes move to a bounded session cache so repair supplies only a corrected path and opaque reference. | `test/file-mutation-preflight.test.ts`; `test/file-encoding-policy.test.ts`; `test/phone-filesystem-workflow.test.ts` |
+| Missing/stale edit | `edit` accepted replacement payloads before existence checks and could apply a plan prepared against older bytes. | One semantic model call; the harness snapshots path identity, rechecks after queue admission and immediately before writing, and rejects missing or changed targets. Valid edits paired with only a missing/non-file path receive the same bounded retarget treatment and are fully revalidated against each corrected candidate. | `test/file-mutation-preflight.test.ts`; `test/file-mutation-queue.test.ts`; `test/phone-filesystem-workflow.test.ts` |
 | Repeated exact content | Copying identical generated content to another destination required retransmitting it. | Successful writes/edits return a session-local `contentRef`; the bounded controller hashes the source and performs exclusive verified copies without retaining bytes on the JS heap. | `test/file-mutation-preflight.test.ts` |
-| Encoding corruption | An unsafe text edit could be remembered as a retryable operation and teach repair/re-read loops. | The central execution-error catalogue classifies `PI_FILE_ENCODING_CORRUPTION` as change-approach, consumes the edit intent, retains no operation arguments, exposes one bounded directive, and expires it after the next assistant response. | `packages/ai/test/tool-execution-error-catalogue.test.ts`; `packages/agent/test/tool-failure-memory.test.ts` |
+| Encoding corruption | An unsafe text edit could be remembered as a retryable operation and teach repair/re-read loops. | The central execution-error catalogue classifies `PI_FILE_ENCODING_CORRUPTION` as change-approach, retains no operation arguments, exposes one bounded directive, and expires it after the next assistant response. | `packages/ai/test/tool-execution-error-catalogue.test.ts`; `packages/agent/test/tool-failure-memory.test.ts` |
 | Edit preview flattening | Preview rendering used `JSON.stringify({ path, edits })` during render and result settlement, copying the complete edit payload. | Constant-size request generations fence asynchronous previews; partial renders do not scan accumulated edits. | `test/edit-tool-no-full-redraw.test.ts` |
 | Write preview flattening | Collapsed streamed previews compared the complete prior content prefix, split and highlighted complete snapshots, and retained duplicate full line arrays. | Collapsed rendering inspects at most 8,192 characters, caches by argument-generation identity, and performs one allocation-free final line count; complete text is materialized only on explicit expansion. | `test/tool-execution-component.test.ts` |
 | Loop/failure payload retention | Stall and failure signatures serialized complete tool arguments and stored the normalized string in the loop window. | A streaming structural fingerprint returns 32 hex characters; failure display keeps a bounded structural preview and never serializes the original payload. | `packages/agent/test/tool-failure-memory.test.ts` |
@@ -74,11 +75,12 @@ the interpreter. An invalid working directory can therefore waste the entire gen
 
 Required design:
 
-- Add a path-only/runtime-only prepare action for inline-code mode and a path/runtime prepare action for script
-  mode.
-- Commit consumes a single-use session intent. Runtime failure or coordinator reset invalidates the intent; the
-  code is not stored as retry memory.
-- Do not add a legacy one-phase fallback.
+- Keep one semantic model call. The harness owns cwd/runtime preflight at the start of execution and performs no
+  code evaluation or process creation until it passes.
+- Runtime failure or coordinator reset invalidates any internal lease; code is not stored as retry memory and
+  no preparation token is exposed to the model.
+- If a provider exposes a complete path before the remaining arguments, speculative streaming preflight may
+  warm the same authority check, but final execution remains authoritative and provider-neutral.
 
 Acceptance evidence: invalid cwd/runtime tests prove that no `code` field was accepted; stale and cross-session
 intents fail; successful warm preparation meets the same p95 budget as P0.1.
@@ -102,8 +104,8 @@ path traversal, and cleanup-failure probes; parent session remains responsive an
 
 ### P0.4 Close edit's external-writer race
 
-Evidence: edit commit verifies identity before `readFile()` and later overwrites by path. A non-Pi writer can
-replace the file after the identity check but before the final write.
+Evidence: edit now verifies identity before `readFile()` and again immediately before `writeFile()`. A non-Pi
+writer can still replace the file in the final check/write gap because the adapter overwrites by path.
 
 Required design: bind read/compare/commit to a file handle or an adapter-owned compare-and-replace primitive;
 fail closed when identity changes. Define Windows replace/share semantics explicitly and preserve BOM/newlines.
@@ -139,9 +141,9 @@ same-timestamp replacement, Windows sharing violations, abort, and cleanup failu
 - **Ropes/piece tables for provider payloads:** rejected at the network boundary. Providers still require a
   contiguous JSON/body representation; chunked message ownership, pruning before formatting, and one terminal
   serialization are the useful controls.
-- **Two-phase preflight for `read`, `grep`, `find`, `ls`, and artifact retrieval:** rejected unless new evidence
-  shows large arguments. Their requests are small, outputs are bounded or artifact-backed, and an extra model
-  round trip would cost more than the local validation.
+- **Model-visible two-call preflight for `read`, `grep`, `find`, `ls`, and artifact retrieval:** rejected unless
+  new evidence shows large arguments. Their requests are small, outputs are bounded or artifact-backed, and an
+  extra model round trip would cost more than harness-owned validation.
 - **Replacing native JSON globally:** rejected without per-boundary benchmarks. Several provider transports
   require JSON text; changing parsers cannot remove serialization and may add copies. Optimize duplicate
   serialization and retained ownership first.
@@ -150,11 +152,12 @@ same-timestamp replacement, Windows sharing violations, abort, and cleanup failu
 
 ## Incomplete probes
 
-- Windows timing distributions for local and SSH-backed prepare/commit.
+- Windows timing distributions for local and SSH-backed automatic preflight/final mutation.
+- Live SSH round-trip coverage for remote retained-payload staging, expiry, retarget, and cleanup; the adapter is compile-checked but this cycle used no SSH fixture.
 - Heap/GC profiles for multi-megabyte skill drafts and extension smoke tests.
 - External-writer race reproduction on NTFS with antivirus/indexer sharing behavior.
-- Provider-specific cost of the extra prepare turn versus rejected-payload tokens across native and text tool
-  protocols.
+- Provider-specific rejected-payload cost when a one-call mutation fails preflight after response completion,
+  plus the portability and cancellation semantics of speculative streaming preflight.
 - Persistent Python protocol throughput and reset cost; no implementation exists yet, so prior process-spawn
   timings are not acceptance evidence.
 

package/docs/tool-repair.md

@@ -11,7 +11,7 @@ Execution failures are not argument repairs. Pi removes their potentially large
 - Repair is built-in and has no settings toggle. `PI_TOOL_REPAIR_DISABLED=1` is only an emergency diagnostic kill switch; normal configuration should leave repair on.
 - Teaching can be disabled independently with `toolRepair.teach: false` or `PI_TOOL_REPAIR_TEACH_DISABLED=1`. Repairs can still execute; the in-band "Tool argument repair note" is suppressed.
 - Tool-recovery logging can be disabled with `toolRepair.logging: false`. Repairs still run, but Pi does not enqueue recovery records or spawn the background recovery-log worker.
-- Text tool-call protocol calibration can be enabled per model with `textToolCallProtocol: true` in `models.json`. `/toolprobe [provider/model]` can also persist a host-local text-protocol verdict for one model after a live probe. Use `toolRepair.textProtocol` only as a global emergency force/kill switch; `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` always disables it.
+- Text tool-call protocol calibration can be enabled per model with `textToolCallProtocol: true` in `models.json`. `/toolprobe [provider/model]` probes native calls first and can persist a host-local text-protocol verdict only when native calls are absent. A persisted native verdict always keeps that model off the text protocol, including when global or model settings enable it. Use `toolRepair.textProtocol` only as a global emergency force/kill switch for models without native proof; `PI_TEXT_TOOL_CALL_PROTOCOL_DISABLED=1` always disables it.
 
 Example project settings:
 
@@ -29,7 +29,7 @@ Example project settings:
 
 - Interactive tool panels show `[repaired arguments]` when execution used repaired arguments.
 - RPC `tool_execution_start`, `tool_execution_update`, and `tool_execution_end` events include a `repair` object when arguments were repaired.
-- `/toolhealth` prints model adaptation records for this host: tool-probe verdicts, calibrated or failed text protocol, learned standing rules, teach statistics, and recovery-log worker counters.
+- `/toolhealth` prints model adaptation records for this host: tool-probe verdicts, calibrated or failed text protocol, learned standing rules, teach statistics, recovery-log worker counters, and execution-failure counts by phase.
 - `/toolrule-remove <provider/model> <mode>` removes one learned standing rule from the host-local adaptation store.
 - `/toolprotocol-reset <provider/model>` removes a stored text protocol calibration or failed-calibration record so the next turn can calibrate again.
 - `/toolprobe [provider/model]` probes the current fleet or one explicit model for native tool calls first, then text-protocol fallback, persists the verdict in the host-local adaptation store, and prints a report table.
@@ -45,7 +45,7 @@ node scripts/tool-repair-replay.mjs ~/.pi/agent/state/failure-corpus.jsonl --jso
 node scripts/tool-repair-replay.mjs ~/.pi/agent/sessions/<session>.jsonl --fixtures /tmp/tool-repair-fixtures.json
 ```
 
-The replay helper reads `tool_validation` corpus records and legacy bounced `tool_argument_validation` session entries. Current recovery telemetry is written by a dedicated `node:worker_threads` worker to `state/tool-recovery-events.jsonl`; bounced records also append sanitized `tool_validation` corpus rows. Records contain shape metadata, failure modes, and error keywords; they do not store full tool arguments.
+The replay helper reads `tool_validation` corpus records and legacy bounced `tool_argument_validation` session entries. Current recovery telemetry is written by a dedicated `node:worker_threads` worker to `state/tool-recovery-events.jsonl`; bounced calls append sanitized `tool_validation` corpus rows, while rejected or failed executions append bounded `tool_execution` rows with phase, failure code, optional redacted diagnostic, and next action. Records do not store full tool arguments.
 
 ## Repair modes
 

package/docs/windows.md

@@ -13,7 +13,7 @@ Pi supports native Windows on x64 and ARM64. The Node.js package runs under Wind
 The model always sees one stable `bash` tool contract. On Windows, a deterministic router classifies every command into one of three tiers instead of parsing the full Bash grammar in one place:
 
 1. **PowerShell floor** (always available): one simple command — a bounded set of builtin translations or a quoted external argv — converted deterministically to PowerShell, exactly as before this tier existed.
-2. **Bundled Python engine** (uv-provisioned Python 3.13, on by default): pipelines, redirection, chaining, quoting, expansion, globs, and the coreutils vocabulary below, plus every state-mutating command (`cd`, `export`, `unset`), which the engine always owns so there is a single mutator.
+2. **Bundled Python engine** (uv-provisioned Python 3.13, on by default): pipelines, redirection, chaining, word-list and arithmetic `for` loops, loop control, quoting, expansion, globs, and the coreutils vocabulary below, plus every state-mutating command (`cd`, `export`, `unset`), which the engine always owns so there is a single mutator.
 
 External programs are not reimplemented. A simple `rg` call runs the installed native `rg.exe` through the persistent PowerShell floor; when a pipeline or chain requires the Python coordinator, it spawns that same `rg.exe` directly without resolving or starting PowerShell. A `.ps1` target in an engine-owned command is adapted through the same selected PowerShell executable as the floor, without starting a nested model-authored shell.
 3. **Named fail-closed refusal**: constructs outside the supported grammar (see below) return an actionable error naming the construct instead of guessing or downgrading silently.
@@ -36,7 +36,9 @@ The PowerShell tier runs with `-NoLogo -NoProfile -NonInteractive -Command` and
 | Sequencing | `a ; b`, newline-separated, `a && b`, `a \|\| b`, `! pipeline` | Left-to-right / short-circuit / negation, bash-standard. |
 | Subshell | `( … )` | Isolated cwd/env copy — inner `cd`/`export` do not leak out. |
 | Brace group | `{ …; }` | Shares state — inner `cd`/`export` persist. |
-| Redirection | `>`, `>>`, `1>`, `1>>`, `<`, `2>`, `2>>`, `2>&1`, `&>`, `>&` | `/dev/null` maps to `os.devnull`. A builtin's stderr is merged into its own stdout (one sink) — an explicit `2>file` on a builtin does not capture its error text; external commands capture normally. |
+| For loop | `for name in words; do …; done`, `for name; do …; done`, `for ((init; condition; update)); do …; done` | Word lists expand once before iteration; the final value remains in the session environment. The omitted-list form iterates shell positional arguments, which Pi does not supply. Arithmetic clauses support integer variables, updates, assignments, comparisons, logical/bitwise operators, and signed 64-bit wrapping. |
+| Loop control | `break [N]`, `continue [N]` | Works across nested word-list and arithmetic loops. An omitted count means one; invalid counts report status 1 without crashing the coordinator. |
+| Redirection | `>`, `>>`, `1>`, `1>>`, `<`, `2>`, `2>>`, `2>&1`, `&>`, `>&` | `/dev/null` maps to `os.devnull`. Unredirected stderr shares Pi's session output; explicit stderr redirection is honored for builtins, state commands, and external programs. |
 | Quoting | `'…'`, `"…"`, `\x`, `$'…'` | Standard single/double/backslash/ANSI-C semantics. |
 | Tilde | `~`, `~/x` | Word-start, unquoted, expands to `$HOME`. `~user` is unsupported (refusal). |
 | Parameter expansion | `$VAR`, `$?`, `${VAR}`, `${V:-w}`, `${V:=w}`, `${V:+w}`, `${V:?w}`, `${#VAR}` | `$?` is the latest foreground pipeline status. POSIX `:`-prefixed (empty-or-unset) semantics only; other `${…}` operators refuse. |
@@ -53,13 +55,13 @@ Builtins: `cd`, `pwd`, `echo [-n -e -E]`, `printf`, `export`, `unset`, `exit [N]
 - `wc`/`uniq -c` column widths reproduce GNU's dynamic field width only for the single-count stdin case; multi-count/file-arg forms use fixed deterministic padding.
 - No shell-variable vs. exported-environment distinction: every `NAME=value` sets engine env.
 - Sorting is always ordinal (`LC_ALL=C`): globs, `ls`, `find`, and default `sort`.
-- A builtin's stderr is merged into its own stdout; only external commands honor an explicit `2>`.
+- Arithmetic loop variables use deterministic signed 64-bit wrapping; invalid shifts, division by zero, negative exponents, and malformed expressions return status 1 with a bounded diagnostic.
 - Globs expand only the final path segment (`dir/*.py` works; `*/x.py` matches the directory part literally).
 - `wc -m` counts UTF-8 characters (bash under `LC_ALL=C` counts bytes).
 
 ### Named unsupported constructs
 
-Each of these fails closed with a named, actionable error instead of an approximation: `job-control` (trailing `&`, `fg`/`bg`/`jobs`/`wait`/`disown`), `process-substitution` (`<(…)`/`>(…)`), `arithmetic-expansion` (`$((…))`, `((…))`, `let`), `brace-expansion` (`{a,b,c}`), `nested-shell` (`bash`/`sh`/`cmd`/`powershell`/`pwsh`/`wsl`/… as a command word), `exec-builtin`, `heredoc`/`here-string` (`<<`, `<<-`, `<<<`), `function-definition`, `control-flow` (`if`/`for`/`while`/`until`/`case`/`select`), `extended-glob` (`@(…)`, `!(…)`, etc.), `unsupported-builtin` (`eval`, `source`/`.`, `alias`, `trap`, `set`, `shopt`, `read`, `declare`, `local`), `unsupported-flag`, `posix-script` (`*.sh`, `/bin/…`), `cwd-missing`, `tilde-user`, `malformed-syntax` (unbalanced quote/paren/brace, empty pipeline element, missing redirect target), `parameter-expansion` (a `${…}` form outside the supported op set).
+Each of these fails closed with a named, actionable error instead of an approximation: `job-control` (trailing `&`, `fg`/`bg`/`jobs`/`wait`/`disown`), `process-substitution` (`<(…)`/`>(…)`), `arithmetic-expansion` (`$((…))`, standalone `((…))`, and `let`; arithmetic `for` headers are supported), `brace-expansion` (`{a,b,c}`), `nested-shell` (`bash`/`sh`/`cmd`/`powershell`/`pwsh`/`wsl`/… as a command word), `exec-builtin`, `heredoc`/`here-string` (`<<`, `<<-`, `<<<`), `function-definition`, `control-flow` (`if`/`while`/`until`/`case`/`select`), `extended-glob` (`@(…)`, `!(…)`, etc.), `unsupported-builtin` (`eval`, `source`/`.`, `alias`, `trap`, `set`, `shopt`, `read`, `declare`, `local`), `unsupported-flag`, `posix-script` (`*.sh`, `/bin/…`), `cwd-missing`, `tilde-user`, `malformed-syntax` (unbalanced quote/paren/brace, empty pipeline element, missing redirect target, malformed `for` loop), `parameter-expansion` (a `${…}` form outside the supported op set).
 
 ### State and session semantics
 
@@ -73,7 +75,7 @@ The Python interpreter and engine imports stay warm in one coordinator process p
 
 `windowsShell.pythonEngine` (default `true`) is the kill switch. Set it to `false` to restore the PowerShell-only contract verbatim: only the simple-command floor is used, and every pipeline/redirection/expansion/chaining form that would have routed to the engine instead returns the same fail-closed error it did before the engine existed.
 
-When the setting is left on but the bundled Python runtime cannot be resolved (uv missing, network failure provisioning Python 3.13, or similar), the engine tier is simply unavailable: simple commands still run on the PowerShell floor exactly as always, and any command that needs the engine returns a named error stating the Python runtime is unavailable, that the simple-command floor still works, and to fix `uv`/network to restore pipelines, redirection, expansion, and chaining. There is no silent approximation — a complex command is never downgraded to a plausible-but-wrong simple execution.
+When the setting is left on but the bundled Python runtime cannot be resolved (uv missing, network failure provisioning Python 3.13, or similar), the engine tier is simply unavailable: simple commands still run on the PowerShell floor exactly as always, and any command that needs the engine returns a named error stating the Python runtime is unavailable, that the simple-command floor still works, and to fix `uv`/network to restore loops, pipelines, redirection, expansion, and chaining. There is no silent approximation — a complex command is never downgraded to a plausible-but-wrong simple execution.
 
 The native `python` tool uses the same contract on Windows and Unix-like systems. Pi provisions a pinned uv executable, resolves or installs Python 3.13 through uv, then spawns the interpreter directly with UTF-8 and bytecode-cache suppression. Python calls default to 30 seconds. See [Native Python](python.md).
 

package/examples/extensions/built-in-tool-renderer.ts

@@ -237,7 +237,7 @@ export default function (pi: ExtensionAPI) {
 		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("write "));
 			text += theme.fg("accent", args.path);
-			const writeContent = args.action === "commit" && "content" in args ? args.content : undefined;
+			const writeContent = "content" in args ? args.content : undefined;
 			if (writeContent) text += theme.fg("dim", ` (${writeContent.length} characters)`);
 			return new Text(text, 0, 0);
 		},

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.85.0",
+  "version": "0.85.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.85.0",
+      "version": "0.85.4",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.85.0",
+  "version": "0.85.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.85.0",
+  "version": "0.85.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/minimal-mode.ts

@@ -180,7 +180,7 @@ export default function (pi: ExtensionAPI) {
 		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
 			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
-			const writeContent = args.action === "commit" && "content" in args ? args.content : undefined;
+			const writeContent = "content" in args ? args.content : undefined;
 			const sizeInfo = writeContent ? theme.fg("muted", ` (${writeContent.length} characters)`) : "";
 
 			return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${sizeInfo}`, 0, 0);

package/examples/extensions/prompt-customizer.ts

@@ -37,13 +37,13 @@ function addToolGuidance(options: BuildSystemPromptOptions, basePrompt: string):
 
 	if (hasTool("edit")) {
 		parts.push(
-			"• Use `edit` action=prepare before generating precise replacements, then commit with the returned intent. Match exact content including whitespace.",
+			"• Use `edit` once with the target path and precise replacements. The harness owns preflight and rejects stale targets. Match exact content including whitespace.",
 		);
 	}
 
 	if (hasTool("write")) {
 		parts.push(
-			"• Use `write` action=prepare before generating content; commit creates a new file and never overwrites.",
+			"• Use `write` once with the target path and content. The harness owns preflight, and creation never overwrites an existing file.",
 		);
 	}
 

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "0.85.0",
+	"version": "0.85.4",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "0.85.0",
+			"version": "0.85.4",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "0.85.0",
+	"version": "0.85.4",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/ssh.ts

@@ -148,7 +148,24 @@ function createRemoteIntentOps(remote: string, remoteCwd: string, localCwd: stri
 			if (!digest || !/^[0-9a-f]{64}$/i.test(digest)) throw new Error(`Invalid remote sha256 for ${p}`);
 			return digest.toLowerCase();
 		},
+		readPayload: (p) =>
+			sshExec(remote, `cat -- ${shellQuote(toRemote(p))}`).then((output) => output.toString("utf8")),
 		removeFile: (p) => sshExec(remote, `rm -- ${shellQuote(toRemote(p))}`).then(() => {}),
+		async stagePayload(content) {
+			const stagedPath = (await sshExec(remote, `umask 077; mktemp "\${TMPDIR:-/tmp}/pi-file-mutation.XXXXXXXXXX"`))
+				.toString("utf8")
+				.trim();
+			if (!stagedPath.startsWith("/") || stagedPath.includes("\n")) {
+				throw new Error("Remote mktemp returned an invalid mutation payload path.");
+			}
+			try {
+				await sshExec(remote, `cat > ${shellQuote(stagedPath)}`, content);
+				return stagedPath;
+			} catch (error) {
+				await sshExec(remote, `rm -f -- ${shellQuote(stagedPath)}`).catch(() => {});
+				throw error;
+			}
+		},
 	};
 }
 

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.85.0",
+  "version": "0.85.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.85.0",
+      "version": "0.85.4",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "0.85.0",
+  "version": "0.85.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",