@tduyng/pi-prewalk 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+Use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 tduyng

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @tduyng/pi-prewalk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## The problem
+
+Stencil measured 1.81B tokens over ~2M tool calls and found edits are about 9% of them. Reads are the rest.
+
+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, 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.
+
+## 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.
+
+Each route returns one request's model, so the planner and the executor can differ per request inside one 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.
+
+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.
+
+**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.
+
+**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.
+
+**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 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.
+
+**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.
+
+**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.
+
+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.
+
+## The score that is gone
+
+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.
+
+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.
+
+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.
+
+## Grading the routes
+
+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`.
+
+Read it as a survey. The log grows while the run reads it, so the numbers move under you.
+
+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 and context
+
+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 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.
+
+## 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.
+
+```json
+{
+  "planner": ["opencode-go/mimo-v2.6-pro", "anthropic/claude-opus-4-6"],
+  "executor": ["opencode-z/space-bunny-free", "z-ai/glm-5.3-flash"]
+}
+```
+
+`/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
+
+## 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                 |
+
+`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, `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.
+
+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.
+
+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.
+
+## Configuration
+
+`~/.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.
+
+```json
+{
+  "planner": ["opencode-go/mimo-v2.6-pro"],
+  "executor": ["opencode-go/mimo-v2.6-flash"],
+  "mode": "plan",
+  "review": true
+}
+```
+
+`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 is per project file, and `mode: "off"` still lets `/prewalk plan`, `/prewalk run`, and `/prewalk <planner> <executor> [task]` work.
+
+## Install
+
+```bash
+pi install npm:@tduyng/pi-prewalk
+```
+
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-prewalk`

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@tduyng/pi-prewalk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Plan on the frontier model, execute on the cheap one. The session model swaps the moment the first edit lands.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "cost",
+    "model-routing",
+    "planning"
+  ],
+  "homepage": "https://gitlab.com/tduyng/pi-agent/-/tree/main/extensions/pi-prewalk#readme",
+  "bugs": "https://gitlab.com/tduyng/pi-agent/-/issues",
+  "license": "Apache-2.0",
+  "author": "tduyng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tduyng/pi-agent.git",
+    "directory": "extensions/pi-prewalk"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "ata-validator": "^1.62.1"
+  }
+}

package/src/bash-writes.ts

@@ -0,0 +1,42 @@
+import { isScratchPath } from './logic.js'
+
+const HEREDOC = /(?<!<)<<(?!<)-?\s*(['"]?)(\w+)\1/
+const QUOTED = /'[^']*'|"(?:[^"\\]|\\.)*"/g
+const REDIRECT = />>?\s*([^\s;&|()<>]+)/g
+const WRITER_VERB =
+    /(^|[\s;&|(])(sed\b[^|;&\n]*\s(-[a-zA-Z]*i[a-zA-Z]*|--in-place)|perl\b[^|;&\n]*\s-[a-zA-Z]*i|git\s+(apply|am))(?![\w-])|(^|[;&|(]\s*)(tee|patch)(?![\w-])/
+const INTERPRETER = /(^|[;&|(]\s*)(python3?|node|bun|deno|ruby|perl)(?![\w-])/
+const SCRIPT_WRITE =
+    /\b(writeFileSync|appendFileSync|write_text|write_bytes|Bun\.write)\b|\bopen\([^)]*,\s*['"][wax]\+?b?['"]/
+
+function withoutInertText(command: string): string {
+    const kept: string[] = []
+    let end: string | null = null
+    for (const line of command.split('\n')) {
+        if (end !== null) {
+            if (line.trim() === end) end = null
+            continue
+        }
+        kept.push(line)
+        end = HEREDOC.exec(line)?.[2] ?? null
+    }
+    return kept.join('\n').replace(QUOTED, "''")
+}
+
+function redirectsToWorkspace(command: string, cwd: string): boolean {
+    const text = withoutInertText(command)
+    for (const match of text.matchAll(REDIRECT)) {
+        const before = text[match.index - 1]
+        const target = match[1] ?? ''
+        if (before === '-' || before === '=' || target.startsWith('=')) continue
+        if (target.startsWith('/dev/') || isScratchPath(target, cwd)) continue
+        return true
+    }
+    return false
+}
+
+export function bashWritesFiles(command: string, cwd: string): boolean {
+    if (redirectsToWorkspace(command, cwd)) return true
+    const text = withoutInertText(command)
+    return WRITER_VERB.test(text) || (INTERPRETER.test(text) && SCRIPT_WRITE.test(command))
+}

package/src/config.ts

@@ -0,0 +1,108 @@
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { Validator, type Infer } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+export const PREWALK_CONFIG_FILE = 'prewalk.json'
+
+export function prewalkConfigPath(): string {
+    return join(getAgentDir(), PREWALK_CONFIG_FILE)
+}
+
+export function prewalkProjectConfigPath(): string {
+    return join(process.cwd(), '.pi', PREWALK_CONFIG_FILE)
+}
+
+/** A project that carries the file owns later writes. Otherwise they stay in the agent dir, which
+ * is the file every session had before the project one existed. */
+export function prewalkWritePath(): string {
+    const project = prewalkProjectConfigPath()
+    return existsSync(project) ? project : prewalkConfigPath()
+}
+
+export type PrewalkMode = 'plan' | 'off'
+
+export type PrewalkConfig = {
+    planner: string[]
+    executor: string[]
+    mode: PrewalkMode
+    review: boolean
+}
+
+/**
+ * `plan` by default, and not because routing is free.
+ *
+ * The score that used to pick the planner or the cheap tier read 0.548 AUC against how long a
+ * turn ran, so it did not separate, and the phase already decides the rest: a task plans and the
+ * cheap tier runs the steps of the plan it was given. `off` runs everything on the cheap tier with
+ * no plan at all.
+ */
+export const DEFAULT_PREWALK_CONFIG: PrewalkConfig = {
+    planner: [],
+    executor: [],
+    mode: 'plan',
+    review: true
+}
+
+const RoleChain = t.union([t.string(), t.array(t.string())])
+
+const PrewalkSettings = t.object({
+    planner: t.optional(RoleChain),
+    executor: t.optional(RoleChain),
+    mode: t.optional(t.union([t.literal('plan'), t.literal('off'), t.literal('auto')])),
+    review: t.optional(t.boolean())
+})
+const isPrewalkSettings = new Validator(PrewalkSettings).isValidObject
+
+/** The shape a `prewalk.json` may hold, before defaults fill it in. */
+export type PrewalkSettings = Infer<typeof PrewalkSettings>
+
+function modelChain(value: string | string[] | undefined): string[] {
+    if (value === undefined) return []
+    const raw = Array.isArray(value) ? value : [value]
+    return raw.filter((entry) => entry.trim() !== '')
+}
+
+function prewalkConfigFrom(settings: PrewalkSettings): PrewalkConfig {
+    return {
+        planner: modelChain(settings.planner),
+        executor: modelChain(settings.executor),
+        mode: settings.mode === 'off' ? 'off' : 'plan',
+        review: settings.review !== false
+    }
+}
+
+function readSettingsFile(path: string): PrewalkSettings {
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+        return isPrewalkSettings(parsed) ? parsed : {}
+    } catch {
+        return {}
+    }
+}
+
+export function readPrewalkConfig(path: string = prewalkConfigPath()): PrewalkConfig {
+    return prewalkConfigFrom(readSettingsFile(path))
+}
+
+/** The project file overrides the agent dir one field by field, so a checkout can pin its own
+ * models without the machine losing the pair it ships with. */
+export function readEffectivePrewalkConfig(
+    agentPath: string = prewalkConfigPath(),
+    projectPath: string = prewalkProjectConfigPath()
+): PrewalkConfig {
+    return prewalkConfigFrom({ ...readSettingsFile(agentPath), ...readSettingsFile(projectPath) })
+}
+
+export function writePrewalkConfig(config: PrewalkConfig, path: string = prewalkWritePath()): boolean {
+    try {
+        const target = existsSync(path) ? realpathSync(path) : path
+        const temporary = `${target}.${process.pid}.tmp`
+        writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`)
+        renameSync(temporary, target)
+        return true
+    } catch {
+        return false
+    }
+}