TASK-729: walk runner writes a machine-readable pass/fail

docs/runbooks/first-user-walk.md

@@ -77,6 +77,37 @@ cleanup reports `account <username>` as a survivor and the manifest is
 never holds the email. Only a run that dies before its manifest write (before
 signup starts) leaves nothing to find, and that case needs no purge.
 
+## Result file (what SRE reads)
+
+Every run, including one that fails before its first step, overwrites
+`~/.commonly/state/walk-729/result.json` (override with `COMMONLY_WALK_RESULT`).
+Write is atomic (temp file, then rename), so a reader never sees a half file.
+
+```json
+{
+  "schema": 1,
+  "sha": "<deployed sha from WALK_SHA, or null when the scheduler did not set it>",
+  "startedAt": "...", "finishedAt": "...",
+  "base": "https://api.commonly.me", "mode": "signup",
+  "walk": "walk-<stamp>",
+  "overall": "pass | fail | incomplete",
+  "exitCode": 0,
+  "steps": [{ "name": "signup", "result": "pass | fail | not-covered", "ms": 0, "reason": "only when not pass" }],
+  "cleanup": { "ok": true, "status": "clean | needs-admin-purge | not-run", "survivors": [] }
+}
+```
+
+- The result is written at the end of a run. A run killed midway leaves the previous file, so check `finishedAt`.
+- `overall` and the exit code agree: `pass` = `0`, `fail` = `1`, `incomplete` = `2`.
+- `incomplete` means every covered step passed and a step is not covered yet
+  (Bring your own connect). Today every full run is `incomplete`, never `pass`,
+  until that step is built. Roll back on `fail` only; treat `incomplete` as
+  not-green but not as a regression.
+- `mode` is `signup` or `signin`, or `not-chosen` when the run was refused before a mode was accepted (no request was made).
+- `cleanup.status` is `not-run` (and `ok` null) when the run stopped before cleanup could start, for example a refused mode.
+- The file holds no password, token or email. A `needs-admin-purge` cleanup
+  points SRE at the manifest in `~/.commonly/state/walk-706/`.
+
 ## Daily schedule
 
 The CTO schedules the run on the host (launchd) and posts the result to the