@evident-ai/runner-synchroniser 0.1.0 → 0.1.1-dev.0a5718b

package/README.md

@@ -15,8 +15,10 @@ the boot script gates on. It also renders the `litestream.yml` that covers the s
 database, so both halves read their bucket, prefix and paths from one config module
 instead of two.
 
-It is a CLI, not a library: the runner's `entrypoint.sh` invokes it as a single
-self-contained bundle (`node cli.js <command>`).
+It is a CLI, not a library, invoked by two consumers that differ in how they get the
+binary: the Fargate runner image installs the published package and invokes it by name
+(`runner-synchroniser <command>`); the MicroVM still builds it from source and runs the
+bundle directly (`node cli.js <command>`).
 
 ## Install
 
@@ -30,11 +32,25 @@ npx @evident-ai/runner-synchroniser@dev env
 `dist/cli.js` is a single self-contained ESM bundle with **no runtime dependencies** —
 the AWS SDK is bundled at build time, so installing it pulls nothing else in.
 
-> Publishing is being rolled out (#612). The `dev` tag is published on every merge to
-> `main` that touches this package; the first publish is a human bootstrap (#694), and
-> the `latest`-on-release path is not wired up yet. Nothing in this repo installs the
-> package: the runner image and the MicroVM still build the bundle from source, and will
-> keep doing so until that flip lands.
+### Versioning
+
+The package's version **tracks the product release version**, exactly like
+`@evident-ai/cli`. `latest` is published on a product release, at the release
+version. `dev` is published on every merge to `main` that touches this package or
+the root `package.json`, at `<root major>.<minor>.<patch+1>-dev.<sha>`, so `dev`
+stays strictly ahead of `latest`.
+
+The version committed in this package's `package.json` is **vestigial** — CI
+overwrites it before every publish. This is why `latest` jumped straight from
+`0.1.0` to `3.x.y`: the `0.1.x` line predates the policy, not a missing
+major-version story, and because npm publishes are immutable that jump is
+permanent.
+
+The two consumers still differ in how they get the binary: the Fargate runner
+image installs the published package
+(`ARG RUNNER_SYNCHRONISER_VERSION=dev`, resolved to a concrete version by the
+deploy workflow); the MicroVM still builds it from source and reads no npm
+version at all.
 
 ## Commands
 
@@ -47,9 +63,9 @@ the AWS SDK is bundled at build time, so installing it pulls nothing else in.
 | `model-auth-ready`             | —                                       | `0` = ready, `10` = not ready; other = tool broken       |
 | `self-stop`                    | —                                       | `0` = stopped, `20` = keep the task; other = tool broken |
 
-`self-stop` scales this agent's own ECS service to `desiredCount=0` on a clean idle
-exit, reading `CLUSTER`, `SERVICE` and (optionally) `EVIDENT_SELFSTOP_ROLE_ARN` from the
-environment. It exits `0` **only** on a confirmed `desiredCount` of 0.
+`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`
+**only** on a confirmed `desiredCount` of 0.
 
 Everything the operator needs to read goes to **stderr**, prefixed `[auth-persistence]`,
 so a caller can safely capture stdout. The prefix now covers more than credentials — the
@@ -96,23 +112,28 @@ real violation also rejects correct rewrites.
 
 ## Configuration
 
-All configuration is environment variables, resolved once in `src/config.ts`.
+Configuration is environment variables; `src/config.ts` resolves the shared paths, keys
+and settings below once for every command. The three variables marked † are read
+directly by `self-stop` instead — they configure that one command, not a shared path or
+key, so they never appear in `env`'s output or `litestream.yml`.
+
+| Variable                                  | Meaning                                                                   | When absent                                                                        |
+| ------------------------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `HOME`                                    | Every credential and database path is derived from it.                   | Throws; logged `FATAL:`, exits `1`. Affects every command.                        |
+| `LITESTREAM_BUCKET` / `LITESTREAM_PREFIX` | Object-store bucket and key prefix.                                       | Persistence off (needs **both**): `restore`/`sync-once` no-op, `env` warns.       |
+| `AWS_REGION`                              | Region for the AWS clients (S3, and the ECS/STS calls `self-stop` makes). | Left to the SDK's own resolution.                                                 |
+| `CREDS_SYNC_INTERVAL`                     | Seconds between sync ticks, reported by `env` for the caller's loop.     | Falls back to `60`; also on unparseable or non-positive values.                   |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`    | Presence alone counts as configured model auth (see `model-auth-ready`). | No API-key fallback; `model-auth-ready` then depends solely on the credential files. |
+| `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`. |
 
-| Variable                               | Meaning                                                                                      |
-| -------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `HOME`                                 | **Required.** Every credential and database path is derived from it; unset is a fatal error. |
-| `LITESTREAM_BUCKET`                    | Object-store bucket.                                                                         |
-| `LITESTREAM_PREFIX`                    | Key prefix within the bucket.                                                                |
-| `AWS_REGION`                           | Region for the S3 client. Unset leaves it to the SDK's own resolution.                       |
-| `CREDS_SYNC_INTERVAL`                  | Seconds between sync ticks, reported by `env` for the caller's loop. Defaults to `60`.       |
-| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | Presence alone counts as configured model auth (see `model-auth-ready`).                     |
+`packages/runner-image/README.md` documents these same three from the deployment side —
+keep them in sync.
 
-**Persistence is enabled only when both `LITESTREAM_BUCKET` and `LITESTREAM_PREFIX` are
-set.** With either missing, `restore` and `sync-once` become no-ops and `env` warns
-loudly that credentials will be lost when the task is replaced — half a location can
-never produce a malformed key.
+Requiring **both** `LITESTREAM_BUCKET` and `LITESTREAM_PREFIX` (never just one) means
+half a location can never produce a malformed key.
 
-The paths and keys that follow from that:
+The paths and keys that follow from the bucket/prefix:
 
 | Store       | Local path                                | Object key                          |
 | ----------- | ----------------------------------------- | ----------------------------------- |
@@ -121,7 +142,7 @@ The paths and keys that follow from that:
 | 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.
 
@@ -171,10 +192,11 @@ pnpm lint
 
 From the repository root, prefix with `pnpm --filter @evident-ai/runner-synchroniser`.
 
-The bundle must stay a **single file**: the runner image copies exactly one artifact out
-of its builder stage, so code splitting would ship a `cli.js` importing chunks that are
-not there. `tsup.config.ts` disables splitting and bundles the AWS SDK, and the
-Dockerfile asserts the output is one file.
+The bundle must stay a **single file**: both consumers need a self-contained
+`dist/cli.js` with no sibling chunks — the npm `files: ["dist"]` install ships
+whatever `dist` contains, and the MicroVM runs `dist/cli.js` directly with no
+`node_modules` alongside it. `tsup.config.ts` disables splitting and bundles the
+AWS SDK so neither consumer needs anything else.
 
 The restore/sync/CLI tests need neither AWS nor a real filesystem — rather than shimming
 a fake `aws` binary onto `PATH`, they inject two ports: `InMemoryObjectStore` (in

package/dist/cli.js

@@ -39606,6 +39606,87 @@ function describeRestoreOutcome(label, path2, outcome) {
       return assertNever(outcome);
   }
 }
+function assertNeverSessionDb(value) {
+  throw new Error(`Unhandled session-DB restore outcome: ${JSON.stringify(value)}`);
+}
+function assertNeverUnusableReplicaReason(value) {
+  throw new Error(`Unhandled unusable-replica reason: ${JSON.stringify(value)}`);
+}
+function assertNeverFatalCause(value) {
+  throw new Error(`Unhandled fatal cause: ${JSON.stringify(value)}`);
+}
+function sessionDbExitCode(outcome) {
+  switch (outcome.kind) {
+    case "disabled":
+    case "restored":
+    case "noReplica":
+      return 0;
+    case "retryTransient":
+    case "recovered":
+      return 32;
+    // re-run `litestream restore` and ask again
+    case "unusableReplica":
+      return 31;
+    // booted with a fresh DB; the shell must skip `litestream replicate`
+    case "fatal":
+      return 30;
+    // shared by a genuine misconfig and a deliberate `crash` choice
+    default:
+      return assertNeverSessionDb(outcome);
+  }
+}
+function describeUnusableReplica(reason) {
+  const base = "SESSION-DB-REPLICA-UNUSABLE: booting with a FRESH opencode.db; prior session history is lost until the replica is fixed.";
+  switch (reason) {
+    case "strategy":
+      return `${base} (--on-unusable-replica=leave was selected; nothing in S3 was touched.)`;
+    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.)`;
+    case "recoveryFailed":
+      return `${base} (the recovery delete itself failed; see the warning above for the S3 error.)`;
+    case "targetHealthy":
+      return `${base} (--on-unusable-replica=prune found a newest L0 object but could not confirm it is corrupt \u2014 it either passed the LTX structural check or could not be re-read \u2014 so it declined to delete it; nothing in S3 was touched.)`;
+    default:
+      return assertNeverUnusableReplicaReason(reason);
+  }
+}
+function describeSessionDbFatal(outcome, config) {
+  switch (outcome.cause) {
+    // Names the bucket/region and the probe error — never the crash flag.
+    case "misconfig":
+      return `FATAL: could not verify the opencode.db replica in S3 is reachable/authorised (bucket=${config.bucket ?? "<unset>"}, region=${config.region ?? "<unset>"}): ${outcome.detail}`;
+    // Names the flag and states nothing was touched — never bucket/region, so an
+    // operator reading this is never sent chasing IAM over their own flag.
+    case "deliberate":
+      return `FATAL: ${outcome.detail}`;
+    default:
+      return assertNeverFatalCause(outcome.cause);
+  }
+}
+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.";
+    case "noReplica":
+      return "No opencode.db replica found in the object store; opencode will create a fresh session DB.";
+    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(", ")})`;
+      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":
+      return describeUnusableReplica(outcome.reason);
+    case "fatal":
+      return describeSessionDbFatal(outcome, config);
+    default:
+      return assertNeverSessionDb(outcome);
+  }
+}
 
 // src/file-ops.ts
 init_esm_shims();
@@ -39708,6 +39789,48 @@ async function modelAuthReady(config, fileOps) {
   return config.hasModelApiKey;
 }
 
+// src/replica-keys.ts
+init_esm_shims();
+var DEFAULT_UNUSABLE_REPLICA_STRATEGY = "prune";
+var STRATEGIES = ["prune", "leave", "clear", "crash"];
+function parseUnusableReplicaStrategy(value) {
+  if (value === void 0) return DEFAULT_UNUSABLE_REPLICA_STRATEGY;
+  return STRATEGIES.includes(value) ? value : null;
+}
+function replicaDbPrefix(prefix) {
+  return `${prefix}/opencode.db/`;
+}
+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/`;
+  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;
+  const match = LTX_FILENAME.exec(filename);
+  if (!match) return null;
+  return {
+    level: Number.parseInt(levelPart, 10),
+    minTxid: BigInt(`0x${match[1]}`),
+    maxTxid: BigInt(`0x${match[2]}`)
+  };
+}
+function newestL0Key(prefix, keys) {
+  let newest = null;
+  for (const key of keys) {
+    const parsed = parseLtxKey(prefix, key);
+    if (parsed === null || parsed.level !== 0) continue;
+    if (newest === null || parsed.maxTxid > newest.maxTxid) {
+      newest = { key, maxTxid: parsed.maxTxid };
+    }
+  }
+  return newest?.key ?? null;
+}
+function isDeletableReplicaKey(prefix, key) {
+  if (!key.startsWith(replicaDbPrefix(prefix))) return false;
+  return !key.split("/").includes("..");
+}
+
 // src/restore.ts
 init_esm_shims();
 import { dirname as dirname3 } from "path";
@@ -43273,6 +43396,10 @@ var _ep4 = {
   DisableS3ExpressSessionAuth: { type: "staticContextParams", value: true },
   Bucket: { type: "contextParams", name: "Bucket" }
 };
+var _ep8 = {
+  Bucket: { type: "contextParams", name: "Bucket" },
+  Prefix: { type: "contextParams", name: "Prefix" }
+};
 var _mw011 = (Command3, cs, config, o7) => [
   getThrow200ExceptionsPlugin(config)
 ];
@@ -49549,11 +49676,21 @@ var S3Client = class extends Client {
   }
 };
 
+// ../../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$) {
+};
+
 // ../../node_modules/.pnpm/@aws-sdk+client-s3@3.1095.0/node_modules/@aws-sdk/client-s3/dist-es/commands/GetObjectCommand.js
 init_esm_shims();
 var GetObjectCommand = class extends command11(_ep011, _mw7, "GetObject", GetObject$) {
 };
 
+// ../../node_modules/.pnpm/@aws-sdk+client-s3@3.1095.0/node_modules/@aws-sdk/client-s3/dist-es/commands/ListObjectsV2Command.js
+init_esm_shims();
+var ListObjectsV2Command = class extends command11(_ep8, _mw011, "ListObjectsV2", ListObjectsV2$) {
+};
+
 // ../../node_modules/.pnpm/@aws-sdk+client-s3@3.1095.0/node_modules/@aws-sdk/client-s3/dist-es/commands/PutObjectCommand.js
 init_esm_shims();
 var PutObjectCommand = class extends command11(_ep011, _mw11, "PutObject", PutObject$) {
@@ -49588,8 +49725,190 @@ var S3ObjectStore = class {
   async put(key, body) {
     await this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body }));
   }
+  async list(prefix) {
+    const keys = [];
+    let continuationToken;
+    do {
+      const response = await this.client.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: prefix,
+          ContinuationToken: continuationToken
+        })
+      );
+      for (const object of response.Contents ?? []) {
+        if (object.Key) keys.push(object.Key);
+      }
+      continuationToken = response.NextContinuationToken;
+    } while (continuationToken);
+    return keys;
+  }
+  async delete(key) {
+    try {
+      await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+    } catch (error) {
+      if (isNotFound(error)) return;
+      throw error;
+    }
+  }
 };
 
+// src/session-db.ts
+init_esm_shims();
+
+// src/replica-recovery.ts
+init_esm_shims();
+
+// src/ltx-format.ts
+init_esm_shims();
+var LTX_HEADER_SIZE = 100;
+var LTX_MAGIC = "LTX1";
+function isStructurallySoundLtxObject(bytes) {
+  if (bytes.length < LTX_HEADER_SIZE) return false;
+  return bytes.subarray(0, LTX_MAGIC.length).toString("ascii") === LTX_MAGIC;
+}
+
+// src/replica-recovery.ts
+async function probeReplica(store, prefix, log) {
+  const root12 = replicaDbPrefix(prefix);
+  try {
+    const keys = await store.list(root12);
+    return { ok: true, keys };
+  } catch (error) {
+    const detail = describeError(error);
+    log(`WARNING: could not list the replica prefix ${root12}: ${detail}`);
+    return { ok: false, detail };
+  }
+}
+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.`);
+    }
+    return { deleted: null, reason: "layoutMismatch" };
+  }
+  let bytes;
+  try {
+    bytes = await store.get(target);
+  } catch (error) {
+    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" };
+  }
+  if (bytes === null || isStructurallySoundLtxObject(bytes)) {
+    log(
+      `INFO: the newest L0 replica object ${target} ` + (bytes === null ? "is already gone" : "looks structurally sound") + "; declining to prune it without positive evidence it is the corrupt one."
+    );
+    return { deleted: null, reason: "targetHealthy" };
+  }
+  log(`INFO: pruning the newest L0 replica object ${target} (fails the LTX structural check).`);
+  try {
+    await store.delete(target);
+  } catch (error) {
+    log(`WARNING: failed to prune ${target}: ${describeError(error)}`);
+    return { deleted: null, reason: "deleteFailed" };
+  }
+  return { deleted: target };
+}
+async function clearReplica(store, prefix, keys, log) {
+  const deleted = [];
+  const failed = [];
+  for (const key of keys) {
+    if (!isDeletableReplicaKey(prefix, key)) {
+      log(`WARNING: refusing to delete ${key}: outside the replica prefix.`);
+      continue;
+    }
+    try {
+      await store.delete(key);
+      deleted.push(key);
+    } catch (error) {
+      log(`WARNING: failed to delete ${key}: ${describeError(error)}`);
+      failed.push(key);
+    }
+  }
+  return { deleted, failed };
+}
+
+// src/session-db.ts
+function assertNeverStrategy(value) {
+  throw new Error(`Unhandled unusable-replica strategy: ${JSON.stringify(value)}`);
+}
+async function classifySessionDbRestore(params) {
+  const outcome = await decideSessionDbRestore(params);
+  if (outcome.kind === "unusableReplica") {
+    await discardLocalDebris(params.fileOps, params.config.opencodeDbPath, params.log);
+  }
+  return outcome;
+}
+async function decideSessionDbRestore(params) {
+  const { exitCode, attempt, strategy, config, fileOps, store, log } = params;
+  if (config.bucket === null || config.prefix === null) {
+    return { kind: "disabled" };
+  }
+  const prefix = config.prefix;
+  if (exitCode === 0) {
+    const stat2 = await fileOps.stat(config.opencodeDbPath);
+    return stat2 !== null && stat2.size > 0 ? { kind: "restored" } : { kind: "noReplica" };
+  }
+  if (store === null) {
+    return {
+      kind: "fatal",
+      cause: "misconfig",
+      detail: "persistence is enabled (LITESTREAM_BUCKET/LITESTREAM_PREFIX are set) but no object store is available to verify the replica is reachable"
+    };
+  }
+  if (attempt === 1) {
+    return { kind: "retryTransient" };
+  }
+  if (attempt >= 3) {
+    return { kind: "unusableReplica", reason: "attemptsExhausted" };
+  }
+  const probe = await probeReplica(store, prefix, log);
+  if (!probe.ok) {
+    return {
+      kind: "fatal",
+      cause: "misconfig",
+      detail: `could not verify the session-DB replica is reachable: ${probe.detail}`
+    };
+  }
+  const keys = probe.keys;
+  switch (strategy) {
+    case "crash":
+      return {
+        kind: "fatal",
+        cause: "deliberate",
+        detail: "the replica is unusable and --on-unusable-replica=crash was selected; no S3 object was touched"
+      };
+    case "leave":
+      return { kind: "unusableReplica", reason: "strategy" };
+    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 };
+      }
+      return { kind: "recovered", strategy: "prune", deleted: [result.deleted] };
+    }
+    case "clear": {
+      const result = await clearReplica(store, prefix, keys, log);
+      return { kind: "recovered", strategy: "clear", deleted: result.deleted };
+    }
+    default:
+      return assertNeverStrategy(strategy);
+  }
+}
+async function discardLocalDebris(fileOps, dbPath, log) {
+  for (const path2 of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    try {
+      await fileOps.remove(path2);
+    } catch (error) {
+      log(`WARNING: could not remove local session-DB debris at ${path2}: ${describeError(error)}`);
+    }
+  }
+}
+
 // src/self-stop.ts
 init_esm_shims();
 function isComplete(credentials) {
@@ -49666,7 +49985,15 @@ async function selfStop({
 
 // src/shell-contract.json
 var shell_contract_default = {
-  commands: ["env", "litestream-config", "restore", "sync-once", "model-auth-ready", "self-stop"]
+  commands: [
+    "env",
+    "litestream-config",
+    "restore",
+    "sync-once",
+    "model-auth-ready",
+    "self-stop",
+    "session-db-classify"
+  ]
 };
 
 // src/sync.ts
@@ -49718,6 +50045,9 @@ var EXIT_NOT_READY = 10;
 var EXIT_KEEP_TASK = 20;
 var EXIT_USAGE = 2;
 var EXIT_BROKEN = 1;
+var EXIT_SESSION_DB_FATAL = 30;
+var EXIT_SESSION_DB_UNUSABLE = 31;
+var EXIT_SESSION_DB_RETRY = 32;
 var STATE_SUFFIX = ".synchash";
 var COMMANDS = shell_contract_default.commands;
 var USAGE = `Usage: runner-synchroniser <command> [args]
@@ -49729,6 +50059,12 @@ var USAGE = `Usage: runner-synchroniser <command> [args]
   model-auth-ready             exit 0 when some model auth is configured, ${EXIT_NOT_READY} when not
   self-stop                    scale this agent's own ECS service to 0; exit 0 only
                                when desiredCount is confirmed 0, ${EXIT_KEEP_TASK} to keep the task
+  session-db-classify <litestream-restore-exit-code> <attempt>
+                               [--on-unusable-replica=<prune|leave|clear|crash>]
+                               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
 `;
 function shellQuote(value) {
   return `'${value.replaceAll("'", `'\\''`)}'`;
@@ -49742,11 +50078,39 @@ function awsSelfStopAccessFor(config) {
 function parseStoreName(value) {
   return value === "claude" || value === "opencode" ? value : null;
 }
+var ON_UNUSABLE_REPLICA_FLAG = "--on-unusable-replica=";
+function parseNonNegativeInt(value) {
+  return /^\d+$/.test(value) ? Number.parseInt(value, 10) : null;
+}
+function parseSessionDbClassifyArgs(args) {
+  let strategyRaw;
+  const positional = [];
+  for (const arg of args) {
+    if (arg.startsWith(ON_UNUSABLE_REPLICA_FLAG)) {
+      if (strategyRaw !== void 0) return null;
+      strategyRaw = arg.slice(ON_UNUSABLE_REPLICA_FLAG.length);
+    } else if (arg.startsWith("--")) {
+      return null;
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length !== 2) return null;
+  const exitCode = parseNonNegativeInt(positional[0]);
+  const attempt = parseNonNegativeInt(positional[1]);
+  const strategy = parseUnusableReplicaStrategy(strategyRaw);
+  if (exitCode === null || attempt === null || attempt < 1 || strategy === null) return null;
+  return { exitCode, attempt, strategy };
+}
 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))}`
@@ -49812,6 +50176,20 @@ async function commandSyncOnce(name, config, deps) {
     await writeLastHash(fileOps, statePath, result.hash, log);
   }
 }
+async function commandSessionDbClassify(args, config, deps) {
+  const { fileOps, log } = deps;
+  const outcome = await classifySessionDbRestore({
+    exitCode: args.exitCode,
+    attempt: args.attempt,
+    strategy: args.strategy,
+    config: { bucket: config.bucket, prefix: config.prefix, opencodeDbPath: config.opencodeDbPath },
+    fileOps,
+    store: (deps.objectStoreFor ?? s3ObjectStoreFor)(config),
+    log
+  });
+  log(describeSessionDbClassification(outcome, { bucket: config.bucket, region: config.region }));
+  return sessionDbExitCode(outcome);
+}
 async function main(argv, deps) {
   const { env: env3, fileOps, log, out } = deps;
   const [command12, ...rest] = argv;
@@ -49847,6 +50225,17 @@ ${USAGE}`);
     });
     return stopped ? 0 : EXIT_KEEP_TASK;
   }
+  if (command12 === "session-db-classify") {
+    const args = parseSessionDbClassifyArgs(rest);
+    if (args === null) {
+      log(
+        `'session-db-classify' needs <litestream-restore-exit-code> <attempt> and an optional --on-unusable-replica=<prune|leave|clear|crash>.
+${USAGE}`
+      );
+      return EXIT_USAGE;
+    }
+    return commandSessionDbClassify(args, config, deps);
+  }
   const name = parseStoreName(rest[0]);
   if (name === null) {
     log(`'${command12}' needs a store name: claude or opencode.
@@ -49886,6 +50275,9 @@ export {
   EXIT_BROKEN,
   EXIT_KEEP_TASK,
   EXIT_NOT_READY,
+  EXIT_SESSION_DB_FATAL,
+  EXIT_SESSION_DB_RETRY,
+  EXIT_SESSION_DB_UNUSABLE,
   EXIT_USAGE,
   main
 };

package/package.json

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