@evident-ai/runner-synchroniser 3.4.1-dev.9d58811 → 3.4.1-dev.b2ce99d

package/README.md

@@ -56,7 +56,7 @@ build time.
 | `env`                          | resolved config as shell-eval'able vars | `0` = ran; non-zero = tool broken                        |
 | `litestream-config`            | the generated `litestream.yml`          | `0` = ran; non-zero = tool broken                        |
 | `restore <claude\|opencode>`   | —                                       | `0` = ran; non-zero = tool broken                        |
-| `sync-once <claude\|opencode>` | —                                       | `0` = ran; non-zero = tool broken                        |
+| `sync-once <claude\|opencode>` | —                                       | `0` = uploaded/unchanged/absent/disabled; `40` = not persisted; other = tool broken |
 | `model-auth-ready`             | —                                       | `0` = ready, `10` = not ready; other = tool broken       |
 | `self-stop`                    | —                                       | `0` = stopped, `20` = keep the task; other = tool broken |
 | `session-db-classify <litestream-restore-exit-code> <attempt> [--on-unusable-replica=<prune\|leave\|clear\|crash>] [--recovery-occurred] [--fresh-db-fallback]` | — | `0` = restored/no-replica/disabled, `32` = re-run and ask again, `31` = unusable (booted fresh, replicates into the existing prefix), `30` = fatal; other = usage/tool broken |
@@ -86,6 +86,13 @@ a warning `restore_retried` record before the retry's result is known. Writing i
 and never changes this command's exit code. The CLI reader owns this record contract: add a new
 `v` rather than repurposing a field.
 
+MicroVM boot-shell give-ups use that same JSONL contract and path. The hook truncates the
+report at the start of each `/run`, so a later startup decision supersedes an earlier one;
+`/resume` preserves the current report. Their `replication_suspended` field is `true`, meaning
+that start is not backing up its new session history. The normal mapper defaults the field to
+`false`; the MicroVM `--fresh-db-fallback` outcome is also `true` because it cannot safely
+replicate that boot.
+
 #### Positionals
 
 | Positional                       | Meaning                                                                                                                                |
@@ -119,6 +126,9 @@ marks a runtime that intentionally has no retry budget and will therefore boot f
 otherwise-transient failure. Each flag may appear once, does not change the command's exit code,
 and is rejected when repeated.
 
+On the MicroVM's one-attempt path, `--fresh-db-fallback` also means the fresh database does not
+replicate during that boot.
+
 #### Outcome → exit code
 
 | Outcome                                        | Code | When                                                                        |
@@ -138,6 +148,9 @@ and is rejected when repeated.
 | `fatal(misconfig)`                              | `30` | no object store while persistence is enabled, or the probe failed on attempt 2   |
 | `fatal(deliberate)`                             | `30` | attempt 2, `crash`                                                                |
 
+Fatal exit codes 30 and 34 are reported directly to `POST /v1/runners/self/startup-failure`
+before the CLI starts. Reporting is best-effort and never changes the exit code.
+
 `31` also guarantees local debris (`opencode.db`, `-wal`, `-shm`) is discarded, one `try` per path, at the classifier's single return point. Note `32` isn't purely "transient" — `recovered` shares it with `retryTransient` even though a `recovered` outcome already mutated S3.
 
 The probe is a `list`, not a `get`: S3 answers a wrong bucket name with `NoSuchBucket`, also a 404, so a `get`-based probe would read a misconfigured bucket as healthy and unlock recovery against it.
@@ -237,8 +250,7 @@ and it can never repair corruption at a higher compaction level.
 
 `EVIDENT_ON_UNUSABLE_REPLICA` is a `runner/docker-images/fargate` (entrypoint) variable translated into the flag above at boot — this CLI never reads it, so it has no row in this README's Configuration table below; see [the Fargate image README](../docker-images/fargate/README.md#when-the-replica-is-unusable-evident_on_unusable_replica). An unrecognised value (including wrong casing, e.g. `Prune`) exits `2`, outside `entrypoint.sh`'s `0|10|20|30|31|32|33` allow-list — a typo **crash-loops the task on attempt 1** rather than falling back to `prune`, and also logs the misleading "credential persistence is DEGRADED" ERROR.
 
-See `specs/local-runner.feature`'s "Recovering session history at startup" scenarios for
-the behavioural anchor (31 comes online, 30 does not).
+The behavioural anchor is explicit: **31 comes online, 30 does not**.
 
 ### `session-db-verify`
 
@@ -314,15 +326,16 @@ same way it already reuses `SESSION-DB-REPLICA-UNUSABLE` for `session-db-classif
 
 ### Why the contract is asymmetric
 
-`restore` and `sync-once` **never** report a domain outcome through the exit code. A
-missing remote object, a corrupt local file, a failed upload, an IAM denial — all of
-those are logged and still exit `0`. None of them should abort a boot: a runner with no
-credentials yet is a runner a human can still log into.
+`restore` logs domain outcomes and still exits `0`: a missing remote object or a
+restore failure should not abort a boot, because a runner with no credentials yet
+is a runner a human can still log into. `sync-once` returns `40` when the current
+credential file is not persisted (`failed`, `hashFailed`, or `localInvalid`), while
+`absent` and `disabled` remain legitimate `0` outcomes.
 
-The consequence is the point: **any non-zero status from `restore`/`sync-once` means the
-tool itself broke** — bad arguments (`2`), an uncaught throw (`1`), or a bundle that
-would not run at all. The shell needs no case analysis to know something is wrong, so
-its "credential persistence is DEGRADED" error lives in exactly one helper.
+The consequence is the point: **any non-zero status from `restore` means the tool itself
+broke** — and `sync-once` uses `40` for its typed persistence answer; other non-zero
+statuses still mean bad arguments (`2`), an uncaught throw (`1`), or a bundle that would
+not run at all. The shell keeps that distinction in one helper.
 
 The **two predicates** — `model-auth-ready` and `self-stop` — each need to distinguish
 "the answer is no" from "the tool is broken", so each answers no with its own dedicated