@celilo/cli 2.1.0 → 2.2.0

package/src/registry/client.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import { createHash } from 'node:crypto';
 import type { IndexEntry } from './client';
 import { DEFAULT_REGISTRY, RegistryClient } from './client';
 
@@ -312,3 +313,151 @@ describe('RegistryClient owner methods', () => {
     );
   });
 });
+
+// ── get() retry ───────────────────────────────────────────────────────────────
+//
+// Every registry read goes through one private `get()`. It used to make exactly
+// one attempt, so a single transient — the shape the 15s→30s timeout bump was
+// already chasing — failed a module install outright. Measured 2026-09-04:
+// `module import iptables` failed twice with "Download failed: The operation
+// timed out" while the identical call had succeeded minutes earlier.
+
+describe('RegistryClient.get retry', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  test('a transient network failure is retried and the download succeeds', async () => {
+    const payload = new Uint8Array([1, 2, 3, 4]);
+    fetchSpy
+      .mockRejectedValueOnce(new DOMException('The operation timed out.', 'TimeoutError'))
+      .mockResolvedValueOnce(new Response(payload, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4');
+
+    expect(new Uint8Array(data)).toEqual(payload);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a 5xx is retried', async () => {
+    fetchSpy
+      .mockResolvedValueOnce(new Response(null, { status: 503 }))
+      .mockResolvedValueOnce(new Response(new Uint8Array([9]), { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await client.download('iptables', '3.1.4');
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a 404 is NOT retried — it is an answer, not a transient', async () => {
+    fetchSpy.mockResolvedValue(new Response(null, { status: 404 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.download('nope', '1.0.0')).rejects.toThrow('HTTP 404');
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('gives up after a bounded number of attempts', async () => {
+    fetchSpy.mockRejectedValue(new DOMException('The operation timed out.', 'TimeoutError'));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const error = await client.download('iptables', '3.1.4').then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(error).toBeInstanceOf(Error);
+    // The exhaustion report is the event, not the last attempt (celilo#1264):
+    // the bare lastError read as an unretried first attempt, because that is
+    // exactly what the same string meant before the retry existed.
+    expect((error as Error).message).toMatch(/failed after 3 attempts over \d+(\.\d+)?s/);
+    expect((error as Error).message).toContain('The operation timed out.');
+    expect((error as { cause?: unknown }).cause).toBeInstanceOf(DOMException);
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+  });
+});
+
+// ── download integrity ────────────────────────────────────────────────────────
+//
+// `cksum` is computed at publish time, shipped in every index entry, and was
+// never checked on the consuming side. A short download was therefore accepted
+// and blew up later in gunzip as "zlib: unexpected end of file", which blames
+// the package rather than the transfer. Measured 2026-09-04 in the e2e rig.
+// Retrying cannot help a fault it cannot detect, so verification is what makes
+// the retry meaningful.
+
+describe('RegistryClient.download integrity', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+  const body = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+  // sha256 of the 8 bytes above, in the `sha256:<hex>` shape publish() writes.
+  const goodCksum = `sha256:${createHash('sha256').update(body).digest('hex')}`;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  test('a truncated payload is rejected and retried, then succeeds', async () => {
+    fetchSpy
+      .mockResolvedValueOnce(new Response(body.slice(0, 3), { status: 200 })) // short
+      .mockResolvedValueOnce(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4', goodCksum);
+
+    expect(new Uint8Array(data)).toEqual(body);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test('a payload that never verifies fails with an error naming the integrity check', async () => {
+    // A fresh Response per call: one shared instance would be consumed by the
+    // first attempt and the retry would report "Body already used", hiding the
+    // integrity failure this test exists to assert.
+    fetchSpy.mockImplementation(() => new Response(body.slice(0, 3), { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.download('iptables', '3.1.4', goodCksum)).rejects.toThrow(
+      /integrity check/i,
+    );
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+  });
+
+  test('a correct payload verifies on the first attempt', async () => {
+    fetchSpy.mockResolvedValue(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    await client.download('iptables', '3.1.4', goodCksum);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('no expected cksum still downloads — callers may not have one', async () => {
+    fetchSpy.mockResolvedValue(new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4');
+    expect(new Uint8Array(data)).toEqual(body);
+  });
+
+  test('a non-digest cksum sentinel skips verification instead of failing', async () => {
+    // The registry's bootstrap path publishes `cksum: 'bootstrap'`
+    // (packages/registry-server/src/bootstrap.ts:114) because those modules are
+    // packaged on demand and have no stable digest. Treating a sentinel as a
+    // digest rejects a perfectly good 2.7MB package on every import.
+    fetchSpy.mockImplementation(() => new Response(body, { status: 200 }));
+
+    const client = new RegistryClient('https://reg.example.com');
+    const data = await client.download('iptables', '3.1.4', 'bootstrap');
+
+    expect(new Uint8Array(data)).toEqual(body);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/registry/client.ts

@@ -11,6 +11,98 @@ import { readFile } from 'node:fs/promises';
 
 export const DEFAULT_REGISTRY = 'https://celilo.computer/registry';
 
+/** Attempts per idempotent registry read, including the first. */
+const GET_ATTEMPTS = 3;
+/** Per-attempt ceiling for metadata reads. Packages use DOWNLOAD_TIMEOUT_MS. */
+const GET_TIMEOUT_MS = 30_000;
+/** Linear backoff: 1s, then 2s. Short, because a deploy is waiting on this. */
+const GET_RETRY_DELAY_MS = 1_000;
+/**
+ * Per-attempt ceiling for a package download.
+ *
+ * This was briefly 180s, on the reasoning that a package is megabytes and
+ * metadata is not. That was wrong, and measurably so: the whole retry budget has
+ * to fit inside the CALLER's window, and celilo's own e2e harness gives a command
+ * 120s by default (`packages/e2e/src/container-manager.ts`). Three attempts at
+ * 180s allows ~543s, so a slow download stopped failing as a download and started
+ * being killed by the caller — a worse error, further from the cause.
+ *
+ * 30s x 3 attempts plus backoff is ~93s, which fits. The durability comes from
+ * retrying, not from a wider window: a 2.6MB transfer that normally takes about a
+ * second does not need 180s, it needs another go.
+ */
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+/**
+ * Read a body to completion, reporting progress so a failure can say how far it
+ * got. `Response.arrayBuffer()` gives no partial count when it throws.
+ */
+async function readCounting(
+  resp: Response,
+  onProgress: (bytes: number) => void,
+): Promise<ArrayBuffer> {
+  if (!resp.body) return resp.arrayBuffer();
+
+  const reader = resp.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        chunks.push(value);
+        total += value.byteLength;
+        onProgress(total);
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out.buffer;
+}
+
+/**
+ * A status worth trying again. 5xx is the server failing, 408 and 429 are it
+ * asking us to wait. Every other 4xx is a settled answer.
+ */
+function isRetryableStatus(status: number): boolean {
+  return status >= 500 || status === 408 || status === 429;
+}
+
+/**
+ * A settled answer from the registry. Retrying cannot change it, so `withRetry`
+ * rethrows it immediately rather than spending the backoff on a known 404.
+ */
+class RegistryAnswer extends Error {}
+
+/** `publish` writes `sha256:<hex>`; tolerate a bare hex digest from older entries. */
+function normalizeCksum(value: string): string {
+  return value.replace(/^sha256:/, '').toLowerCase();
+}
+
+/**
+ * Is this index entry's `cksum` an actual digest we can check against?
+ *
+ * Not every entry carries one. The registry's bootstrap path publishes the
+ * literal string `bootstrap` (packages/registry-server/src/bootstrap.ts), because
+ * those modules are packaged on demand and have no stable digest to publish.
+ * A sentinel means "no integrity data", which is a reason to skip the check and
+ * not a reason to reject the package — treating it as a digest rejects every
+ * bootstrap-served import.
+ */
+function isVerifiableCksum(value: string): boolean {
+  return /^[0-9a-f]{64}$/.test(normalizeCksum(value));
+}
+
 export interface SparseConfig {
   dl: string;
   api: string;
@@ -109,9 +201,56 @@ export class RegistryClient {
     return `${this.baseUrl}/api/v1/modules/${encodeURIComponent(name)}/${encodeURIComponent(version)}/download`;
   }
 
-  async download(name: string, version: string): Promise<ArrayBuffer> {
-    const resp = await this.get(this.downloadUrl(name, version));
-    return resp.arrayBuffer();
+  /**
+   * Fetch a module .netapp, verifying it against the index entry's `cksum`.
+   *
+   * `cksum` has always been computed at publish time and shipped in every index
+   * entry, and nothing on this side ever checked it. A short transfer was
+   * therefore accepted as a complete package and failed later in gunzip as
+   * "zlib: unexpected end of file", which points at the package rather than at
+   * the download that produced it.
+   *
+   * Verification is also what makes the retry mean anything: a fault nobody can
+   * detect is a fault nobody can retry. Pass `expectedCksum` whenever the caller
+   * holds the entry — both callers do.
+   */
+  async download(name: string, version: string, expectedCksum?: string): Promise<ArrayBuffer> {
+    const url = this.downloadUrl(name, version);
+
+    return this.withRetry(async () => {
+      const startedAt = Date.now();
+      const resp = await this.fetchOnce(url, DOWNLOAD_TIMEOUT_MS);
+
+      // Read in chunks so a failure can say how far it got. A bare
+      // `arrayBuffer()` that times out reports nothing, which is why three runs
+      // of this failure told us only that it was slow and never how slow. Bytes
+      // and elapsed together separate a steady trickle from a stall, and those
+      // two want different fixes (a bigger window versus an idle timeout).
+      let data: ArrayBuffer;
+      let received = 0;
+      try {
+        data = await readCounting(resp, (n) => {
+          received = n;
+        });
+      } catch (err) {
+        const seconds = (Date.now() - startedAt) / 1000;
+        const rate = seconds > 0 ? received / 1024 / seconds : 0;
+        throw new Error(
+          `Download of ${name}@${version} failed after ${received} bytes in ${seconds.toFixed(1)}s (${rate.toFixed(0)} KiB/s): ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      if (expectedCksum && isVerifiableCksum(expectedCksum)) {
+        const actual = createHash('sha256').update(new Uint8Array(data)).digest('hex');
+        if (actual !== normalizeCksum(expectedCksum)) {
+          throw new Error(
+            `Package ${name}@${version} failed its integrity check: got ${data.byteLength} bytes with sha256 ${actual}, expected ${normalizeCksum(expectedCksum)}. A short or corrupted download, not a bad package.`,
+          );
+        }
+      }
+
+      return data;
+    });
   }
 
   /**
@@ -232,14 +371,67 @@ export class RegistryClient {
   }
 
   private async get(url: string): Promise<Response> {
-    // 30s (was 15s): a module .netapp can be tens of MB and the download must
-    // finish within one window. 15s was too aggressive on slow links — the
-    // download of a ~19MB module over a multi-hop path (e2e sim NAT, real WAN)
-    // intermittently timed out mid-transfer.
-    const resp = await fetch(url, { signal: AbortSignal.timeout(30_000) });
-    if (!resp.ok) {
-      throw new Error(`Registry error at ${url}: HTTP ${resp.status}`);
+    // 30s per attempt: a module .netapp can be tens of MB, and the download of a
+    // ~19MB module over a multi-hop path (e2e sim NAT, real WAN) intermittently
+    // times out mid-transfer.
+    //
+    // The window used to be the whole story — one attempt, and the response to
+    // observed flakiness was widening it from 15s to 30s. A wider single window
+    // is not a durable fetch, it is a bigger gap to fall through. Measured
+    // 2026-09-04: `module import iptables` failed twice with "Download failed:
+    // The operation timed out" on a loaded host, while the identical call had
+    // succeeded minutes earlier. This client is the fleet's module delivery
+    // path, so a single transient failing an import is an operator-facing
+    // outage, not just an e2e flake.
+    //
+    // Every caller of get() is an idempotent read (config, search, metadata,
+    // download), so retrying is safe. `publish` does not route through here.
+    // A 4xx is an answer and is never retried: a 404 must stay fast and say
+    // "not found" rather than stall for the whole backoff.
+    return this.withRetry(() => this.fetchOnce(url));
+  }
+
+  /** One attempt. Throws `RegistryAnswer` for a status retrying cannot change. */
+  private async fetchOnce(url: string, timeoutMs = GET_TIMEOUT_MS): Promise<Response> {
+    const resp = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (resp.ok) return resp;
+
+    const message = `Registry error at ${url}: HTTP ${resp.status}`;
+    if (!isRetryableStatus(resp.status)) throw new RegistryAnswer(message);
+    throw new Error(message);
+  }
+
+  /**
+   * Retry a whole operation, not a piece of one.
+   *
+   * The unit matters. Retrying only the request leaves the body download
+   * outside the retry, and a body is where a large transfer actually fails.
+   */
+  private async withRetry<T>(run: () => Promise<T>): Promise<T> {
+    const startedAt = Date.now();
+    let lastError: unknown;
+
+    for (let attempt = 1; attempt <= GET_ATTEMPTS; attempt++) {
+      try {
+        return await run();
+      } catch (err) {
+        if (err instanceof RegistryAnswer) throw err;
+        lastError = err;
+        if (attempt < GET_ATTEMPTS) {
+          await new Promise((resolve) => setTimeout(resolve, GET_RETRY_DELAY_MS * attempt));
+        }
+      }
     }
-    return resp;
+
+    // Exhausting the budget is itself the event worth reporting. The bare last
+    // error said only what the final attempt said, which is the same string the
+    // caller got before the retry existed, so the operator cannot tell whether
+    // the retry ran (celilo#1264). The original error rides along as `cause`.
+    const seconds = (Date.now() - startedAt) / 1000;
+    const detail = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new Error(
+      `Registry fetch failed after ${GET_ATTEMPTS} attempts over ${seconds.toFixed(1)}s: ${detail}`,
+      { cause: lastError },
+    );
   }
 }

package/src/services/alerting/format.test.ts

@@ -6,9 +6,11 @@ import {
   humaniseRemaining,
   moduleHealthCell,
   renderAlertTable,
+  renderMonitorRunMessage,
   sortAlertRows,
   toAlertRow,
 } from './format';
+import type { MonitorRunOutcomeSummary } from './run-monitor';
 
 const NOW = new Date('2026-07-28T12:00:00Z');
 const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
@@ -190,3 +192,58 @@ describe('moduleHealthCell', () => {
     );
   });
 });
+
+describe('renderMonitorRunMessage — names the failing check (#1266)', () => {
+  function summary(over: Partial<MonitorRunOutcomeSummary>): MonitorRunOutcomeSummary {
+    return {
+      monitorId: 'mon-1',
+      outcome: 'success',
+      createdIds: [],
+      resolvedIds: [],
+      ...over,
+    } as MonitorRunOutcomeSummary;
+  }
+
+  const caddyRunning = {
+    key: 'module:caddy/check:caddy_running',
+    severity: 'critical' as const,
+    message: 'caddy systemd service is not active',
+  };
+
+  test('a failing check is named, with its reason', () => {
+    const message = renderMonitorRunMessage('caddy', summary({ failingKeys: [caddyRunning] }));
+    expect(message).toContain('module:caddy/check:caddy_running');
+    expect(message).toContain('caddy systemd service is not active');
+    expect(message).toContain('1 failing');
+  });
+
+  test('every failing key is named, not just the first', () => {
+    const diskSpace = {
+      key: 'module:caddy/check:disk-space',
+      severity: 'warning' as const,
+      message: '/var 94% used',
+    };
+    const message = renderMonitorRunMessage(
+      'caddy',
+      summary({ failingKeys: [caddyRunning, diskSpace] }),
+    );
+    expect(message).toContain('module:caddy/check:caddy_running');
+    expect(message).toContain('module:caddy/check:disk-space');
+    expect(message).toContain('2 failing');
+  });
+
+  test('a healthy run keeps the zero the suite greps for', () => {
+    const message = renderMonitorRunMessage('caddy', summary({ failingKeys: [] }));
+    expect(message).toContain('0 failing');
+    expect(message).toContain('0 resolved');
+  });
+
+  test('a run that could not execute says why instead of inventing a count', () => {
+    const message = renderMonitorRunMessage(
+      'caddy',
+      summary({ outcome: 'error', errorMessage: 'hook exited 1' }),
+    );
+    expect(message).toContain('check could not run');
+    expect(message).toContain('hook exited 1');
+  });
+});

package/src/services/alerting/format.ts

@@ -10,6 +10,7 @@
  */
 
 import type { Alert, AlertState } from '../../db/schema';
+import type { MonitorRunOutcomeSummary } from './run-monitor';
 
 export interface AlertRow {
   key: string;
@@ -148,3 +149,26 @@ export function moduleHealthCell(input: {
   if (input.firingCount > 0) return `${input.firingCount} firing`;
   return 'ok';
 }
+
+/**
+ * The message `celilo monitor run <target>` reports.
+ *
+ * The count line stays greppable (`0 failing` is what a healthy fleet prints),
+ * and each failing key is named underneath it with its reason — an operator
+ * paged by this line learns WHAT failed, not just that something did (#1266).
+ *
+ * Pure — takes the run summary, returns the string — so the wording can be
+ * asserted without a database or a fleet.
+ */
+export function renderMonitorRunMessage(target: string, summary: MonitorRunOutcomeSummary): string {
+  if (summary.outcome === 'error') {
+    return `${target}: check could not run — ${summary.errorMessage ?? 'unknown error'}`;
+  }
+  const lines = [
+    `${target}: ${summary.failingKeys.length} failing, ${summary.resolvedIds.length} resolved`,
+  ];
+  for (const failing of summary.failingKeys) {
+    lines.push(`  [${failing.severity}] ${failing.key}: ${failing.message}`);
+  }
+  return lines.join('\n');
+}

package/src/services/alerting/run-monitor.ts

@@ -47,7 +47,7 @@ export interface MonitorRunOutcomeSummary {
   monitorId: string;
   outcome: 'success' | 'error';
   errorMessage?: string;
-  failingKeyCount: number;
+  failingKeys: FailingKey[];
   createdIds: string[];
   resolvedIds: string[];
 }
@@ -186,7 +186,7 @@ export async function runOneMonitor(
     monitorId: monitor.id,
     outcome: product.outcome,
     errorMessage: product.errorMessage,
-    failingKeyCount: product.failingKeys.length,
+    failingKeys: product.failingKeys,
     createdIds,
     resolvedIds,
   };

package/src/services/backup-create.ts

@@ -6,15 +6,16 @@
 import { copyFileSync, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
+import { create as tarCreate } from 'tar';
 import { getDbPath, getMasterKeyPath } from '../config/paths';
 import { getDb } from '../db/client';
 import { moduleConfigs, modules, secrets as secretsTable } from '../db/schema';
 import { invokeHook } from '../hooks/executor';
+import { createHookStores } from '../hooks/hook-store';
 import { createConsoleLogger } from '../hooks/logger';
 import type { ModuleManifest } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
-import { shellEscape } from '../utils/shell';
 import { encryptFileToFile } from './backup-cipher';
 import { buildManifest } from './backup-manifest';
 import {
@@ -153,8 +154,7 @@ export async function createSystemStateBackup(
     // Tar the envelope. Operator can re-extract a backup file manually
     // for diagnostics: `age -d -p file.backup | tar -t` shows the contents.
     const tarPath = join(tempDir, 'envelope.tar');
-    const { execSync } = await import('node:child_process');
-    execSync(`tar -cf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)} .`);
+    await tarCreate({ file: tarPath, cwd: envelopeDir }, ['.']);
 
     // Encrypt the tar, streamed — see backup-cipher.ts. The plaintext is
     // never held in memory, so a large fleet DB can't OOM the snapshot.
@@ -401,6 +401,7 @@ export async function createModuleBackup(
         debug: false,
         systems: getModuleSystems(moduleId, db),
         remoteAccess: remoteAccessPolicy(moduleId, db),
+        hookStores: () => createHookStores(db, moduleId),
       },
     );
 
@@ -434,8 +435,7 @@ export async function createModuleBackup(
 
     // Tar the envelope (manifest.json + data/).
     const tarPath = join(tempDir, 'envelope.tar');
-    const { execSync } = await import('node:child_process');
-    execSync(`tar -cf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)} .`);
+    await tarCreate({ file: tarPath, cwd: envelopeDir }, ['.']);
 
     // Encrypt the tar, streamed — see backup-cipher.ts. Module artifacts run
     // to hundreds of MB (forgejo's are ~774 MB); holding one in memory is
@@ -566,6 +566,7 @@ export async function importModuleBackup(
           debug: false,
           systems: getModuleSystems(moduleId, db),
           remoteAccess: remoteAccessPolicy(moduleId, db),
+          hookStores: () => createHookStores(db, moduleId),
         },
       );
 
@@ -590,8 +591,7 @@ export async function importModuleBackup(
 
     // Tar the artifacts
     const tarPath = join(tempDir, 'backup.tar');
-    const { execSync } = await import('node:child_process');
-    execSync(`tar -cf ${shellEscape(tarPath)} -C ${shellEscape(artifactDir)} .`);
+    await tarCreate({ file: tarPath, cwd: artifactDir }, ['.']);
 
     // Encrypt the tar, streamed — see backup-cipher.ts.
     const masterKey = await getOrCreateMasterKey();

package/src/services/backup-envelope-roundtrip.test.ts

@@ -16,16 +16,25 @@
 
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { getDbPath } from '../config/paths';
 import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { backups, systemConfig } from '../db/schema';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { decryptFileToFile, encryptFileToFile } from './backup-cipher';
 import { createSystemStateBackup } from './backup-create';
-import { MANIFEST_SCHEMA_VERSION, parseManifest } from './backup-manifest';
+import { MANIFEST_SCHEMA_VERSION, buildManifest, parseManifest } from './backup-manifest';
 import { restoreSystemStateBackup } from './backup-restore';
 import { addBackupStorage, setDefaultBackupStorage, verifyBackupStorage } from './backup-storage';
 
@@ -121,6 +130,40 @@ describe('backup envelope round-trip', () => {
     expect(restoreResult.error).toBeUndefined();
   });
 
+  it('an archive written by SYSTEM tar (the pre-library producer) restores via the tar library', async () => {
+    // The tar library replaced `tar -cf/-xf` shell-outs (celilo#1235). A
+    // self-consistent round-trip cannot detect a layout change, because the
+    // new extract sites would happily read back the new layout. So this test
+    // builds the envelope with the SYSTEM tar — byte-for-byte the command the
+    // old code ran — and restores it with the current code, proving a backup
+    // taken BEFORE the change still restores after it.
+    const db = getDb();
+    db.insert(systemConfig).values({ key: 'pre-change-sentinel', value: 'before-backup' }).run();
+
+    // Take a real backup to get a valid row + storage location, then swap the
+    // artifact for one produced by the system tar the old code shelled out to.
+    const result = await createSystemStateBackup();
+    expect(result.success).toBe(true);
+    const artifactPath = join(storageDir, 'celilo-backups', result.storagePath as string);
+
+    const envelopeDir = join(dir, 'pre-change-envelope');
+    mkdirSync(envelopeDir, { recursive: true });
+    copyFileSync(getDbPath(), join(envelopeDir, 'celilo.db'));
+    writeFileSync(
+      join(envelopeDir, 'manifest.json'),
+      JSON.stringify(buildManifest({ kind: 'system' }), null, 2),
+    );
+    const tarPath = join(dir, 'pre-change.tar');
+    execSync(`tar -cf '${tarPath}' -C '${envelopeDir}' .`);
+    const masterKey = await getOrCreateMasterKey();
+    await encryptFileToFile(tarPath, artifactPath, masterKey);
+
+    const backupRow = db.select().from(backups).all()[0];
+    const restoreResult = await restoreSystemStateBackup(backupRow);
+    expect(restoreResult.success).toBe(true);
+    expect(restoreResult.error).toBeUndefined();
+  });
+
   it('system restore refuses an artifact with a wrong manifest kind', async () => {
     // Create a valid backup, then poison the manifest by re-packing.
     const result = await createSystemStateBackup();