@evident-ai/runner-synchroniser 3.5.2-dev.43244a2 → 3.5.2-dev.4f7b3ac

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` = uploaded/unchanged/absent/disabled; `40` = not persisted; other = tool broken |
+| `sync-once <claude\|opencode>` | —                                       | `0` = uploaded (per-runner) or published/adopted/unchanged/absent/disabled (shared vault); `40` = not persisted this tick; 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 |
@@ -278,8 +278,13 @@ nothing had ever run a real `PRAGMA integrity_check`).
    then the prefix is re-listed as empty before the corrupt local DB and sidecars are
    discarded. Only both proofs permit a fresh boot. Otherwise exit `34` stops the boot before
    OpenCode or Litestream starts; the backup history remains readable at its quarantine
-    destination or original key, and surviving local files remain in place without a process
-    opening or writing them.
+   destination or original key, and surviving local files remain in place without a process
+   opening or writing them.
+
+Each restore-point listing and each individual candidate restore has its own hard timeout.
+Replica separation also has a wall-clock budget. When that budget expires, the synchroniser
+reports the number moved and remaining, leaves the active prefix unverified, and exits `34`;
+the next refused start can continue moving the remaining prefix.
 
 A walked-back boot keeps replicating into the **same** replica — no S3 mutation, no new
 prefix. litestream re-bases to the replica's high-water mark and continues the txid
@@ -311,6 +316,7 @@ before looking at everything" would report the wrong conclusion to the operator.
 | `WARNING: SESSION-DB-INTEGRITY-FAILED` | `verifySessionDb` (`session-db-verify.ts`) | The local DB fails its check, before the walkback starts | — (prose carries the PRAGMA's own detail) |
 | `WARNING: SESSION-DB-WALKBACK-ENUMERATION-FAILED` | the walkback loop (`session-db-verify.ts`) | `litestream ltx` exited non-zero (prose carries its stderr — missing binary, bad `-config`, S3 error) or answered with a listing that could not be parsed | — (prose carries litestream's own stderr) |
 | `WARNING: SESSION-DB-WALKBACK-CANDIDATE-FAILED` | the walkback loop (`session-db-verify.ts`) | A candidate restore point fails to restore, or restores but also fails its own check | `txid` |
+| `WARNING: SESSION-DB-REPLICA-QUARANTINED` | `quarantineReplica` (`replica-recovery.ts`) | A corrupt replica is moved aside, whether the move finishes or its disposal budget stops it early | `moved`, `remaining`, quarantine destination |
 | `INFO: SESSION-DB-WALKBACK-ADOPTED` | `adopt` (`session-db-verify.ts`) | A candidate passes and is adopted over `opencode.db` | `txid`, `candidates`, `bytes` |
 | `SESSION-DB-INTEGRITY` | `describeSessionDbVerification` (`diagnostics.ts`), logged once per invocation as the final outcome | The local DB passed its check as-is | `bytes` |
 | `SESSION-DB-INTEGRITY-WALKBACK` | `describeSessionDbVerification` (`diagnostics.ts`), logged once per invocation as the final outcome | Same event as `SESSION-DB-WALKBACK-ADOPTED` above, restated as the command's outcome | `txid`, `candidates`, `bytes` |
@@ -318,19 +324,45 @@ before looking at everything" would report the wrong conclusion to the operator.
 | `SESSION-DB-REPLICA-SEPARATED` | `separateCorruptReplica` (`replica-recovery.ts`) | The active prefix was re-listed empty after separation | replica root and quarantine destination |
 | `SESSION-DB-REPLICA-SEPARATION-UNVERIFIED` | `separateCorruptReplica` (`replica-recovery.ts`) | A separation could not be proven | remaining objects or list error |
 | `SESSION-DB-LOCAL-DISCARD-FAILED` | `verifySessionDb` (`session-db-verify.ts`) | The local DB or a sidecar could not be proven gone | removed and surviving paths |
-
-The first four fire only while the walkback loop runs; the last three are always the
-one message this command logs as its own final word on the outcome — `entrypoint.sh`
-reuses `SESSION-DB-INTEGRITY-EXHAUSTED` verbatim when it logs its own `33` handling, the
-same way it already reuses `SESSION-DB-REPLICA-UNUSABLE` for `session-db-classify`'s `31`.
+| `SESSION-DB-VERIFY-TIMEOUT` | the boot wrapper around `session-db-verify` | Verification did not finish before its outer deadline; the message says whether corruption was already proven and whether separation had started | timeout and refusal reason |
+
+The walkback markers describe each attempt and its progress. The final outcome markers
+describe whether the active prefix and local files were proven safe; `entrypoint.sh` reuses
+`SESSION-DB-INTEGRITY-EXHAUSTED` verbatim when it logs its own `33` handling, the same way it
+already reuses `SESSION-DB-REPLICA-UNUSABLE` for `session-db-classify`'s `31`. The CLI wrapper
+emits `SESSION-DB-VERIFY-TIMEOUT` when the outer verification deadline is reached.
+
+#### Refused verification outcomes
+
+The recovery report records `replica_separation_unproven` when separation did not prove the
+active prefix empty, `local_discard_failed` when local session-database files could not be
+proven removed, `verification_timeout_before_separation` when verification timed out after
+integrity failure but before replica separation began, and
+`verification_timeout_during_separation` when the timeout occurred after separation had
+started. The timeout reasons point to `SESSION-DB-VERIFY-TIMEOUT` and do not claim that
+objects were removed.
+
+On a refused boot, wait while the reported `remaining` count falls: each start moves another
+bounded slice and the runner comes online after the active prefix drains. If it stops falling,
+move or delete the objects under `<prefix>/opencode.db/` manually; the next start then uses a
+fresh session database. Set-aside history remains at
+`<prefix>/quarantine/opencode.db/<stamp>/`, with one stamp for each start that moved anything.
+Do not use `EVIDENT_ON_UNUSABLE_REPLICA` for this case; that variable controls the earlier
+restore-failure classification path, not post-restore verification.
+
+A store too large for one candidate restore to finish inside
+`EVIDENT_SESSION_DB_RESTORE_CANDIDATE_TIMEOUT_SECONDS` is refused and drained rather than
+adopting an older restore point.
 
 ### Why the contract is asymmetric
 
 `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.
+credential file is not persisted. In per-runner mode, that means `failed`, `hashFailed`,
+or `localInvalid`; in shared-vault mode it also includes `remoteFailed`, `remoteInvalid`,
+`noEtag`, `contended`, and `adoptFailed`. `published` (created or replaced), `adopted`,
+`unchanged`, `absent`, and `disabled` are legitimate `0` outcomes.
 
 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
@@ -379,10 +411,14 @@ key, so they never appear in `env`'s output or `litestream.yml`.
 | ------------------------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
 | `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.       |
+| `CREDENTIAL_VAULT_PREFIX`                 | Shared prefix for both credential objects; it does not redirect the session database. | Unset or blank: use this runner's `LITESTREAM_PREFIX`; ignored when persistence is disabled. |
 | `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.                   |
 | `EVIDENT_SESSION_DB_WALKBACK_MAX_POINTS`  | Distinct restore points `session-db-verify`'s walkback will try before giving up. | Falls back to `10`; also on unparseable or non-positive values.                   |
 | `EVIDENT_SESSION_DB_WALKBACK_BUDGET_SECONDS` | Wall-clock budget, in seconds, for the whole walkback loop.           | Falls back to `180`; also on unparseable or non-positive values.                  |
+| `EVIDENT_SESSION_DB_RESTORE_POINTS_TIMEOUT_SECONDS` | Hard timeout, in seconds, for one `litestream ltx` restore-point listing. | Falls back to `120`; also on unparseable or non-positive values.                  |
+| `EVIDENT_SESSION_DB_RESTORE_CANDIDATE_TIMEOUT_SECONDS` | Hard timeout, in seconds, for each individual `litestream restore` walkback candidate. | Falls back to `300`; also on unparseable or non-positive values.                  |
+| `EVIDENT_SESSION_DB_DISPOSAL_BUDGET_SECONDS` | Wall-clock budget, in seconds, for moving a corrupt replica aside. | Falls back to `900`; also on unparseable or non-positive values.                  |
 | `EVIDENT_SESSION_DB_RECOVERY_REPORT` | JSONL report drained once into runner activity after authentication. | `$HOME/.local/state/evident/session-db-recovery.jsonl`; blank values use the default. |
 | `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. |
@@ -402,6 +438,11 @@ The paths and keys that follow from the bucket/prefix:
 | OpenCode    | `$HOME/.local/share/opencode/auth.json`   | `<prefix>/opencode/auth.json`       |
 | OpenCode DB | `$HOME/.local/share/opencode/opencode.db` | `<prefix>/opencode.db` (litestream) |
 
+When persistence is enabled and `CREDENTIAL_VAULT_PREFIX` is set, both credential keys
+use that shared prefix instead of `<prefix>`. The OpenCode database continues replicating
+under `LITESTREAM_PREFIX`; the vault prefix only redirects the two credential objects. The
+Evident CLI resolves this value from the runner's vault binding.
+
 The session database is replicated by litestream itself; this package only generates its
 config. `env` emits `PERSISTENCE_BUCKET`, `CLAUDE_CREDS`, `OPENCODE_DB_PATH` and
 `CREDS_SYNC_INTERVAL`, each single-quoted so a value containing shell metacharacters is
@@ -435,18 +476,44 @@ running that version — the runner installs this package from a floating npm ta
 - **Nothing throws out of `restore`/`sync`.** `sync-once` runs on an unsupervised timer,
   where an unguarded failure would silently stop persisting credentials for the rest of
   the task's life. Failures degrade to a warning and are retried on the next tick.
-- **`sync-once` uploads only on change.** Each store's last uploaded hash (a sha256, not
-  the credentials) is kept in a state file next to it, so every invocation is a
-  self-contained process.
+- **Per-runner `sync-once` uploads only on change.** Its last uploaded hash (a sha256, not
+  the credentials) is kept in a state file next to the credential file, so every invocation
+  is a self-contained process.
+- **Shared-vault mode is two-way and conditional.** `sync-once` adopts a changed shared
+  credential or publishes a locally changed one with a conditional write. A writer that
+  loses the race adopts the winner instead of overwriting it. A `40` exit is an expected
+  "not persisted this tick" result, not a broken tool; the polling loop accepts it and
+  retries on the next tick.
 - **Not-found is distinguished from failed.** A missing object is reported as "nothing to
   restore"; an access or network error is reported as a failure, because that tells the
   operator their persisted credentials may still be recoverable.
 
+### Shared-vault log markers
+
+In shared-vault mode, these markers identify the synchronization result without logging
+credential bytes. Hash values are short prefixes and ETags remain opaque:
+
+| Marker | Meaning |
+| ------ | ------- |
+| `VAULT-MODE` | Both credential stores use the shared vault prefix. |
+| `VAULT-PUBLISHED` | A credential was created in, or conditionally replaced in, the vault. |
+| `VAULT-ADOPTED` | A valid vault credential was installed locally. |
+| `VAULT-CONTENDED` | Another writer won the conditional write, so this runner is adopting its result. |
+| `VAULT-CONTENDED-UNRESOLVED` | The winning object could not be read; the next tick will retry. |
+| `VAULT-REMOTE-INVALID` | The vault object was not valid JSON and was either replaced or left untouched. |
+| `VAULT-REMOTE-UNREADABLE` | The vault read failed; the next tick will retry. |
+| `VAULT-NO-ETAG` | Publication was skipped because a remote object had no ETag. |
+| `VAULT-ADOPT-FAILED` | A valid vault credential could not be installed locally; the next tick will retry. |
+
 ## The `ObjectStore` port
 
-`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
+The `ObjectStore` port has seven methods. `get(key)` returns `{ body, etag }` or `null`
+when the object is absent; `etag` is an opaque compare-and-swap token and may be `null`
+when the store did not report one. `put(key, body)` is the unconditional write used by
+per-runner synchronization. `putIfAbsent(key, body)` creates with a conditional
+`If-None-Match: *` write, and `putIfMatch(key, body, etag)` replaces with a conditional
+`If-Match: <etag>` write. Both return `'written'` or `'conflict'`; only contention
+returns `'conflict'`, while every other error throws. `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`,

package/dist/cli.js

@@ -50887,6 +50887,9 @@ init_esm_shims();
 var DEFAULT_SYNC_INTERVAL_SECONDS = 60;
 var DEFAULT_WALKBACK_MAX_POINTS = 10;
 var DEFAULT_WALKBACK_BUDGET_SECONDS = 180;
+var DEFAULT_RESTORE_POINTS_TIMEOUT_SECONDS = 120;
+var DEFAULT_RESTORE_CANDIDATE_TIMEOUT_SECONDS = 300;
+var DEFAULT_DISPOSAL_BUDGET_SECONDS = 900;
 function positiveIntOr(value, defaultValue) {
   const parsed = Number.parseInt(value ?? "", 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
@@ -50903,22 +50906,24 @@ function resolveConfig(env4) {
   const bucket = nonEmpty(env4.LITESTREAM_BUCKET);
   const prefix = nonEmpty(env4.LITESTREAM_PREFIX);
   const persistenceEnabled = bucket !== null && prefix !== null;
+  const vaultPrefix = persistenceEnabled ? nonEmpty(env4.CREDENTIAL_VAULT_PREFIX)?.replace(/\/+$/, "") || null : null;
   return {
     homeDir,
     claude: {
       label: "Claude",
       path: `${homeDir}/.claude/.credentials.json`,
-      key: persistenceEnabled ? `${prefix}/claude/credentials.json` : null
+      key: persistenceEnabled ? `${vaultPrefix ?? prefix}/claude/credentials.json` : null
     },
     opencode: {
       label: "OpenCode",
       path: `${homeDir}/.local/share/opencode/auth.json`,
-      key: persistenceEnabled ? `${prefix}/opencode/auth.json` : null
+      key: persistenceEnabled ? `${vaultPrefix ?? prefix}/opencode/auth.json` : null
     },
     opencodeDbPath: `${homeDir}/.local/share/opencode/opencode.db`,
     sessionDbRecoveryReportPath: nonEmpty(env4.EVIDENT_SESSION_DB_RECOVERY_REPORT) ?? `${homeDir}/.local/state/evident/session-db-recovery.jsonl`,
     bucket: persistenceEnabled ? bucket : null,
     prefix: persistenceEnabled ? prefix : null,
+    vaultPrefix,
     region: nonEmpty(env4.AWS_REGION),
     syncIntervalSeconds: positiveIntOr(env4.CREDS_SYNC_INTERVAL, DEFAULT_SYNC_INTERVAL_SECONDS),
     walkbackMaxPoints: positiveIntOr(
@@ -50929,6 +50934,18 @@ function resolveConfig(env4) {
       env4.EVIDENT_SESSION_DB_WALKBACK_BUDGET_SECONDS,
       DEFAULT_WALKBACK_BUDGET_SECONDS
     ),
+    restorePointsTimeoutSeconds: positiveIntOr(
+      env4.EVIDENT_SESSION_DB_RESTORE_POINTS_TIMEOUT_SECONDS,
+      DEFAULT_RESTORE_POINTS_TIMEOUT_SECONDS
+    ),
+    restoreCandidateTimeoutSeconds: positiveIntOr(
+      env4.EVIDENT_SESSION_DB_RESTORE_CANDIDATE_TIMEOUT_SECONDS,
+      DEFAULT_RESTORE_CANDIDATE_TIMEOUT_SECONDS
+    ),
+    disposalBudgetSeconds: positiveIntOr(
+      env4.EVIDENT_SESSION_DB_DISPOSAL_BUDGET_SECONDS,
+      DEFAULT_DISPOSAL_BUDGET_SECONDS
+    ),
     hasModelApiKey: nonEmpty(env4.ANTHROPIC_API_KEY) !== null || nonEmpty(env4.OPENAI_API_KEY) !== null,
     runnerKey: nonEmpty(env4.EVIDENT_RUNNER_KEY) ?? nonEmpty(env4.EVIDENT_AGENT_KEY),
     apiUrl: nonEmpty(env4.EVIDENT_API_URL)
@@ -50940,9 +50957,14 @@ function storeOf(config, name) {
 
 // src/diagnostics.ts
 init_esm_shims();
-function assertNever(value) {
-  throw new Error(`Unhandled restore outcome: ${JSON.stringify(value)}`);
+
+// src/assert-never.ts
+init_esm_shims();
+function assertNever(value, subject) {
+  throw new Error(`Unhandled ${subject}: ${JSON.stringify(value)}`);
 }
+
+// src/diagnostics.ts
 function describeRestoreOutcome(label, path, outcome) {
   switch (outcome.kind) {
     case "local":
@@ -50960,21 +50982,9 @@ function describeRestoreOutcome(label, path, outcome) {
     case "disabled":
       return `No ${label} credentials at ${path}; credential persistence is disabled (LITESTREAM_BUCKET/LITESTREAM_PREFIX unset), so nothing could be restored.`;
     default:
-      return assertNever(outcome);
+      return assertNever(outcome, "restore 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 assertNeverNoReplicaLocalDb(value) {
-  throw new Error(`Unhandled noReplica local-DB state: ${JSON.stringify(value)}`);
-}
 function sessionDbExitCode(outcome) {
   switch (outcome.kind) {
     case "disabled":
@@ -50992,7 +51002,7 @@ function sessionDbExitCode(outcome) {
       return 30;
     // shared by a genuine misconfig and a deliberate `crash` choice
     default:
-      return assertNeverSessionDb(outcome);
+      return assertNever(outcome, "session-DB restore outcome");
   }
 }
 function describeUnusableReplica(reason) {
@@ -51011,7 +51021,7 @@ function describeUnusableReplica(reason) {
     case "targetHealthy":
       return `${base2} (--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);
+      return assertNever(reason, "unusable-replica reason");
   }
 }
 function describeSessionDbFatal(outcome, config) {
@@ -51024,7 +51034,7 @@ function describeSessionDbFatal(outcome, config) {
     case "deliberate":
       return `FATAL: ${outcome.detail}`;
     default:
-      return assertNeverFatalCause(outcome.cause);
+      return assertNever(outcome.cause, "fatal cause");
   }
 }
 function describeNoReplica(localDb) {
@@ -51034,7 +51044,7 @@ function describeNoReplica(localDb) {
     case "empty":
       return "litestream restore succeeded but left a zero-byte opencode.db; opencode will create a fresh session DB.";
     default:
-      return assertNeverNoReplicaLocalDb(localDb);
+      return assertNever(localDb, "noReplica local-DB state");
   }
 }
 function describeSessionDbClassification(outcome, config) {
@@ -51059,24 +51069,9 @@ function describeSessionDbClassification(outcome, config) {
     case "fatal":
       return describeSessionDbFatal(outcome, config);
     default:
-      return assertNeverSessionDb(outcome);
+      return assertNever(outcome, "session-DB restore outcome");
   }
 }
-function assertNeverSessionDbVerify(value) {
-  throw new Error(`Unhandled session-DB verify outcome: ${JSON.stringify(value)}`);
-}
-function assertNeverSessionDbVerifySkippedLocalDb(value) {
-  throw new Error(`Unhandled session-DB verify skipped local-DB state: ${JSON.stringify(value)}`);
-}
-function assertNeverSessionDbVerifyExhaustedReason(value) {
-  throw new Error(`Unhandled session-DB verify exhausted reason: ${JSON.stringify(value)}`);
-}
-function assertNeverSessionDbVerifySeparation(value) {
-  throw new Error(`Unhandled session-DB verify separation: ${JSON.stringify(value)}`);
-}
-function assertNeverSessionDbVerifyLocalDb(value) {
-  throw new Error(`Unhandled session-DB verify local-DB disposal: ${JSON.stringify(value)}`);
-}
 function sessionDbVerifyExitCode(outcome) {
   switch (outcome.kind) {
     case "skipped":
@@ -51093,7 +51088,7 @@ function sessionDbVerifyExitCode(outcome) {
         case "unreachable":
           return 34;
         default:
-          return assertNeverSessionDbVerifySeparation(outcome.separation);
+          return assertNever(outcome.separation, "session-DB verify separation");
       }
       switch (outcome.localDb.kind) {
         case "discarded":
@@ -51102,10 +51097,10 @@ function sessionDbVerifyExitCode(outcome) {
         case "discardFailed":
           return 34;
         default:
-          return assertNeverSessionDbVerifyLocalDb(outcome.localDb);
+          return assertNever(outcome.localDb, "session-DB verify local-DB disposal");
       }
     default:
-      return assertNeverSessionDbVerify(outcome);
+      return assertNever(outcome, "session-DB verify outcome");
   }
 }
 function describeSessionDbVerifySkipped(localDb) {
@@ -51115,7 +51110,7 @@ function describeSessionDbVerifySkipped(localDb) {
     case "empty":
       return "opencode.db is zero bytes; nothing to verify at boot.";
     default:
-      return assertNeverSessionDbVerifySkippedLocalDb(localDb);
+      return assertNever(localDb, "session-DB verify skipped local-DB state");
   }
 }
 function describeSessionDbVerifyExhausted(outcome) {
@@ -51135,7 +51130,7 @@ function describeSessionDbVerifyExhausted(outcome) {
       reason = `opencode.db failed its integrity check; the walkback search budget ran out before every retained restore point was tried (${tried}) \u2014 widen it with EVIDENT_SESSION_DB_WALKBACK_MAX_POINTS/EVIDENT_SESSION_DB_WALKBACK_BUDGET_SECONDS if there was more to try`;
       break;
     default:
-      return assertNeverSessionDbVerifyExhaustedReason(outcome.reason);
+      return assertNever(outcome.reason, "session-DB verify exhausted reason");
   }
   let separation;
   switch (outcome.separation.kind) {
@@ -51153,7 +51148,7 @@ function describeSessionDbVerifyExhausted(outcome) {
       separation = ` Boot is stopping because replica separation could not be proven (${outcome.separation.detail}); backup history remains readable at its original key or quarantine destination.`;
       break;
     default:
-      return assertNeverSessionDbVerifySeparation(outcome.separation);
+      return assertNever(outcome.separation, "session-DB verify separation");
   }
   let localDb;
   switch (outcome.localDb.kind) {
@@ -51167,7 +51162,7 @@ function describeSessionDbVerifyExhausted(outcome) {
       localDb = ` Boot is stopping because local disposal could not be proven; removed=${outcome.localDb.removed.join(", ") || "(none)"} survived=${outcome.localDb.survived.join(", ") || "(none)"}. See SESSION-DB-LOCAL-DISCARD-FAILED.`;
       break;
     default:
-      return assertNeverSessionDbVerifyLocalDb(outcome.localDb);
+      return assertNever(outcome.localDb, "session-DB verify local-DB disposal");
   }
   return `SESSION-DB-INTEGRITY-EXHAUSTED: ${reason}.${separation}${localDb}`;
 }
@@ -51182,7 +51177,7 @@ function describeSessionDbVerification(outcome) {
     case "exhausted":
       return describeSessionDbVerifyExhausted(outcome);
     default:
-      return assertNeverSessionDbVerify(outcome);
+      return assertNever(outcome, "session-DB verify outcome");
   }
 }
 
@@ -51261,49 +51256,88 @@ function stderrOf(error) {
   }
   return describeError(error);
 }
+function commandDetail(error, operation4, timeoutSeconds) {
+  if (typeof error === "object" && error !== null) {
+    const processError = error;
+    const signal = typeof processError.signal === "string" ? processError.signal : null;
+    if (processError.killed === true || signal === "SIGKILL") {
+      return `${operation4} timed out after ${timeoutSeconds}s (process killed with ${signal ?? "SIGKILL"})`;
+    }
+  }
+  return stderrOf(error);
+}
 var LitestreamCli = class {
-  constructor(configPath, dbPath) {
+  constructor(configPath, dbPath, timeouts) {
     this.configPath = configPath;
     this.dbPath = dbPath;
+    this.timeouts = timeouts;
   }
   async listRestorePoints() {
     try {
-      const { stdout, stderr } = await execFileAsync("litestream", [
-        "ltx",
-        "-config",
-        this.configPath,
-        // MEASURED: `-level` defaults to 0, which only shows L0 — `all` is
-        // required to see the L1/L2/L9 compaction levels too (plan §2.3).
-        "-level",
-        "all",
-        "-json",
-        this.dbPath
-      ]);
+      const { stdout, stderr } = await execFileAsync(
+        "litestream",
+        [
+          "ltx",
+          "-config",
+          this.configPath,
+          // MEASURED: `-level` defaults to 0, which only shows L0 — `all` is
+          // required to see the L1/L2/L9 compaction levels too (plan §2.3).
+          "-level",
+          "all",
+          "-json",
+          this.dbPath
+        ],
+        {
+          timeout: this.timeouts.restorePointsTimeoutSeconds * 1e3,
+          killSignal: "SIGKILL"
+        }
+      );
       return { stdout, detail: stderr };
     } catch (error) {
-      return { stdout: null, detail: stderrOf(error) };
+      return {
+        stdout: null,
+        detail: commandDetail(
+          error,
+          "litestream restore-point enumeration",
+          this.timeouts.restorePointsTimeoutSeconds
+        )
+      };
     }
   }
   async restoreAt(txid, outputPath) {
     try {
-      const { stderr } = await execFileAsync("litestream", [
-        "restore",
-        "-config",
-        this.configPath,
-        "-txid",
-        txid,
-        // MEASURED: without `-force`, restoring into a path that already
-        // exists exits 1 with "output path already exists and is not
-        // empty" (plan §2.4) — the caller always restores into a scratch
-        // path it just cleared, so overwriting it is always intended.
-        "-force",
-        "-o",
-        outputPath,
-        this.dbPath
-      ]);
+      const { stderr } = await execFileAsync(
+        "litestream",
+        [
+          "restore",
+          "-config",
+          this.configPath,
+          "-txid",
+          txid,
+          // MEASURED: without `-force`, restoring into a path that already
+          // exists exits 1 with "output path already exists and is not
+          // empty" (plan §2.4) — the caller always restores into a scratch
+          // path it just cleared, so overwriting it is always intended.
+          "-force",
+          "-o",
+          outputPath,
+          this.dbPath
+        ],
+        {
+          timeout: this.timeouts.restoreCandidateTimeoutSeconds * 1e3,
+          killSignal: "SIGKILL"
+        }
+      );
       return { ok: true, detail: stderr };
     } catch (error) {
-      return { ok: false, detail: stderrOf(error) };
+      return {
+        ok: false,
+        detail: commandDetail(
+          error,
+          `litestream restore of txid=${txid}`,
+          this.timeouts.restoreCandidateTimeoutSeconds
+        )
+      };
     }
   }
 };
@@ -51339,20 +51373,23 @@ init_esm_shims();
 
 // src/valid-json.ts
 init_esm_shims();
-async function isValidJson(fileOps, path) {
-  let contents;
+function isValidJsonBytes(contents) {
+  if (contents.length === 0) return false;
   try {
-    contents = await fileOps.readFile(path);
+    const value = JSON.parse(contents.toString("utf8"));
+    return value !== null && value !== false;
   } catch {
     return false;
   }
-  if (contents.length === 0) return false;
+}
+async function isValidJson(fileOps, path) {
+  let contents;
   try {
-    const value = JSON.parse(contents.toString("utf8"));
-    return value !== null && value !== false;
+    contents = await fileOps.readFile(path);
   } catch {
     return false;
   }
+  return isValidJsonBytes(contents);
 }
 
 // src/model-auth.ts
@@ -51409,55 +51446,20 @@ function isDeletableReplicaKey(prefix, key) {
 
 // src/restore.ts
 init_esm_shims();
+import { dirname as dirname4 } from "node:path";
+
+// src/credential-install.ts
+init_esm_shims();
 import { dirname as dirname3 } from "node:path";
-async function restore(params) {
-  const { label, path, bucket, key, store, fileOps, log } = params;
+async function installCredentialBytes({
+  label,
+  path,
+  body,
+  source,
+  fileOps,
+  log
+}) {
   const dir = dirname3(path);
-  try {
-    await fileOps.mkdirp(dir);
-  } catch (error) {
-    log(`WARNING: could not create ${label} credential directory ${dir}: ${describeError(error)}`);
-    return { kind: "failed", reason: `could not create ${dir}: ${describeError(error)}` };
-  }
-  try {
-    await fileOps.chmod(dir, 448);
-  } catch (error) {
-    log(
-      `WARNING: could not restrict ${label} credential directory ${dir}: ${describeError(error)}`
-    );
-  }
-  const local = await fileOps.stat(path);
-  if (local !== null && local.size > 0 && !await isValidJson(fileOps, path)) {
-    log(
-      `WARNING: local ${label} credentials at ${path} are invalid or unreadable; keeping them and skipping restore.`
-    );
-    return { kind: "localInvalid" };
-  }
-  if (local !== null && local.size === 0) {
-    log(
-      `Local ${label} credentials at ${path} are empty; will attempt to restore from S3 instead of protecting them.`
-    );
-  }
-  if (await isValidJson(fileOps, path)) {
-    await chmodOrWarn(fileOps, log, path, `local ${label} credentials at ${path}`);
-    log(`Keeping valid local ${label} credentials at ${path}; no restore.`);
-    return { kind: "local" };
-  }
-  if (store === null || bucket === null || key === null) {
-    return { kind: "disabled" };
-  }
-  const location = `s3://${bucket}/${key}`;
-  let body;
-  try {
-    body = await store.get(key);
-  } catch (error) {
-    log(`WARNING: ${label} credentials download failed from ${location}: ${describeError(error)}`);
-    return { kind: "failed", reason: describeError(error) };
-  }
-  if (body === null) {
-    log(`No persisted ${label} credentials at ${location}; nothing to restore.`);
-    return { kind: "missing" };
-  }
   const temp = `${dir}/.credentials.${Math.random().toString(36).slice(2, 8)}`;
   try {
     await fileOps.createExclusive(temp);
@@ -51486,12 +51488,12 @@ async function restore(params) {
     await fileOps.writeFile(temp, body);
   } catch (error) {
     await fileOps.remove(temp);
-    log(`WARNING: ${label} credentials download failed from ${location}: ${describeError(error)}`);
+    log(`WARNING: ${label} credentials download failed from ${source}: ${describeError(error)}`);
     return { kind: "failed", reason: describeError(error) };
   }
   if (!await isValidJson(fileOps, temp)) {
     await fileOps.remove(temp);
-    log(`WARNING: discarded invalid ${label} credentials from ${location}.`);
+    log(`WARNING: discarded invalid ${label} credentials from ${source}.`);
     return { kind: "invalid" };
   }
   try {
@@ -51504,8 +51506,7 @@ async function restore(params) {
     return { kind: "failed", reason: `could not install ${path}: ${describeError(error)}` };
   }
   await chmodOrWarn(fileOps, log, path, `restored ${label} credentials at ${path}`);
-  log(`Restored ${label} credentials from ${location} to ${path}.`);
-  return { kind: "restored" };
+  return { kind: "installed" };
 }
 async function chmodOrWarn(fileOps, log, path, subject) {
   try {
@@ -51515,6 +51516,71 @@ async function chmodOrWarn(fileOps, log, path, subject) {
   }
 }
 
+// src/restore.ts
+async function restore(params) {
+  const { label, path, bucket, key, store, fileOps, log } = params;
+  const dir = dirname4(path);
+  try {
+    await fileOps.mkdirp(dir);
+  } catch (error) {
+    log(`WARNING: could not create ${label} credential directory ${dir}: ${describeError(error)}`);
+    return { kind: "failed", reason: `could not create ${dir}: ${describeError(error)}` };
+  }
+  try {
+    await fileOps.chmod(dir, 448);
+  } catch (error) {
+    log(
+      `WARNING: could not restrict ${label} credential directory ${dir}: ${describeError(error)}`
+    );
+  }
+  const local = await fileOps.stat(path);
+  if (local !== null && local.size > 0 && !await isValidJson(fileOps, path)) {
+    log(
+      `WARNING: local ${label} credentials at ${path} are invalid or unreadable; keeping them and skipping restore.`
+    );
+    return { kind: "localInvalid" };
+  }
+  if (local !== null && local.size === 0) {
+    log(
+      `Local ${label} credentials at ${path} are empty; will attempt to restore from S3 instead of protecting them.`
+    );
+  }
+  if (await isValidJson(fileOps, path)) {
+    await chmodOrWarn(fileOps, log, path, `local ${label} credentials at ${path}`);
+    log(`Keeping valid local ${label} credentials at ${path}; no restore.`);
+    return { kind: "local" };
+  }
+  if (store === null || bucket === null || key === null) {
+    return { kind: "disabled" };
+  }
+  const location = `s3://${bucket}/${key}`;
+  let object;
+  try {
+    object = await store.get(key);
+  } catch (error) {
+    log(`WARNING: ${label} credentials download failed from ${location}: ${describeError(error)}`);
+    return { kind: "failed", reason: describeError(error) };
+  }
+  if (object === null) {
+    log(`No persisted ${label} credentials at ${location}; nothing to restore.`);
+    return { kind: "missing" };
+  }
+  const installation = await installCredentialBytes({
+    label,
+    path,
+    body: object.body,
+    source: location,
+    fileOps,
+    log
+  });
+  if (installation.kind === "installed") {
+    log(`Restored ${label} credentials from ${location} to ${path}.`);
+    return { kind: "restored" };
+  }
+  if (installation.kind === "invalid") return { kind: "invalid" };
+  return { kind: "failed", reason: installation.reason };
+}
+
 // src/s3-object-store.ts
 init_esm_shims();
 
@@ -61293,6 +61359,11 @@ function isNotFound(error) {
   if (candidate.name === "NoSuchKey" || candidate.name === "NotFound") return true;
   return candidate.$metadata?.httpStatusCode === 404;
 }
+function isConditionalConflict(error) {
+  if (typeof error !== "object" || error === null) return false;
+  const candidate = error;
+  return candidate.name === "PreconditionFailed" || candidate.name === "ConditionalRequestConflict" || candidate.$metadata?.httpStatusCode === 412 || candidate.$metadata?.httpStatusCode === 409;
+}
 var S3ObjectStore = class {
   constructor(bucket, region = null, client) {
     this.bucket = bucket;
@@ -61305,7 +61376,10 @@ var S3ObjectStore = class {
         new GetObjectCommand({ Bucket: this.bucket, Key: key })
       );
       if (!response.Body) return null;
-      return Buffer.from(await response.Body.transformToByteArray());
+      return {
+        body: Buffer.from(await response.Body.transformToByteArray()),
+        etag: response.ETag ?? null
+      };
     } catch (error) {
       if (isNotFound(error)) return null;
       throw error;
@@ -61314,6 +61388,38 @@ var S3ObjectStore = class {
   async put(key, body) {
     await this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body }));
   }
+  async putIfAbsent(key, body) {
+    try {
+      await this.client.send(
+        new PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Body: body,
+          IfNoneMatch: "*"
+        })
+      );
+      return "written";
+    } catch (error) {
+      if (isConditionalConflict(error)) return "conflict";
+      throw error;
+    }
+  }
+  async putIfMatch(key, body, etag) {
+    try {
+      await this.client.send(
+        new PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Body: body,
+          IfMatch: etag
+        })
+      );
+      return "written";
+    } catch (error) {
+      if (isConditionalConflict(error) || isNotFound(error)) return "conflict";
+      throw error;
+    }
+  }
   async list(prefix) {
     const objects = [];
     let continuationToken;
@@ -61392,7 +61498,9 @@ async function probeReplica(store, prefix, log) {
     return { ok: true, objects };
   } catch (error) {
     const detail = describeError(error);
-    log(`WARNING: could not list the replica prefix ${root12}: ${detail}`);
+    log(
+      `WARNING: SESSION-DB-REPLICA-SEPARATION-UNVERIFIED: could not list the replica prefix ${root12}: ${detail}`
+    );
     return { ok: false, detail };
   }
 }
@@ -61421,7 +61529,8 @@ async function pruneNewestL0(store, prefix, keys, log) {
   }
   let bytes;
   try {
-    bytes = await store.get(target);
+    const object = await store.get(target);
+    bytes = object === null ? null : object.body;
   } 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.`
@@ -61446,13 +61555,15 @@ async function pruneNewestL0(store, prefix, keys, log) {
 function quarantineRoot(prefix, stamp) {
   return `${prefix}/quarantine/opencode.db/${stamp}/`;
 }
-async function quarantineReplica(store, prefix, objects, log, stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")) {
+async function quarantineReplica(store, prefix, objects, log, stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-"), budgetSeconds = DEFAULT_DISPOSAL_BUDGET_SECONDS, now = Date.now) {
   const destination = quarantineRoot(prefix, stamp);
   const root12 = replicaDbPrefix(prefix);
   const moved = [];
   const failed = [];
   let movedBytes = 0;
+  const deadline = now() + budgetSeconds * 1e3;
   for (const object of objects) {
+    if (now() >= deadline) break;
     const { key } = object;
     if (!isDeletableReplicaKey(prefix, key)) {
       log(`WARNING: refusing to quarantine ${key}: outside the replica prefix.`);
@@ -61480,15 +61591,15 @@ async function quarantineReplica(store, prefix, objects, log, stamp = (/* @__PUR
     moved.push(key);
     movedBytes += object.size;
   }
-  logQuarantined(destination, moved, failed, log);
+  logQuarantined(destination, moved, failed, objects.length - moved.length, log);
   return { destination, moved, failed, movedBytes };
 }
-function logQuarantined(destination, moved, failed, log) {
+function logQuarantined(destination, moved, failed, remaining, log) {
   log(
-    `WARNING: SESSION-DB-REPLICA-QUARANTINED: moved ${moved.length} unusable replica object(s) aside to ${destination} (${failed.length} could not be moved). Moved history remains readable at that destination; failed moves remain at their original keys.` + (failed.length > 0 ? " The active replica prefix is not clear." : "") + `See SESSION-DB-REPLICA-SIZE above for how much was set aside.`
+    `WARNING: SESSION-DB-REPLICA-QUARANTINED: moved ${moved.length} unusable replica object(s) aside to ${destination} (${failed.length} could not be moved). Moved history remains readable at that destination; failed moves remain at their original keys.` + (remaining > 0 ? ` The active replica prefix still has ${remaining} object(s).` : "") + ` Progress: moved=${moved.length} remaining=${remaining}. See SESSION-DB-REPLICA-SIZE above for how much was set aside.`
   );
 }
-async function separateCorruptReplica(store, prefix, log, stamp) {
+async function separateCorruptReplica(store, prefix, log, stamp, disposalBudgetSeconds = DEFAULT_DISPOSAL_BUDGET_SECONDS, now = Date.now) {
   const probe = await probeReplica(store, prefix, log);
   if (!probe.ok) return { kind: "unreachable", detail: probe.detail };
   const root12 = replicaDbPrefix(prefix);
@@ -61498,7 +61609,15 @@ async function separateCorruptReplica(store, prefix, log, stamp) {
     );
     return { kind: "alreadyEmpty" };
   }
-  const result = await quarantineReplica(store, prefix, probe.objects, log, stamp);
+  const result = await quarantineReplica(
+    store,
+    prefix,
+    probe.objects,
+    log,
+    stamp,
+    disposalBudgetSeconds,
+    now
+  );
   try {
     const remaining = await store.list(root12);
     if (remaining.length > 0) {
@@ -61540,9 +61659,6 @@ async function clearReplica(store, prefix, keys, log) {
 }
 
 // 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") {
@@ -61634,7 +61750,7 @@ async function decideSessionDbRestore(params) {
       return { kind: "recovered", strategy: "clear", deleted: result.deleted, recovery };
     }
     default:
-      return assertNeverStrategy(strategy);
+      return assertNever(strategy, "unusable-replica strategy");
   }
 }
 function shouldEscalateToQuarantine(reason, prefix, keys) {
@@ -61653,7 +61769,7 @@ async function discardLocalDebris(fileOps, dbPath, log) {
 
 // src/session-db-recovery-report.ts
 init_esm_shims();
-import { dirname as dirname4 } from "node:path";
+import { dirname as dirname5 } from "node:path";
 function base(at2, stage) {
   return {
     v: 1,
@@ -61761,7 +61877,7 @@ async function appendSessionDbRecoveryRecord(record, path, fileOps, log) {
       );
       return;
     }
-    await fileOps.mkdirp(dirname4(path));
+    await fileOps.mkdirp(dirname5(path));
     await fileOps.appendFile(path, line);
   } catch (error) {
     log(
@@ -61832,7 +61948,14 @@ async function verifySessionDb(params) {
   );
   const decision = await walkBack(params);
   if (decision.kind !== "exhausted") return decision;
-  const separation = params.store === null || config.prefix === null ? { kind: "notConfigured" } : await separateCorruptReplica(params.store, config.prefix, log);
+  const separation = params.store === null || config.prefix === null ? { kind: "notConfigured" } : await separateCorruptReplica(
+    params.store,
+    config.prefix,
+    log,
+    void 0,
+    params.disposalBudgetSeconds,
+    params.now
+  );
   const localDb = separation.kind === "notConfigured" || separation.kind === "alreadyEmpty" || separation.kind === "quarantined" ? await discardCorruptDb(fileOps, dbPath, log) : { kind: "retained", reason: "separationUnproven" };
   return { ...decision, separation, localDb };
 }
@@ -62108,21 +62231,25 @@ var nodeSqliteIntegrity = {
 
 // src/sync.ts
 init_esm_shims();
-async function sync(params) {
-  const { label, path, bucket, key, store, lastHash, fileOps, log } = params;
-  if (store === null || bucket === null || key === null) {
-    return { outcome: { kind: "disabled" }, hash: lastHash };
-  }
+
+// src/local-credential.ts
+init_esm_shims();
+async function readLocalCredential({
+  label,
+  path,
+  fileOps,
+  log
+}) {
   const exists = await fileOps.stat(path) !== null;
   const valid = await isValidJson(fileOps, path);
   if (exists && !valid) {
     log(
       `WARNING: local ${label} credentials at ${path} are invalid or unreadable; keeping them and skipping sync.`
     );
-    return { outcome: { kind: "localInvalid" }, hash: lastHash };
+    return { kind: "invalid" };
   }
   if (!valid) {
-    return { outcome: { kind: "absent" }, hash: lastHash };
+    return { kind: "absent" };
   }
   try {
     await fileOps.chmod(path, 384);
@@ -62138,8 +62265,28 @@ async function sync(params) {
     log(
       `WARNING: could not hash local ${label} credentials at ${path} (${describeError(error)}); skipping this sync tick.`
     );
+    return { kind: "hashFailed" };
+  }
+  return { kind: "ok", hash };
+}
+
+// src/sync.ts
+async function sync(params) {
+  const { label, path, bucket, key, store, lastHash, fileOps, log } = params;
+  if (store === null || bucket === null || key === null) {
+    return { outcome: { kind: "disabled" }, hash: lastHash };
+  }
+  const local = await readLocalCredential({ label, path, fileOps, log });
+  if (local.kind === "invalid") {
+    return { outcome: { kind: "localInvalid" }, hash: lastHash };
+  }
+  if (local.kind === "absent") {
+    return { outcome: { kind: "absent" }, hash: lastHash };
+  }
+  if (local.kind === "hashFailed") {
     return { outcome: { kind: "hashFailed" }, hash: lastHash };
   }
+  const { hash } = local;
   if (hash === lastHash) {
     return { outcome: { kind: "unchanged" }, hash: lastHash };
   }
@@ -62154,6 +62301,256 @@ async function sync(params) {
   return { outcome: { kind: "uploaded" }, hash };
 }
 
+// src/vault-sync.ts
+init_esm_shims();
+import { createHash as createHash10 } from "node:crypto";
+import { dirname as dirname6 } from "node:path";
+async function syncVault(params) {
+  const { label, path, bucket, key, store, lastHash, fileOps, log } = params;
+  if (store === null || bucket === null || key === null) {
+    return { outcome: { kind: "disabled" }, hash: lastHash };
+  }
+  const location = `s3://${bucket}/${key}`;
+  let remote;
+  try {
+    remote = await store.get(key);
+  } catch (error) {
+    const reason = describeError(error);
+    log(
+      `WARNING: VAULT-REMOTE-UNREADABLE: could not read the shared ${label} credential at ${location}: ${reason}`
+    );
+    return { outcome: { kind: "remoteFailed", reason }, hash: lastHash };
+  }
+  let local;
+  try {
+    local = await readLocalCredential({ label, path, fileOps, log });
+  } catch (error) {
+    log(
+      `WARNING: local ${label} credentials at ${path} are invalid or unreadable; keeping them and skipping sync. (${describeError(error)})`
+    );
+    return { outcome: { kind: "localInvalid" }, hash: lastHash };
+  }
+  if (local.kind === "invalid") {
+    return { outcome: { kind: "localInvalid" }, hash: lastHash };
+  }
+  if (local.kind === "hashFailed") {
+    return { outcome: { kind: "hashFailed" }, hash: lastHash };
+  }
+  if (remote === null) {
+    if (local.kind === "absent") return { outcome: { kind: "absent" }, hash: lastHash };
+    let body;
+    try {
+      body = await fileOps.readFile(path);
+    } catch (error) {
+      log(
+        `WARNING: local ${label} credentials at ${path} are invalid or unreadable; keeping them and skipping sync. (${describeError(error)})`
+      );
+      return { outcome: { kind: "localInvalid" }, hash: lastHash };
+    }
+    return publish(
+      { ...params, bucket, key, store, lastHash, log },
+      body,
+      local.hash,
+      null,
+      location
+    );
+  }
+  const remoteHash = hashBytes(remote.body);
+  const remoteValid = isValidJsonBytes(remote.body);
+  if (local.kind === "absent") {
+    if (!remoteValid) {
+      log(
+        `WARNING: VAULT-REMOTE-INVALID: the shared ${label} credential at ${location} is not valid JSON; keeping this runner's local file and not adopting it.`
+      );
+      return { outcome: { kind: "remoteInvalid" }, hash: lastHash };
+    }
+    return adopt2(
+      { ...params, bucket, key, store, lastHash, log },
+      remote.body,
+      remoteHash,
+      location
+    );
+  }
+  let localBody;
+  try {
+    localBody = await fileOps.readFile(path);
+  } catch (error) {
+    log(
+      `WARNING: local ${label} credentials at ${path} are invalid or unreadable; keeping them and skipping sync. (${describeError(error)})`
+    );
+    return { outcome: { kind: "localInvalid" }, hash: lastHash };
+  }
+  if (remoteValid && remoteHash === local.hash) {
+    return { outcome: { kind: "unchanged" }, hash: remoteHash };
+  }
+  if (!remoteValid) {
+    if (remote.etag === null) {
+      return noEtag({ label, location, lastHash, log });
+    }
+    log(
+      `WARNING: VAULT-REMOTE-INVALID: the shared ${label} credential at ${location} is not valid JSON; replacing it with this runner's local credential.`
+    );
+    return publish(
+      { ...params, bucket, key, store, lastHash, log },
+      localBody,
+      local.hash,
+      remote,
+      location
+    );
+  }
+  if (remoteHash !== lastHash) {
+    return adopt2(
+      { ...params, bucket, key, store, lastHash, log },
+      remote.body,
+      remoteHash,
+      location
+    );
+  }
+  if (remote.etag === null) {
+    return noEtag({ label, location, lastHash, log });
+  }
+  return publish(
+    { ...params, bucket, key, store, lastHash, log },
+    localBody,
+    local.hash,
+    remote,
+    location
+  );
+}
+function isVaultCredentialPersisted(outcome) {
+  switch (outcome.kind) {
+    case "disabled":
+    case "absent":
+    case "unchanged":
+    case "published":
+    case "adopted":
+      return true;
+    case "localInvalid":
+    case "hashFailed":
+    case "adoptFailed":
+    case "contended":
+    case "remoteFailed":
+    case "remoteInvalid":
+    case "noEtag":
+      return false;
+    default:
+      return assertNever(outcome, "vault sync outcome");
+  }
+}
+async function publish(params, body, hash, remote, location) {
+  const { label, key, store, lastHash, log } = params;
+  if (store === null || key === null) return { outcome: { kind: "disabled" }, hash: lastHash };
+  if (remote !== null && remote.etag === null) {
+    return noEtag({ label, location, lastHash, log });
+  }
+  let result;
+  try {
+    if (remote === null) {
+      result = await store.putIfAbsent(key, body);
+    } else {
+      const { etag } = remote;
+      if (etag === null) return noEtag({ label, location, lastHash, log });
+      result = await store.putIfMatch(key, body, etag);
+    }
+  } catch (error) {
+    const reason = describeError(error);
+    log(`WARNING: ${label} credentials upload failed to ${location}: ${reason}`);
+    return { outcome: { kind: "remoteFailed", reason }, hash: lastHash };
+  }
+  if (result === "written") {
+    const mode = remote === null ? "created" : "replaced";
+    const previous = remote === null ? "" : ` previous=${shortHash(lastHash ?? hashBytes(remote.body))}`;
+    log(
+      `VAULT-PUBLISHED: ${mode === "created" ? "created" : "replaced"} the shared ${label} credential at ${location} hash=${shortHash(hash)}${previous}`
+    );
+    return { outcome: { kind: "published", mode }, hash };
+  }
+  log(
+    `WARNING: VAULT-CONTENDED: another writer changed the shared ${label} credential at ${location} first; adopting theirs instead of overwriting it.`
+  );
+  let winner;
+  try {
+    winner = await store.get(key);
+  } catch (error) {
+    return unresolvedContention(params, location, describeError(error));
+  }
+  if (winner === null)
+    return unresolvedContention(params, location, "the winning object is absent");
+  if (!isValidJsonBytes(winner.body)) {
+    return unresolvedContention(params, location, "the winning object is not valid JSON");
+  }
+  const winnerHash = hashBytes(winner.body);
+  if (winnerHash === hash) return { outcome: { kind: "unchanged" }, hash: winnerHash };
+  return adopt2(params, winner.body, winnerHash, location);
+}
+async function adopt2(params, body, hash, location) {
+  const { label, path, fileOps, log, lastHash } = params;
+  const dir = dirname6(path);
+  try {
+    await fileOps.mkdirp(dir);
+  } catch (error) {
+    return adoptFailed(params, location, describeError(error));
+  }
+  let installation;
+  try {
+    installation = await installCredentialBytes({
+      label,
+      path,
+      body,
+      source: location,
+      fileOps,
+      log
+    });
+  } catch (error) {
+    return adoptFailed(params, location, describeError(error));
+  }
+  if (installation.kind === "installed") {
+    log(
+      `VAULT-ADOPTED: installed the shared ${label} credential from ${location} hash=${shortHash(hash)} previous=${lastHash === null ? "none" : shortHash(lastHash)}`
+    );
+    return { outcome: { kind: "adopted" }, hash };
+  }
+  return adoptFailed(
+    params,
+    location,
+    installation.kind === "invalid" ? "the winning object was not valid JSON" : installation.reason
+  );
+}
+function adoptFailed(params, location, reason) {
+  const { label, log, lastHash } = params;
+  log(
+    `WARNING: VAULT-ADOPT-FAILED: could not install the shared ${label} credential from ${location} (${reason}); keeping the local file and retrying on the next tick.`
+  );
+  return { outcome: { kind: "adoptFailed" }, hash: lastHash };
+}
+function unresolvedContention(params, location, reason) {
+  const { label, log, lastHash } = params;
+  log(
+    `WARNING: VAULT-CONTENDED-UNRESOLVED: could not read the winning ${label} credential at ${location} (${reason}); retrying on the next tick.`
+  );
+  return { outcome: { kind: "contended" }, hash: lastHash };
+}
+function noEtag({
+  label,
+  location,
+  lastHash,
+  log
+}) {
+  log(
+    `WARNING: VAULT-NO-ETAG: the shared ${label} credential at ${location} came back without an ETag; skipping publication this tick rather than overwriting it unconditionally.`
+  );
+  return {
+    outcome: { kind: "noEtag" },
+    hash: lastHash
+  };
+}
+function hashBytes(body) {
+  return createHash10("sha256").update(body).digest("hex");
+}
+function shortHash(hash) {
+  return hash.slice(0, 12);
+}
+
 // src/cli.ts
 var EXIT_NOT_READY = 10;
 var EXIT_KEEP_TASK = 20;
@@ -62172,7 +62569,8 @@ var USAGE = `Usage: runner-synchroniser <command> [args]
   env                          print the resolved config as shell-sourceable lines
   litestream-config            print the generated litestream.yml
   restore <claude|opencode>    restore a credential store from the object store
-  sync-once <claude|opencode>  upload a credential store if it changed
+  sync-once <claude|opencode>  synchronize a credential store; shared-vault mode may
+                                adopt or conditionally publish credentials
   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
@@ -62202,8 +62600,11 @@ function awsSelfStopAccessFor(config) {
 function nodeSqliteIntegrityFor() {
   return nodeSqliteIntegrity;
 }
-function litestreamCliFor(configPath, dbPath) {
-  return new LitestreamCli(configPath, dbPath);
+function litestreamCliFor(configPath, dbPath, config) {
+  return new LitestreamCli(configPath, dbPath, {
+    restorePointsTimeoutSeconds: config.restorePointsTimeoutSeconds,
+    restoreCandidateTimeoutSeconds: config.restoreCandidateTimeoutSeconds
+  });
 }
 function parseStoreName(value) {
   return value === "claude" || value === "opencode" ? value : null;
@@ -62302,7 +62703,7 @@ async function commandSyncOnce(name, config, deps) {
   const store = storeOf(config, name);
   const statePath = `${store.path}${STATE_SUFFIX}`;
   const lastHash = await readLastHash(fileOps, statePath, log);
-  const result = await sync({
+  const params = {
     label: store.label,
     path: store.path,
     bucket: config.bucket,
@@ -62311,10 +62712,14 @@ async function commandSyncOnce(name, config, deps) {
     lastHash,
     fileOps,
     log
-  });
+  };
+  const result = config.vaultPrefix === null ? await sync(params) : await syncVault(params);
   if (result.hash !== null && result.hash !== lastHash) {
     await writeLastHash(fileOps, statePath, result.hash, log);
   }
+  if (config.vaultPrefix !== null) {
+    return isVaultCredentialPersisted(result.outcome) ? 0 : EXIT_SYNC_NOT_PERSISTED;
+  }
   return result.outcome.kind === "failed" || result.outcome.kind === "hashFailed" || result.outcome.kind === "localInvalid" ? EXIT_SYNC_NOT_PERSISTED : 0;
 }
 async function commandSessionDbClassify(args, config, deps) {
@@ -62359,7 +62764,8 @@ async function commandSessionDbVerify(litestreamConfigPath, config, deps) {
   const { fileOps, log } = deps;
   const litestream = (deps.litestreamFor ?? litestreamCliFor)(
     litestreamConfigPath,
-    config.opencodeDbPath
+    config.opencodeDbPath,
+    config
   );
   const outcome = await verifySessionDb({
     config: { opencodeDbPath: config.opencodeDbPath, prefix: config.prefix },
@@ -62369,7 +62775,8 @@ async function commandSessionDbVerify(litestreamConfigPath, config, deps) {
     litestream,
     log,
     maxPoints: config.walkbackMaxPoints,
-    budgetSeconds: config.walkbackBudgetSeconds
+    budgetSeconds: config.walkbackBudgetSeconds,
+    disposalBudgetSeconds: config.disposalBudgetSeconds
   });
   log(describeSessionDbVerification(outcome));
   if (outcome.kind === "exhausted" && sessionDbVerifyExitCode(outcome) === 34) {
@@ -62402,8 +62809,14 @@ ${USAGE}`);
   const config = resolveConfig(env4);
   if (command12 === "env") {
     if (config.bucket === null) {
+      const vaultPrefixIgnored = (env4.CREDENTIAL_VAULT_PREFIX?.trim() ?? "") !== "";
+      log(
+        "WARNING: credential persistence is DISABLED (LITESTREAM_BUCKET/LITESTREAM_PREFIX unset). Credentials stay on this task's ephemeral disk and are LOST when it is replaced." + (vaultPrefixIgnored ? " The requested CREDENTIAL_VAULT_PREFIX is ignored because persistence requires both LITESTREAM_BUCKET and LITESTREAM_PREFIX." : "")
+      );
+    }
+    if (config.vaultPrefix !== null) {
       log(
-        "WARNING: credential persistence is DISABLED (LITESTREAM_BUCKET/LITESTREAM_PREFIX unset). Credentials stay on this task's ephemeral disk and are LOST when it is replaced."
+        `VAULT-MODE: both Claude and OpenCode credential files are shared through bucket=${config.bucket} prefix=${config.vaultPrefix} instead of this runner's own prefix.`
       );
     }
     out(renderEnv(config));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-synchroniser",
-  "version": "3.5.2-dev.43244a2",
+  "version": "3.5.2-dev.4f7b3ac",
   "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",