From 39c10cb552d519cb44fd518312e2c8d2c3ccc94d Mon Sep 17 00:00:00 2001
From: Tyler <53561637+im-tyler@users.noreply.github.com>
Date: Sun, 4 Oct 2026 02:26:19 -0700
Subject: [PATCH 1/2] feat(s19): snapshot producer, restore-check, live doctor
 probes, bundle folding

Productizes the practiced procedure in scripts/ship-backup.sh where that is
safe, keeping its invariants load-bearing in the CLI too:

- teploy-ship snapshot: same archive shape as the script (tar of the nucleus
  data dir + sha256 sidecar + manifest); refuses while ship-* containers run
  unless the operator attests the coordinated stop (--i-stopped-writers);
  never overwrites; never deletes anything except its own partial output
  after a failed production so a failed tar cannot wedge the label+date slot.
- teploy-ship restore-check: verifies an archive WITHOUT unpacking (sidecar
  in sha256sum -c form, full-stream gzip integrity, content listing failing
  on absolute/.. paths); verdict is integrity-only and names the rehearsal
  as the restore proof. The unpack and rehearse stay in the script.
- doctor: store liveness (SELECT 1) and clock skew against the store's own
  clock (SELECT now()) probed read-only when NUCLEUS_URL is set; unknown
  otherwise or when the engine answers no time query; store consistency
  deliberately not probed (read-only while writers may run).
- support bundle (scriptVersion 2): doctor.json + the latest backup manifest
  (the receipt, never the archive), both degrading to note files.

Tests: 11 snapshot/restore-check tests incl. negative controls (running-writer
refusal with the exact stop line, overwrite refusal, tampered sidecar,
truncated archive with re-computed checksum caught by gzip, path-escape
listing, failed-production cleanup), 4 live-probe doctor tests against a fake
store client, 2 bundle folding tests. Fake fixtures only; no live systems.

No upstream defects found; nothing to report upstream.
---
 AUDIT_OPEN.md                             |   9 +-
 CHANGELOG.md                              |  23 ++
 docs/BACKUP.md                            |  32 ++
 docs/SHIP_RELEASE_PROGRAMME_2026-09-21.md |   2 +-
 docs/SUPPORT.md                           |  22 +-
 src/args.ts                               |   2 +
 src/cli.ts                                | 118 +++++-
 src/install-doctor.test.ts                |  70 +++-
 src/install-doctor.ts                     |  70 +++-
 src/snapshot.test.ts                      | 332 ++++++++++++++++
 src/snapshot.ts                           | 462 ++++++++++++++++++++++
 src/support.test.ts                       |  53 ++-
 src/support.ts                            |  44 ++-
 13 files changed, 1218 insertions(+), 21 deletions(-)
 create mode 100644 src/snapshot.test.ts
 create mode 100644 src/snapshot.ts

diff --git a/AUDIT_OPEN.md b/AUDIT_OPEN.md
index f4e83fe5..a0d9b98b 100644
--- a/AUDIT_OPEN.md
+++ b/AUDIT_OPEN.md
@@ -44,8 +44,13 @@ All off by default or observe-only; flags are in the programme's wave-4 table.
 - **S15/S17 (PR #46):** inert; callers must redact log excerpts.
 - **S22 (PR #47):** the coordination record does not keep the revision the
   client was planned against.
-- **S19 (PR #49):** doctor's store and clock checks report unknown until real
-  probes exist; the restore comparison has no snapshot producer.
+- **S19 (PR #49; tail landed 2026-10-04):** doctor now answers store liveness
+  and clock skew read-only when `NUCLEUS_URL` is set (unknown otherwise, and
+  unknown when the engine answers no time query — honest, not a gap to paper
+  over); `teploy-ship snapshot` / `restore-check` exist with the script's
+  invariants. Still open: the unpack and rehearsal remain script-only by
+  design; restore-readiness has no command; none of the S19 tail has run
+  against a live store.
 - **S07 (PR #53):** unwired; wiring must not add a durable step to existing runs.
 - **Agent hygiene:** parallel agents share one scratch directory and the fixed
   grading port 8901. A backup-file collision corrupted one agent's mutation
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 71bcc9ac..64c85b90 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,29 @@ All notable changes to Teploy Ship are recorded here.
 ## [Unreleased]
 
 ### Added
+- **S19 tail: `teploy-ship snapshot` and `teploy-ship restore-check`, live
+  doctor probes, and doctor + backup receipt in the support bundle.** The
+  practiced procedure in `scripts/ship-backup.sh` is now productized where
+  that is safe: `snapshot` produces the identical archive shape (tar of the
+  nucleus data dir + sha256 sidecar + manifest under
+  `$SHIP_BACKUP_DIR/<label>-<date>/`), refuses while any `ship-*` container
+  it can see is running — printing the exact coordinated `docker stop` it
+  expects — unless the operator attests with `--i-stopped-writers`, never
+  overwrites, and never deletes anything except its own partial output after
+  a failed production (so a failed tar cannot wedge the label+date slot;
+  retention stays the operator's). `restore-check` verifies an archive
+  WITHOUT unpacking it: sha256 sidecar in `sha256sum -c` form (the sidecar
+  must travel with its archive), full-stream gzip integrity, and the content
+  listing, failing on absolute or `..` paths; its verdict is integrity-only
+  and names the rehearsal as the restore proof — the unpack and rehearse
+  steps stay in the script, deliberately. `doctor` stops reporting blind
+  unknowns for the store and clock when `NUCLEUS_URL` is set: read-only
+  liveness (`SELECT 1`) and skew against the store's own clock
+  (`SELECT now()`), each degrading to unknown rather than guessing, and
+  store consistency deliberately not probed at all (read-only, writers may
+  run — that proof is a rehearsal). The support bundle (`scriptVersion` 2)
+  now carries `doctor.json` and the latest backup manifest — the receipt,
+  never the archive — both degrading to note files.
 - **The takeover panel has a BROWSER tab (S12's last surface).** While a
   lease is held, the operator drives a real headless Chromium running inside
   the sandbox — the same one the visual and flow rungs use (the node and go
diff --git a/docs/BACKUP.md b/docs/BACKUP.md
index 5e4f7623..46807501 100644
--- a/docs/BACKUP.md
+++ b/docs/BACKUP.md
@@ -62,6 +62,38 @@ Environment: `SHIP_ROOT` (default `/deployments/ship`), `SHIP_BACKUP_DIR`
 (default `$SHIP_ROOT/_backups`), and for `rehearse` only: `SHIP_BIN`
 (default `teploy-ship`), `SHIP_NUCLEUS_IMAGE`, `SHIP_REHEARSE_TIMEOUT_S`.
 
+## The CLI commands: `snapshot` and `restore-check`
+
+The producer and the verifier are also first-class CLI commands, with the
+same invariants and the same archive shape — a backup taken with either tool
+verifies with both:
+
+```sh
+teploy-ship snapshot [--label NAME] [--ship-root DIR] [--backup-dir DIR]
+                     [--dry-run] [--i-stopped-writers] [--json]
+teploy-ship restore-check <archive> [--json]
+```
+
+- `snapshot` writes the identical `<label>-<date>/nucleus-data-full.tgz` +
+  `.sha256` sidecar + `manifest.txt` under `SHIP_BACKUP_DIR` (flags
+  `--ship-root`/`--backup-dir`, env `SHIP_ROOT`/`SHIP_BACKUP_DIR`, same
+  defaults as the script). It refuses while `ship-*` containers run unless
+  you attest the coordinated stop with `--i-stopped-writers`, never
+  overwrites an existing backup dir, and never deletes anything — except its
+  own partial output when a production fails, so a failed tar does not
+  occupy the label+date slot forever. Retention stays yours.
+- `restore-check` verifies an archive WITHOUT unpacking it: sha256 sidecar
+  (in `sha256sum -c` form — the sidecar must travel with its archive),
+  full-stream gzip integrity, and the tar content listing, failing on
+  absolute or `..` paths that would escape an unpack target. It is integrity
+  only: it says plainly that no engine has booted on the archive and points
+  at `scripts/ship-backup.sh rehearse` as the restore proof.
+
+The unpack (`restore --into` an empty isolated dir) and the rehearsal stay
+in the script, deliberately: they are the steps that touch a live recovery,
+and a shell script an operator reads line by line is the right shape for
+them.
+
 ## What the archive contains
 
 The complete engine data directory (`accessories/nucleus/nucleus-data`):
diff --git a/docs/SHIP_RELEASE_PROGRAMME_2026-09-21.md b/docs/SHIP_RELEASE_PROGRAMME_2026-09-21.md
index 837d2714..e5c93987 100644
--- a/docs/SHIP_RELEASE_PROGRAMME_2026-09-21.md
+++ b/docs/SHIP_RELEASE_PROGRAMME_2026-09-21.md
@@ -546,7 +546,7 @@ Same rules as wave 3: every change is off by default or observe-only, with tests
 | S15, S17 | #46 | none (inert modules) | `src/recovery-compat.ts` (migration-aware recovery check: unread or unclassified state holds; a newer contract or irreversible migration is incompatible; a recovery plan never counts as a pass) and `src/incident-evidence.ts` (facts, hypotheses and unknowns kept apart; other-service evidence set aside; fewer than five samples is unknown; confidence capped at medium) | 19 tests, 8 negative controls | Unwired; no migration-state reader; no page timeline; log excerpts clamped not redacted (callers must redact); no live incident |
 | S22 | #47 | `SHIP_MISSION_VIEW=on` (off) | Read-only mission view on the coordination page; accepted only when the task record says accepted; waivers shown as waived | 23 tests, 4 negative controls | No launching, persistence or replanning; planned-on revision not recorded on the client child, so a moved upstream with no delivery record is invisible |
 | S26 | #48 | `SHIP_PLACEMENT=shadow` (off) | Placement decision recorded beside the sandbox pool's host choice and the host-loss path; `placement shadow-report` | 19 tests through the real pool and durable path, 3 mutations | No enforcement; per-run architecture or browser needs not recorded; no drain concept in the pool; a failed liveness probe looks like a TTL expiry |
-| S19 | #49 | none (new command) | `teploy-ship doctor`: install prerequisites with pass, fail or unknown (unknown is never pass), secrets reported by presence only, redacted output; restore-readiness comparison module | 20 tests, 8 negative controls, planted-secret control | Store and clock probes report unknown; no snapshot producer or restore-check command; not in the support bundle; S04 not started |
+| S19 | #49 | none (new command) | `teploy-ship doctor`: install prerequisites with pass, fail or unknown (unknown is never pass), secrets reported by presence only, redacted output; restore-readiness comparison module. **S19 tail:** doctor answers store liveness (`SELECT 1`) and clock skew (against the store's own clock, `SELECT now()`) read-only when `NUCLEUS_URL` is set, unknown otherwise; `teploy-ship snapshot` produces the script's archive shape (tar + sha256 sidecar + manifest) and refuses running writers without `--i-stopped-writers`, never overwrites, never deletes; `teploy-ship restore-check` verifies an archive (sidecar + gzip integrity + content listing, no unpacking; integrity-only verdict names the rehearsal as the restore proof); the support bundle carries `doctor.json` + the latest backup manifest (never the archive) | 20 doctor tests + 4 live-probe tests (fake store client), 8 negative controls, planted-secret control; 11 snapshot/restore-check tests incl. negative controls (running-writer refusal with exact stop line, overwrite refusal, tampered sidecar, truncated archive with re-computed checksum caught by gzip, path-escape listing, failed-production cleanup); 2 bundle tests (doctor+receipt included, degrade to notes); CLI wiring type-checked only | S04 not started; doctor's clock stays unknown with no configured store or when the engine does not answer a time query (honest by design); the unpack and rehearsal remain script-only (`scripts/ship-backup.sh restore/rehearse`) — the CLI verifies without unpacking by design; restore-readiness comparison still has no command; nothing in the tail has run against a live store or live docker |
 | S13 | #50 | `SHIP_HARNESS_RECORD=on` (off) | Probes for plan-review, steer and investigate across native, claude-code and opencode (fake binaries); harness identity recorded as a sibling key on run-started (step fingerprint unchanged); "Ran on" block on the run page; credential-lifecycle tests | 15 root and 4 web tests, negative controls | Real vendor binaries; five operations unprobed; probes not run at startup or in CI |
 | S21 | #51 | `SHIP_KNOWLEDGE_PROVENANCE=off|shadow|on` (off) | Sidecar provenance store (new table, no migration); notes screened and labelled fresh, stale or unknown in `on`; redaction cascades on delete; summaries recorded as agent claims | 25 tests, 6 negative controls, durable step sequence identical across modes | No live Nucleus; freshness coarse; replay-exact derivation not available; cli.ts and agent.ts paths unwired; project scope is repo-only |
 | S24 | #52 | `SHIP_TOOL_MANIFEST=shadow|on`, `SHIP_EVENT_ENVELOPE=on` (both off) | `tool validate` dry-run CLI; manifest conformance findings recorded per tool call (never block); signed event envelope as extra webhook headers; client verification example | 14 tests, 4 negative controls, default-off header and body byte identity | The loop sees only the action kind, so host and secret findings cannot fire until the executor reports them; no tool registry or web view |
diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md
index 6cd4e224..98fd4b3c 100644
--- a/docs/SUPPORT.md
+++ b/docs/SUPPORT.md
@@ -29,6 +29,8 @@ states are recorded as note files inside the bundle instead.
 | `config-summary.json` | The known-safe Ship settings — a fixed **whitelist** of model ids, numbers, booleans, policy maps and URL hosts (`SHIP_MODEL`, `SHIP_MAX_STEPS`, `SHIP_SANDBOX_TTL_SEC`, `SHIP_WARM_PARKS`, `SHIP_PUBLIC_URL` as host, `SHIP_TELEMETRY`, `SHIP_INTAKE_POLICIES`, `SHIP_MIN_FREE_MB`, `SHIP_MAX_CONCURRENT_RUNS`, `SHIP_HARNESS_MODEL`). |
 | `runs-summary.json` | Counts by state over the read window, plus the 20 most recent runs: id, state, repo, createdAt, cost when attributed, and a one-line terminal error for failed runs. |
 | `selfwatch.txt` | The health snapshot from `src/selfwatch.ts` (queue depth, worker staleness, stuck runs) computed against the same store, plus its warnings. |
+| `doctor.json` | The redacted `teploy-ship doctor` report, run at assembly time with the same probes the command uses — live store liveness and clock skew when `NUCLEUS_URL` is set. Degrades to `doctor-unavailable.txt` when the doctor did not run or failed. |
+| `backup-receipt.txt` | The manifest of the newest backup under `SHIP_BACKUP_DIR` (default `$SHIP_ROOT/_backups`) — the receipt only; **the archive itself is never part of a bundle**. A note names where it looked when no backup exists. |
 | `logs/` | The last `--log-lines` lines of each `ship-*` container (`docker logs --tail`), or a note file explaining why not. |
 | `REDACTION-REPORT.txt` | Counts of every redaction the gate performed, by category. |
 
@@ -73,11 +75,21 @@ Every check reports `pass`, `fail` or `unknown`; **unknown is not pass**. The
 verdict is `ready` only when all pass, `not-ready` on any fail, `incomplete`
 when nothing failed but something could not be established. Exit code is 0 only
 for `ready`. Passing the `store-url` shape check does not mean the store was
-reached: `store-connectivity` stays `unknown` until a live check answers (use
-`teploy-ship preflight`). `--out` writes the redacted JSON, suitable to attach
-to a support request. The restore side is `src/restore-readiness.ts`, which
-compares backup and restored history snapshots and reports `unverified`
-whenever it did not actually compare; it is not yet exposed as a command.
+reached: with `NUCLEUS_URL` set, `store-connectivity` is probed read-only
+(`SELECT 1` — the rehearse proof's own liveness question) and `clock` measures
+skew against the store's own clock (`SELECT now()`); without a configured store,
+or when the engine does not answer a time query, both honestly stay `unknown` —
+store CONSISTENCY is deliberately not probed at all, because it cannot be
+established read-only while writers run (that proof is a snapshot rehearsal).
+`--out` writes the redacted JSON, suitable to attach to a support request.
+
+The snapshot side is now productized: `teploy-ship snapshot` produces the same
+archive shape as `scripts/ship-backup.sh backup` (see [BACKUP.md](BACKUP.md)),
+and `teploy-ship restore-check <archive>` verifies an archive — sha256 sidecar,
+gzip integrity, content listing — without unpacking it. The restore comparison
+module (`src/restore-readiness.ts`) still has no command of its own; the
+rehearsal (`scripts/ship-backup.sh rehearse`) plus `preflight` remain the
+restore proof.
 
 ## The support policy shape
 
diff --git a/src/args.ts b/src/args.ts
index 6ce82144..9d4ce697 100644
--- a/src/args.ts
+++ b/src/args.ts
@@ -76,6 +76,8 @@ export const COMMAND_FLAGS: Record<string, FlagSpec> = {
   web: { boolean: ["dev"], value: ["port", "token", "model"] },
   support: { value: ["out", "log-lines", "days"] },
   doctor: { boolean: ["json"], value: ["out"] },
+  snapshot: { boolean: ["dry-run", "i-stopped-writers", "json"], value: ["label", "ship-root", "backup-dir"] },
+  "restore-check": { boolean: ["json"] },
   eval: { boolean: ["critic", "settle"], value: ["model", "suite", "repeats"] },
 };
 
diff --git a/src/cli.ts b/src/cli.ts
index 044c8595..45241e77 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -85,7 +85,16 @@ import { NucleusCodeIndex } from "./code-index.js";
 import type { CodeSearch } from "./code-index.js";
 import { startWorker } from "./worker.js";
 import { assembleSupportBundle, defaultDocker } from "./support.js";
-import { defaultProbes, formatDoctor, renderDoctor, runDoctor } from "./install-doctor.js";
+import { defaultProbes, formatDoctor, nucleusProbes, renderDoctor, runDoctor } from "./install-doctor.js";
+import {
+  DEFAULT_SHIP_ROOT,
+  SnapshotRefusal,
+  defaultSnapshotDocker,
+  formatRestoreCheck,
+  latestBackupReceipt,
+  produceSnapshot,
+  runRestoreCheck,
+} from "./snapshot.js";
 import { costUSD, isPricedModel } from "./pricing.js";
 import { defaultRetryPolicy, withRetry, withCallTimeout, modelTimeoutFromEnv } from "./provider.js";
 import { builtinSuite } from "./tasks.js";
@@ -205,10 +214,27 @@ Usage:
       [--port N] [--token <t>]        token also via SHIP_WEB_TOKEN (required)
       [--dev]                         vite dev server instead of the built app
   teploy-ship doctor [--json] [--out f]  check this machine is ready (pass|fail|unknown; unknown is not pass)
+                                       store liveness and clock skew are probed read-only
+                                       when NUCLEUS_URL is set; without a store they
+                                       stay unknown — nothing is guessed
+  teploy-ship snapshot [--label NAME] [--ship-root DIR] [--backup-dir DIR]
+                      [--dry-run] [--i-stopped-writers] [--json]
+                                       consistent-snapshot producer (same archive shape
+                                       as scripts/ship-backup.sh: tar of the nucleus
+                                       data dir + sha256 sidecar + manifest). Refuses
+                                       while ship-* containers run unless you attest
+                                       the coordinated stop; never overwrites, never
+                                       deletes. Retention is yours.
+  teploy-ship restore-check <archive> [--json]
+                                       verify an archive WITHOUT unpacking it: sha256
+                                       sidecar, gzip integrity, content listing.
+                                       Integrity only — the proof an archive restores
+                                       is scripts/ship-backup.sh rehearse
   teploy-ship support                 assemble a REDACTED diagnostic bundle (see docs/SUPPORT.md)
       [--out DIR] [--log-lines N]     what a vendor needs: versions, safe config keys,
-      [--days N]                      bounded logs, run-state summaries. Credentials
-                                      never enter it, but skim it before handing it over.
+      [--days N]                      bounded logs, run-state summaries, the doctor
+                                       report and the latest backup receipt. Credentials
+                                       never enter it, but skim it before handing it over.
   teploy-ship eval [--suite builtin|hard|extreme|all] [--repeats N] [--json] [--critic] [--settle]
 
 Config: flags > env > ~/.config/teploy-ship/config.json
@@ -2401,6 +2427,7 @@ async function supportCommand(rest: string[]): Promise<void> {
   const logLines = numFlag(args.flags["log-lines"], "log-lines", 200, { min: 1, max: 2000, integer: true });
   const days = args.flags.days !== undefined ? numFlag(args.flags.days, "days", 7, { min: 1, max: 3650, integer: true }) : undefined;
   const runtime = await makeRuntime(args, config);
+  const backupDir = process.env.SHIP_BACKUP_DIR ?? join(process.env.SHIP_ROOT ?? DEFAULT_SHIP_ROOT, "_backups");
   let result;
   try {
     result = await assembleSupportBundle({
@@ -2410,6 +2437,10 @@ async function supportCommand(rest: string[]): Promise<void> {
       store: runtime,
       config: { model: config.model, intake: config.intake, maxConcurrentRuns: config.maxConcurrentRuns, nucleusUrl: config.nucleusUrl },
       docker: defaultDocker(),
+      // The doctor report and the latest backup manifest (never the archive)
+      // ride along; both degrade to note files inside the bundle.
+      doctorJson: async () => renderDoctor(await runDoctor(doctorProbes())).json,
+      backupReceipt: () => latestBackupReceipt(backupDir),
     });
   } finally {
     await runtime.close();
@@ -2429,19 +2460,88 @@ async function supportCommand(rest: string[]): Promise<void> {
 // doctor — S19 install-readiness checks (all logic in src/install-doctor.ts)
 // ---------------------------------------------------------------------------
 
+/** The doctor probes every command shares: local checks always, live store checks when NUCLEUS_URL is set. */
+function doctorProbes(): ReturnType<typeof defaultProbes> {
+  const port = Number(process.env.SHIP_WEB_PORT ?? process.env.PORT ?? 7460);
+  const probes = defaultProbes({
+    env: process.env,
+    stateDir: stateDir(),
+    webPort: Number.isInteger(port) ? port : 7460,
+    nodeVersion: process.version,
+  });
+  const url = process.env.NUCLEUS_URL;
+  if (url !== undefined && url.trim() !== "") {
+    // Read-only liveness + the store's clock as the skew reference. With no
+    // configured store there is nothing to ask: connectivity and skew stay
+    // unknown rather than guessed.
+    Object.assign(probes, nucleusProbes(url));
+  }
+  return probes;
+}
+
 /** Exit 0 only for "ready"; 1 for not-ready or incomplete (unknown is not pass). */
 async function doctorCommand(rest: string[]): Promise<void> {
   const args = parseArgs(rest, COMMAND_FLAGS.doctor);
-  const port = Number(process.env.SHIP_WEB_PORT ?? process.env.PORT ?? 7460);
-  const report = await runDoctor(
-    defaultProbes({ env: process.env, stateDir: stateDir(), webPort: Number.isInteger(port) ? port : 7460, nodeVersion: process.version }),
-  );
+  const report = await runDoctor(doctorProbes());
   const rendered = renderDoctor(report);
   if (typeof args.flags.out === "string") writeFileSync(args.flags.out, rendered.json);
   process.stdout.write(args.flags.json === true ? rendered.json : formatDoctor(report));
   if (report.verdict !== "ready") process.exitCode = 1;
 }
 
+// ---------------------------------------------------------------------------
+// snapshot + restore-check — S19 tail, the CLI half of scripts/ship-backup.sh
+// (all logic in src/snapshot.ts)
+// ---------------------------------------------------------------------------
+
+async function snapshotCommand(rest: string[]): Promise<void> {
+  const args = parseArgs(rest, COMMAND_FLAGS.snapshot);
+  if (args.positional.length > 0) fail("snapshot takes no positional arguments — everything is a flag");
+  const label = (args.flags.label as string | undefined) ?? "manual";
+  const shipRoot = (args.flags["ship-root"] as string | undefined) ?? process.env.SHIP_ROOT ?? DEFAULT_SHIP_ROOT;
+  const backupDir = (args.flags["backup-dir"] as string | undefined) ?? process.env.SHIP_BACKUP_DIR ?? join(shipRoot, "_backups");
+  let result;
+  try {
+    result = await produceSnapshot({
+      shipRoot,
+      backupDir,
+      label,
+      dryRun: args.flags["dry-run"] === true,
+      attested: args.flags["i-stopped-writers"] === true,
+      docker: defaultSnapshotDocker(),
+      log: (line) => process.stderr.write(`${dim(line)}\n`),
+    });
+  } catch (error) {
+    if (error instanceof SnapshotRefusal) fail(error.message);
+    throw error;
+  }
+  for (const note of result.advisory) process.stderr.write(`${yellow(note)}\n`);
+  if (result.status === "dry-run") {
+    process.stdout.write(`dry-run: would create ${result.dir}/\n`);
+    process.stdout.write(`  archive   ${result.archive}  (tar czf of ${join(shipRoot, "accessories", "nucleus", "nucleus-data")})\n`);
+    process.stdout.write(`  sidecar   ${result.archive}.sha256\n`);
+    process.stdout.write(`  manifest  ${join(result.dir, "manifest.txt")}\n`);
+    process.stdout.write("  then checksum-verify + gzip-test the archive\n");
+    process.stdout.write("no files written\n");
+  } else {
+    process.stdout.write(`snapshot complete: ${result.archive} (${result.bytes} bytes, sha256 ${result.sha256})\n`);
+    process.stdout.write(`verify:   teploy-ship restore-check ${result.archive}\n`);
+    process.stdout.write(`rehearse: scripts/ship-backup.sh rehearse ${result.archive}\n`);
+    process.stdout.write("retention is yours: this command never deletes a backup\n");
+  }
+  if (args.flags.json === true) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+/** Verify without unpacking; exit 0 only for "verified". */
+async function restoreCheckCommand(rest: string[]): Promise<void> {
+  const args = parseArgs(rest, COMMAND_FLAGS["restore-check"]);
+  if (args.positional.length < 1) fail("restore-check needs an archive path");
+  if (args.positional.length > 1) fail("restore-check takes one argument");
+  const report = await runRestoreCheck(args.positional[0]!);
+  process.stdout.write(args.flags.json === true ? `${JSON.stringify(report, null, 2)}\n` : formatRestoreCheck(report));
+  if (report.verdict !== "verified") process.exitCode = 1;
+}
+
 // ---------------------------------------------------------------------------
 
 async function main(): Promise<void> {
@@ -2503,6 +2603,10 @@ async function main(): Promise<void> {
       return supportCommand(rest);
     case "doctor":
       return doctorCommand(rest);
+    case "snapshot":
+      return snapshotCommand(rest);
+    case "restore-check":
+      return restoreCheckCommand(rest);
     case "eval":
       return evalCommand(rest);
     default:
diff --git a/src/install-doctor.test.ts b/src/install-doctor.test.ts
index b38b2ef7..49efb96c 100644
--- a/src/install-doctor.test.ts
+++ b/src/install-doctor.test.ts
@@ -5,8 +5,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
 
-import { MAX_CLOCK_SKEW_MS, defaultProbes, formatDoctor, renderDoctor, runDoctor } from "./install-doctor.js";
-import type { DoctorProbes } from "./install-doctor.js";
+import { MAX_CLOCK_SKEW_MS, defaultProbes, formatDoctor, nucleusProbes, renderDoctor, runDoctor } from "./install-doctor.js";
+import type { DoctorProbes, StoreQueryClient } from "./install-doctor.js";
 
 // Fake secrets assembled at runtime so no secret-shaped literal sits in source.
 const FAKE_WEB_TOKEN = "webtok" + "-" + "Zq9".repeat(8);
@@ -174,3 +174,69 @@ test("real write probe against an unwritable path fails", async () => {
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// nucleusProbes — the live store probes doctorCommand injects with NUCLEUS_URL
+// ---------------------------------------------------------------------------
+
+/** A fake store client: answers per-SQL, so the probes' read-only surface is pinned. */
+function fakeClient(behavior: { sql?: (sql: string) => unknown; error?: (sql: string) => Error | undefined }): StoreQueryClient {
+  return {
+    async query(sql: string) {
+      const error = behavior.error?.(sql);
+      if (error !== undefined) throw error;
+      const value = behavior.sql?.(sql);
+      return value === undefined ? [] : [{ t: value }];
+    },
+    async close() {},
+  };
+}
+
+test("nucleusProbes: liveness is SELECT 1, answered true, unanswered false — never unknown-pass", async () => {
+  const probes = nucleusProbes("postgres://store:5432/ship", { connect: () => fakeClient({}) });
+  assert.equal(await probes.storeReachable("postgres://store:5432/ship"), true, "a store that answers SELECT 1 is reachable");
+
+  const dead = nucleusProbes("postgres://store:5432/ship", {
+    connect: () => fakeClient({ error: () => new Error("ECONNREFUSED") }),
+  });
+  assert.equal(await dead.storeReachable("postgres://store:5432/ship"), false, "a store that does not answer is fail, not unknown");
+});
+
+test("nucleusProbes: the store's clock is the reference — Date, epoch-number and ISO string all parse", async () => {
+  const ref = NOW - 2_000;
+  const byDate = nucleusProbes("postgres://s/x", { connect: () => fakeClient({ sql: () => new Date(ref) }) });
+  const byNumber = nucleusProbes("postgres://s/x", { connect: () => fakeClient({ sql: () => ref }) });
+  const byString = nucleusProbes("postgres://s/x", { connect: () => fakeClient({ sql: () => new Date(ref).toISOString() }) });
+  assert.equal(await byDate.referenceMs(), ref);
+  assert.equal(await byNumber.referenceMs(), ref);
+  assert.equal(await byString.referenceMs(), ref);
+});
+
+test("nucleusProbes: a store without a time query degrades the clock to unknown, never a guess", async () => {
+  const noTime = nucleusProbes("postgres://s/x", { connect: () => fakeClient({ sql: (sql) => (sql.includes("now()") ? "not-a-time" : undefined) }) });
+  assert.equal(await noTime.referenceMs(), undefined);
+  const throwing = nucleusProbes("postgres://s/x", { connect: () => fakeClient({ error: (sql) => (sql.includes("now()") ? new Error("unknown function") : undefined) }) });
+  assert.equal(await throwing.referenceMs(), undefined);
+
+  // And doctor reports that honestly: reachable store, clock unknown.
+  const r = await runDoctor(allGood({ ...nucleusProbes("postgres://s/x", { connect: () => fakeClient({ sql: (sql) => (sql.includes("now()") ? "not-a-time" : undefined) }) }) }));
+  assert.equal(byId(r, "store-connectivity").status, "pass");
+  assert.equal(byId(r, "clock").status, "unknown");
+  assert.equal(r.verdict, "incomplete");
+});
+
+test("nucleusProbes wired through runDoctor: an answering store with its clock is ready; a silent store fails connectivity", async () => {
+  const good = await runDoctor(allGood({ ...nucleusProbes("postgres://s/x", { connect: () => fakeClient({ sql: () => new Date(NOW + 1000) }) }) }));
+  assert.equal(good.verdict, "ready");
+  assert.equal(byId(good, "store-connectivity").status, "pass");
+  assert.equal(byId(good, "clock").status, "pass");
+
+  const silent = await runDoctor(
+    allGood({
+      ...nucleusProbes("postgres://s/x", { connect: () => fakeClient({ error: () => new Error("connection refused") }) }),
+    }),
+  );
+  assert.equal(byId(silent, "store-connectivity").status, "fail");
+  assert.equal(byId(silent, "clock").status, "unknown");
+  assert.equal(silent.verdict, "not-ready");
+});
diff --git a/src/install-doctor.ts b/src/install-doctor.ts
index 406eb8b1..ea11e883 100644
--- a/src/install-doctor.ts
+++ b/src/install-doctor.ts
@@ -17,8 +17,10 @@
  *    to pass tells a fresh operator they are ready when nobody looked.
  * 2. **Shape is not connectivity.** The store-url check parses NUCLEUS_URL and
  *    never opens a socket; the separate store-connectivity check is "unknown"
- *    unless a connect probe was injected and answered. Passing the first must
- *    not read as passing the second.
+ *    unless a connect probe was injected and answered. The CLI injects the
+ *    read-only `nucleusProbes` when NUCLEUS_URL is set; with no configured
+ *    store there is nothing to ask and connectivity honestly stays unknown.
+ *    Passing the first must not read as passing the second.
  * 3. **Values never leave.** Env checks report presence only, never the value
  *    or its length, and the whole report passes the support RedactionGate
  *    before it is emitted (`renderDoctor`), so even a detail string that
@@ -34,6 +36,7 @@ import { mkdir, rm, statfs, writeFile } from "node:fs/promises";
 import { createServer } from "node:net";
 import { join } from "node:path";
 
+import { NucleusPgwire } from "./nucleus-pgwire.js";
 import { RedactionGate } from "./support.js";
 
 export type CheckStatus = "pass" | "fail" | "unknown";
@@ -259,3 +262,66 @@ export function defaultProbes(base: Pick<DoctorProbes, "env" | "stateDir" | "web
       }),
   };
 }
+
+// ---------------------------------------------------------------------------
+// live store probes — read-only, or honestly unknown
+// ---------------------------------------------------------------------------
+
+/** The read-only query surface the live probes need. */
+export interface StoreQueryClient {
+  query(sql: string): Promise<Record<string, unknown>[]>;
+  close(): Promise<void>;
+}
+
+export interface LiveStoreProbes {
+  storeReachable: NonNullable<DoctorProbes["storeReachable"]>;
+  referenceMs: () => Promise<number | undefined>;
+}
+
+/**
+ * Real read-only probes against the store NUCLEUS_URL names — the one this
+ * machine will actually run on, so asking it is not new network surface.
+ *
+ * `storeReachable` is liveness only (`SELECT 1`, the rehearse proof's own
+ * question). `referenceMs` asks the store its clock (`SELECT now()`); the
+ * store's clock is the independent reference the skew check needs, and when
+ * the engine does not answer a time query the clock check stays UNKNOWN and
+ * says why — never a guessed reference. What is deliberately NOT probed:
+ * anything write-shaped, and store CONSISTENCY, which cannot be established
+ * read-only while writers run (that proof is a snapshot rehearsal, not a
+ * doctor check).
+ */
+export function nucleusProbes(url: string, deps: { connect?: () => StoreQueryClient } = {}): LiveStoreProbes {
+  const connect = deps.connect ?? (() => new NucleusPgwire(url, "doctor"));
+  return {
+    storeReachable: async () => {
+      const client = connect();
+      try {
+        await client.query("SELECT 1");
+        return true;
+      } catch {
+        return false;
+      } finally {
+        await client.close().catch(() => {});
+      }
+    },
+    referenceMs: async () => {
+      const client = connect();
+      try {
+        const rows = await client.query("SELECT now() AS t");
+        const value = Object.values(rows[0] ?? {})[0];
+        if (value instanceof Date) return value.getTime();
+        if (typeof value === "number" && Number.isFinite(value)) return value;
+        if (typeof value === "string") {
+          const t = Date.parse(value);
+          if (Number.isFinite(t)) return t;
+        }
+        return undefined;
+      } catch {
+        return undefined;
+      } finally {
+        await client.close().catch(() => {});
+      }
+    },
+  };
+}
diff --git a/src/snapshot.test.ts b/src/snapshot.test.ts
new file mode 100644
index 00000000..4ebd6838
--- /dev/null
+++ b/src/snapshot.test.ts
@@ -0,0 +1,332 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, truncateSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import {
+  ARCHIVE_NAME,
+  NUCLEUS_DATA_REL,
+  SnapshotRefusal,
+  latestBackupReceipt,
+  produceSnapshot,
+  runRestoreCheck,
+  verifyArchive,
+} from "./snapshot.js";
+import type { ShipContainerLine, SnapshotDocker } from "./snapshot.js";
+
+/**
+ * The snapshot producer guards the only copy of Ship's history, so its
+ * refusals are the product. Every test runs against a FAKE ship root in a
+ * temp dir and an injected docker — nothing here needs a live engine, a real
+ * docker socket, or /deployments. tar itself is real (the same binary the
+ * script and the producer shell out to).
+ */
+
+const NOW = new Date(2026, 9, 4, 12, 0, 0);
+const STAMP = "2026-10-04";
+
+const RUNNING: ShipContainerLine[] = [
+  { name: "ship-web-1a2b3c", image: "nexus/ship:v9", id: "cid1" },
+  { name: "ship-worker-4d5e6f", image: "nexus/ship:v9", id: "cid2" },
+  { name: "ship-nucleus-7g8h9i", image: "neutron-build/nucleus:v1.1.1", id: "cid3" },
+];
+
+function docker(over: { running?: ShipContainerLine[] | undefined; known?: ShipContainerLine[] | undefined } = {}): SnapshotDocker {
+  return {
+    running: async () => ("running" in over ? over.running : []),
+    known: async () => ("known" in over ? over.known : []),
+  };
+}
+
+function fakeShipRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "ship-snapshot-test-"));
+  const data = join(dir, NUCLEUS_DATA_REL);
+  mkdirSync(join(data, "deep"), { recursive: true });
+  writeFileSync(join(data, "runs.log"), "run-1 completed\nrun-2 failed\n");
+  writeFileSync(join(data, "deep", "wal.json"), '{"wal":"v2"}');
+  return dir;
+}
+
+const digestOf = (path: string): string => createHash("sha256").update(readFileSync(path)).digest("hex");
+
+function onlyArchiveDir(backupDir: string): string {
+  const found = readdirSync(backupDir).filter((d) => d !== "rehearsals");
+  assert.equal(found.length, 1, `expected exactly one backup dir, saw ${found.join(",")}`);
+  return join(backupDir, found[0]!);
+}
+
+async function produce(root: string, over: Omit<Partial<Parameters<typeof produceSnapshot>[0]>, "shipRoot"> = {}) {
+  return produceSnapshot({ shipRoot: root, label: "proof", now: () => NOW, docker: docker(), ...over });
+}
+
+test("produces the script's archive shape: tar + sha256 sidecar + manifest", async () => {
+  const root = fakeShipRoot();
+  try {
+    const result = await produce(root);
+    assert.equal(result.status, "produced");
+    const dest = join(root, "_backups", `proof-${STAMP}`);
+    assert.equal(result.dir, dest);
+    const archive = join(dest, ARCHIVE_NAME);
+    assert.ok(existsSync(archive), "no archive");
+    assert.equal(result.sha256, digestOf(archive), "reported digest is the archive's actual digest");
+    assert.equal(readFileSync(`${archive}.sha256`, "utf8"), `${digestOf(archive)}  ${ARCHIVE_NAME}\n`, "sidecar is sha256sum format");
+    const manifest = readFileSync(join(dest, "manifest.txt"), "utf8");
+    assert.match(manifest, /^ship-backup manifest \(teploy-ship snapshot version \d+\.\d+\.\d+\)/m);
+    assert.match(manifest, /^date: \S+/m);
+    assert.match(manifest, /^hostname: \S+/m);
+    assert.match(manifest, /^bytes: \d+/m);
+    assert.match(manifest, new RegExp(`^sha256: ${digestOf(archive)}$`, "m"), "manifest sha256 is the archive's actual digest");
+    assert.match(manifest, /none found/, "writer check answered and found none");
+    // Roots at nucleus-data/, exactly like the script — a restore must not
+    // tar-bomb its target.
+    const listing = spawnSync("tar", ["-tzf", archive], { encoding: "utf8" }).stdout;
+    assert.match(listing, /^nucleus-data\/runs\.log$/m);
+    assert.match(listing, /^nucleus-data\/deep\/wal\.json$/m);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("NEGATIVE CONTROL: refuses while ship containers run, names the exact stop, writes nothing", async () => {
+  const root = fakeShipRoot();
+  try {
+    await assert.rejects(
+      produce(root, { docker: docker({ running: RUNNING, known: RUNNING }) }),
+      (error: unknown) => {
+        assert.ok(error instanceof SnapshotRefusal);
+        assert.match(error.message, /ship containers are still running/);
+        assert.match(error.message, /docker stop ship-web-1a2b3c ship-worker-4d5e6f ship-nucleus-7g8h9i/, "must print the exact coordinated stop");
+        assert.match(error.message, /--i-stopped-writers/);
+        return true;
+      },
+    );
+    assert.ok(!existsSync(join(root, "_backups")), "the refused snapshot must have written nothing");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("--i-stopped-writers attests past the refusal and the manifest records what docker knew", async () => {
+  const root = fakeShipRoot();
+  try {
+    const result = await produce(root, { attested: true, docker: docker({ running: RUNNING, known: RUNNING }) });
+    assert.equal(result.status, "produced");
+    const manifest = readFileSync(join(result.dir, "manifest.txt"), "utf8");
+    assert.match(manifest, /ship-worker-4d5e6f\s+nexus\/ship:v9\s+cid2/, "manifest records the running containers");
+    assert.match(manifest, /ship-nucleus-7g8h9i\s+neutron-build\/nucleus:v1\.1\.1/, "manifest records the engine image rollback needs");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("docker unavailable is advisory, not a refusal — a box without docker can still snapshot", async () => {
+  const root = fakeShipRoot();
+  try {
+    const result = await produce(root, { docker: { running: async () => undefined, known: async () => undefined } });
+    assert.equal(result.status, "produced");
+    assert.ok(result.advisory.some((a) => /writer check skipped \(advisory\)/.test(a)), "the advisory is reported");
+    const manifest = readFileSync(join(result.dir, "manifest.txt"), "utf8");
+    assert.match(manifest, /docker unavailable — not checked \(advisory\)/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("NEGATIVE CONTROL: never overwrites — a second snapshot of the same label+date refuses, original untouched", async () => {
+  const root = fakeShipRoot();
+  try {
+    const first = await produce(root);
+    const before = readFileSync(first.archive);
+    await assert.rejects(produce(root), (error: unknown) => {
+      assert.ok(error instanceof SnapshotRefusal);
+      assert.match(error.message, /refusing to overwrite existing backup dir/);
+      return true;
+    });
+    assert.deepEqual(readFileSync(first.archive), before, "the existing backup's bytes are unchanged");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("dry-run prints a plan and writes nothing", async () => {
+  const root = fakeShipRoot();
+  try {
+    const result = await produce(root, { dryRun: true });
+    assert.equal(result.status, "dry-run");
+    assert.equal(result.dir, join(root, "_backups", `proof-${STAMP}`));
+    assert.ok(!existsSync(join(root, "_backups")), "dry-run must not create the backup dir");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a missing engine data dir and a bad label are refusals", async () => {
+  const empty = mkdtempSync(join(tmpdir(), "ship-snapshot-empty-"));
+  try {
+    await assert.rejects(produce(empty), /engine data dir not found/);
+    const root = fakeShipRoot();
+    try {
+      await assert.rejects(produce(root, { label: "../evil" }), /label must start alphanumeric/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  } finally {
+    rmSync(empty, { recursive: true, force: true });
+  }
+});
+
+test("a failed production removes only its own partial output, never the source store", async () => {
+  const root = fakeShipRoot();
+  try {
+    await assert.rejects(
+      produce(root, {
+        runTar: async () => {
+          throw new Error("tar exploded");
+        },
+      }),
+      /tar exploded/,
+    );
+    assert.ok(!existsSync(join(root, "_backups", `proof-${STAMP}`)), "the failed run's partial dir is gone");
+    assert.ok(existsSync(join(root, NUCLEUS_DATA_REL, "runs.log")), "the live store is untouched");
+    // The slot is free again after the failure — the never-overwrite rule must
+    // not be wedged by output nobody completed.
+    const retry = await produce(root);
+    assert.equal(retry.status, "produced");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// verifyArchive / restore-check
+// ---------------------------------------------------------------------------
+
+test("verifyArchive passes a produced archive; tampered sidecar, wrong-name sidecar and missing sidecar each fail", async () => {
+  const root = fakeShipRoot();
+  try {
+    const result = await produce(root);
+    const archive = result.archive;
+    assert.deepEqual(await verifyArchive(archive), { ok: true, sha256: result.sha256 });
+
+    // Copies keep the canonical basename (a sidecar must travel with its
+    // archive under the name it records), so each lives in its own subdir.
+    const tamperedDir = join(root, "tampered");
+    mkdirSync(tamperedDir);
+    const tampered = join(tamperedDir, ARCHIVE_NAME);
+    copyFileSync(archive, tampered);
+    writeFileSync(`${tampered}.sha256`, `0000000000000000000000000000000000000000000000000000000000000000  ${ARCHIVE_NAME}\n`);
+    const bad = await verifyArchive(tampered);
+    assert.ok(!bad.ok && /checksum mismatch/.test(bad.reason ?? ""), bad.ok ? "" : (bad.reason ?? ""));
+
+    const renamed = join(root, "renamed.tgz");
+    copyFileSync(archive, renamed);
+    copyFileSync(`${archive}.sha256`, `${renamed}.sha256`);
+    const wrongName = await verifyArchive(renamed);
+    assert.ok(!wrongName.ok && /sidecar names/.test(wrongName.reason ?? ""));
+
+    const naked = join(root, "naked.tgz");
+    copyFileSync(archive, naked);
+    const noSidecar = await verifyArchive(naked);
+    assert.ok(!noSidecar.ok && /missing checksum sidecar/.test(noSidecar.reason ?? ""));
+
+    const ghost = await verifyArchive(join(root, "ghost.tgz"));
+    assert.ok(!ghost.ok && /no such archive/.test(ghost.reason ?? ""));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("NEGATIVE CONTROL: a truncated archive with a re-computed sidecar fails gzip integrity — the checksum alone cannot catch it", async () => {
+  const root = fakeShipRoot();
+  try {
+    const result = await produce(root);
+    const truncatedDir = join(root, "truncated");
+    mkdirSync(truncatedDir);
+    const truncated = join(truncatedDir, ARCHIVE_NAME);
+    copyFileSync(result.archive, truncated);
+    truncateSync(truncated, Math.floor(statSync(truncated).size / 2));
+    const digest = digestOf(truncated);
+    writeFileSync(`${truncated}.sha256`, `${digest}  ${ARCHIVE_NAME}\n`);
+
+    const verified = await verifyArchive(truncated);
+    assert.ok(!verified.ok && /gzip integrity failure/.test(verified.reason ?? ""), "gzip must catch what the checksum cannot");
+
+    const report = await runRestoreCheck(truncated);
+    assert.equal(report.verdict, "not-verified");
+    assert.equal(report.sha256.status, "pass", "the re-computed sidecar does its job");
+    assert.equal(report.gzip.status, "fail");
+    assert.equal(report.contents.status, "unknown", "contents are not checked past a failed integrity check");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("restore-check verifies a produced archive without unpacking and names what it does not prove", async () => {
+  const root = fakeShipRoot();
+  try {
+    const result = await produce(root);
+    const report = await runRestoreCheck(result.archive);
+    assert.equal(report.verdict, "verified");
+    assert.equal(report.sha256.status, "pass");
+    assert.equal(report.gzip.status, "pass");
+    assert.equal(report.contents.status, "pass");
+    assert.ok(report.contents.entries >= 2);
+    assert.deepEqual(report.contents.roots, ["nucleus-data"]);
+    assert.match(report.notProven, /rehearse/, "the rehearsal is named as the restore proof");
+    // Nothing was unpacked: only the backup dir exists under the root.
+    assert.deepEqual(readdirSync(join(root, "_backups")).filter((d) => d !== "rehearsals"), [`proof-${STAMP}`]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("NEGATIVE CONTROL: listing entries that would escape the unpack target fail the contents check", async () => {
+  const root = fakeShipRoot();
+  try {
+    const result = await produce(root);
+    const report = await runRestoreCheck(result.archive, {
+      listArchive: async () => ["nucleus-data/runs.log", "../evil.sh", "/etc/passwd"],
+    });
+    assert.equal(report.verdict, "not-verified");
+    assert.equal(report.sha256.status, "pass");
+    assert.equal(report.gzip.status, "pass");
+    assert.equal(report.contents.status, "fail");
+    assert.match(report.contents.detail, /\.\.\/evil\.sh/);
+    assert.match(report.contents.detail, /\/etc\/passwd/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// the support-bundle receipt
+// ---------------------------------------------------------------------------
+
+test("latestBackupReceipt picks the newest manifest, skips rehearsals, and is bounded", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "ship-receipt-test-"));
+  try {
+    assert.equal(await latestBackupReceipt(dir), undefined, "empty backup dir has no receipt");
+
+    mkdirSync(join(dir, "older-2026-10-01"));
+    writeFileSync(join(dir, "older-2026-10-01", "manifest.txt"), "ship-backup manifest (script version 1.0.0)\ndate: older\n");
+    mkdirSync(join(dir, "newer-2026-10-04"));
+    writeFileSync(join(dir, "newer-2026-10-04", "manifest.txt"), "ship-backup manifest (script version 1.0.0)\ndate: newer\n");
+    mkdirSync(join(dir, "rehearsals", "rehearse-1"), { recursive: true });
+    writeFileSync(join(dir, "rehearsals", "rehearse-1", "manifest.txt"), "not a backup\n");
+    mkdirSync(join(dir, "not-a-backup"));
+    const t0 = new Date(2026, 9, 1);
+    utimesSync(join(dir, "older-2026-10-01", "manifest.txt"), t0, t0);
+
+    const receipt = await latestBackupReceipt(dir);
+    assert.ok(receipt !== undefined);
+    assert.equal(receipt.name, "newer-2026-10-04");
+    assert.equal(receipt.backupDir, dir);
+    assert.match(receipt.text, /date: newer/);
+    assert.ok(!receipt.text.includes("rehearse"), "the rehearsal dir is not the receipt");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/src/snapshot.ts b/src/snapshot.ts
new file mode 100644
index 00000000..b987dc44
--- /dev/null
+++ b/src/snapshot.ts
@@ -0,0 +1,462 @@
+/**
+ * S19 tail: the snapshot producer (`teploy-ship snapshot`) and the
+ * restore-check command — the CLI half of the practiced procedure in
+ * scripts/ship-backup.sh, whose invariants are load-bearing here too:
+ *
+ *  - A consistent snapshot needs the COORDINATED STOP (ship web + worker +
+ *    the nucleus engine). The producer refuses while any ship-* container it
+ *    can see is running and prints the exact stop it expects;
+ *    `--i-stopped-writers` is the operator's attestation that the stop
+ *    happened (joined workers are systemd units this box's docker cannot
+ *    see). A tar of a live store is a corrupt archive with a backup's name.
+ *  - Backups are never overwritten, and nothing in this module ever deletes
+ *    a backup. The only removal is this run's OWN partial output after a
+ *    failed production — otherwise a failed tar would occupy the label+date
+ *    slot forever, because the never-overwrite rule would refuse every retry.
+ *    Retention is the operator's alone.
+ *  - restore-check verifies WITHOUT unpacking over anything. The unpack
+ *    itself stays in the script (`restore --into` an empty isolated dir);
+ *    the proof an archive restores into a working store is the rehearsal.
+ *
+ * Every dependency (docker, tar, clock) is injected, so the refusals are
+ * unit-tested against fake fixtures — never a live engine or docker socket.
+ */
+
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+
+import { RedactionGate } from "./support.js";
+
+export const SNAPSHOT_VERSION = "1.0.0";
+export const DEFAULT_SHIP_ROOT = "/deployments/ship";
+export const NUCLEUS_DATA_REL = "accessories/nucleus/nucleus-data";
+export const ARCHIVE_NAME = "nucleus-data-full.tgz";
+/** A manifest bigger than this is not a manifest this command ever wrote. */
+export const RECEIPT_MAX_BYTES = 64 * 1024;
+
+/** A refusal is the product: it says what to stop, never what to ignore. */
+export class SnapshotRefusal extends Error {}
+
+function refuse(message: string): never {
+  throw new SnapshotRefusal(message);
+}
+
+function capture(bin: string, args: string[], timeoutMs = 120_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(bin, args, { timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error !== null) {
+        reject(new Error(stderr !== "" && stderr !== undefined ? `${bin}: ${String(stderr).trim()}` : error.message));
+        return;
+      }
+      resolve(String(stdout));
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// docker: which writers are still alive
+// ---------------------------------------------------------------------------
+
+export interface ShipContainerLine {
+  name: string;
+  image: string;
+  id: string;
+}
+
+export interface SnapshotDocker {
+  /**
+   * Running ship-* containers. `undefined` means docker is absent or
+   * unreachable: a box without docker must still be able to take a snapshot,
+   * so that state is advisory, never a refusal.
+   */
+  running(): Promise<ShipContainerLine[] | undefined>;
+  /** Every ship-* container docker knows about (`docker ps -a`) — the manifest
+   * records the engine image because a Nucleus rollback is
+   * restore-archive-with-matching-image, not an image swap. */
+  known(): Promise<ShipContainerLine[] | undefined>;
+}
+
+function ps(bin: string, all: boolean, prefix: string): Promise<ShipContainerLine[] | undefined> {
+  const args = ["ps", ...(all ? ["-a"] : []), "--format", "{{.Names}}\t{{.Image}}\t{{.ID}}"];
+  return capture(bin, args, 30_000).then(
+    (out) =>
+      out
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+          const [name, image, id] = l.split("\t");
+          return { name: name ?? "", image: image ?? "", id: id ?? "" };
+        })
+        .filter((c) => c.name.startsWith(prefix)),
+    () => undefined,
+  );
+}
+
+export function defaultSnapshotDocker(bin = "docker", prefix = "ship-"): SnapshotDocker {
+  return {
+    running: () => ps(bin, false, prefix),
+    known: () => ps(bin, true, prefix),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// checksum + gzip integrity
+// ---------------------------------------------------------------------------
+
+async function sha256File(path: string): Promise<string> {
+  const h = createHash("sha256");
+  for await (const chunk of createReadStream(path)) h.update(chunk);
+  return h.digest("hex");
+}
+
+/** Decompress the whole stream and discard it — the honest `gzip -t`. */
+async function gzipIntact(path: string): Promise<void> {
+  await pipeline(
+    createReadStream(path),
+    createGunzip(),
+    async function* consume(source) {
+      for await (const _chunk of source) yield _chunk;
+    },
+  );
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  /** Which stage failed. A gzip failure means the checksum itself DID match. */
+  stage?: "checksum" | "gzip";
+  reason?: string;
+  /** The recorded digest, present whenever the sidecar parsed and matched. */
+  sha256?: string;
+}
+
+/** Sidecar + checksum + gzip integrity, in the script's order, without unpacking. */
+export async function verifyArchive(archive: string): Promise<VerifyResult> {
+  if (!existsSync(archive)) return { ok: false, stage: "checksum", reason: `no such archive: ${archive}` };
+  const sidecar = `${archive}.sha256`;
+  if (!existsSync(sidecar)) {
+    return { ok: false, stage: "checksum", reason: `missing checksum sidecar: ${sidecar} (an archive without its recorded sha256 cannot be verified)` };
+  }
+  let sidecarText: string;
+  try {
+    sidecarText = await readFile(sidecar, "utf8");
+  } catch (error) {
+    return { ok: false, stage: "checksum", reason: `cannot read checksum sidecar: ${sidecar} (${error instanceof Error ? error.message : String(error)})` };
+  }
+  const m = /^([0-9a-f]{64})\s+(\S+)\s*$/.exec(sidecarText.trim());
+  if (m === null) {
+    return { ok: false, stage: "checksum", reason: `checksum sidecar is malformed: ${sidecar} (expected "<sha256>  ${basename(archive)}")` };
+  }
+  if (m[2] !== basename(archive)) {
+    return { ok: false, stage: "checksum", reason: `checksum sidecar names "${m[2]}", not "${basename(archive)}" — the sidecar must travel with its archive` };
+  }
+  const actual = await sha256File(archive);
+  if (actual !== m[1]) return { ok: false, stage: "checksum", reason: `checksum mismatch: ${archive}` };
+  try {
+    await gzipIntact(archive);
+  } catch (error) {
+    return { ok: false, stage: "gzip", reason: `gzip integrity failure: ${archive} (${error instanceof Error ? error.message.split("\n")[0] : String(error)})` };
+  }
+  return { ok: true, sha256: m[1] };
+}
+
+// ---------------------------------------------------------------------------
+// the producer
+// ---------------------------------------------------------------------------
+
+export interface ProduceDeps {
+  shipRoot: string;
+  /** Default: $SHIP_ROOT/_backups (env override happens in the CLI). */
+  backupDir?: string;
+  label?: string;
+  dryRun?: boolean;
+  /** --i-stopped-writers: the operator's attestation of the coordinated stop. */
+  attested?: boolean;
+  now?: () => Date;
+  /** Undefined docker means: no writer check possible (advisory, not a refusal). */
+  docker?: SnapshotDocker;
+  /** Archive creation seam. Default: tar czf of the data dir, rooted at its basename. */
+  runTar?: (archive: string, dataDir: string) => Promise<void>;
+  log?: (line: string) => void;
+}
+
+export interface SnapshotOutcome {
+  status: "produced" | "dry-run";
+  dir: string;
+  archive: string;
+  /** 0 on a dry-run. */
+  bytes: number;
+  /** "" on a dry-run. */
+  sha256: string;
+  /** Advisory notes (e.g. docker unavailable — writer check skipped). */
+  advisory: string[];
+}
+
+function localDateStamp(d: Date): string {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+function containerLines(lines: ShipContainerLine[]): string {
+  return lines.map((c) => `  ${c.name}  ${c.image}  ${c.id}`).join("\n");
+}
+
+async function manifestText(opts: {
+  now: Date;
+  shipRoot: string;
+  bytes: number;
+  digest: string;
+  running: ShipContainerLine[] | undefined;
+  known: ShipContainerLine[] | undefined;
+}): Promise<string> {
+  const lines = [
+    `ship-backup manifest (teploy-ship snapshot version ${SNAPSHOT_VERSION})`,
+    `date: ${opts.now.toISOString().replace(/\.\d{3}Z$/, "Z")}`,
+    `hostname: ${hostname()}`,
+    `ship-root: ${opts.shipRoot}`,
+    `data-dir: ${NUCLEUS_DATA_REL}`,
+    `archive: ${ARCHIVE_NAME}`,
+    `bytes: ${opts.bytes}`,
+    `sha256: ${opts.digest}`,
+    "containers-running (advisory):",
+  ];
+  if (opts.running === undefined) lines.push("  docker unavailable — not checked (advisory)");
+  else if (opts.running.length === 0) lines.push("  none found");
+  else lines.push(containerLines(opts.running));
+  lines.push("containers-known (docker ps -a, ship-* — rollback wants the matching engine image):");
+  if (opts.known === undefined || opts.known.length === 0) lines.push("  docker unavailable or no ship-* containers (advisory)");
+  else lines.push(containerLines(opts.known));
+  return `${lines.join("\n")}\n`;
+}
+
+export async function produceSnapshot(deps: ProduceDeps): Promise<SnapshotOutcome> {
+  const now = deps.now ?? (() => new Date());
+  const log = deps.log ?? (() => {});
+  const backupDir = deps.backupDir ?? join(deps.shipRoot, "_backups");
+  const label = deps.label ?? "manual";
+  const dataDir = join(deps.shipRoot, NUCLEUS_DATA_REL);
+  if (!existsSync(dataDir)) {
+    refuse(`engine data dir not found: ${dataDir} (set --ship-root or SHIP_ROOT)`);
+  }
+
+  const advisory: string[] = [];
+  let running: ShipContainerLine[] | undefined;
+  if (deps.attested !== true) {
+    if (deps.docker === undefined) {
+      advisory.push("docker unavailable — writer check skipped (advisory)");
+    } else {
+      running = await deps.docker.running();
+      if (running === undefined) {
+        advisory.push("docker present but unreachable — writer check skipped (advisory)");
+      } else if (running.length > 0) {
+        const stop = running.map((c) => c.name).join(" ");
+        refuse(
+          [
+            "refusing: ship containers are still running — a tar of a live store is not a consistent backup:",
+            ...running.map((c) => `  ${c.name}  ${c.image}`),
+            "the coordinated stop this command expects:",
+            `  docker stop ${stop}`,
+            "then re-run with --i-stopped-writers",
+          ].join("\n"),
+        );
+      }
+    }
+  } else if (deps.docker !== undefined) {
+    // Even attested, the manifest should record what docker could see.
+    running = await deps.docker.running();
+  }
+
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(label)) {
+    refuse(`label must start alphanumeric and contain only [A-Za-z0-9._-]: ${label}`);
+  }
+  const dest = join(backupDir, `${label}-${localDateStamp(now())}`);
+
+  if (deps.dryRun === true) {
+    for (const a of advisory) log(`# ${a}`);
+    return { status: "dry-run", dir: dest, archive: join(dest, ARCHIVE_NAME), bytes: 0, sha256: "", advisory };
+  }
+
+  if (existsSync(dest)) refuse(`refusing to overwrite existing backup dir: ${dest} (backups are never overwritten)`);
+
+  const known = deps.docker === undefined ? undefined : await deps.docker.known();
+  const runTar =
+    deps.runTar ??
+    (async (archive: string, dir: string) => {
+      await capture("tar", ["-czf", archive, "-C", dirname(dir), basename(dir)]);
+    });
+
+  await mkdir(dest, { recursive: true });
+  try {
+    const archive = join(dest, ARCHIVE_NAME);
+    await runTar(archive, dataDir);
+    const digest = await sha256File(archive);
+    const bytes = (await stat(archive)).size;
+    await writeFile(`${archive}.sha256`, `${digest}  ${ARCHIVE_NAME}\n`, "utf8");
+    await writeFile(join(dest, "manifest.txt"), await manifestText({ now: now(), shipRoot: deps.shipRoot, bytes, digest, running, known }), "utf8");
+    const verified = await verifyArchive(archive);
+    if (!verified.ok) refuse(`produced archive failed its own verification: ${verified.reason}`);
+    return { status: "produced", dir: dest, archive, bytes, sha256: digest, advisory };
+  } catch (error) {
+    // Only this run's OWN partial output is removed, and only because this
+    // run created the directory a few lines above (a pre-existing dir would
+    // have been refused before anything was written). A completed backup is
+    // never the thing deleted.
+    await rm(dest, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// restore-check
+// ---------------------------------------------------------------------------
+
+export interface RestoreCheckSection {
+  status: "pass" | "fail" | "unknown";
+  detail: string;
+}
+
+export interface RestoreCheckReport {
+  version: 1;
+  archive: string;
+  verdict: "verified" | "not-verified";
+  sha256: RestoreCheckSection;
+  gzip: RestoreCheckSection;
+  contents: RestoreCheckSection & { entries: number; roots: string[] };
+  /** What verification did NOT establish — the rehearsal is the restore proof. */
+  notProven: string;
+}
+
+export const NOT_PROVEN =
+  "integrity only: the archive was not unpacked and no engine has booted on it. The proof an " +
+  "archive restores into a working store is the rehearsal — scripts/ship-backup.sh rehearse <archive> — " +
+  "which unpacks into an isolated directory, starts an isolated nucleus against the copy and reads run " +
+  "counts and step fingerprints (doctor's store-connectivity question, answered against the restored copy).";
+
+function unsafeEntries(entries: string[]): string[] {
+  return entries.filter((e) => e.startsWith("/") || e.split("/").includes(".."));
+}
+
+export interface RestoreCheckDeps {
+  /** Listing seam: the tar member names, in order. Default: `tar -tzf`. */
+  listArchive?: (archive: string) => Promise<string[]>;
+}
+
+export async function runRestoreCheck(archive: string, deps: RestoreCheckDeps = {}): Promise<RestoreCheckReport> {
+  const verified = await verifyArchive(archive);
+  // Attribute the failure to the stage that failed: a gzip failure happens
+  // only after the checksum MATCHED, so the checksum section still passes.
+  const sha256: RestoreCheckSection =
+    verified.ok || verified.stage === "gzip"
+      ? { status: "pass", detail: `sha256 ${verified.sha256} matches the sidecar` }
+      : { status: "fail", detail: verified.reason ?? "verification failed" };
+
+  let gzip: RestoreCheckSection;
+  if (verified.ok) {
+    gzip = { status: "pass", detail: "full-stream decompression clean (gzip -t equivalent)" };
+  } else if (verified.stage === "gzip") {
+    gzip = { status: "fail", detail: verified.reason ?? "gzip integrity failure" };
+  } else {
+    gzip = { status: "unknown", detail: "not checked — the checksum already failed" };
+  }
+
+  const base = { entries: 0, roots: [] as string[] };
+  let contents: RestoreCheckReport["contents"];
+  if (sha256.status !== "pass" || gzip.status !== "pass") {
+    contents = { status: "unknown", detail: "not checked — integrity already failed", ...base };
+  } else {
+    let listed: string[];
+    let listError: string | undefined;
+    try {
+      listed =
+        deps.listArchive !== undefined
+          ? await deps.listArchive(archive)
+          : (await capture("tar", ["-tzf", archive])).split("\n").map((l) => l.trim()).filter(Boolean);
+    } catch (error) {
+      listed = [];
+      listError = error instanceof Error ? error.message.split("\n")[0] : String(error);
+    }
+    if (listError !== undefined) {
+      contents = { status: "unknown", detail: `could not list the archive (tar unavailable or failed): ${listError}`, ...base };
+    } else {
+      const roots = [...new Set(listed.map((e) => e.replace(/\/$/, "").split("/")[0]!))].sort();
+      const unsafe = unsafeEntries(listed);
+      contents = {
+        status: unsafe.length > 0 ? "fail" : "pass",
+        detail:
+          unsafe.length > 0
+            ? `listing contains paths that would escape the unpack target: ${unsafe.slice(0, 5).join(", ")}${unsafe.length > 5 ? ` (+${unsafe.length - 5} more)` : ""}`
+            : `${listed.length} entries under ${roots.join(", ")} — all relative, no parent traversal`,
+        entries: listed.length,
+        roots,
+      };
+    }
+  }
+
+  return {
+    version: 1,
+    archive,
+    verdict: sha256.status === "pass" && gzip.status === "pass" && contents.status === "pass" ? "verified" : "not-verified",
+    sha256,
+    gzip,
+    contents,
+    notProven: NOT_PROVEN,
+  };
+}
+
+export function formatRestoreCheck(report: RestoreCheckReport): string {
+  const gate = new RedactionGate();
+  const mark: Record<RestoreCheckSection["status"], string> = { pass: "PASS   ", fail: "FAIL   ", unknown: "UNKNOWN" };
+  const lines = [
+    `${mark[report.sha256.status]} checksum: ${gate.redact(report.sha256.detail)}`,
+    `${mark[report.gzip.status]} gzip:     ${gate.redact(report.gzip.detail)}`,
+    `${mark[report.contents.status]} contents: ${gate.redact(report.contents.detail)}`,
+    `verdict: ${report.verdict}`,
+    "",
+    gate.redact(report.notProven),
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// the receipt the support bundle carries
+// ---------------------------------------------------------------------------
+
+export interface BackupReceipt {
+  backupDir: string;
+  name: string;
+  text: string;
+}
+
+/**
+ * The manifest of the newest backup — the receipt, never the archive. A
+ * support bundle must not carry the store itself.
+ */
+export async function latestBackupReceipt(backupDir: string): Promise<BackupReceipt | undefined> {
+  let entries;
+  try {
+    entries = await readdir(backupDir, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+  let best: { name: string; mtimeMs: number } | undefined;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === "rehearsals") continue;
+    const manifest = join(backupDir, entry.name, "manifest.txt");
+    try {
+      const s = await stat(manifest);
+      if (best === undefined || s.mtimeMs > best.mtimeMs) best = { name: entry.name, mtimeMs: s.mtimeMs };
+    } catch {
+      // not a backup dir; skip
+    }
+  }
+  if (best === undefined) return undefined;
+  let text = await readFile(join(backupDir, best.name, "manifest.txt"), "utf8");
+  if (text.length > RECEIPT_MAX_BYTES) text = `${text.slice(0, RECEIPT_MAX_BYTES)}\n[truncated at ${RECEIPT_MAX_BYTES} bytes]\n`;
+  return { backupDir, name: best.name, text };
+}
diff --git a/src/support.test.ts b/src/support.test.ts
index eac84f62..ead8ad3d 100644
--- a/src/support.test.ts
+++ b/src/support.test.ts
@@ -290,7 +290,7 @@ test("a bundle from a fake store carries manifest+versions+runs-summary, bounded
     const manifest = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
     assert.equal(manifest.hostname, "box.example.internal");
     assert.equal(manifest.shipVersion, "0.2.1-test");
-    assert.equal(manifest.scriptVersion, 1);
+    assert.equal(manifest.scriptVersion, 2);
     assert.equal(manifest.logLines, 10);
     assert.ok(typeof manifest.buildFingerprint === "string" && manifest.buildFingerprint.length > 0);
 
@@ -382,3 +382,54 @@ test("the config summary and versions never carry the Nucleus URL's credentials"
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test("the bundle carries the doctor report and the latest backup receipt — never the archive", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "ship-support-test-"));
+  try {
+    await assembleSupportBundle(
+      bundleDeps({
+        outDir: dir,
+        store: fakeStore([], {}),
+        doctorJson: async () => `{"verdict": "incomplete", "note": "clock unknown, token ${GHP_TOKEN} in a detail"}`,
+        backupReceipt: async () => ({
+          backupDir: "/deployments/ship/_backups",
+          name: "pre-upgrade-2026-10-04",
+          text: `ship-backup manifest (script version 1.0.0)\nsha256: deadbeef\n`,
+        }),
+      }),
+    );
+    const doctor = JSON.parse(readFileSync(join(dir, "doctor.json"), "utf8"));
+    assert.equal(doctor.verdict, "incomplete");
+    assert.ok(!JSON.stringify(doctor).includes(GHP_TOKEN), "doctor output is redacted inside the bundle");
+    assert.ok(readFileSync(join(dir, "doctor.json"), "utf8").includes("[REDACTED"), "a marker is present");
+
+    const receipt = readFileSync(join(dir, "backup-receipt.txt"), "utf8");
+    assert.match(receipt, /latest backup receipt: pre-upgrade-2026-10-04/);
+    assert.match(receipt, /never part of a support bundle/);
+    assert.match(receipt, /sha256: deadbeef/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("doctor and receipt degrade to note files — the bundle still ships without them", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "ship-support-test-"));
+  try {
+    await assembleSupportBundle(
+      bundleDeps({
+        outDir: dir,
+        store: fakeStore([], {}),
+        doctorJson: async () => {
+          throw new Error("probe blew up");
+        },
+        backupReceipt: async () => undefined,
+      }),
+    );
+    const doctor = readFileSync(join(dir, "doctor-unavailable.txt"), "utf8");
+    assert.match(doctor, /doctor did not complete/);
+    const receipt = readFileSync(join(dir, "backup-receipt.txt"), "utf8");
+    assert.match(receipt, /no backup manifest found/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/src/support.ts b/src/support.ts
index 0b0ece58..a432fcf2 100644
--- a/src/support.ts
+++ b/src/support.ts
@@ -56,7 +56,7 @@ import { computeHealth, healthWarnings } from "./selfwatch.js";
 import { SECRET_PATTERNS, redactionMarker } from "./secret-patterns.js";
 
 /** Version of this bundle format. Bump when a file is added or a field changes meaning. */
-export const SUPPORT_SCRIPT_VERSION = 1;
+export const SUPPORT_SCRIPT_VERSION = 2;
 
 /** Default and hard cap for --log-lines. The cap is applied here, not trusted to the CLI. */
 export const DEFAULT_LOG_LINES = 200;
@@ -357,6 +357,16 @@ export interface SupportDeps {
   /** Create the .tgz next to the bundle dir. Returns its path, or undefined when tar is unavailable. */
   makeTgz?: (dir: string) => Promise<string | undefined>;
   files?: SupportFiles;
+  /**
+   * The rendered doctor report (renderDoctor().json), run at assembly time.
+   * Degrades to a note file when absent or failed — the bundle still ships.
+   */
+  doctorJson?: () => Promise<string>;
+  /**
+   * The latest backup MANIFEST (the receipt — the archive itself is never
+   * part of a bundle). Degrades to a note naming where it looked.
+   */
+  backupReceipt?: () => Promise<{ backupDir: string; name: string; text: string } | undefined>;
 }
 
 export interface SupportBundleResult {
@@ -591,6 +601,38 @@ export async function assembleSupportBundle(deps: SupportDeps): Promise<SupportB
     }
   }
 
+  // --- doctor --------------------------------------------------------------
+  // The install doctor folded in: a vendor reading a bundle gets the same
+  // pass/fail/unknown picture the operator sees, redacted the same way.
+  // A doctor that did not run is named, not omitted.
+  if (deps.doctorJson === undefined) {
+    await write("doctor-unavailable.txt", "the install doctor was not run for this bundle.\n");
+  } else {
+    try {
+      await write("doctor.json", gate.redact(await deps.doctorJson()));
+    } catch (error) {
+      await write("doctor-unavailable.txt", gate.redact(`doctor did not complete: ${error instanceof Error ? error.message : String(error)}\n`));
+    }
+  }
+
+  // --- backup receipt ------------------------------------------------------
+  // The receipt only: a support bundle must not carry the store itself.
+  if (deps.backupReceipt === undefined) {
+    await write("backup-receipt.txt", "no backup receipt was collected for this bundle.\n");
+  } else {
+    try {
+      const receipt = await deps.backupReceipt();
+      await write(
+        "backup-receipt.txt",
+        receipt === undefined
+          ? `no backup manifest found — backups are looked for under SHIP_BACKUP_DIR (default $SHIP_ROOT/_backups).\n`
+          : gate.redact(`# latest backup receipt: ${receipt.name} (from ${receipt.backupDir})\n# the archive itself is never part of a support bundle\n\n${receipt.text}`),
+      );
+    } catch (error) {
+      await write("backup-receipt.txt", gate.redact(`backup receipt unavailable: ${error instanceof Error ? error.message : String(error)}\n`));
+    }
+  }
+
   // --- redaction report ----------------------------------------------------
   const entries = Object.entries(gate.counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
   const report =

From d021eb3137b940ba182ed2cdfc0a8033875e3e19 Mon Sep 17 00:00:00 2001
From: Tyler <53561637+im-tyler@users.noreply.github.com>
Date: Sun, 4 Oct 2026 02:38:14 -0700
Subject: [PATCH 2/2] docs: NEXT_SESSION item 4 reflects S07/S19 wave-5
 landings

---
 NEXT_SESSION.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/NEXT_SESSION.md b/NEXT_SESSION.md
index e9468d65..4da5ca24 100644
--- a/NEXT_SESSION.md
+++ b/NEXT_SESSION.md
@@ -17,7 +17,7 @@ Wave 4's state ("implemented and checked by automated tests only") is now partly
 1. **Shadow-log review** after soak (placement/policy/budget/tool-manifest/knowledge-provenance JSONL + reports); set `SHIP_MODEL_ROUTING_POLICY` so the routing shadow has something to record. Only then discuss any `on` flips.
 2. **S08 wiring** (approved): findings into PR body + webhook behind a default-off flag; worker-path change, so shadow-first per the standing rule.
 3. **Live proofs still open**: S01 credential proofs on a real sandbox with a private repo; S03 storage migration (write the additive migration, rehearse on a restored copy — backup `pre-80c9187-shadow-deploy-2026-10-04` is available and verified); S27 real teploy-adapter run against a scratch target; S19 doctor probes against the real store/clock; human observation of dashboard users.
-4. **Code still unfinished**: S04 and S12 barely started; most of S07 beyond the grounding check; S10 follow-ups (offline/error states, other roles, screen readers); wiring the inert modules (S15/S17 into delivery+incidents, S19 snapshot producer + restore-check, S18 worker tree provisioning, S07 into the plan-park point).
+4. **Code still unfinished**: S04 and S12 barely started; most of S07 beyond the grounding check; S10 follow-ups (offline and error states, other roles, screen readers); wiring the inert modules (S15/S17 into delivery+incidents, S18 worker tree provisioning). Done in wave 5: S07's plan-park wiring (#59), S19's snapshot producer + restore-check + doctor probes (this PR).
 5. **Re-grade retained runs where possible**: only transcripts were preserved for pre-batch runs, so regrades are limited to transcript+fixture-verifiable scenarios; write supplementary `regrade-*.json` beside the records, never replacing originals.
 6. **Deferred**: configuration B of the S02 comparison (needs real API spend, owner-gated).