@tduyng/pi-prewalk 0.0.2 → 0.0.3

package/README.md

@@ -1,66 +1,87 @@
 # @tduyng/pi-prewalk
 
-A task goes to the frontier planner, the planner gives the cheap executor a plan to carry out, and the executor hands the work back if it hits a wall. The phase decides every boundary, and no model is asked to.
+Plan on the frontier model, execute on the cheap one, in one unbroken context. The first edit swaps the model, and the planner comes back only when the executor hits a wall.
 
-## The problem
+## What it costs
 
-Stencil measured 1.81B tokens over ~2M tool calls and found edits are about 9% of them. Reads are the rest.
+`prewalk_plan` is deferred at 716 tokens in the sessions that load it, and nothing before that. The router is one hook on `streamSimple` and registers no extra schema, so an armed session pays the router and the plan tool, and an unarmed one pays nothing.
 
-A plan document does not help. Whoever executes it opens the same files again.
+The saving is the tier. On SWE-bench this reached 92 to 97 percent of the frontier pass rate for 53 to 61 percent of its cost. Planning is the expensive step, and it is bought once per task rather than once per turn.
 
-prewalk keeps one context instead. The planner explores and makes the first edit, then the cheap model carries on from the same history. On SWE-bench it reached 92 to 97% of the frontier pass rate for 53 to 61% of its cost.
+## Why not a plan document
+
+Stencil measured 1.81B tokens over about 2M tool calls and found edits are roughly 9 percent of them. Reads are the rest, so a plan document does not help: whoever executes it opens the same files again.
+
+prewalk keeps one context instead. The planner explores and makes the first edit, and the cheap model carries on from the same history with the plan in hand.
 
 ## The router
 
-prewalk registers one virtual model, `prewalk/auto`. Select it with `/prewalk` or from `/model`. Pi calls the router before every request, so prewalk never moves the session's model itself and no `setModel` runs in the middle of a task. Every model change in the session file is one prewalk made.
+prewalk registers one virtual model, `prewalk/auto`, selected with `/prewalk` or from `/model`. Pi calls the router before every request, so prewalk never moves the session's model itself and no `setModel` runs mid task. Every model change in the session file is one prewalk made.
 
-Each route returns one request's model, so the planner and the executor can differ per request inside one task.
+Each route returns one request's model, so planner and executor can differ inside a single task.
 
 ## A task boundary
 
-prewalk asks one question, and only when a task is about to start. The boundary is the gap between one settled run and the next prompt typed after it, so a task is routed once and the turns inside it are never touched.
+prewalk asks one question, and only when a task is about to start. The boundary is the gap between one settled run and the next prompt typed after it, so a task routes once and the turns inside it are never touched.
+
+Pi's own `reason: "user"` cannot carry that boundary, because it fires for a steer and a follow-up too. prewalk keeps its own flag set from the `input` event, which reads `streamingBehavior` as the three cases it is: undefined when the session was idle, `steer` when the text joins the turn in flight, and `followUp` when it waits for that turn to settle and opens a task of its own. The first router call that sees the flag consumes it, so one prompt routes once. A message from another extension opens a task the same way, and the only text that opens nothing is prewalk's own nudge, recognized by its `[prewalk]` prefix.
+
+| You type | What happens |
+| --- | --- |
+| A prompt during the task in flight | The model stays, the prompt runs as written, no routing call. This is the common case, and what keeps the bill linear in turns rather than quadratic |
+| A question while the executor is in play | A steer long enough to be a question moves the task back to the planner, which stays until the next edit hands it over. No routing call, because the phase answers it. A one-word steer is a redirect and stays where it is |
+| A new task | The session moves to the planner before the first token |
+| A prompt under 8 characters | Not a task: it holds whatever is in play |
 
-Pi's own `reason: "user"` cannot carry that boundary. It fires for a steer and a follow-up too, because both arrive as a user message after the last assistant message. prewalk keeps its own flag, set from the `input` event, which reads `streamingBehavior` as the three cases it actually is: undefined when the session was idle, `steer` when the text joins the turn in flight, and `followUp` when it waits for that turn to settle and then opens a task of its own. The first router call that sees the flag consumes it, so one prompt routes once. The source does not matter: a message from another extension opens a task the same way, and the only text that opens nothing is prewalk's own nudge, recognized by its `[prewalk]` prefix.
+## The handoff
 
-**A prompt inside the task in flight.** The model stays where it is, the prompt runs as written, and no routing call is made. This is the common case, and it is the one that makes the bill linear in the turn count rather than quadratic.
+The planner explores, then must commit a structured plan through `prewalk_plan` before it can edit. The first edit is blocked once with a message naming the tool, and a planner that ignores the block degrades to a plain edit-only swap.
 
-**A question typed while the executor is in play.** The text used to be dropped on the way in, so a mid-task question could never reach the planner. It does now: a steer long enough to be a question moves the task back to the planner, whatever reason pi carries the request under, and the planner stays in play until the next edit hands it to the executor again, and the session says so. No routing call is spent, because the phase answers it. A one-word steer is a redirect rather than a question and stays on the model in play.
+The first `edit`, `write`, `multiedit`, or `notebookedit` after the plan swaps the session to the executor, and so does a bash command that writes a file outside the temp dir (a redirect, `sed -i`, `tee`, `patch`, `git apply`, or an inline script that writes), which also demands the plan first. A third tool call after the plan still hands over, for a planner that writes in a way the check cannot see. An edit under the temp dir is scratch and swaps nothing.
 
-**A task routed to the planner.** The session moves to the planner before the first token. The planner explores, then must commit a structured plan through the `prewalk_plan` tool before it can edit: the first edit is blocked once with a message naming the tool, and a planner that ignores the block degrades to a plain edit-only swap. The first `edit`, `write`, `multiedit` or `notebookedit` after that swaps the session to the executor, and so does a bash command that writes a file outside the temp dir (a redirect, `sed -i`, `tee`, `patch`, `git apply`, or an inline script that writes), which also demands the plan first. The third tool call after the plan still hands over for a planner that writes in a way the check cannot see. An edit under the temp dir is scratch and swaps nothing. The plan tool returns the handoff brief itself: the goal, the facts with file:line, each step with file, anchor, change and verify command, the out-of-scope list, and the rules of engagement. Both roles read the same bytes, so neither cache is rewritten.
+The plan tool returns the handoff brief itself: the goal, the facts with file:line, each step with file, anchor, change, and verify command, the out-of-scope list, and the rules of engagement. Both roles read the same bytes, so neither cache is rewritten.
 
-**The cheap tier.** A task plans: the planner opens it, and the executor joins from the first edit on and runs the steps of the plan the planner gave, and nothing else. A prompt too short to be a task, under eight characters, is not a task: it holds whatever is in play rather than opening one. `/prewalk off` puts every task on the cheap model with no plan, and `/prewalk run <task>` does it for one task.
+## When the executor is stuck
 
-**A task the executor is stuck on.** Three failed tool results in a row are a wall. One miss does not hand the task back, and any success resets the count. The third failure appends a brief naming the step, and the planner takes the task back on the next request until its next edit. The task buys two upgrades, because each swap re-reads the whole prefix at the new model's rate, so a task cannot ping-pong between the models.
+Three failed tool results in a row are a wall. One miss does not hand the task back, and any success resets the count. The third failure appends a brief naming the step, and the planner takes the task back on the next request until its next edit.
 
-**The review.** When the executor finishes the plan, or stalls after its nudge, the planner takes the task back once per plan. It reads the edits already in the transcript, runs the final check, and fixes what is wrong. Work the plan did not cover gets a new plan, which is how a long task runs in phases of up to 20 steps. `"review": false` in `prewalk.json` turns it off.
+A task buys two upgrades, because each swap re-reads the whole prefix at the new model's input rate, and a task cannot ping-pong between the models.
 
-That is the one place a stuck cheap model hands the task over by itself: the wall is the evidence. The failing result carries a brief with the step and the failure count, and the planner decides whether to fix it here or commit the steps that are left. The session badge reads `prewalk replan` while it happens.
+When the executor finishes the plan, or stalls after its nudge, the planner takes the task back once per plan. It reads the edits already in the transcript, runs the final check, and fixes what is wrong. Work the plan did not cover gets a new plan, which is how a long task runs in phases of up to 20 steps. `"review": false` in `prewalk.json` turns that off.
 
-## The score that is gone
+The session badge reads `prewalk replan` while this happens.
 
-The routing call used to ask three questions over the prompt text and gate the boundary on the answer. `difficulty` asked how much a stronger model would improve the answer, scored across four levels from 0 to 3. `tool` asked whether the fix follows mechanically from what the code already says, and `needsTools` whether the work needs tools and live code, or only the repository's contents.
+## The plan tool
+
+`prewalk_plan` is in the active set while prewalk is armed in plan mode, and the executor meets it only through tool search. Its description carries the planning brief, which is why nothing is prepended to your prompt.
 
-It did not separate. The difficulty expectation read 0.548 AUC against how long the turn ran, and the three tail readouts read 0.527 to 0.537, so the distribution shape held no more than its mean. Against the label that matters for routing, which model actually ran the turn, it read 0.755 AUC over 20 turns on the frontier model and 255 on the free one, and the four live prompts that mattered came out the way round: a bug analysis at 0.907 and a variable rename at 1.514.
+| Field | Meaning |
+| --- | --- |
+| `summary` | One-line goal |
+| `facts` | Findings from exploration the executor cannot re-derive, each with file:line |
+| `steps` | `{ file, change, anchor?, verify? }` in order, up to 20 |
+| `check` | Final verification command |
+| `outOfScope` | Files the executor must not touch |
 
-Two cuts were fitted on it and both came out wrong, one above the range and one with a hold band that put every task on the cheap model. The score is deleted, and so is the call that produced it, because a router that cannot tell a bug from a rename is not a router. The phase already answers the same question: a task plans, and the cheap tier runs the steps of the plan it was given.
+## Progress
 
-## Grading the routes
+After each edit the extension matches the edited path against the plan steps and advances a step pointer, walking forward from the current step so batched edits and missed results catch up instead of freezing the count. A short footer is appended to the edit result: what was done, what comes next, the anchor, and the verify command. No model cooperation is needed.
 
-The route is kept in the session's own state entry, so a session grades itself and the check needs no model. `just routes` reads every session under `sessions/`, splits the tasks by the route each one took, and prints what they cost, how many landed an edit, and how many ran the plan's own `check`.
+The badge reads `prewalk route` between tasks, `prewalk plan` or `prewalk run` on the first turn of one, `prewalk exec 3/7` while the plan runs, and `prewalk done 7/7` at the end.
 
-Read it as a survey. The log grows while the run reads it, so the numbers move under you.
+A planner that commits a plan but ends the turn without an edit still gets the swap, and the executor is nudged to start step 1. An executor that settles with steps open gets one steer to resume. Your input or progress re-arms it, so at most one nudge is spent per stall.
 
-A wrong swap costs a whole cache re-read at the new model's input rate, so a prompt too short to be a task keeps the model already in play.
+## Cache
 
-## Cache and context
+A prompt cache belongs to one model, so the swap is the only thing that has to be paid for, and a task pays it at most once: the executor meets a prefix it has never seen, at the cheap model's input rate.
 
-A prompt cache belongs to one model. The swap is the only thing that has to be paid for, and a task pays it at most once: the executor meets a prefix it has never seen, at the cheap model's input rate.
+Prompts are never rewritten. There is no wrapper on your message and no message is edited afterwards, so both models read the transcript you wrote and each keeps its cache warm across its own turns. The one message prewalk writes is the plan tool's result, at the swap.
 
-Prompts are never rewritten. There is no wrapper on your message and no message is edited after the fact, so both models read the transcript you wrote and each keeps its cache warm across its own turns. The single message prewalk writes is the plan tool's result, and it is written once at the swap. The `prewalk_plan` tool stays in the active set for as long as prewalk is armed in plan mode, because a toolset change rewrites the system prompt and the tool list, and the claude provider answers that by opening a new session that replays the whole transcript.
+`prewalk_plan` stays in the active set for as long as prewalk is armed in plan mode, because a toolset change rewrites the system prompt and the tool list, and the claude provider answers that by opening a new session that replays the whole transcript.
 
 ## Model chains
 
-Each role is an ordered list, walked until one model resolves against pi's registry and has credentials. Two ordinary things break a single model: a provider with no API key, and a frontier model that runs out of its usage window part way through the day. The chain absorbs both without a config edit.
+Each role is an ordered list, walked until one model resolves against pi's registry and has credentials. Two ordinary things break a single model: a provider with no key, and a frontier model that runs out of its usage window part way through the day. The chain absorbs both without a config edit.
 
 ```json
 {
@@ -69,54 +90,36 @@ Each role is an ordered list, walked until one model resolves against pi's regis
 }
 ```
 
-`/prewalk models` prints both chains and marks each entry `router`, `ready`, or `unavailable` against the registry pi's `/model` reads, with the context window and input price the picker shows, and the mode underneath.
-
-## Progress tracking
-
-After each edit, the extension matches the edited file path against the plan steps and auto-advances a step pointer. The match walks forward from the current step, so batched edits and missed results catch up instead of freezing the count. A short footer is appended to the edit result: what was done, what comes next, the anchor, and the verify command. No model cooperation is required.
-
-The status badge reads `prewalk route` between tasks, `prewalk plan` or `prewalk run` on the first turn of one, `prewalk exec 3/7` while the plan runs, and `prewalk done 7/7` at the end.
-
-If the planner commits a plan but the turn ends without an edit, the extension swaps anyway and nudges the executor to start step 1. When the executor settles with steps open, one steer resumes the plan. User input or progress re-arms it, so at most one nudge is spent per stall.
-
-## The plan tool
-
-`prewalk_plan` is in the active set while prewalk is armed in plan mode, and the executor only meets it through tool search. Its description carries the planning brief, which is why nothing is prepended to your prompt. Its schema:
-
-- `summary`: one-line goal
-- `facts`: findings from exploration the executor cannot re-derive, each with file:line
-- `steps`: `{ file, change, anchor?, verify? }` in order, max 20
-- `check`: final verification command
-- `outOfScope`: files the executor must not touch
+`/prewalk models` prints both chains and marks each entry `router`, `ready`, or `unavailable` against the registry `/model` reads, with the context window and input price, and the mode underneath.
 
 ## Commands
 
-| Command                                | Effect                                                    |
-| -------------------------------------- | --------------------------------------------------------- |
-| `/prewalk`                             | status while armed, arm from `prewalk.json` when not      |
-| `/prewalk off`                         | disarm                                                    |
-| `/prewalk status`                      | both chains, the mode, and where the task is              |
-| `/prewalk models`                      | both chains, what resolves, what it costs, and the mode   |
-| `/prewalk mode off`                    | nothing happens unless you ask                            |
-| `/prewalk mode plan`                   | every task plans (the default)                            |
-| `/prewalk planner <model>...`          | replace the planner chain, or pick one from a list        |
-| `/prewalk executor <model>...`         | replace the executor chain, or pick one from a list        |
-| `/prewalk plan [task]`                 | the next task plans, decided by hand                      |
-| `/prewalk run [task]`                  | the next task runs on the cheap model, decided by hand    |
-| `/prewalk <executor> [task]`           | set the executor. A task given here starts on the planner |
-| `/prewalk <planner> <executor> [task]` | set both roles and, with a task, start it                 |
+| Command | Effect |
+| --- | --- |
+| `/prewalk` | Status while armed, arm from `prewalk.json` when not |
+| `/prewalk off` | Disarm |
+| `/prewalk status` | Both chains, the mode, and where the task is |
+| `/prewalk models` | Both chains, what resolves, what it costs, and the mode |
+| `/prewalk mode off` | Nothing happens unless you ask |
+| `/prewalk mode plan` | Every task plans (the default) |
+| `/prewalk planner <model>...` | Replace the planner chain, or pick one from a list |
+| `/prewalk executor <model>...` | Replace the executor chain, or pick one from a list |
+| `/prewalk plan [task]` | The next task plans, decided by hand |
+| `/prewalk run [task]` | The next task runs on the cheap model, decided by hand |
+| `/prewalk <executor> [task]` | Set the executor. A task given here starts on the planner |
+| `/prewalk <planner> <executor> [task]` | Set both roles and, with a task, start it |
 
-`plan` and `run` spend one routing decision, so they work with nothing else running. Slash commands and skill blocks (`<skill `) are left alone, so skill expansion still works.
+A role named with no model opens the same dialog pi's own model list is built from, each line carrying `provider/id`, the context window, and the input price per million, sorted by price because the executor is the tier you pay for.
 
-A role named with no model opens the same dialog pi's own model list is built from, `ctx.ui.select`, since pi keeps its selector private and no extension API opens it. Each line carries what a role choice turns on, `provider/id`, the context window, and the input price per million, sorted by price because the executor is the tier you pay for. A chain of several models still takes arguments, because a dialog picks one.
+Slash commands and skill blocks are left alone, so skill expansion still works.
 
-An armed prewalk owns the session model, because every task routes through the router. A switch away from it is a session where nothing routes at all, for the rest of its life, and one press of the model cycle key used to make it silently: the `12:20` model change in the session that reported the router stuck on `mimo-v2.6-flash` left 130 assistant messages on `space-bunny-free` with no routing at all. prewalk now takes the router back on `model_select` and on every session start and branch switch, and says which model it took. `/prewalk off` is the mode that plans nothing and takes no model, so that is how a physical model is kept.
+An armed prewalk owns the session model, because every task routes through the router. A switch away from it leaves a session where nothing routes for the rest of its life, and one press of the model cycle key used to do that silently: the `12:20` model change in one session left 130 assistant messages on a cheap model with no routing at all. prewalk now takes the router back on `model_select` and on every session start and branch switch, and says which model it took. `/prewalk off` is how a physical model is kept.
 
-Model naming is a bare id (`deepseek-v4-flash`) or provider/id (`google/gemini-3-flash`). Resolution is exact provider/id, then exact bare id, then unique id suffix. A bare id that several providers carry is an error rather than a guess.
+Model naming is a bare id (`deepseek-v4-flash`) or provider/id (`google/gemini-3-flash`). Resolution is exact provider/id, then exact bare id, then unique id suffix, and a bare id that several providers carry is an error rather than a guess.
 
-## Configuration
+## Configure
 
-`~/.pi/agent/prewalk.json` holds the machine-wide settings. A project's `.pi/prewalk.json` overrides `planner`, `executor` and `mode` field by field. The commands write to the project file when one exists, otherwise to the agent dir. Edit either for anything they do not cover.
+`~/.pi/agent/prewalk.json` holds the machine-wide settings. A project's `.pi/prewalk.json` overrides `planner`, `executor`, and `mode` field by field. The commands write to the project file when one exists, otherwise to the agent dir.
 
 ```json
 {
@@ -127,13 +130,9 @@ Model naming is a bare id (`deepseek-v4-flash`) or provider/id (`google/gemini-3
 }
 ```
 
-`mode` is how a task gets its model. `plan` is the default: every task starts on the frontier model and the executor carries the steps of the plan it was given. `off` plans nothing unless you ask, so every task runs on the executor. `/prewalk run [task]` still picks a single task for the cheap model. A file written before the score was removed, with `mode: "auto"`, reads as `plan`.
-
-The router must be selected for any of this to run. An armed session takes it back on session start and on a branch switch, and says which model it took. A session that was never armed stays on whatever model you chose.
-
-A string is still accepted for either role, so a file written before the chains existed reads the same way. A missing, unparseable, or wrongly shaped file costs its settings and not the session.
+`mode` decides how a task gets its model. `plan` is the default: every task starts on the frontier model and the executor carries the steps it was given. `off` plans nothing unless you ask, so every task runs on the executor. A file written before the score was removed, with `mode: "auto"`, reads as `plan`.
 
-Mode is per project file, and `mode: "off"` still lets `/prewalk plan`, `/prewalk run`, and `/prewalk <planner> <executor> [task]` work.
+The router must be selected for any of this to run. A string is still accepted for either role, so a file written before the chains existed reads the same. A missing, unparseable, or wrongly shaped file costs its settings and not the session.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tduyng/pi-prewalk",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Plan on the frontier model, execute on the cheap one. The session model swaps the moment the first edit lands.",
   "keywords": [
     "pi",