@evident-ai/runner-synchroniser 3.5.1-dev.bf9e537 → 3.5.2-dev.06654ec

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 |
@@ -329,8 +329,10 @@ same way it already reuses `SESSION-DB-REPLICA-UNUSABLE` for `session-db-classif
 `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,6 +381,7 @@ 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.                   |
@@ -402,6 +405,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 +443,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

@@ -50903,22 +50903,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(
@@ -50940,9 +50942,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 +50967,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 +50987,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 +51006,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 +51019,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 +51029,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 +51054,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 +51073,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 +51082,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 +51095,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 +51115,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 +51133,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 +51147,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 +51162,7 @@ function describeSessionDbVerification(outcome) {
     case "exhausted":
       return describeSessionDbVerifyExhausted(outcome);
     default:
-      return assertNeverSessionDbVerify(outcome);
+      return assertNever(outcome, "session-DB verify outcome");
   }
 }
 
@@ -51339,20 +51319,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 +51392,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 +51434,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 +51452,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 +51462,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 +61305,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 +61322,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 +61334,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;
@@ -61421,7 +61473,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.`
@@ -61540,9 +61593,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 +61684,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 +61703,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 +61811,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(
@@ -62108,21 +62158,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 +62192,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 +62228,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 +62496,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
@@ -62302,7 +62627,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 +62636,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) {
@@ -62402,8 +62731,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.1-dev.bf9e537",
+  "version": "3.5.2-dev.06654ec",
   "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",