diff --git a/packages/loopover-miner/docs/ams-shared-store-concurrency-model.md b/packages/loopover-miner/docs/ams-shared-store-concurrency-model.md
new file mode 100644
index 0000000000..abe4925a6b
--- /dev/null
+++ b/packages/loopover-miner/docs/ams-shared-store-concurrency-model.md
@@ -0,0 +1,107 @@
+# AMS shared-store concurrency model
+
+Canonical statement of **what the AMS local-store / `SqliteDriver` seam guarantees under concurrent
+access**, and what it deliberately does **not** — for [#4942](https://github.com/JSONbored/loopover/issues/4942),
+after the [#7175](https://github.com/JSONbored/loopover/issues/7175) shared-seam migration unblocked this work.
+
+> **Audience:** maintainers and contributors wiring hosted AMS / control-plane tenancy, not day-to-day
+> laptop operators. For the operator-facing single-file SQLite rules (`busy_timeout`, one loop per
+> state dir), see [`operations-runbook.md`](operations-runbook.md).
+
+## Scope
+
+| Layer | File(s) | Role in this model |
+|-------|---------|--------------------|
+| Miner `SqliteDriver` seam | `packages/loopover-miner/lib/store-db-adapter.ts`, `local-store.ts` | Sync `query`/`exec` + D1-shaped `createD1Adapter` (`batch` = `BEGIN` → stmts → `COMMIT`) |
+| Miner default backend | `node:sqlite` via `nodeSqliteDriver` / `openLocalStoreDb` | Still the self-host / laptop default after #7175 — the seam is real; a miner `createPgAdapter` cutover is a later slice |
+| ORB Postgres adapter | `src/selfhost/pg-adapter.ts` | The shared-service Postgres implementation the seam was designed to swap in (`batch` pins one `PoolClient`, `BEGIN` → `runOn` → `COMMIT`) |
+| Contrast (not store atomicity) | `src/selfhost/installation-concurrency-admission.ts`, `src/queue/map-with-concurrency.ts` | Per-installation **GitHub-fetch job** admission, and generic fan-out worker pools — fairness / throughput, **not** row-level store guarantees |
+
+**Tenancy boundary (control-plane):** hosted AMS is provisioned as **one container + one database per
+tenant+product**, not a shared multi-tenant table with `tenant_id` row filters. “Multiple tenant
+sessions” in this doc means concurrent clients/workers against **one tenant’s** store (or one shared
+test DB), not cross-tenant isolation inside a single SQLite file. Cross-tenant isolation is
+infrastructure (provisioning), not `PRAGMA` / file locks. Default in-process store singletons remain
+unsafe if many tenants share one Node process — see [`global-singleton-tenant-audit.md`](global-singleton-tenant-audit.md).
+
+## What is guaranteed
+
+### SQLite (`node:sqlite` / `openLocalStoreDb`)
+
+| Guarantee | Mechanism |
+|-----------|-----------|
+| Short writers eventually proceed or fail loudly | `PRAGMA busy_timeout = 5000` (default) on every store open |
+| Read-then-conditional-write cannot interleave with another writer on the same file | Interactive sites use **`BEGIN IMMEDIATE`** (takes the write lock before the first read) — e.g. `claimIssueWithinCap`, portfolio `batchClaim`, governor `withTransaction`, append-only ledgers |
+| Single-row claim / dequeue is atomic | `INSERT … ON CONFLICT` / `UPDATE … RETURNING` (no app-level RMW) |
+| Two processes racing the same claim or dequeue produce one winner | Empirically gated by `test/unit/miner-concurrent-store-races.test.ts` (#4867) and the #4942 load suite |
+
+**Invariant (unchanged from the runbook):** two long-running `loopover-miner loop` daemons on the
+**same** `LOOPOVER_MINER_CONFIG_DIR` remain **unsupported**. `busy_timeout` is not a multi-writer
+cluster protocol.
+
+### `SqliteDriver` + `createD1Adapter.batch` (miner seam)
+
+- `batch(statements)` runs on the sync driver as `BEGIN` → execute each statement → `COMMIT` /
+  `ROLLBACK` (`store-db-adapter.ts`).
+- That is a **predetermined** statement list (D1-shaped): the result of statement *N* cannot decide
+  statement *N+1* inside the same `batch` call. Interactive AMS sites that still need
+  read-then-write stay on `BEGIN IMMEDIATE` against `DatabaseSync` until an async `runOn`-style API
+  lands for miner Postgres.
+- Concurrent callers that use **single-statement conditional SQL** (`UPDATE … SET n = n + 1`,
+  `INSERT … ON CONFLICT`, `UPDATE … WHERE … RETURNING`) see no lost updates under SQLite’s writer
+  serialization — verified by the #4942 load test.
+
+### Postgres (`createPgAdapter` — ORB / future hosted AMS)
+
+| Guarantee | Mechanism |
+|-----------|-----------|
+| Multi-statement atomicity for a predetermined batch | `batch()` acquires one `PoolClient`, `BEGIN`, runs each stmt via `runOn(client)`, `COMMIT` / `ROLLBACK` |
+| Multi-instance self-host | Shared Postgres replaces single-file SQLite (ORB’s original motivation in `pg-adapter.ts`) |
+| Queue claim under many workers | Sibling pattern `FOR UPDATE SKIP LOCKED` in `src/selfhost/pg-queue.ts` (queue, not AMS ledgers) |
+| Atomic counter / upsert style writes | Same SQL shapes as SQLite when expressed as one statement (or one `batch` of predetermined stmts) |
+
+Default isolation for `BEGIN` with no `SET TRANSACTION ISOLATION LEVEL` is **READ COMMITTED** (Postgres
+default) — **not** SERIALIZABLE.
+
+## What is not guaranteed
+
+| Non-guarantee | Why |
+|---------------|-----|
+| **SERIALIZABLE** / predicate locking | Neither miner `BEGIN IMMEDIATE` nor ORB `batch()` sets SERIALIZABLE. App-level RMW across separate statements/transactions can still lose updates under READ COMMITTED / SQLite if you omit conditional SQL or `BEGIN IMMEDIATE`. |
+| Cross-process **queue admission** fairness | `installation-concurrency-admission.ts` is an in-process `Map` — single process per deployment by design. |
+| Fan-out helpers as store locks | `mapWithConcurrency` only bounds Promise concurrency; it does not serialize DB writers. |
+| Two loops on one SQLite directory | Explicitly unsupported (runbook). |
+| Default store singletons across tenants in one process | Module-scoped `default*` handles — see tenant audit doc. |
+| Miner already running on Postgres today | #7175 shipped the **seam** + non-interactive store rollout; interactive stores still use `DatabaseSync` + `BEGIN IMMEDIATE`. ORB’s `createPgAdapter` is the shared-service reference implementation to document against. |
+| Plain `createD1Adapter.batch` `BEGIN` ≡ `BEGIN IMMEDIATE` | Miner D1 adapter uses plain `BEGIN`. Do not assume it takes the write lock before the first read the way interactive AMS sites do. |
+
+## Mapping: AMS interactive sites → shared backend
+
+| AMS pattern today | SQLite guarantee | Shared Postgres analogue |
+|-------------------|------------------|---------------------------|
+| `claimIssueWithinCap` / ledger append | `BEGIN IMMEDIATE` + count + insert | Pinned client + interactive txn (`runOn`) — **later miner slice**; until then keep SQLite IMMEDIATE |
+| Portfolio dequeue / claim upsert | Single-statement `UPDATE…RETURNING` / `ON CONFLICT` | Same SQL via `prepare().run()` / `batch` of fixed stmts |
+| CRUD caches on `openLocalStoreAdapter` | Sync `driver.query` | Swap driver; no interactive txn required |
+| ORB job queue claim | n/a (ORB) | `FOR UPDATE SKIP LOCKED` |
+
+## Load / race verification (#4942)
+
+Correctness (not wall-clock) coverage lives in:
+
+- `test/unit/miner-concurrent-store-races.test.ts` — cross-process claim + dequeue (#4867)
+- `test/unit/miner-shared-store-concurrency-*.test.ts` — #4942 split across three files so scoped
+  CI shards each still emit non-empty `coverage/lcov.info` under `--coverage.all=false`:
+  - `…-cap.test.ts` — cross-process `claimIssueWithinCap`
+  - `…-adapter.test.ts` — concurrent `SqliteDriver` / `createD1Adapter` increments (+ optional
+    Postgres `createPgAdapter` when `PG_TEST_URL` is set)
+  - `…-doc.test.ts` — doc-surface assertions (+ a local-store smoke open for coverage)
+
+These suites assert **final counts / uniqueness**, not latency. Informational HTTP/engine load scripts
+(`docs/load-test-worker.md`, engine iterate-loop load test) are out of scope here.
+
+## See also
+
+- [`operations-runbook.md`](operations-runbook.md) — operator SQLite concurrency
+- [`ams-storage-abstraction-research.md`](ams-storage-abstraction-research.md) — why Postgres + the ORB seam
+- [`global-singleton-tenant-audit.md`](global-singleton-tenant-audit.md) — in-process default-store hazards
+- [`sizing.md`](sizing.md) — replicas need separate volumes for SQLite
diff --git a/packages/loopover-miner/docs/ams-storage-abstraction-research.md b/packages/loopover-miner/docs/ams-storage-abstraction-research.md
index 63121ab56b..8e548a9482 100644
--- a/packages/loopover-miner/docs/ams-storage-abstraction-research.md
+++ b/packages/loopover-miner/docs/ams-storage-abstraction-research.md
@@ -140,3 +140,9 @@ pool with `translateSql`/`translateDdl`. Reusing this means AMS gets **D1-or-Pos
 for free, and the follow-up design issue chooses the deployment target without a second abstraction. The
 recommendation here — Postgres-lead, D1-alternative, KV-excluded — is a non-binding input to that
 maintainer-owned design issue.
+
+## See also
+
+- [`ams-shared-store-concurrency-model.md`](ams-shared-store-concurrency-model.md) — post-#7175
+  concurrency guarantees (and non-guarantees) for the shared `SqliteDriver` / `pg-adapter` seam under
+  concurrent sessions (#4942).
diff --git a/packages/loopover-miner/docs/operations-runbook.md b/packages/loopover-miner/docs/operations-runbook.md
index 4c236aec73..10b2616a0a 100644
--- a/packages/loopover-miner/docs/operations-runbook.md
+++ b/packages/loopover-miner/docs/operations-runbook.md
@@ -49,6 +49,11 @@ PRAGMA busy_timeout = 5000;
 
 **Invariant:** one active loop (or one intentional writer set) per state directory. Horizontal scale = **isolated state dirs** (separate compose projects, separate `LOOPOVER_MINER_CONFIG_DIR`, or the k8s StatefulSet pattern in [`../DEPLOYMENT.md`](../DEPLOYMENT.md)).
 
+For the **shared-service** model (what the `SqliteDriver` / ORB `pg-adapter` seam guarantees under
+concurrent sessions after #7175 — and what it does not), see
+[`ams-shared-store-concurrency-model.md`](ams-shared-store-concurrency-model.md) (#4942). That doc is
+the maintainer reference; this section stays the laptop/fleet operator contract for one SQLite state dir.
+
 ### Quick health check
 
 ```sh
diff --git a/test/fixtures/miner-concurrent-stores/claim-within-cap-child.mjs b/test/fixtures/miner-concurrent-stores/claim-within-cap-child.mjs
new file mode 100644
index 0000000000..959593e8e0
--- /dev/null
+++ b/test/fixtures/miner-concurrent-stores/claim-within-cap-child.mjs
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Cross-process helper for claimIssueWithinCap concurrent-load tests (#4942).
+// Opens the shared ledger, waits for a stdin "go" signal, then races
+// claimIssueWithinCap so multiple Node processes contend on BEGIN IMMEDIATE +
+// the per-repo active-claim cap against the same dbPath.
+import { openClaimLedger } from "../../../packages/loopover-miner/lib/claim-ledger.js";
+
+const [dbPath, repoFullName, issueNumberStr, maxConcurrentClaimsStr, note] = process.argv.slice(2);
+if (!dbPath || !repoFullName || !issueNumberStr || !maxConcurrentClaimsStr) {
+  process.stderr.write(
+    "usage: claim-within-cap-child.mjs <dbPath> <repoFullName> <issueNumber> <maxConcurrentClaims> [note]\n",
+  );
+  process.exit(2);
+}
+
+const ledger = openClaimLedger(dbPath);
+let started = false;
+
+function runClaim() {
+  if (started) return;
+  started = true;
+  try {
+    const result = ledger.claimIssueWithinCap(
+      repoFullName,
+      Number(issueNumberStr),
+      note || null,
+      undefined,
+      Number(maxConcurrentClaimsStr),
+    );
+    process.stdout.write(`${JSON.stringify({ ok: true, result })}\n`);
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stdout.write(`${JSON.stringify({ ok: false, message })}\n`);
+    process.exit(1);
+  } finally {
+    ledger.close();
+  }
+}
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", () => runClaim());
+process.stdout.write("READY\n");
diff --git a/test/unit/miner-operations-runbook.test.ts b/test/unit/miner-operations-runbook.test.ts
index 8f28d66bff..8f34c87741 100644
--- a/test/unit/miner-operations-runbook.test.ts
+++ b/test/unit/miner-operations-runbook.test.ts
@@ -1,12 +1,22 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
+
+// Touch local-store so a scoped CI shard that only selects this file still emits non-empty lcov
+// under --coverage.all=false (#4942 / PR #8002 empty-shard failure mode).
+import { openLocalStoreDb } from "../../packages/loopover-miner/lib/local-store.ts";
 
 const repoRoot = process.cwd();
 const runbookPath = join(repoRoot, "packages/loopover-miner/docs/operations-runbook.md");
 const codingAgentDriverDocPath = join(repoRoot, "packages/loopover-miner/docs/coding-agent-driver.md");
 const deploymentDocPath = join(repoRoot, "packages/loopover-miner/DEPLOYMENT.md");
 
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
 describe("miner operations runbook (#4875)", () => {
   it("covers the three operational scenarios from the issue plus the busy_timeout guarantee", () => {
     const doc = readFileSync(runbookPath, "utf8");
@@ -17,6 +27,7 @@ describe("miner operations runbook (#4875)", () => {
     expect(doc).toContain("PRAGMA busy_timeout");
     expect(doc).toContain("5000");
     expect(doc).toContain("BEGIN IMMEDIATE");
+    expect(doc).toContain("ams-shared-store-concurrency-model.md");
   });
 
   it("links from coding-agent-driver.md related docs (invariant: entry resolves)", () => {
@@ -29,4 +40,12 @@ describe("miner operations runbook (#4875)", () => {
     const deploymentDoc = readFileSync(deploymentDocPath, "utf8");
     expect(deploymentDoc).toContain("docs/operations-runbook.md");
   });
+
+  it("opens a local store so coverage.include is hit when this file is the only shard selection", () => {
+    const root = mkdtempSync(join(tmpdir(), "loopover-miner-runbook-coverage-"));
+    roots.push(root);
+    const db = openLocalStoreDb(join(root, "runbook.sqlite3"));
+    db.exec("CREATE TABLE runbook_smoke (id INTEGER PRIMARY KEY)");
+    db.close();
+  });
 });
diff --git a/test/unit/miner-shared-store-concurrency-adapter.test.ts b/test/unit/miner-shared-store-concurrency-adapter.test.ts
new file mode 100644
index 0000000000..10919d93aa
--- /dev/null
+++ b/test/unit/miner-shared-store-concurrency-adapter.test.ts
@@ -0,0 +1,95 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import pg from "pg";
+
+// Import .ts so CI's build:miner-before-coverage layout attributes hits under --coverage.all=false.
+import { openLocalStoreDb } from "../../packages/loopover-miner/lib/local-store.ts";
+import { createD1Adapter, nodeSqliteDriver } from "../../packages/loopover-miner/lib/store-db-adapter.ts";
+import { createPgAdapter } from "../../src/selfhost/pg-adapter.ts";
+
+// #4942: SqliteDriver / createD1Adapter (and optional Postgres) concurrent increment correctness.
+
+const roots: string[] = [];
+
+function tempRoot(): { root: string; dbPath: string } {
+  const root = mkdtempSync(join(tmpdir(), "loopover-miner-shared-store-adapter-"));
+  roots.push(root);
+  return { root, dbPath: join(root, "store.sqlite3") };
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("SqliteDriver / createD1Adapter concurrent increments (#4942)", () => {
+  it("N concurrent atomic UPDATE n = n + 1 writers produce exactly N (no lost updates)", async () => {
+    const { dbPath } = tempRoot();
+    const db = openLocalStoreDb(dbPath);
+    const driver = nodeSqliteDriver(db);
+    driver.exec("CREATE TABLE counters (id TEXT PRIMARY KEY, n INTEGER NOT NULL)");
+    driver.query("INSERT INTO counters (id, n) VALUES (?, ?)", ["shared", 0]);
+
+    const adapter = createD1Adapter(driver);
+    const workers = 32;
+    await Promise.all(
+      Array.from({ length: workers }, () =>
+        adapter.batch([adapter.prepare("UPDATE counters SET n = n + 1 WHERE id = ?").bind("shared")]),
+      ),
+    );
+
+    const row = driver.query("SELECT n AS n FROM counters WHERE id = ?", ["shared"]).rows[0] as { n: number };
+    expect(row.n).toBe(workers);
+    db.close();
+  });
+
+  it("naive app-level RMW across separate statements can lose updates (documents the non-guarantee)", () => {
+    const { dbPath } = tempRoot();
+    const a = openLocalStoreDb(dbPath);
+    const b = openLocalStoreDb(dbPath);
+    a.exec("CREATE TABLE counters (id TEXT PRIMARY KEY, n INTEGER NOT NULL)");
+    a.prepare("INSERT INTO counters (id, n) VALUES (?, ?)").run("shared", 0);
+
+    const readA = (a.prepare("SELECT n AS n FROM counters WHERE id = ?").get("shared") as { n: number }).n;
+    const readB = (b.prepare("SELECT n AS n FROM counters WHERE id = ?").get("shared") as { n: number }).n;
+    a.prepare("UPDATE counters SET n = ? WHERE id = ?").run(readA + 1, "shared");
+    b.prepare("UPDATE counters SET n = ? WHERE id = ?").run(readB + 1, "shared");
+
+    const final = (a.prepare("SELECT n AS n FROM counters WHERE id = ?").get("shared") as { n: number }).n;
+    expect(final).toBe(1);
+    a.close();
+    b.close();
+  });
+});
+
+const PG_URL = process.env.PG_TEST_URL;
+const pgSuite = PG_URL ? describe : describe.skip;
+
+pgSuite("Postgres createPgAdapter concurrent increments (#4942)", () => {
+  it("N concurrent atomic UPDATE n = n + 1 writers produce exactly N (no lost updates)", async () => {
+    pg.types.setTypeParser(20, (v: string) => Number.parseInt(v, 10));
+    const pool = new pg.Pool({ connectionString: PG_URL });
+    try {
+      await pool.query("DROP TABLE IF EXISTS ams_concurrency_counters");
+      await pool.query("CREATE TABLE ams_concurrency_counters (id TEXT PRIMARY KEY, n INTEGER NOT NULL)");
+      const db = createPgAdapter(pool);
+      await db.prepare("INSERT INTO ams_concurrency_counters (id, n) VALUES (?, ?)").bind("shared", 0).run();
+
+      const workers = 32;
+      await Promise.all(
+        Array.from({ length: workers }, () =>
+          db.prepare("UPDATE ams_concurrency_counters SET n = n + 1 WHERE id = ?").bind("shared").run(),
+        ),
+      );
+
+      const row = await db
+        .prepare("SELECT n AS n FROM ams_concurrency_counters WHERE id = ?")
+        .bind("shared")
+        .first<{ n: number }>();
+      expect(row?.n).toBe(workers);
+    } finally {
+      await pool.end();
+    }
+  });
+});
diff --git a/test/unit/miner-shared-store-concurrency-cap.test.ts b/test/unit/miner-shared-store-concurrency-cap.test.ts
new file mode 100644
index 0000000000..0fbada0111
--- /dev/null
+++ b/test/unit/miner-shared-store-concurrency-cap.test.ts
@@ -0,0 +1,120 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+
+// Import .ts so CI's build:miner-before-coverage layout attributes hits under --coverage.all=false.
+import { openClaimLedger } from "../../packages/loopover-miner/lib/claim-ledger.ts";
+
+// #4942: cross-process claimIssueWithinCap load — BEGIN IMMEDIATE + per-repo cap, no double-active rows.
+
+const claimWithinCapChildScript = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../fixtures/miner-concurrent-stores/claim-within-cap-child.mjs",
+);
+
+const roots: string[] = [];
+
+function tempRoot(): { root: string; dbPath: string } {
+  const root = mkdtempSync(join(tmpdir(), "loopover-miner-shared-store-cap-"));
+  roots.push(root);
+  return { root, dbPath: join(root, "store.sqlite3") };
+}
+
+function spawnChild(script: string, args: string[]): ChildProcessWithoutNullStreams {
+  return spawn(process.execPath, [script, ...args], { stdio: ["pipe", "pipe", "pipe"] });
+}
+
+async function waitForReady(child: ChildProcessWithoutNullStreams): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    let buffer = "";
+    const onData = (chunk: Buffer | string) => {
+      buffer += chunk.toString();
+      if (buffer.includes("READY\n")) {
+        child.stdout.off("data", onData);
+        resolve();
+      }
+    };
+    child.stdout.on("data", onData);
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code !== 0 && code !== null) reject(new Error(`child exited before READY (${code})`));
+    });
+  });
+}
+
+async function runBarriered<T>(children: ChildProcessWithoutNullStreams[]): Promise<T[]> {
+  await Promise.all(children.map((child) => waitForReady(child)));
+  for (const child of children) child.stdin.write("go\n");
+  return Promise.all(
+    children.map(
+      (child) =>
+        new Promise<T>((resolve, reject) => {
+          let stdout = "";
+          child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+          });
+          child.once("error", reject);
+          child.once("exit", () => {
+            const line = stdout
+              .split("\n")
+              .map((entry) => entry.trim())
+              .find((entry) => entry.startsWith("{"));
+            if (!line) {
+              reject(new Error(`child produced no JSON result: ${stdout}`));
+              return;
+            }
+            resolve(JSON.parse(line) as T);
+          });
+        }),
+    ),
+  );
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+type CapChildResult = {
+  ok: boolean;
+  result?: { claimed: boolean; activeClaimCount: number; maxConcurrentClaims: number };
+  message?: string;
+};
+
+describe("claimIssueWithinCap cross-process load (#4942)", () => {
+  it("N processes racing cap=1 on distinct issues: exactly one claim wins, no lost/duplicated active rows", async () => {
+    const { dbPath } = tempRoot();
+    const issues = ["1", "2", "3", "4", "5", "6", "7", "8"];
+    const children = issues.map((issue) =>
+      spawnChild(claimWithinCapChildScript, [dbPath, "acme/widgets", issue, "1", `note:${issue}`]),
+    );
+    const results = await runBarriered<CapChildResult>(children);
+
+    expect(results.every((result) => result.ok)).toBe(true);
+    const winners = results.filter((result) => result.result?.claimed === true);
+    const losers = results.filter((result) => result.result?.claimed === false);
+    expect(winners).toHaveLength(1);
+    expect(losers).toHaveLength(issues.length - 1);
+
+    const ledger = openClaimLedger(dbPath);
+    try {
+      const active = ledger.listActiveClaims("acme/widgets");
+      expect(active).toHaveLength(1);
+      expect(ledger.listClaims({ repoFullName: "acme/widgets", status: "active" })).toHaveLength(1);
+      expect(issues.map(Number)).toContain(active[0]?.issueNumber);
+    } finally {
+      ledger.close();
+    }
+  });
+
+  it("rejects the claim-within-cap-child helper when required args are missing", async () => {
+    const child = spawn(process.execPath, [claimWithinCapChildScript], { stdio: ["ignore", "pipe", "pipe"] });
+    const exitCode = await new Promise<number | null>((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", resolve);
+    });
+    expect(exitCode).toBe(2);
+  });
+});
diff --git a/test/unit/miner-shared-store-concurrency-doc.test.ts b/test/unit/miner-shared-store-concurrency-doc.test.ts
new file mode 100644
index 0000000000..a7597ed356
--- /dev/null
+++ b/test/unit/miner-shared-store-concurrency-doc.test.ts
@@ -0,0 +1,51 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+// Import .ts so CI's build:miner-before-coverage layout still attributes hits to coverage.include
+// (a sibling .js would otherwise steal the resolve and leave shard lcov empty under --coverage.all=false).
+import { openLocalStoreDb, resolveLocalStoreDbPath } from "../../packages/loopover-miner/lib/local-store.ts";
+
+// #4942: doc-surface assertions for the shared-store concurrency model. Also touches local-store so a
+// scoped CI shard that only picks up this file still emits a non-empty coverage/lcov.info.
+
+const repoRoot = process.cwd();
+const concurrencyModelDocPath = join(repoRoot, "packages/loopover-miner/docs/ams-shared-store-concurrency-model.md");
+const runbookPath = join(repoRoot, "packages/loopover-miner/docs/operations-runbook.md");
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("ams-shared-store-concurrency-model.md (#4942)", () => {
+  it("documents guarantees, non-guarantees, and the SqliteDriver / pg-adapter seam", () => {
+    expect(existsSync(concurrencyModelDocPath)).toBe(true);
+    const doc = readFileSync(concurrencyModelDocPath, "utf8");
+    expect(doc).toContain("# AMS shared-store concurrency model");
+    expect(doc).toContain("BEGIN IMMEDIATE");
+    expect(doc).toContain("READ COMMITTED");
+    expect(doc).toContain("createPgAdapter");
+    expect(doc).toContain("SqliteDriver");
+    expect(doc).toContain("What is not guaranteed");
+    expect(doc).toContain("installation-concurrency-admission");
+    expect(doc).toContain("map-with-concurrency");
+  });
+
+  it("is linked from the operator runbook", () => {
+    const runbook = readFileSync(runbookPath, "utf8");
+    expect(runbook).toContain("ams-shared-store-concurrency-model.md");
+  });
+
+  it("exercises openLocalStoreDb so this shard produces coverage under --coverage.all=false", () => {
+    const root = mkdtempSync(join(tmpdir(), "loopover-miner-shared-store-doc-"));
+    roots.push(root);
+    const dbPath = join(root, "smoke.sqlite3");
+    expect(resolveLocalStoreDbPath("smoke.sqlite3", "LOOPOVER_MINER_MISSING_ENV", {})).toContain("loopover-miner");
+    const db = openLocalStoreDb(dbPath);
+    db.exec("CREATE TABLE smoke (id INTEGER PRIMARY KEY)");
+    db.close();
+  });
+});