@evident-ai/runner-synchroniser 3.4.1-dev.3e4cb34 → 3.4.1-dev.59c7df3

package/README.md

@@ -75,7 +75,7 @@ saved query.
 
 ### `session-db-classify`
 
-Implementation-facing reference for the 7th command: it decides what a just-run `litestream restore` of `opencode.db` means and, on attempt 2 only, may run a recovery strategy against S3. `packages/runner-image/README.md`'s [Strategy/What/Cost table](../runner-image/README.md#when-the-replica-is-unusable-evident_on_unusable_replica) is the operator-facing view of the same command — this section doesn't restate it.
+Implementation-facing reference for the 7th command: it decides what a just-run `litestream restore` of `opencode.db` means and, on attempt 2 only, may run a recovery strategy against S3. `runner/docker-images/fargate/README.md`'s [Strategy/What/Cost table](../docker-images/fargate/README.md#when-the-replica-is-unusable-evident_on_unusable_replica) is the operator-facing view of the same command — this section doesn't restate it.
 
 #### Activity recovery report
 
@@ -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.
@@ -217,7 +230,7 @@ what it is.
 - **`clear`** — deletes every key under `<prefix>/opencode.db/` passing `isDeletableReplicaKey`; that guard, not the `list()` prefix, is the boundary (IAM grants `s3:DeleteObject*` bucket-wide). One `try` per key. A **partial** clear still reports `recovered`/`32`. Cost: all saved history, unconditionally.
 - **`crash`** — first in the switch, no S3 mutation even considered → `fatal(deliberate)`/`30` → `entrypoint.sh` `die`s → task replaced → **crash loop** until an operator intervenes.
 
-#### The measured real-world key layout (litestream 0.5.13)
+#### The measured real-world key layout (litestream 0.5.13 historical sample)
 
 `parseLtxKey` (`src/replica-keys.ts`) expects
 `<prefix>/opencode.db/<level:04d>/<minTxid>-<maxTxid>.ltx` — **no `ltx/` path segment**,
@@ -235,7 +248,7 @@ at boot the newest L0 is normally *absent* (`noL0Present`) or freshly written an
 (`targetHealthy`) — `prune`'s real-world reach is narrower than the code alone suggests,
 and it can never repair corruption at a higher compaction level.
 
-`EVIDENT_ON_UNUSABLE_REPLICA` is a `packages/runner-image` (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 [runner-image's README](../runner-image/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.
+`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).
@@ -344,8 +357,8 @@ alter the command's exit code.
 
 `src/shell-contract.json` is the machine-checked source of truth for the command list, and
 `shell-contract.test.ts` holds **every** shell that speaks it to it — Fargate's
-`packages/runner-image/entrypoint.sh` and the MicroVM's
-`packages/runner-cdk/microvm-image/hooks` (#608), discovered by grep so a third one
+`runner/docker-images/fargate/entrypoint.sh` and the MicroVM's
+`runner/docker-images/microvm/hooks` (#608), discovered by grep so a third one
 cannot go unchecked. Each shell must: call only subcommands the CLI implements (and, for
 `entrypoint.sh`, call all of them); route every call through one `run_synchroniser`; report
 a broken tool; and take each answer code the commands it calls can return **silently and by
@@ -375,7 +388,7 @@ key, so they never appear in `env`'s output or `litestream.yml`.
 | `CLUSTER` † / `SERVICE` †                 | ECS cluster/service `self-stop` scales to `desiredCount=0`.              | Warns "cannot self-stop" and exits `20` (keep the task). Ignored by every other command. |
 | `EVIDENT_SELFSTOP_ROLE_ARN` †             | Role `self-stop` assumes for its ECS calls.                              | Optional: falls back to the task role's own credentials. A failed/incomplete assume-role → `20`. |
 
-`packages/runner-image/README.md` documents these same three from the deployment side —
+`runner/docker-images/fargate/README.md` documents these same three from the deployment side —
 keep them in sync.
 
 Requiring **both** `LITESTREAM_BUCKET` and `LITESTREAM_PREFIX` (never just one) means