@evident-ai/runner-synchroniser 0.1.1-dev.96bc2ed → 0.1.1-dev.a63323f

package/README.md

@@ -115,7 +115,9 @@ Implementation-facing reference for the 7th command: it decides what a just-run
 | `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\|layoutMismatch)` | `31` | attempt 2, `prune` declined to delete anything                                   |
+| `unusableReplica(targetHealthy)`                | `31` | attempt 2, `prune`; the newest L0 isn't provably corrupt, so it declined to delete it |
+| `unusableReplica(noL0Present)`                  | `31` | attempt 2, `prune`; no level-0 object was present to prune — **normal**, see below |
+| `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                                         |
 | `fatal(misconfig)`                              | `30` | no object store while persistence is enabled, or the probe failed on attempt 2   |
 | `fatal(deliberate)`                             | `30` | attempt 2, `crash`                                                                |
@@ -126,14 +128,33 @@ The probe is a `list`, not a `get`: S3 answers a wrong bucket name with `NoSuchB
 
 #### 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`; declined (`targetHealthy`/`layoutMismatch`) or a failed delete (`recoveryFailed`) → `31`. **Header-only** check: a valid header with deeper corruption is judged sound and left alone — the real trade-off, and **not** "can destroy a healthy L0 object when an older one is corrupt" (false of merged `main`: the delete is unreachable unless the object's own bytes fail the check). `targetHealthy` also covers an unreadable object (absent evidence must not unlock a delete). Never escalates to `clear`, never prunes twice.
+- **`prune` (default)** — ≤1 guarded delete iff the newest L0's own bytes fail the LTX header check (`length >= 100` and magic `"LTX1"`) → `recovered`/`32`; declined (`targetHealthy`/`noL0Present`/`layoutMismatch`) or a failed delete (`recoveryFailed`) → `31`. **Header-only** check: a valid header with deeper corruption is judged sound and left alone — the real trade-off, and **not** "can destroy a healthy L0 object when an older one is corrupt" (false of merged `main`: the delete is unreachable unless the object's own bytes fail the check). `targetHealthy` also covers an unreadable object (absent evidence must not unlock a delete). Never escalates to `clear`, never prunes twice.
 - **`leave`** — zero S3 mutation → `31`. Cost is not just "prior history lost": `entrypoint.sh` also skips `litestream replicate` for the **whole boot**, so this boot's history is ephemeral too. 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:49-70` for the behavioural anchor (31 comes online, 30 does not).
+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
 

package/dist/cli.js

@@ -39643,7 +39643,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":
@@ -39803,7 +39805,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 +39828,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("..");
@@ -49780,12 +49785,22 @@ async function probeReplica(store, prefix, log) {
     return { ok: false, detail };
   }
 }
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-synchroniser",
-  "version": "0.1.1-dev.96bc2ed",
+  "version": "0.1.1-dev.a63323f",
   "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",