M4.1: toolchain preflight

A model works out and sets up what a project needs on its build VM;
code makes sure that happens, bounds it and checks the result (D3).

- Before each driver run on a project, one round trip checks the build
  VM: the harness's own baseline (missing: the item waits, a template
  problem), the workspace clone (missing: cloned again and said; the
  item resumes from what it pushed) and a per-project marker.
- No marker (a new project, a new or wiped VM): the item's driver model
  runs a bounded preflight first, with its own prompt, the execution
  tools (screened as ever) and toolchain_ready. The harness runs each
  reported version command itself (version-shaped commands only, even
  from the marker, which the model's commands could edit) and writes
  the marker. Gaps and an unfinished preflight are facts and work goes
  on; the thread hears only of installs and gaps. A rebuilt VM starts
  from the last toolchain.
- Later runs check the versions again; a change is a fact and a thread
  line. The PR body says what the work was tested with.
- A changed host key is its own failure (HostKeyChanged): the item
  waits for the operator's `trust new host key`, which drops the pin;
  then the VM is set up again.
- A prompt line: install what the work needs on the build VM, say why,
  and put lasting needs in the project's own pins.
- tuning.preflight: max_turns, command_timeout_s.
- The property walk gains a VM wipe and ready_before_work (checked
  against a mutant that skips preflight); parked_work_safe accepts that
  a wipe loses what wasn't pushed (D3).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

docs/Development-Plan.md

@@ -380,6 +380,28 @@ agent merging behind protection it can't satisfy, verified by a test (D4, D5, #6
 **M4.1 Toolchain preflight, M4.2 recording installs, M4.3 environment repair.**
 *Pre-approved.* All on the build VM (D3).
 
+**M4.1** is **done** (this PR). A model works out and sets up what a project
+needs; code makes sure that happens, bounds it and checks the result.
+- Before each driver run on a project, one round trip checks the build VM: the
+  harness's own baseline (missing: the item waits, a template problem), the
+  workspace clone (missing: cloned again, said, and the item resumes from what
+  it pushed) and a per-project marker (`~/.nisse/<project>.ready`).
+- No marker (a new project, a new or wiped VM): the item's driver model runs
+  the preflight first, with its own prompt (the project's toolchain, not the
+  template's basics or tools that act on other systems; never credentials),
+  the execution tools (screened as ever) and `toolchain_ready`. The harness
+  runs each reported version command itself (version-shaped commands only,
+  wherever they come from) and writes the marker. Gaps and an unfinished
+  preflight are facts, and work goes on; the thread hears only of installs and
+  gaps. A rebuilt VM gets the last toolchain as its starting point.
+- Later runs check the versions again; a change is a fact and a thread line,
+  and the PR body says what the work was tested with.
+- A changed host key is its own failure: the item waits for the operator's
+  `trust new host key`, then the VM is set up again.
+- Decided with the operator: the model judges toolchains (the harness can't
+  without it), preflight runs on the driver's model, gaps don't block. Turning
+  off unattended upgrades and the template's baseline are template choices.
+
 ### Phase 5 — Memory
 
 **M5.1 The vault.** *Pre-approved.* The folder, per-agent mounts, control tools,

docs/Tuning-Guide.md

@@ -193,6 +193,26 @@ looking around, not doing the work. Before M2.8 this was
   (escalation is doing its job). Second, how often the local model recovers
   on its own after its second failure (the limit may be too low).
 
+### `tuning.preflight.max_turns` — default 20
+
+How many model calls the toolchain preflight may make (D3). The preflight runs
+before the driver plans, whenever a project's build VM has no marker from a
+finished one: a new project, a new or wiped VM.
+
+- **Too low:** a project with several things to install doesn't finish, and
+  says so; work goes on with what's missing stated, and the next item tries
+  again.
+- **Too high:** a model that can't settle on a toolchain spends its time there
+  instead of on the work.
+- **Deciding:** a project that only needs checking takes 2–4 calls; each
+  install adds one or two.
+
+### `tuning.preflight.command_timeout_s` — default 900
+
+The limit on one command during the preflight, in place of
+`tuning.tools.command_timeout_s`: installing a compiler or a language runtime
+can take minutes. Commands in ordinary runs keep their own, shorter limit.
+
 ### `tuning.expert.consult_budget` — default 3
 
 How many `ask_expert` calls one milestone may make. `ask_expert` is a single