@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/docs/usage.md

@@ -30,13 +30,21 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
 | File reference | Type `@` to fuzzy-search project files |
 | Path completion | Press Tab to complete paths |
 | Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
-| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Images | Paste with Ctrl+V on Unix/macOS, Alt+V on Windows, or either on WSL; the same action pastes text when no image is present |
 | Platform shell command | `!command` runs in PowerShell on Windows or Bash elsewhere and sends output to the model |
 | Hidden platform shell command | `!!command` runs without sending output to the model |
 | External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |
 
 See [Keybindings](keybindings.md) for all shortcuts and customization.
 
+Pasted images are stored under `~/.pi/agent/state/attachments` by default and attached to the current prompt as numbered markers. Later prompts can say `look at image #2` or `look at the image` for the latest current-session attachment. Set `images.clipboardDirectory` to use another folder; a relative folder is an explicit workspace-relative choice. Storage is bounded and Pi never writes an attachment folder into the workspace by default.
+
+### Questions, Steps, and Workers
+
+When an owner choice materially changes the result, the built-in `ask_question` interaction presents up to four questions together. It supports single choice, multi-select, an unrestricted multi-line custom **Other** answer, clipboard text or image paste, explicit **Skip**, configurable keyboard navigation, cancellation, and a final review before a multi-question answer is submitted. The request is checkpointed before display; `/resume` restores the original tool call, and large answers remain exact in a retrievable artifact while only a bounded projection enters prompt context. TUI and RPC hosts use the same fail-closed typed request. Image paste is refused with a visible explanation when the routed model cannot accept images instead of silently replacing it with a placeholder. Non-interactive sessions fail closed instead of inventing an answer, and worker sessions do not construct the question tool.
+
+Native task steps and worker lanes share the same compact work panel. Steps and agents are grouped separately; durable worker task labels and owner-authored profile ids remain visible after `/resume`. Completed worker output remains untrusted until the parent verifies it through the existing result and review contracts.
+
 ## Slash Commands
 
 Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
@@ -64,6 +72,8 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/toolhealth` | Show tool repair diagnostics and learned standing rules |
 | `/toolprobe [provider/model]` | Probe native/text tool-call support and persist a host-local verdict |
 | `/toolrule-remove <model> <mode>` | Remove one learned tool repair standing rule |
+| `/goal [status\|resume\|complete\|close\|reopen <requirement-id>\|override <text>]` | Inspect or control the durable session goal |
+| `/goal-continue [maxTurns] [maxStallTurns] [maxMinutes]` | Continue the active goal within explicit bounds |
 | `/task`, `/steps` | Manage the native session checklist; see [Task steps](task-steps.md) |
 | `/quit` | Quit pi |
 
@@ -96,6 +106,8 @@ pi --fork <path|id>    # Fork a session into a new session file
 Useful session commands:
 
 - `/session` shows the current session file and ID.
+- `/resume` also resumes a blocked durable goal before that session's worker/process supervision starts;
+  `/goal resume` applies the same persisted transition in place.
 - `/tree` navigates the in-file session tree and can summarize abandoned branches.
 - `/fork` creates a new session from an earlier user message.
 - `/clone` duplicates the current active branch into a new session file.
@@ -202,7 +214,7 @@ cat README.md | pi -p "Summarize this text"
 | `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
 | `--no-tools`, `-nt` | Disable all tools |
 
-Built-in tools include `read`, `edit`, `write`, `grep`, `find`, `ls`, and the uv-managed `python` tool. The agent always sees one stable `bash` tool contract. On Windows, Pi parses its supported simple-command grammar and converts it deterministically to PowerShell; unsupported shell constructs fail closed. Agent, interactive, and RPC shell calls have a 120-second wall-clock default, and Python calls default to 30 seconds. Native goal, task-step, delegation, context, and toolkit tools are activated when their capability/profile gates allow them.
+Built-in tools include `read`, `edit`, `write`, `grep`, `find`, `ls`, `ask_question`, and the uv-managed `python` tool. The agent always sees one stable `bash` tool contract. On Windows, Pi parses its supported simple-command grammar and converts it deterministically to PowerShell; unsupported shell constructs fail closed. Agent, interactive, and RPC shell calls have a 120-second wall-clock default, and Python calls default to 30 seconds. Native goal, task-step, human-question, delegation, context, and toolkit tools are activated when their capability/profile gates allow them.
 
 ### Resource Options
 

package/docs/windows.md

@@ -10,13 +10,62 @@ Pi supports native Windows on x64 and ARM64. The Node.js package runs under Wind
 - Git for Windows for native Git commands
 - Windows Terminal, WezTerm, or the VS Code terminal for the best keyboard support
 
-The model always sees one stable `bash` tool contract. On Windows, Pi parses one simple command, converts supported Bash-like builtins and external argv deterministically to PowerShell, and fails closed for unsupported syntax. The agent never selects a shell or emits native PowerShell. Pi resolves the Windows backend in this order:
+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.
+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.
+
+The agent never selects a shell or emits native PowerShell or Python. Pi resolves the PowerShell executable in this order:
 
 1. `shellPath` in `%USERPROFILE%\.pi\agent\settings.json`
 2. PowerShell 7 (`pwsh.exe`) on `PATH` or under `Program Files`
 3. Windows PowerShell (`powershell.exe`) under `System32` or on `PATH`
 
-The backend runs with `-NoLogo -NoProfile -NonInteractive -Command` and a best-effort UTF-8 console-output prefix. Supported contract forms include quoted external commands and bounded forms of `pwd`, `echo`, `which`, `ls`, `cat`, `head`, `tail`, `grep`, `find`, `rm`, `cp`, `mv`, `mkdir`, and `touch`. Pipelines, redirection, variable or command expansion, shell chaining, nested shells, POSIX scripts, unclosed quotes, and unsupported builtin options return an actionable error instead of reaching PowerShell unchanged. Every agent, interactive, and RPC shell call has a 120-second wall-clock default, even while output continues.
+The PowerShell tier runs with `-NoLogo -NoProfile -NonInteractive -Command` and a best-effort UTF-8 console-output prefix. Every agent, interactive, and RPC shell call has a 120-second wall-clock default, even while output continues.
+
+### Supported forms
+
+| Grammar | Forms | Notes |
+| --- | --- | --- |
+| Pipeline | `a \| b \| c` | Real OS pipes, binary-safe; exit code is the last element's (after `!`). |
+| 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. |
+| 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}` | POSIX `:`-prefixed (empty-or-unset) semantics only; other `${…}` operators refuse. |
+| Command substitution | `$(…)`, `` `…` `` | Runs through the same executor; trailing newlines stripped; nesting bounded to depth 8. |
+| Glob | `*`, `?`, `[…]` | Case-sensitive, `/`-normalized, ordinal (`LC_ALL=C`) sort; final path segment only; no match falls back to the literal word. |
+| Assignment | `NAME=value` (standalone or prefixed to a command) | Standalone sets engine env for the session; prefixed applies only to that command. No shell-var/exported-env split — every assignment sets env. |
+
+Builtins: `cd`, `pwd`, `echo [-n -e -E]`, `printf`, `export`, `unset`, `true`, `false`, `which`, `test`/`[`, `ls [-a -A -1 -r]`, `cat`, `head [-n N]`, `tail [-n N]`, `grep [-i -v -n -c -l -w -F -E]`, `find [-type f|d] [-name GLOB]`, `rm [-f -r -rf]`, `cp [-r|-R]`, `mv`, `mkdir [-p]`, `touch`, `wc [-l -w -c -m]`, `sort [-r -n -u -f]`, `uniq [-c -d -u -i]`, `cut -d/-f` or `-c`, `tr [-d -s -c]`, `basename`, `dirname`, `sed 's/RE/REPL/[g][i]'` (substitute only), `xargs [-0 -n -I]`. An unknown flag on a listed builtin, or any builtin/form not listed, returns a named `unsupported-flag`/`unsupported-builtin` refusal rather than a guess.
+
+### Divergences from bash (intentional, documented)
+
+- `grep`/`sed` regex is Python `re`, not POSIX BRE/ERE.
+- `ls`/`find` output always uses a trailing `/` on directories, `/`-normalized paths, and ordinal sort — matching the PowerShell floor so output is identical regardless of which tier ran.
+- `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>`.
+- 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).
+
+### State and session semantics
+
+`cd`, `export`, and `unset` always route to the Python engine, the sole mutator of session state (working directory and environment). That state is held once per agent session and read by both tiers: the next call — whether it routes to the PowerShell floor or back to the engine — sees the updated cwd/env. A subshell `( … )` runs against an isolated copy and never leaks its `cd`/`export` back out; a brace group `{ …; }` shares and persists state like the top level.
+
+### The `windowsShell.pythonEngine` setting and degradation
+
+`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.
 
 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).
 
@@ -47,7 +96,7 @@ A Windows release is expected to preserve the same Pi features as Linux and macO
 | --- | --- | --- |
 | CLI, print, JSON, and RPC modes | Native | Full package build and test suite on `windows-latest` |
 | Interactive TUI and configurable keybindings | Native | TUI tests on Windows; packaged `win32-console-mode.node`; Windows Terminal mappings below |
-| `read`, `write`, `edit`, `grep`, `find`, and stable `bash` contract tools | Native; Bash-like commands are routed deterministically to PowerShell | Router/platform-shell tests plus native Windows CI; release `pi.exe` executes the platform shell through RPC |
+| `read`, `write`, `edit`, `grep`, `find`, and stable `bash` contract tools | Native; Bash-like commands are routed deterministically across a PowerShell floor and a bundled Python shell engine (pipelines, redirection, chaining, expansion, coreutils), with named refusals outside that grammar | Router/platform-shell tests, engine conformance suite, Linux differential bash-oracle suite, and Windows cross-tier integration tests, plus native Windows CI; release `pi.exe` executes the platform shell through RPC |
 | Provider APIs, OAuth, API-key auth, model routing, and retries | Native | AI, agent, and coding-agent tests on Windows; live credentials are not used in CI |
 | Extensions, skills, prompts, themes, and pi packages | Native | Discovery, loading, reload, package-manager, and isolation tests on Windows |
 | Sessions, branching, compaction, context storage, export, and sharing | Native | Agent and coding-agent session tests on Windows |

package/docs/work-directory.md

@@ -22,7 +22,7 @@ The default per-tenant retention policy is 30 days, 64 inactive runs, 512 MiB, 1
 
 ## Repository API
 
-Extensions and internal code can use the public helpers:
+Harness internals and programmatic SDK integrations can use the low-level public helpers:
 
 ```ts
 import { acquireWorkRun, getProcessWorkRun, pruneWorkTenant } from "@caupulican/pi-adaptative";
@@ -34,8 +34,48 @@ import { acquireWorkRun, getProcessWorkRun, pruneWorkTenant } from "@caupulican/
 
 Use a named run only for transient coordination that must be shared across Pi processes. Use a generated run for commands, reports, downloads, tests, benchmarks, probes, and output spills.
 
+Packaged extensions should use `pi.getStorage("extension-name").acquireWorkRun()` instead. It binds work to one extension namespace, releases leases automatically on failure/unload, and clamps extension-selected retention to the harness ceiling. Calling `getStorage()` alone creates no directories. Durable extension state and rebuildable extension cache similarly live under `state/extensions/<namespace>/` and `cache/extensions/<namespace>/`; see [extensions.md](extensions.md#pigetstoragenamespace).
+
 ## Not transient
 
-Configuration and durable user data stay outside `work/`: `settings.json`, `auth.json`, `models.json`, `sessions/`, `state/`, `skills/`, `extensions/`, `prompts/`, `themes/`, profiles, backups, and managed binaries.
+Configuration and durable user data stay outside `work/`: `settings.json`, `auth.json`, `models.json`, `sessions/`, `state/`, `skills/`, `extensions/`, `prompts/`, `themes/`, profiles, backups, and managed binaries. Directory overlays are contained under `profiles/directories/`; explicit configuration snapshots are contained under `state/backups/config/`.
 
 Do not put Automata memory or its graph in Pi's work directory. Automata remains an external memory system.
+
+## Agent directory layout
+
+`work/` is one wedge of the full canonical layout under `~/.pi/agent/` (`getAgentDir()`). Everything
+machine-managed resolves through one typed path module, `src/core/agent-paths.ts` — every writer of
+machine data (stores, caches, managed runtimes/models, cross-process coordination) goes through it
+instead of hand-rolling `join(agentDir, …)`, so a new writer can't silently reintroduce a root-level
+straggler:
+
+```text
+~/.pi/agent/
+  auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user config/memory (root)
+  okf-memory/                                                                          authored memory (root)
+  skills/ extensions/ prompts/ themes/ profiles/                                       user resources (root)
+    profiles/directories/<workspace-hash>/settings.json                                directory overlays
+  state/     durable machine state: model adaptation/fitness, tool-performance,        -- stateDir/stateFile
+             learning observations, trust decisions, failure corpus, config backups, …
+    state/backups/config/                                                              explicit config snapshots
+    state/extensions/<namespace>/                                                      extension durable state
+  cache/     rebuildable, safe to delete: tool-path probes, jiti transform cache, uv    -- cacheDir/cacheFile
+    cache/extensions/<namespace>/                                                      extension rebuildable cache
+  bin/       managed executable helpers (fd, rg)                                       -- binDir (legacy getBinDir accessor)
+  work/      transient/scratch (this document)                                         -- re-exported from agent-paths.ts
+    work/extensions/<namespace>/<run-id>/                                              extension leased work
+  runtimes/<kind>  models/<kind>  sessions/  npm/  git/  worktrees/                    -- runtimesDir/modelsDir/sessionsDir/npmDir/gitDir/worktreesDir
+```
+
+`state/` holds durable history — deleting it loses real data, not just cache. `cache/` is always safe
+to delete; the next run re-probes or recomputes it. A startup migration (`migrateAgentDirLayout`,
+`src/migrations.ts`, run before any store/trust read) relocates confirmed root-level stragglers into
+their canonical locations: `trust.json` into `state/`, `backups/` into `state/backups/config/`, and
+`resource-profiles/` into `profiles/directories/`. Obsolete root `auto-learn/` and `tmp/` trees are
+preserved under `state/legacy-layout/`, where they cannot compete with live config/resources. Whole
+roots move atomically when possible; literal Windows `auth.json:Zone.Identifier` sidecars move there
+too. Partial migrations scan a bounded number of top-level entries and preserve collisions under
+`state/migration-conflicts/` instead of overwriting either copy.
+
+`pi doctor` performs a bounded, read-only scan of the agent directory root. It stays silent for the canonical config, memory, resource, and storage entries above and warns about external or legacy root writers. The audit never relocates or deletes unknown data.

package/docs/worktree-sync.md

@@ -0,0 +1,250 @@
+# worktree-sync
+
+`worktree_sync` is a core (built-in, not extension) tool: a hard-gated, worktree-per-lane
+parallel-work workflow for a solo developer who does not use PRs. Every writing agent works in
+its own local git worktree on its own lane branch; integration is always rebase-onto-main +
+fast-forward — linear history, no merge commits, no PRs, no push. `origin` is never touched;
+push stays a manual owner act.
+
+## Workflow overview
+
+1. A lane worktree is created off main (`create_lane`) with its own branch (`pi/wt/<laneKey>`).
+2. The agent bound to the lane works and commits inside that worktree only.
+3. Before landing, the lane must be fresh relative to main: `sync` rebases current main onto the
+   lane branch. A clean rebase leaves the lane fresh; conflicts leave the rebase in progress and
+   return a structured worklist.
+4. `land` is the only door to main: serialized under one integration lock, freshness-checked,
+   gate-command-verified, fast-forward-only.
+5. A successful land bumps a shared integration epoch and marks every other active lane stale —
+   structurally, not by convention — so the next lane to touch files or land is directed to sync
+   first.
+6. `release_lane` removes a fully-landed, clean lane worktree and branch.
+
+Correctness never depends on a notification arriving; it depends on `land`'s own freshness check
+(G3 below), re-derived from git at land time while holding the lock. Notifications only make
+lanes aware *promptly*.
+
+## Enabling
+
+Enabled by default; `"worktreeSync": { "enabled": false }` is the explicit off-switch — zero
+behavior change once set. Settings live under `worktreeSync` in `settings.json`:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Master switch. Explicit `false` is the hard off-switch: the tool is hidden and no gating runs. |
+| `mainBranch` | unset (auto) | Overrides default-branch resolution (`main`, then `master`; never guessed further). |
+| `syncPolicy` | `"on_land_mandatory"` | Staleness-propagation policy — see below. |
+| `gateCommand` | unset | Land gate command (G4), e.g. `"npm run check"`, run in the lane worktree at the exact tip that becomes main. |
+| `gate` | `"on"` | `"off"` is the owner-level G4 opt-out, recorded per land event. Agents cannot flip this at runtime. |
+| `gateTimeoutMs` | `900000` | Gate command timeout. |
+| `maxLanes` | `5` | Active-lane ceiling; `create_lane` refuses beyond it. |
+| `worktreesRoot` | agent-paths default | Overrides the lane-checkout root. |
+| `workerLand` | `"deny"` | `"allow"` lets a WORKER session (see "Identity, UAC, and zero footprint" below) run `land` on its own bound lane; still subject to normal freshness/ownership gating. |
+
+`syncPolicy` values:
+
+- **`on_land_mandatory`** (default) — every successful land marks every *other* active lane
+  `sync_required`; under this policy a stale lane's file mutations are refused until it syncs.
+- **`overlap_mandatory`** — `sync_required` fires only when the land's changed paths overlap the
+  lane's own changed paths; otherwise staleness stays advisory until land time.
+- **`land_time_only`** — staleness is always advisory; only the land gate (G3) enforces.
+
+## The hard gates (G1–G11)
+
+Enforced in core code paths, never by prompt compliance. Every refusal carries a tagged code and
+appends an audit event.
+
+| # | Gate |
+|---|---|
+| G1 | `land` is serialized under one integration lock — two concurrent lands are impossible. |
+| G2 | `land` requires the lane worktree clean (no uncommitted/untracked-modified state). Refusal: `lane_dirty`. |
+| G3 | `land` requires the lane fresh (current main is an ancestor of the lane tip), re-derived from git while holding the lock. Refusal: `stale_lane` + a structural sync directive. This is the backstop that cannot be evaded even if every notification failed. |
+| G4 | `land` requires the configured gate command to pass at the exact tip that will become main, unless the owner set `gate: "off"` (recorded per land event). |
+| G5 | Main only ever moves by a fast-forward merge of the lane branch in the hub checkout — no merge commits, no force, no rewrite of main. |
+| G6 | `land` refuses `hub_dirty` only when hub-local modifications intersect the land's changed-file set (overlap-based, not pristine-hub-based). |
+| G7 | A successful land bumps the epoch and broadcasts staleness in the same critical section as the merge, before the lock releases. |
+| G8 | A stale lane under the mandatory policy is refused by the file-mutation tools (edit/write/mutating bash) of a lane-bound `pi` session until it syncs. Hard for `pi` children; cooperative for foreign CLIs. |
+| G9 | Sync completion requires the rebase finished, zero conflict markers (byte-scanned), and freshness passing. Refusals: `conflict_markers_present`, `rebase_in_progress`. |
+| G10 | No lane touches main directly — a lane-bound `pi` session's `git commit/merge/rebase/reset/switch` targeting main is refused (`main_mutation_refused`). Main is written by the land gate alone. |
+| G11 | A lane with unlanded commits or dirty state is never auto-deleted; `release_lane` on such a lane requires `confirm: "yes-discard-lane"`. |
+
+## The `worktree_sync` tool
+
+One tool, eight actions — the entire agent-facing surface, so a model never improvises git
+ceremony. Every outcome carries a tagged code (`details.code`) and refusal text always names the
+exact recovery step.
+
+| Action | Effect |
+|---|---|
+| `status` | The deterministic full picture: epoch, hub state, lock, per-lane freshness/staleness/dirty/rebase state, and a one-sentence assembled `advice`. Read-only. |
+| `create_lane` | Worktree add + branch + registration off main. Params: `laneKey?` (else auto-allocated), `goalId?`, `requirementId?`. |
+| `sync` | Rebases current main into the lane branch. Clean → lane fresh. Conflicts → rebase left in progress plus a structured worklist. |
+| `continue` | After conflicts are resolved: verifies zero conflict markers, stages, and drives the rebase to completion (looping per conflicted commit). |
+| `abort_sync` | Aborts the in-progress rebase; the lane returns to its pre-sync tip, still honestly reported as stale. |
+| `land` | The full G1–G7 pipeline. On success returns the new epoch and main sha. |
+| `release_lane` | Unregisters the lane and removes the worktree/branch — only when fully landed and clean, else the G11 confirm. |
+| `reconcile` | Re-syncs the lane registry with git reality (orphaned worktrees, stale locks, cleared owners). Runs automatically at startup; also directly callable. |
+
+## Lane lifecycle
+
+`create` → work/commit on the lane branch → `sync` (rebase current main in) → resolve conflicts
+locally and `continue` → `land` → (optionally) `release`. Landing does not happen automatically
+when a worker finishes its task — it is a distinct, deliberate step the orchestrator (or the
+worker, when instructed) triggers, since the gate run at land time is itself the evidence the
+goal record relies on.
+
+## Session binding: `PI_WORKTREE_LANE` / `--worktree-lane`
+
+A session becomes lane-bound via the `PI_WORKTREE_LANE=<laneKey>` environment variable, or the
+`--worktree-lane <laneKey>` CLI flag (sugar over the same env contract — tmux panes launched by a
+lane-first goal dispatch inherit it automatically). A lane-bound session:
+
+- gets the G8/G10 lane gate wrapped under its file-mutation tools (edit/write/bash);
+- defaults `worktree_sync`'s `laneKey` param to its own bound lane for `sync`/`continue`/
+  `abort_sync`/`land`, so the model rarely needs to pass it explicitly;
+- runs a lane-sync watcher (an `fs.watch` on the shared epoch file, checked at every turn start)
+  that injects a source-labelled system notice when the epoch changes, so the session learns
+  about staleness promptly instead of only at its next `status` call.
+
+A goal-bound tmux dispatch (`goal` tool's `dispatch_worker` with `dispatchTarget: "tmux"`, when
+`worktreeSync.enabled`) creates the lane first, then launches its `pi` worker with `--worktree-lane
+<laneKey>` and one extra system-prompt clause naming the lane doctrine (work only inside this
+lane's worktree; integrate exclusively via `worktree_sync land`; never touch main directly). A
+lane-creation refusal (e.g. `maxLanes` reached) aborts the dispatch cleanly before any tmux
+session is ever launched (`dispatchSkipReason: "worktree_create_failed"`).
+
+## Capability adaptation
+
+The lane-worker surface adapts to the model actually driving it, riding the existing model-capability
+system (`core/model-capability.ts`) rather than a parallel mechanism. A model is eligible to drive a
+worktree-sync lane worker only if it is BOTH capability class `full` AND has a working native
+tool-call path:
+
+- **Class `full`** with a DECLARED context window: the classifier reads the model's own REGISTRY
+  metadata (`Model.contextWindow` -- the source of truth), never the live serving context a local
+  runtime happens to be configured with; an unknown/undeclared window is treated as ineligible for
+  lane-worker duty even though it defaults to class `full` for the general tool surface.
+- **Advertised native tool calling**: `Model.textToolCallProtocol` unset or `false`. A model with
+  `textToolCallProtocol: true` is phone-only by declaration and never eligible.
+- **Not graded-demoted**: a persisted `/toolprobe` verdict of `"text-protocol"` or `"none"` makes the
+  model ineligible. An UNPROBED model (no verdict on record yet) is eligible on its advertised
+  support alone -- unprobed is never treated as demoted.
+
+Additionally, the lean capability class (16k-32k context window) sheds the orchestration surface
+entirely: `goal`, `worktree_sync`, `improvement_loop`, `extensionify`, `skillify`, `model_fitness`,
+`context_scout`, and `tmux_agent_manager` are blocked for a lean-class session regardless of lane
+binding (`MODEL_CAPABILITY_LEAN_BLOCKED_TOOLS`) -- `run_toolkit_script` and `task_steps` stay
+available by design.
+
+Two refusal points, one authority:
+
+- A goal→tmux dispatch (`tools/tmux-dispatch.ts`'s `dispatchTmuxWorker`) checks the DISPATCHING
+  session's own eligibility FIRST, before `createLaneWorktree` or any `fire_task` call --
+  `dispatchSkipReason: "worker_capability_insufficient"`, zero lane/pane side effect on refusal. This
+  is the parent's best-effort expectation only; it can race a model swap between dispatch and child
+  startup.
+- The DISPATCHED child session refuses AUTHORITATIVELY at its own startup (main.ts), regardless of
+  how it became lane-bound (`--worktree-lane`, `PI_WORKTREE_LANE`, or a launcher-set env): an
+  ineligible model prints a deterministic, greppable refusal line (`formatLaneWorkerRefusal`, prefix
+  `worktree-sync lane-worker refusal:`) and exits with a non-zero status before the lane gate or the
+  epoch watcher ever start. There is no silent unbinding -- a session that cannot drive the surface
+  never gets a reduced version of it, it never starts.
+
+Enforcement is orthogonal to prompt complexity: the lane gate (G8/G10) and the epoch watcher stay
+wired for every OTHER session exactly as before this system existed. An ineligible session simply
+never reaches them, because it never reaches session startup's live phase at all.
+
+## Identity, UAC, and zero footprint
+
+A session's **role** (`main` or `worker`) is derived structurally, never asserted by the session
+itself (`core/session-role.ts`): a session is a **worker** iff it is bound to a worktree-sync lane
+(`PI_WORKTREE_LANE`) OR launched with `PI_SESSION_ROLE=worker`. `PI_SESSION_ROLE=main` is
+deliberately **not** an escalation -- it can never override a bound lane, so there is no
+environment value a lane-bound process can set to shed the worker ceiling below.
+
+### Forbidden-tool ceiling
+
+A worker session can never activate: `goal`, `delegate`, `delegate_status`, `improvement_loop`,
+`extensionify`, `skillify`, `run_toolkit_script`, `model_fitness`, `tmux_agent_manager`,
+`context_scout`, `python`. This is enforced as the FIRST line of the tool registry's allow
+predicate (`RuntimeBuilder.refreshToolRegistry`'s `isAllowedTool`) -- it wins over an allow-list,
+an exclude-list, or an active resource profile that names the tool explicitly. `goal`/`delegate`/
+`delegate_status`/`tmux_agent_manager` are sub-orchestration (a worker dispatching its own workers
+defeats single-owner lane accountability); `improvement_loop`/`extensionify`/`skillify` are
+self-adaptation surface a worker should never mutate; `run_toolkit_script`/`model_fitness` spend
+budget a worker's dispatcher does not control. **`python`** is included because it is a bounded but
+still largely unrestricted execution contract -- excluding it is load-bearing for the zero-footprint
+guarantee below (an unbounded interpreter can write state anywhere it can reach on disk).
+**`context_scout`** is excluded because it is itself sub-orchestration: it spawns its own isolated
+agent loop.
+
+`bash` is deliberately **not** forbidden. It stays available as the same documented cooperative
+boundary the lane gate already applies to foreign (non-`pi`) CLIs it cannot structurally contain --
+a worker's bash access is bounded by the lane gate's G8/G10 rules and the path envelope below, not
+by removing the tool.
+
+### `worktree_sync` tool scoping for a worker
+
+A worker session's `worktree_sync` calls are narrowed at the tool layer (independent of the engine
+-- see the next section):
+
+- `status`, `sync`, `continue`, `abort_sync` stay available unconditionally.
+- `create_lane`, `release_lane`, `reconcile` are always refused (`role_forbidden`).
+- `land` is refused by default (`role_forbidden`); the new `worktreeSync.workerLand` setting
+  (`"deny"` default, `"allow"` opt-in) lets a worker land its own lane when set -- still subject to
+  the normal freshness/ownership gates below.
+- An explicit `laneKey` that differs from the session's own bound lane is always refused
+  (`role_forbidden`): a worker may only ever target its own lane.
+
+### Land/release ownership
+
+`land` and `release_lane` refuse `lane_owner_conflict` when the target lane is owned (its
+registration's `ownerSessionId`) by a **different, still-alive** session -- same-host pid liveness,
+the same pattern the integration lock and `reconcile` already use. A lane with no recorded owner,
+owned by the calling session itself, or whose recorded owner is dead never conflicts. This check is
+deliberately engine-level and applies to `land`/`release_lane` ONLY -- `sync`/`continue`/
+`abort_sync` are never owner-gated at the engine; a worker's cross-lane containment for those comes
+from the tool-layer `laneKey` check above. `release_lane`'s existing G11 discard-confirm requirement
+is unaffected: it still applies once ownership no longer conflicts.
+
+### Edit/write path envelope
+
+For a lane-bound session, `edit`/`write` targets are checked against the lane's own worktree root
+(`WorktreeLaneGate.checkMutation`'s `targetPath` parameter, resolved by `RuntimeBuilder`'s tool
+wrapper via the same `resolveToCwd` the tools themselves use). The check is symlink-safe: the
+lane's worktree root and the target are both resolved through `realpath` (walking up to the target's
+nearest EXISTING ancestor when the target itself does not exist yet, so a not-yet-created file
+cannot be smuggled through a symlink that escapes the lane). A target outside the resolved lane root
+is refused (`path_outside_lane`). No active lane record leaves the existing fail-open behavior
+unchanged. `bash` is untouched by this check -- its containment stays the G10 cooperative boundary
+described above.
+
+### Zero state/settings footprint
+
+A worker session leaves no footprint in `~/.pi/agent/state` or `settings.json`: every scattered
+on-disk store (`ToolPerformanceStore`, `ObservationStore`, `ModelAdaptationStore`, `FitnessStore`,
+`ProjectTrustStore`) takes a `readOnly` constructor option defaulting to `isWorkerSession()`, gated
+ABOVE any locking/directory-creation the store's write path performs -- never at the innermost
+`writeFileSync` alone, since the lock itself already creates a lockfile and parent directory before
+any write. A read-only store still returns the value a real write would have produced (e.g.
+`ObservationStore.increment` returns `base + 1`, `ModelAdaptationStore`'s internal `store()` returns
+the computed entry) so callers see normal in-memory behavior; nothing durable ever lands on disk.
+`SettingsManager`'s single write choke (`enqueueWrite`, used by every settings scope: global,
+project, and directory-profile) is gated the same way -- a worker session never writes
+`settings.json` in any scope; in-memory settings reads are unaffected since callers update the
+in-memory state before reaching the write queue. The one INTENTIONAL artifact a worker session still
+produces is its own session transcript -- that is the point of running it, not a footprint to avoid.
+
+## Trust boundary (honest, not faked)
+
+- **`pi` children are hard-gated**: G8/G10 run in core code, wrapped under the file-mutation
+  tools of any lane-bound `pi` session — a stale mutation or a direct write to main is refused
+  structurally, not by prompt compliance.
+- **Foreign CLIs (agy/claude/codex/opencode/custom) are cooperative only**: their internal tool
+  loop is that CLI's own responsibility; the harness cannot enforce G8/G10 inside a process it
+  does not control. Sync directives can still be pushed to a live foreign pane via the tmux
+  extension's existing `send_followup`, but compliance is not guaranteed.
+- **The land gate (G1–G7) is the backstop that cannot be evaded by either kind of worker**: no
+  matter how a lane got dirty, stale, or ignored a notification, `land` re-derives freshness and
+  cleanliness from git itself while holding the integration lock. A stale or dirty lane cannot
+  land, full stop.

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

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.81.38",
+  "version": "0.81.40",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.81.38",
+      "version": "0.81.40",
       "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.81.38",
+  "version": "0.81.40",
   "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.81.38",
+  "version": "0.81.40",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",