@caupulican/pi-adaptative 0.81.38 → 0.81.39

package/docs/tmux-agent-manager.md

@@ -37,12 +37,95 @@ Run `/tmux-agents` or call `tmux_agent_manager` with `action: "status"` to check
 2. writes one atomic terminal result when it sees the worker's `DONE` or `BLOCKED` marker, the pane closes, or its one-shot deadline expires;
 3. updates tmux status metadata and emits a display notification.
 
-The parent Pi session watches result-file events. Once every worker is terminal, it records an exactly-once notification marker and sends a bounded, source-labelled untrusted handoff with `triggerTurn: true`. Startup performs one reconciliation pass for terminal events produced while Pi was offline.
+The parent Pi session watches result-file events. Once a turn's worker is terminal, it records a per-agent notification marker (`notifiedTurn`) and sends a bounded, source-labelled untrusted handoff with `triggerTurn: true`. Startup performs one reconciliation pass for terminal events produced while Pi was offline, and also reconciles tmux **sessions**: see [Persistence](#persistence-follow-ups-reconcile-dismiss) below.
 
 Do not poll pane state, capture pane output, or inspect logs merely to detect completion. Use `job_status` or terminal artifacts after the handoff only when its bounded evidence is insufficient.
 
+## Persistence: follow-ups, reconcile, dismiss
+
+A `fire_task` pane's provider CLI stays alive and interactive after its first terminal marker. Three
+actions manage that persistence:
+
+- **`send_followup`** — re-injects a new prompt into an already-live job's pane (default: the job's
+  first/primary agent; pass `agentId` to target another). It re-arms the completion watcher for a fresh
+  turn using a unique per-turn marker pair, so it cannot be confused with an earlier turn's markers, and
+  reuses the same event-driven, exactly-once handoff. Refuses if the tmux session or pane is gone
+  (relaunch with `fire_task` instead) or if the job was `dismiss`ed.
+- **`dismiss`** — stops tracking a job (no more re-arming, no more handoffs) without killing its tmux
+  session; the pane keeps running and can still be attached to (`tmux attach -t <session>`) or stopped
+  later with `stop_job`/`stop_session`.
+- **Session reconcile** — on session start, Pi diffs live tmux sessions against its own job records for
+  jobs it started. A session that has disappeared while its job was not yet terminal is marked orphaned
+  (informational only — nothing is ever killed to produce this state, and the job directory is never
+  deleted automatically). A session that is still alive with a pending turn has its watcher re-armed so
+  the job can still complete normally. Killing a session always stays behind the explicit
+  `stop_job`/`stop_session` confirm path.
+
+An idle worker (no turn currently dispatched) does not hold this session's reload-quiesce; `/reload` is
+never blocked merely because a persistent tmux worker exists between turns.
+
+## Approval-gated dispatch: the standing grant
+
+A real (non-dry-run) `fire_task` or `send_followup` launch requires either a **standing grant** or a
+one-shot interactive approval — never a silent launch:
+
+- **`grant_dispatch`** authorizes repeated unattended dispatch. Set `agent` (required), `maxLaunches`
+  (required), and optionally `goalId` (an unscoped grant covers any goal), `allowedTools`,
+  `resourceProfile`, `writePaths`, and `expiresInMinutes`. Requires interactive confirmation when a UI is
+  attached; in print/rpc/non-interactive mode, requires the `--allow-tmux-dispatch` CLI flag instead.
+  Once granted, matching launches proceed unattended and consume one unit of `maxLaunches` for each child process launched.
+- **`revoke_grant`** ends a standing grant early (defaults to whichever grant is currently active).
+- With **no covering grant**: an interactive session is prompted for a one-shot approval; a
+  non-interactive session (no UI, no grant) is **refused** with a clear error — never launched silently.
+
+A grant-covered (or one-shot-approved) `pi` child is launched with a **restricted profile**: `--tools`
+(or a read-biased default), `--resource-profile` (or `--no-extensions --no-skills`), and a scoped
+`--append-system-prompt` naming the grant and a fixed hard-stop list (publish/push/tag/credential
+changes/destructive deletion must come back BLOCKED, never self-approved). This pushes the envelope into
+the **child's own** launch configuration — it is not an in-process sandbox, and non-`pi` agents
+(`agy`/`claude`/`codex`/`opencode`/custom) are bounded only at the launch layer; their internal tool-loop
+behavior is that CLI's own responsibility.
+
+Grant budget (`maxLaunches`, `expiresInMinutes`) is real and enforced. `maxUsdAdvisory` and any
+self-reported worker usage are **advisory** — a claim to review, never a hard cap across the process
+boundary (the child bills under its own authentication).
+
+Dispatched tmux workers appear as `tmux-worker` lanes alongside in-process worker lanes in `/autonomy`
+and `delegate_status`; a worker's self-reported changed files are re-checked against the session's active
+write scope and flagged for parent review when out of scope, exactly like an in-process worker's.
+
+## Goal-bound dispatch (`goal dispatch_worker dispatchTarget:"tmux"`)
+
+The `goal` tool's `dispatch_worker` action can bind a single open requirement to a persistent tmux worker
+instead of the default in-process one: pass `dispatchTarget: "tmux"`. Core invokes `fire_task` itself (the
+same call the model would make) with exactly one `pi` agent, so the dispatch maps 1:1 to the
+requirement's bound lane; the launch still goes through the standing-grant authorization above unchanged
+— an unattended goal/idle loop with no covering grant is honestly refused, never silently launched. The
+requirement's binding is recorded either way; a successful tmux dispatch waits and resumes through the
+same lane machinery as an in-process worker.
+
+When no worker was dispatched, the tool response's `dispatchSkipReason` explains why:
+
+- `no_standing_grant` — no covering grant, and this call had no UI to prompt (run `grant_dispatch` first).
+- `tmux_extension_not_loaded` — `tmux_agent_manager` is not loaded in this session (see Enable above).
+- `tmux_dispatch_failed` — the `fire_task` launch threw for a reason other than the grant (a bad jobId, a
+  live session-name collision, an environment failure).
+- `tmux_dispatch_incomplete` — the launch call returned without the job/agent details needed to identify
+  the new lane.
+- `lane_correlation_failed` — the new lane could not be resolved to its internal tracking id.
+- `worktree_create_failed` — worktree-sync refused the lane before any tmux pane was launched.
+- `worker_capability_insufficient` — the selected model is not eligible for a lane worker; no lane or pane was created.
+- `requirement_already_bound` — the requirement is already bound to a lane that is still queued/running;
+  no duplicate dispatch was attempted.
+- `bound_lane_indeterminate` — the requirement is bound to a lane whose liveness/outcome cannot be
+  determined (e.g. after `/reload`); dispatch is refused rather than risking a duplicate worker. A bound
+  lane with a confirmed terminal outcome allows a fresh dispatch normally.
+
 ## Safety
 
-Launch actions run directly unless `dryRun: true` is requested. Stop actions can discard active pane work, so they remain previews by default and require `confirm: "yes-tmux-stop"` for execution. Existing sessions are never replaced silently; `force: true` archives an old job directory but does not kill a live tmux session.
+Launch actions run directly unless `dryRun: true` is requested, and are approval-gated per the standing
+grant above. Stop actions can discard active pane work, so they remain previews by default and require
+`confirm: "yes-tmux-stop"` for execution. Existing sessions are never replaced silently; `force: true`
+archives an old job directory but does not kill a live tmux session.
 
 The package includes the extension README and team templates under `dist/bundled-resources/extensions/tmux-agent-manager/`; the source repository keeps them under the matching `src/bundled-resources/` path.

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

@@ -39,3 +39,32 @@ Use a named run only for transient coordination that must be shared across Pi pr
 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.
 
 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)
+  skills/ extensions/ prompts/ themes/ profiles/                                       user resources (root)
+  state/     durable machine state: model adaptation/fitness, tool-performance,        -- stateDir/stateFile
+             learning observations, trust decisions (trust.json), failure corpus, …
+  cache/     rebuildable, safe to delete: tool-path probes, jiti transform cache, uv    -- cacheDir/cacheFile
+  bin/       managed executable helpers (fd, rg)                                       -- binDir (legacy getBinDir accessor)
+  work/      transient/scratch (this document)                                         -- re-exported from agent-paths.ts
+  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 location — currently just `trust.json` into `state/` — idempotently and without ever
+overwriting an already-migrated target. `resource-profiles/` intentionally stays at the agent-directory
+root rather than moving under `state/`: it's surfaced in two user-visible profile-menu description
+strings, and moving it needs those updated in the same change (tracked open in the bug ledger, not a
+silent gap).

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

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

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

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

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

package/npm-shrinkwrap.json

@@ -1,17 +1,17 @@
 {
 	"name": "@caupulican/pi-adaptative",
-	"version": "0.81.38",
+	"version": "0.81.39",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@caupulican/pi-adaptative",
-			"version": "0.81.38",
+			"version": "0.81.39",
 			"license": "MIT",
 			"dependencies": {
-				"@caupulican/pi-agent-core": "^0.81.38",
-				"@caupulican/pi-ai": "^0.81.38",
-				"@caupulican/pi-tui": "^0.81.38",
+				"@caupulican/pi-agent-core": "^0.81.39",
+				"@caupulican/pi-ai": "^0.81.39",
+				"@caupulican/pi-tui": "^0.81.39",
 				"@silvia-odwyer/photon-node": "0.3.4",
 				"chalk": "5.6.2",
 				"cross-spawn": "7.0.6",
@@ -475,11 +475,11 @@
 			}
 		},
 		"node_modules/@caupulican/pi-agent-core": {
-			"version": "0.81.38",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-agent-core/-/pi-agent-core-0.81.38.tgz",
+			"version": "0.81.39",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-agent-core/-/pi-agent-core-0.81.39.tgz",
 			"license": "MIT",
 			"dependencies": {
-				"@caupulican/pi-ai": "^0.81.38",
+				"@caupulican/pi-ai": "^0.81.39",
 				"ignore": "7.0.5",
 				"typebox": "1.1.38",
 				"yaml": "2.9.0"
@@ -489,8 +489,8 @@
 			}
 		},
 		"node_modules/@caupulican/pi-ai": {
-			"version": "0.81.38",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-ai/-/pi-ai-0.81.38.tgz",
+			"version": "0.81.39",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-ai/-/pi-ai-0.81.39.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.91.1",
@@ -542,8 +542,8 @@
 			}
 		},
 		"node_modules/@caupulican/pi-tui": {
-			"version": "0.81.38",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-tui/-/pi-tui-0.81.38.tgz",
+			"version": "0.81.39",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-tui/-/pi-tui-0.81.39.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"get-east-asian-width": "1.6.0",