@evident-ai/runner-synchroniser 0.1.1-dev.9639f77 → 0.1.1-dev.9d0282a

package/README.md

@@ -62,6 +62,7 @@ version at all.
 | `sync-once <claude\|opencode>` | —                                       | `0` = ran; non-zero = 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>]` | — | `0` = restored/no-replica/disabled, `32` = re-run and ask again, `31` = unusable (booted fresh, starts a fresh backup chain), `30` = fatal; other = usage/tool broken |
 
 `self-stop` scales this agent's own ECS service to `desiredCount=0` on a clean idle exit
 (see Configuration for `CLUSTER`/`SERVICE`/`EVIDENT_SELFSTOP_ROLE_ARN`). It exits `0`
@@ -74,6 +75,156 @@ broader: `src/logger.ts` marks it verbatim because operator greps and CloudWatch
 match on that exact string, so widening what it labels is cheaper than breaking every
 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.
+
+#### Positionals
+
+| Positional                       | Meaning                                                                                                                                |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `<litestream-restore-exit-code>` | Status of the `litestream restore` the shell just ran. `0` → stat the local DB; any non-zero → the recovery ladder below. The value itself is never inspected (a Go panic `2` is treated exactly like a `1`). |
+| `<attempt>`                      | 1-based (`/^\d+$/`, `>= 1`) — the sole mutation gate.                                                                                    |
+
+#### The attempt ladder
+
+| Attempt | Behaviour                                                     |
+| ------- | ---------------------------------------------------------------- |
+| 1       | Plain retry — **zero S3 calls, not even the probe**.              |
+| 2       | The **only** attempt that may probe or mutate S3.                 |
+| ≥ 3     | Gives up **before** the probe.                                    |
+
+`entrypoint.sh` caps its retry loop at a hard-coded `3` as a real second bound: the classifier is stateless per invocation, so nothing except that loop stops attempt 2 from being asked twice.
+
+#### `--on-unusable-replica` flag syntax
+
+- Only the `=`-joined form (`--on-unusable-replica=leave`); the space-separated form is rejected.
+- Position-free.
+- Repeating the flag is rejected, even with the same value both times.
+- Any other `--` token is rejected.
+- Every rejection exits `2` (`EXIT_USAGE`) with the usage message — **never** a silent fall-back to the destructive default.
+
+#### Outcome → exit code
+
+| Outcome                                        | Code | When                                                                        |
+| ----------------------------------------------- | ---- | -------------------------------------------------------------------------------- |
+| `disabled`                                      | `0`  | bucket or prefix unset — short-circuits **before** the exit code is examined     |
+| `restored`                                      | `0`  | restore exit `0` and the local DB is non-empty                                   |
+| `noReplica`                                     | `0`  | restore exit `0` but the DB is absent or zero-byte                               |
+| `retryTransient`                                | `32` | restore failed, attempt 1 — no probe, no S3 call at all                          |
+| `recovered`                                     | `32` | attempt 2, a successful `prune` (1 key) or any `clear` (including a partial one)  |
+| `unusableReplica(strategy)`                     | `31` | attempt 2, `leave`                                                                |
+| `unusableReplica(attemptsExhausted)`            | `31` | attempt ≥ 3, before the probe                                                     |
+| `unusableReplica(targetHealthy)`                | `31` | attempt 2, `prune`; the newest L0 isn't provably corrupt AND the escalation declined (unreadable, or nothing parses) |
+| `unusableReplica(noL0Present)`                  | `31` | attempt 2, `prune`; the prefix is **empty**, so there is nothing to prune and nothing to quarantine |
+| `unusableReplica(layoutMismatch)`               | `31` | attempt 2, `prune`; objects exist under the prefix but **none** parse as an LTX key at all — **a bug**, see below |
+| `unusableReplica(recoveryFailed)`               | `31` | attempt 2, `prune`'s delete itself threw, or the quarantine escalation moved nothing |
+| `recovered(quarantine)`                         | `32` | attempt 2, `prune` found nothing at L0 but the damage is deeper: the replica was moved aside |
+| `fatal(misconfig)`                              | `30` | no object store while persistence is enabled, or the probe failed on attempt 2   |
+| `fatal(deliberate)`                             | `30` | attempt 2, `crash`                                                                |
+
+`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.
+
+#### Boot size signals
+
+Two markers report the numbers a boot already computes but used to throw away (#1113):
+
+| Marker | Emitted from | When it fires | Fields |
+| --- | --- | --- | --- |
+| `SESSION-DB-SIZE` | `describeSessionDbClassification` (`diagnostics.ts`) | Once per `session-db-classify` invocation that reaches `restored` or `noReplica` — i.e. every boot where the restore exit code was `0`. `disabled` and every non-zero-exit outcome (`retryTransient`, `recovered`, `unusableReplica`, `fatal`) never `stat` the local DB, so they emit no size. | `state` (`restored`\|`empty`\|`absent`), `bytes` |
+| `SESSION-DB-REPLICA-SIZE` | `probeReplica` (`replica-recovery.ts`), its `ok` branch | Only on attempt 2's probe, i.e. only after a **failed** first restore — see the caveat below. | `objects`, `bytes` |
+
+**Format convention:** `<MARKER>: <prose> <k>=<v> … bytes=<n>`, with the machine-readable
+fields appended at the end of the line and `bytes` always last:
+
+```
+SESSION-DB-SIZE: <prose> state=<restored|empty|absent> bytes=<n>
+SESSION-DB-REPLICA-SIZE: <prose> objects=<m> bytes=<n>
+```
+
+Numbers go last because a CloudWatch Logs Insights `parse` capture needs a **literal
+delimiter after every capture except the final one**, which runs to end of line — free
+prose after a capture would make the pattern ambiguous. `diagnostics.test.ts` and
+`replica-recovery.test.ts` each pin a line matching `/ (state=\w+ )?bytes=\d+$/`, so an
+edit that appends prose after the number breaks a test rather than silently breaking an
+operator's saved query.
+
+**Logs Insights queries** (copy-pasteable, and the reason the format above is fixed):
+
+Session-DB size distribution across the fleet:
+
+```
+fields @timestamp, @message
+| parse @message "SESSION-DB-SIZE: * state=* bytes=*" as dbProse, dbState, dbBytes
+| filter ispresent(dbBytes)
+| stats count(*) as boots,
+        avg(dbBytes) as avgBytes,
+        pct(dbBytes, 50) as p50Bytes,
+        pct(dbBytes, 95) as p95Bytes,
+        max(dbBytes) as maxBytes
+  by bin(1d)
+| sort @timestamp desc
+```
+
+Growth curve, and how many boots restored nothing:
+
+```
+fields @timestamp, @message
+| parse @message "SESSION-DB-SIZE: * state=* bytes=*" as dbProse, dbState, dbBytes
+| filter ispresent(dbState)
+| stats count(*) as boots, max(dbBytes) as maxBytes by dbState, bin(1d)
+```
+
+Replica size + object count (ECS, failed-first-restore boots only — see the caveat below):
+
+```
+fields @timestamp, @message
+| parse @message "SESSION-DB-REPLICA-SIZE: * objects=* bytes=*" as replicaProse, replicaObjects, replicaBytes
+| filter ispresent(replicaBytes)
+| stats max(replicaBytes) as maxReplicaBytes, max(replicaObjects) as maxObjects by bin(1d)
+```
+
+**Caveat: the two markers have very different fleet coverage.** `SESSION-DB-SIZE` fires
+on **every healthy boot on both runtimes** and is the fleet-wide growth-curve signal.
+`SESSION-DB-REPLICA-SIZE` fires **only** on ECS's attempt 2 — i.e. only when a first
+restore already failed — and essentially never on the MicroVM, whose hook hard-codes the
+classify attempt to `1` (`common.sh:352`), which never reaches the probe. Chart
+`SESSION-DB-SIZE` for growth; treat `SESSION-DB-REPLICA-SIZE` as a diagnostic for
+failed-restore boots only, or an empty series will look like a broken signal instead of
+what it is.
+
+#### The four `--on-unusable-replica` strategies
+
+- **`prune` (default)** — ≤1 guarded delete iff the newest L0's own bytes fail the LTX header check (`length >= 100` and magic `"LTX1"`) → `recovered`/`32`; a failed delete (`recoveryFailed`) or a declined escalation → `31`. **Header-only** check: a valid header with deeper corruption is judged sound and left alone by the *delete* — and since #1106 that is no longer the end of the road. When prune finds nothing to delete (`targetHealthy`/`noL0Present`) **and** at least one key parses as an LTX object, it **escalates to quarantine**: every object under `<prefix>/opencode.db/` is moved to `<prefix>/quarantine/opencode.db/<timestamp>/` → `recovered(quarantine)`/`32`. It does **not** escalate on `layoutMismatch` (we don't understand the layout), on an unreadable object (absent evidence), or on an empty prefix. Never prunes twice.
+- **`leave`** — zero S3 mutation → `31`. Cost is "prior history lost this boot". Since #1106 it is **not** also ephemeral: the boot still starts a fresh backup chain, because the classifier guarantees the local DB is fresh rather than half-restored. Upside: replica left byte-intact for forensics, no crash loop.
+- **`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)
+
+`parseLtxKey` (`src/replica-keys.ts`) expects
+`<prefix>/opencode.db/<level:04d>/<minTxid>-<maxTxid>.ltx` — **no `ltx/` path segment**,
+despite litestream.io's generic docs prose suggesting otherwise (that mismatch was
+#1081: every real key failed to parse, silently disabling `prune` in production).
+Verbatim key sampled live from the production replica:
+`agents/e5d866ac-b699-4940-b369-633b25f8b601/opencode.db/0000/000000000001a978-000000000001a978.ltx`.
+Levels observed on that replica: `0000`/`0001`/`0002`/`0003`/`0009`. The zero-padding is
+an observation, not a contract — `parseLtxKey` accepts an unpadded level directory too.
+
+**L0 objects are short-lived.** litestream's own startup log measured a level-0
+retention of **5 minutes** (`starting L0 retention monitor interval=15s retention=5m0s`;
+compaction runs L1=30s, L2=5m, L3=1h, L9=24h). litestream expires L0 objects itself, so
+at boot the newest L0 is normally *absent* (`noL0Present`) or freshly written and sound
+(`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` 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).
+
 ### Why the contract is asymmetric
 
 `restore` and `sync-once` **never** report a domain outcome through the exit code. A
@@ -97,6 +248,8 @@ that it has no auth. `self-stop` decides whether a task may go away, so a broken
 must never kill one: `entrypoint.sh` reads any non-zero exactly like `20` and keeps the
 task, and only a `0` — returned solely on a confirmed `desiredCount` of 0 — lets it stop.
 
+`session-db-classify` is neither a domain outcome nor a predicate — it's a **third category**: a typed classification with four actionable answers (`0` ran, `32` retry, `31` unusable, `30` fatal), numbered above the two predicates' codes so they can't collide with a future one (`cli.ts:42-47`; see `diagnostics.ts`'s `sessionDbExitCode` for the single outcome → code mapping). The fail-safe direction inverts here: the two predicates above treat an unexpected code as the *safe* answer, but `entrypoint.sh` treats an unexpected code from `session-db-classify` as **fatal** (it `die`s) — correctly, because a boot that can't classify its own replica must not guess about deleting S3 objects.
+
 `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
@@ -142,10 +295,23 @@ The paths and keys that follow from the bucket/prefix:
 | OpenCode DB | `$HOME/.local/share/opencode/opencode.db` | `<prefix>/opencode.db` (litestream) |
 
 The session database is replicated by litestream itself; this package only generates its
-config. `env` emits `CREDS_BUCKET`, `CLAUDE_CREDS`, `OPENCODE_DB_PATH` and
+config. `env` emits `PERSISTENCE_BUCKET`, `CLAUDE_CREDS`, `OPENCODE_DB_PATH` and
 `CREDS_SYNC_INTERVAL`, each single-quoted so a value containing shell metacharacters is
 inert when `eval`'d.
 
+`entrypoint.sh` asserts, right after it `eval`s this output, that each key is *defined*
+(not merely non-empty) and splits the four into two groups: a key is **required** — the
+shell dies naming it — if it has no safe degradation; it is **tolerated** — the shell logs
+a WARNING naming it and carries on — if it does. `OPENCODE_DB_PATH` and
+`CREDS_SYNC_INTERVAL` are required: both are dereferenced for real work (deleting/creating
+the session DB, sizing the sync-loop sleep), so a guessed value would be actively wrong,
+not merely absent. `PERSISTENCE_BUCKET` and `CLAUDE_CREDS` are tolerated: an empty
+`PERSISTENCE_BUCKET` is already the designed "persistence disabled" state, and
+`CLAUDE_CREDS` is dereferenced only in operator-facing message text. If you change
+`renderEnv` to make a required key conditional, the entrypoint will brick every container
+running that version — the runner installs this package from a floating npm tag (`dev` /
+`latest`), so the shell and the CLI can genuinely be different versions (#779, #821).
+
 ## Behaviour worth knowing
 
 - **A non-empty local file that is not valid JSON is protected**, never overwritten and
@@ -170,11 +336,15 @@ inert when `eval`'d.
 
 ## The `ObjectStore` port
 
-`restore` and `sync` talk to a two-method interface — `get(key)` returning `null` when
-the object is absent, and `put(key, body)`. S3 vocabulary (`@aws-sdk/client-s3`, the
-typed `NoSuchKey`/`NotFound` errors) is confined to the single adapter in
+`restore`/`sync` and `session-db-classify` talk to a four-method interface: `get(key)`
+returning `null` when the object is absent, `put(key, body)`, `list(prefix)` and
+`delete(key)` for session-DB recovery. `list(prefix)` returns `{ key, size }` entries
+(`ObjectSummary[]`) — every object under `prefix`, size in bytes. It throws on any error
+and never maps one to `[]` (an empty array means "reached the store, nothing there"); the
+adapter owns pagination, and `delete` is idempotent. S3 vocabulary (`@aws-sdk/client-s3`,
+the typed `NoSuchKey`/`NotFound` errors) is confined to the single adapter in
 `src/s3-object-store.ts`, so the storage backend can be swapped without touching the
-restore/sync logic.
+restore/sync/classify logic.
 
 The S3 adapter is the only one that exists. It uses no static credentials — auth is
 whatever the ambient AWS credential chain resolves (on the Evident runner, the ECS task

package/dist/cli.js

@@ -39615,6 +39615,9 @@ function assertNeverUnusableReplicaReason(value) {
 function assertNeverFatalCause(value) {
   throw new Error(`Unhandled fatal cause: ${JSON.stringify(value)}`);
 }
+function assertNeverNoReplicaLocalDb(value) {
+  throw new Error(`Unhandled noReplica local-DB state: ${JSON.stringify(value)}`);
+}
 function sessionDbExitCode(outcome) {
   switch (outcome.kind) {
     case "disabled":
@@ -39627,7 +39630,7 @@ function sessionDbExitCode(outcome) {
     // re-run `litestream restore` and ask again
     case "unusableReplica":
       return 31;
-    // booted with a fresh DB; the shell must skip `litestream replicate`
+    // booted with a fresh DB; the shell still starts a fresh backup chain (#1106)
     case "fatal":
       return 30;
     // shared by a genuine misconfig and a deliberate `crash` choice
@@ -39643,7 +39646,9 @@ function describeUnusableReplica(reason) {
     case "attemptsExhausted":
       return `${base} (recovery did not make the replica usable after retrying; giving up.)`;
     case "layoutMismatch":
-      return `${base} (no level-0 LTX object was found under the replica prefix, so --on-unusable-replica=prune had nothing matching its expected layout to delete.)`;
+      return `${base} (objects exist under the replica prefix but NONE of them match the LTX key layout --on-unusable-replica=prune expects \u2014 see the SESSION-DB-REPLICA-LAYOUT-MISMATCH warning above for a sample key. This means our key parsing is wrong, or litestream's on-disk layout changed.)`;
+    case "noL0Present":
+      return `${base} (--on-unusable-replica=prune found no level-0 object to prune. This is expected: litestream expires level-0 objects itself after a few minutes, so at boot the newest one is normally absent. prune only ever targets level 0, so it cannot repair corruption at a higher compaction level.)`;
     case "recoveryFailed":
       return `${base} (the recovery delete itself failed; see the warning above for the S3 error.)`;
     case "targetHealthy":
@@ -39665,18 +39670,31 @@ function describeSessionDbFatal(outcome, config) {
       return assertNeverFatalCause(outcome.cause);
   }
 }
+function describeNoReplica(localDb) {
+  switch (localDb) {
+    case "absent":
+      return "No opencode.db replica found in the object store; opencode will create a fresh session DB.";
+    case "empty":
+      return "litestream restore succeeded but left a zero-byte opencode.db; opencode will create a fresh session DB.";
+    default:
+      return assertNeverNoReplicaLocalDb(localDb);
+  }
+}
 function describeSessionDbClassification(outcome, config) {
   switch (outcome.kind) {
     case "disabled":
       return "No opencode.db restore attempted; credential persistence is disabled (LITESTREAM_BUCKET/LITESTREAM_PREFIX unset).";
     case "restored":
-      return "opencode.db restored from the object store.";
+      return `SESSION-DB-SIZE: opencode.db restored from the object store. state=restored bytes=${outcome.bytes}`;
     case "noReplica":
-      return "No opencode.db replica found in the object store; opencode will create a fresh session DB.";
+      return `SESSION-DB-SIZE: ${describeNoReplica(outcome.localDb)} state=${outcome.localDb} bytes=0`;
     case "retryTransient":
       return "opencode.db replica restore failed (transient); retrying.";
     case "recovered": {
       const objects = outcome.deleted.length === 0 ? "no objects (see the warnings above for what failed)" : `${outcome.deleted.length} object${outcome.deleted.length === 1 ? "" : "s"} (${outcome.deleted.join(", ")})`;
+      if (outcome.strategy === "quarantine") {
+        return `Escalated opencode.db replica recovery to quarantine: --on-unusable-replica=prune found nothing at level 0 to delete, so the corruption is deeper than prune can reach. Moved ${objects} aside; retrying the restore. Prior session history is set aside, NOT deleted \u2014 see the SESSION-DB-REPLICA-QUARANTINED warning above for where.`;
+      }
       return `Attempted opencode.db replica recovery via --on-unusable-replica=${outcome.strategy}, deleting ${objects}; retrying the restore.` + (outcome.strategy === "clear" ? " Prior session history is lost." : "");
     }
     case "unusableReplica":
@@ -39803,7 +39821,7 @@ function replicaDbPrefix(prefix) {
 var LTX_FILENAME = /^([0-9a-fA-F]+)-([0-9a-fA-F]+)\.ltx$/;
 function parseLtxKey(prefix, key) {
   if (key.split("/").includes("..")) return null;
-  const root12 = `${replicaDbPrefix(prefix)}ltx/`;
+  const root12 = replicaDbPrefix(prefix);
   if (!key.startsWith(root12)) return null;
   const [levelPart, filename, ...rest] = key.slice(root12.length).split("/");
   if (rest.length > 0 || filename === void 0 || !/^\d+$/.test(levelPart)) return null;
@@ -39826,6 +39844,9 @@ function newestL0Key(prefix, keys) {
   }
   return newest?.key ?? null;
 }
+function hasParsableLtxKey(prefix, keys) {
+  return keys.some((key) => parseLtxKey(prefix, key) !== null);
+}
 function isDeletableReplicaKey(prefix, key) {
   if (!key.startsWith(replicaDbPrefix(prefix))) return false;
   return !key.split("/").includes("..");
@@ -43392,6 +43413,12 @@ var _ep011 = {
   Bucket: { type: "contextParams", name: "Bucket" },
   Key: { type: "contextParams", name: "Key" }
 };
+var _ep13 = {
+  DisableS3ExpressSessionAuth: { type: "staticContextParams", value: true },
+  Bucket: { type: "contextParams", name: "Bucket" },
+  Key: { type: "contextParams", name: "Key" },
+  CopySource: { type: "contextParams", name: "CopySource" }
+};
 var _ep4 = {
   DisableS3ExpressSessionAuth: { type: "staticContextParams", value: true },
   Bucket: { type: "contextParams", name: "Bucket" }
@@ -43403,6 +43430,10 @@ var _ep8 = {
 var _mw011 = (Command3, cs, config, o7) => [
   getThrow200ExceptionsPlugin(config)
 ];
+var _mw1 = (Command3, cs, config, o7) => [
+  getThrow200ExceptionsPlugin(config),
+  getSsecPlugin(config)
+];
 var _mw7 = (Command3, cs, config, o7) => [
   getFlexibleChecksumsPlugin(config, {
     requestChecksumRequired: false,
@@ -49676,6 +49707,11 @@ var S3Client = class extends Client {
   }
 };
 
+// ../../node_modules/.pnpm/@aws-sdk+client-s3@3.1095.0/node_modules/@aws-sdk/client-s3/dist-es/commands/CopyObjectCommand.js
+init_esm_shims();
+var CopyObjectCommand = class extends command11(_ep13, _mw1, "CopyObject", CopyObject$) {
+};
+
 // ../../node_modules/.pnpm/@aws-sdk+client-s3@3.1095.0/node_modules/@aws-sdk/client-s3/dist-es/commands/DeleteObjectCommand.js
 init_esm_shims();
 var DeleteObjectCommand = class extends command11(_ep011, _mw011, "DeleteObject", DeleteObject$) {
@@ -49726,7 +49762,7 @@ var S3ObjectStore = class {
     await this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body }));
   }
   async list(prefix) {
-    const keys = [];
+    const objects = [];
     let continuationToken;
     do {
       const response = await this.client.send(
@@ -49737,11 +49773,11 @@ var S3ObjectStore = class {
         })
       );
       for (const object of response.Contents ?? []) {
-        if (object.Key) keys.push(object.Key);
+        if (object.Key) objects.push({ key: object.Key, size: object.Size ?? 0 });
       }
       continuationToken = response.NextContinuationToken;
     } while (continuationToken);
-    return keys;
+    return objects;
   }
   async delete(key) {
     try {
@@ -49751,6 +49787,30 @@ var S3ObjectStore = class {
       throw error;
     }
   }
+  /**
+   * `CopyObject` — S3 copies the bytes server-side, so a 545 MB snapshot never
+   * enters this process (see `ObjectStore.copy`).
+   *
+   * `CopySource` is `<bucket>/<key>` and S3 expects it URL-encoded. `encodeURI`
+   * (not `encodeURIComponent`) is the right one here: it leaves the `/`
+   * separators intact, which S3 needs, while still escaping anything exotic.
+   * Every key this is called with has already passed `isDeletableReplicaKey`,
+   * so it is `<prefix>/opencode.db/…` with no `..` segment and no `%` to
+   * double-encode.
+   *
+   * Deliberately does NOT swallow a not-found the way `delete` does: the only
+   * caller deletes the source immediately afterwards, so a copy that quietly
+   * did nothing would destroy the object it was meant to preserve.
+   */
+  async copy(fromKey, toKey) {
+    await this.client.send(
+      new CopyObjectCommand({
+        Bucket: this.bucket,
+        CopySource: encodeURI(`${this.bucket}/${fromKey}`),
+        Key: toKey
+      })
+    );
+  }
 };
 
 // src/session-db.ts
@@ -49772,20 +49832,38 @@ function isStructurallySoundLtxObject(bytes) {
 async function probeReplica(store, prefix, log) {
   const root12 = replicaDbPrefix(prefix);
   try {
-    const keys = await store.list(root12);
-    return { ok: true, keys };
+    const objects = await store.list(root12);
+    const objectCount = objects.length;
+    const totalBytes = objects.reduce((sum, object) => sum + object.size, 0);
+    logReplicaSize(root12, objectCount, totalBytes, log);
+    return { ok: true, keys: objects.map((object) => object.key) };
   } catch (error) {
     const detail = describeError(error);
     log(`WARNING: could not list the replica prefix ${root12}: ${detail}`);
     return { ok: false, detail };
   }
 }
+function logReplicaSize(root12, objectCount, totalBytes, log) {
+  log(
+    `INFO: SESSION-DB-REPLICA-SIZE: the opencode.db replica under ${root12} objects=${objectCount} bytes=${totalBytes}`
+  );
+}
+function logLayoutMismatch(prefix, keys, log) {
+  log(
+    `WARNING: SESSION-DB-REPLICA-LAYOUT-MISMATCH: listed ${keys.length} object(s) under the replica prefix ${replicaDbPrefix(prefix)} but none of them match the expected LTX key layout (<prefix>/opencode.db/<level>/<minTxid>-<maxTxid>.ltx). Sample key: ${keys[0]}. --on-unusable-replica=prune cannot select anything to delete until this is fixed.`
+  );
+}
 async function pruneNewestL0(store, prefix, keys, log) {
   const target = newestL0Key(prefix, keys);
-  if (target === null || !isDeletableReplicaKey(prefix, target)) {
-    if (target !== null) {
-      log(`WARNING: refusing to prune ${target}: failed the replica-key guard.`);
+  if (target === null) {
+    if (keys.length > 0 && !hasParsableLtxKey(prefix, keys)) {
+      logLayoutMismatch(prefix, keys, log);
+      return { deleted: null, reason: "layoutMismatch" };
     }
+    return { deleted: null, reason: "noL0Present" };
+  }
+  if (!isDeletableReplicaKey(prefix, target)) {
+    log(`WARNING: refusing to prune ${target}: failed the replica-key guard.`);
     return { deleted: null, reason: "layoutMismatch" };
   }
   let bytes;
@@ -49795,7 +49873,7 @@ async function pruneNewestL0(store, prefix, keys, log) {
     log(
       `WARNING: could not re-read ${target} to check whether it is actually corrupt before pruning it: ${describeError(error)}. Declining to prune without positive evidence.`
     );
-    return { deleted: null, reason: "targetHealthy" };
+    return { deleted: null, reason: "unreadable" };
   }
   if (bytes === null || isStructurallySoundLtxObject(bytes)) {
     log(
@@ -49812,6 +49890,48 @@ async function pruneNewestL0(store, prefix, keys, log) {
   }
   return { deleted: target };
 }
+function quarantineRoot(prefix, stamp) {
+  return `${prefix}/quarantine/opencode.db/${stamp}/`;
+}
+async function quarantineReplica(store, prefix, keys, log, stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")) {
+  const destination = quarantineRoot(prefix, stamp);
+  const root12 = replicaDbPrefix(prefix);
+  const moved = [];
+  const failed = [];
+  for (const key of keys) {
+    if (!isDeletableReplicaKey(prefix, key)) {
+      log(`WARNING: refusing to quarantine ${key}: outside the replica prefix.`);
+      continue;
+    }
+    const target = `${destination}${key.slice(root12.length)}`;
+    try {
+      await store.copy(key, target);
+    } catch (error) {
+      log(
+        `WARNING: could not copy ${key} to ${target}: ${describeError(error)}. Leaving the original in place \u2014 never deleting an object the quarantine did not preserve.`
+      );
+      failed.push(key);
+      continue;
+    }
+    try {
+      await store.delete(key);
+    } catch (error) {
+      log(
+        `WARNING: quarantined ${key} to ${target} but could not delete the original: ${describeError(error)}`
+      );
+      failed.push(key);
+      continue;
+    }
+    moved.push(key);
+  }
+  logQuarantined(destination, moved, failed, log);
+  return { destination, moved, failed };
+}
+function logQuarantined(destination, moved, failed, log) {
+  log(
+    `WARNING: SESSION-DB-REPLICA-QUARANTINED: moved ${moved.length} unusable replica object(s) aside to ${destination} (${failed.length} could not be moved) so this boot can start a fresh backup chain. The bytes are NOT deleted \u2014 copy them back from there to investigate. See SESSION-DB-REPLICA-SIZE above for how much was set aside.`
+  );
+}
 async function clearReplica(store, prefix, keys, log) {
   const deleted = [];
   const failed = [];
@@ -49850,7 +49970,7 @@ async function decideSessionDbRestore(params) {
   const prefix = config.prefix;
   if (exitCode === 0) {
     const stat2 = await fileOps.stat(config.opencodeDbPath);
-    return stat2 !== null && stat2.size > 0 ? { kind: "restored" } : { kind: "noReplica" };
+    return stat2 !== null && stat2.size > 0 ? { kind: "restored", bytes: stat2.size } : { kind: "noReplica", localDb: stat2 === null ? "absent" : "empty" };
   }
   if (store === null) {
     return {
@@ -49886,8 +50006,20 @@ async function decideSessionDbRestore(params) {
     case "prune": {
       const result = await pruneNewestL0(store, prefix, keys, log);
       if (result.deleted === null) {
-        const reason = result.reason === "deleteFailed" ? "recoveryFailed" : result.reason;
-        return { kind: "unusableReplica", reason };
+        if (shouldEscalateToQuarantine(result.reason, prefix, keys)) {
+          const quarantined = await quarantineReplica(store, prefix, keys, log);
+          if (quarantined.moved.length === 0) {
+            return { kind: "unusableReplica", reason: "recoveryFailed" };
+          }
+          return { kind: "recovered", strategy: "quarantine", deleted: quarantined.moved };
+        }
+        if (result.reason === "deleteFailed") {
+          return { kind: "unusableReplica", reason: "recoveryFailed" };
+        }
+        if (result.reason === "unreadable") {
+          return { kind: "unusableReplica", reason: "targetHealthy" };
+        }
+        return { kind: "unusableReplica", reason: result.reason };
       }
       return { kind: "recovered", strategy: "prune", deleted: [result.deleted] };
     }
@@ -49899,6 +50031,10 @@ async function decideSessionDbRestore(params) {
       return assertNeverStrategy(strategy);
   }
 }
+function shouldEscalateToQuarantine(reason, prefix, keys) {
+  if (reason !== "targetHealthy" && reason !== "noL0Present") return false;
+  return hasParsableLtxKey(prefix, keys);
+}
 async function discardLocalDebris(fileOps, dbPath, log) {
   for (const path2 of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
     try {
@@ -50064,7 +50200,7 @@ var USAGE = `Usage: runner-synchroniser <command> [args]
                                classify a just-run \`litestream restore\` of opencode.db;
                                exit 0 restored/no-replica/disabled, ${EXIT_SESSION_DB_RETRY} re-run
                                and ask again, ${EXIT_SESSION_DB_UNUSABLE} unusable (booted fresh,
-                               skip replicate), ${EXIT_SESSION_DB_FATAL} fatal
+                               fresh backup chain), ${EXIT_SESSION_DB_FATAL} fatal
 `;
 function shellQuote(value) {
   return `'${value.replaceAll("'", `'\\''`)}'`;
@@ -50104,9 +50240,13 @@ function parseSessionDbClassifyArgs(args) {
 }
 function renderEnv(config) {
   return [
-    // Empty when persistence is disabled — entrypoint.sh gates the sync loop
-    // on this being non-empty, exactly as it did when it computed it itself.
-    `CREDS_BUCKET=${shellQuote(config.bucket ?? "")}`,
+    // The bucket NAME, kept (not reduced to a boolean) so an operator can
+    // read it; empty exactly when persistence is disabled (both
+    // LITESTREAM_BUCKET and LITESTREAM_PREFIX must be set — see config.ts's
+    // persistenceEnabled). entrypoint.sh gates BOTH the credential-sync
+    // loop and whether it starts litestream replicate on this being
+    // non-empty.
+    `PERSISTENCE_BUCKET=${shellQuote(config.bucket ?? "")}`,
     `CLAUDE_CREDS=${shellQuote(config.claude.path)}`,
     `OPENCODE_DB_PATH=${shellQuote(config.opencodeDbPath)}`,
     `CREDS_SYNC_INTERVAL=${shellQuote(String(config.syncIntervalSeconds))}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-synchroniser",
-  "version": "0.1.1-dev.9639f77",
+  "version": "0.1.1-dev.9d0282a",
   "description": "Restores and syncs the Evident runner's OpenCode credential stores (and litestream config) to an object store, so a runner survives task replacement with almost no state loss.",
   "type": "module",
   "main": "./dist/cli.js",