@indigoai-us/hq-cloud 6.18.44-alpha.9 → 6.18.44

package/dist/manifest/upload-manifest.test.js

@@ -1,1335 +0,0 @@
-/**
- * Unit tests for the shared manifest upload pass (US-004).
- *
- * Every acceptance criterion of the story is a `it()` here, and the suite is
- * deliberately network-free: the transport is the injected seam, so the whole
- * protocol — resend_full, soft skip, 413, the `materialised` gate — is
- * exercised by returning literal server bodies.
- */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { lockPathFor } from "../operation-lock.js";
-import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
-import { validateSyncManifestUpload } from "./contract.js";
-import { SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET, SYNC_MANIFEST_TOO_LARGE_REASON_CODE, } from "./contract.js";
-import { MANIFEST_SNAPSHOT_DIRNAME, manifestSnapshotScopeKey, manifestSnapshotScopeSlug, readManifestSnapshot, writeManifestSnapshot, } from "./snapshot-store.js";
-import { DEFAULT_MANIFEST_UPLOAD_MIN_INTERVAL_MS, MANIFEST_CHUNK_BYTE_BUDGET_FLOOR, MANIFEST_UPLOAD_DISABLED_ENV, MANIFEST_UPLOAD_LOCK_COMMAND, readManifestUploadStatus, MANIFEST_FAILURE_BACKOFF_BASE_MS, manifestFailureBackoffMs, runManifestUploadPass, } from "./upload-manifest.js";
-const NOW_MS = Date.parse("2026-09-04T12:00:00.000Z");
-const SCOPE_KEY = manifestSnapshotScopeKey({ kind: "personal" });
-let hqRoot;
-let stateDir;
-let previousLockStateDir;
-beforeEach(() => {
-    const base = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-upload-"));
-    hqRoot = path.join(base, "hq");
-    stateDir = path.join(base, "state");
-    // The per-scope upload lock lives under `HQ_STATE_DIR || ~/.hq` (it is
-    // machine-local and must never round-trip to the cloud). Point it at this
-    // test's temp dir so the suite never writes into the developer's real ~/.hq.
-    previousLockStateDir = process.env.HQ_STATE_DIR;
-    process.env.HQ_STATE_DIR = path.join(base, "lock-state");
-    fs.mkdirSync(hqRoot, { recursive: true });
-    fs.mkdirSync(stateDir, { recursive: true });
-    fs.mkdirSync(path.join(hqRoot, "notes"), { recursive: true });
-    fs.writeFileSync(path.join(hqRoot, "notes", "a.md"), "alpha", "utf8");
-    // More than one file so a shrunk `maxEntriesPerChunk` actually produces a
-    // multi-chunk pass.
-    fs.writeFileSync(path.join(hqRoot, "notes", "b.md"), "bravo", "utf8");
-    fs.writeFileSync(path.join(hqRoot, "notes", "c.md"), "charlie", "utf8");
-});
-afterEach(() => {
-    vi.useRealTimers();
-    if (previousLockStateDir === undefined)
-        delete process.env.HQ_STATE_DIR;
-    else
-        process.env.HQ_STATE_DIR = previousLockStateDir;
-});
-/** The happy-path server answer: folded and materialised. */
-function accepted(overrides = {}) {
-    return {
-        status: 200,
-        body: {
-            status: "accepted",
-            snapshotId: "snap-server",
-            scopeKey: SCOPE_KEY,
-            chunkIndex: 0,
-            receivedChunks: 1,
-            chunkCount: 1,
-            completed: true,
-            materialised: true,
-            ...overrides,
-        },
-    };
-}
-function transportReturning(...responses) {
-    const queue = [...responses];
-    return vi.fn(async () => queue.length > 1 ? queue.shift() : queue[0]);
-}
-function baseOptions(overrides = {}) {
-    return {
-        scope: { kind: "personal" },
-        hqRoot,
-        stateDir,
-        installationId: "install-abc123",
-        machineId: "machine-abc123",
-        source: "cli",
-        now: NOW_MS,
-        env: {},
-        listJournalsImpl: () => [],
-        transport: transportReturning(accepted()),
-        // These suites predate the stat-only default and assert on computed
-        // hashes throughout. `full` preserves exactly what they were written to
-        // exercise; the stat-only DEFAULT gets its own dedicated coverage below.
-        hashPolicy: "full",
-        ...overrides,
-    };
-}
-/**
- * A stubbed ledger that TRACKS the fixture's files.
- *
- * `baseOptions` stubs the ledger away entirely (`listJournalsImpl: () => []`),
- * which makes every entry `source: "disk"` — on-disk-never-tracked. That is a
- * perfectly good stub for a first-sync scope, but it is exactly the shape the
- * `ledger_implausible` guard refuses when a prior snapshot says the scope WAS
- * tracked. A test that wants a full upload against a seeded snapshot has to
- * describe a machine that could really exist: one whose ledger knows its files.
- */
-function ledgerTracking(...relativePaths) {
-    const files = {};
-    for (const relative of relativePaths) {
-        files[relative] = {
-            hash: `sha256:${"a".repeat(64)}`,
-            size: 5,
-            syncedAt: new Date(NOW_MS - 60_000).toISOString(),
-            direction: "up",
-        };
-    }
-    return () => [
-        {
-            slug: PERSONAL_VAULT_JOURNAL_SLUG,
-            path: path.join(stateDir, `sync-journal.${PERSONAL_VAULT_JOURNAL_SLUG}.json`),
-            journal: { version: "2", lastSync: "", files, pulls: [] },
-        },
-    ];
-}
-function seedSnapshot(overrides = {}) {
-    const snapshot = {
-        snapshotId: "snap-previous",
-        generatedAt: new Date(NOW_MS - 60_000).toISOString(),
-        sequence: 4,
-        entries: { "notes/a.md": { hash: "a".repeat(64), size: 5, mtimeMs: 1 } },
-        ...overrides,
-    };
-    writeManifestSnapshot(stateDir, SCOPE_KEY, snapshot);
-    return snapshot;
-}
-describe("runManifestUploadPass — kill switch", () => {
-    it.each(["1", "true", "TRUE", " 1 "])("is disabled by %s without building or uploading", async (value) => {
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, env: { [MANIFEST_UPLOAD_DISABLED_ENV]: value } }));
-        expect(result.status).toBe("disabled");
-        expect(transport).not.toHaveBeenCalled();
-        // Nothing was built, so nothing was written.
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)).toBeNull();
-    });
-    it.each(["", "0", "false", "no"])("is NOT disabled by %s", async (value) => {
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, env: { [MANIFEST_UPLOAD_DISABLED_ENV]: value } }));
-        expect(result.status).toBe("uploaded");
-        expect(transport).toHaveBeenCalled();
-    });
-});
-describe("runManifestUploadPass — throttle", () => {
-    it("skips a scope uploaded less than the interval ago, without building", async () => {
-        seedSnapshot({ lastUploadAt: new Date(NOW_MS - 60_000).toISOString() });
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport }));
-        expect(result).toEqual({ status: "throttled", scopeKey: SCOPE_KEY });
-        expect(transport).not.toHaveBeenCalled();
-    });
-    it("runs once the interval has elapsed", async () => {
-        seedSnapshot({
-            lastUploadAt: new Date(NOW_MS - DEFAULT_MANIFEST_UPLOAD_MIN_INTERVAL_MS - 1).toISOString(),
-        });
-        const result = await runManifestUploadPass(baseOptions());
-        expect(result.status).toBe("uploaded");
-    });
-    it("bypasses the throttle for an explicit invocation (ignoreThrottle)", async () => {
-        seedSnapshot({ lastUploadAt: new Date(NOW_MS - 60_000).toISOString() });
-        const result = await runManifestUploadPass(baseOptions({ ignoreThrottle: true }));
-        expect(result.status).toBe("uploaded");
-    });
-    it("bypasses the throttle for dryRun (printing is read-only)", async () => {
-        seedSnapshot({ lastUploadAt: new Date(NOW_MS - 60_000).toISOString() });
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, dryRun: true }));
-        expect(result.status).toBe("printed");
-        expect(transport).not.toHaveBeenCalled();
-    });
-    it("never throttles on a future lastUploadAt (clock skew must not wedge uploads off)", async () => {
-        seedSnapshot({ lastUploadAt: new Date(NOW_MS + 5 * 60_000).toISOString() });
-        const result = await runManifestUploadPass(baseOptions());
-        expect(result.status).toBe("uploaded");
-    });
-});
-describe("runManifestUploadPass — dry run", () => {
-    it("returns valid chunks, uploads nothing, and persists nothing", async () => {
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, dryRun: true }));
-        expect(result.status).toBe("printed");
-        expect(transport).not.toHaveBeenCalled();
-        expect(result.chunks?.length).toBeGreaterThan(0);
-        for (const chunk of result.chunks) {
-            expect(() => validateSyncManifestUpload(chunk)).not.toThrow();
-        }
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)).toBeNull();
-    });
-});
-describe("runManifestUploadPass — upload", () => {
-    it("persists the snapshot as the delta base only once materialised", async () => {
-        const result = await runManifestUploadPass(baseOptions());
-        expect(result.status).toBe("uploaded");
-        expect(result.nextModeFull).toBe(false);
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.snapshotId).toBe(result.snapshotId);
-        expect(stored?.baseValid).toBe(true);
-        expect(stored?.lastUploadAt).toBe(new Date(NOW_MS).toISOString());
-        expect(Object.keys(stored?.entries ?? {})).toContain("notes/a.md");
-    });
-    it("reports a REFUSED fold as failed, not uploaded, and takes the failure backoff", async () => {
-        // The canary regression. Every chunk is accepted, so the transport looks
-        // perfect — but `materialised: false` means the server wrote nothing. This
-        // used to return `uploaded` and stamp `lastUploadAt`, which armed the full
-        // 24h throttle on a failure and reported it to the daemon as a success.
-        seedSnapshot();
-        const result = await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: transportReturning(accepted({ materialised: false })),
-        }));
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("not_materialised");
-        expect(result.nextModeFull).toBe(true);
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.snapshotId).not.toBe(result.snapshotId);
-        expect(stored?.baseValid).toBe(false);
-        expect(stored?.lastUploadAt).toBeUndefined();
-        expect(stored?.lastAttemptAt).toBe(new Date(NOW_MS).toISOString());
-        expect(stored?.consecutiveFailures).toBe(1);
-    });
-    it("sends chunks sequentially in ascending chunkIndex with identical snapshot-id inputs", async () => {
-        // Three files + one entry per chunk = a genuinely multi-chunk pass. With
-        // the default 50 000-entry chunk size this fixture is ONE chunk, and every
-        // assertion below is vacuously true.
-        const seen = [];
-        const transport = vi.fn(async (chunk) => {
-            seen.push(chunk);
-            return accepted({
-                chunkIndex: chunk.chunkIndex,
-                chunkCount: chunk.chunkCount,
-                completed: chunk.chunkIndex === chunk.chunkCount - 1,
-                materialised: chunk.chunkIndex === chunk.chunkCount - 1,
-            });
-        });
-        const result = await runManifestUploadPass(baseOptions({ transport, maxEntriesPerChunk: 1 }));
-        expect(result.status).toBe("uploaded");
-        expect(seen.length).toBeGreaterThan(1);
-        expect(result.chunkCount).toBe(seen.length);
-        expect(result.uploadedChunks).toBe(seen.length);
-        expect(seen.map((chunk) => chunk.chunkIndex)).toEqual(seen.map((_chunk, index) => index));
-        const first = seen[0];
-        for (const chunk of seen) {
-            // The server hashes exactly these fields into the snapshotId, so a
-            // single drifting field scatters one pass across several snapshots.
-            expect(chunk.generatedAt).toBe(first.generatedAt);
-            expect(chunk.sequence).toBe(first.sequence);
-            expect(chunk.chunkCount).toBe(first.chunkCount);
-            expect(chunk.machineId).toBe(first.machineId);
-            expect(chunk.installationId).toBe(first.installationId);
-            expect(chunk.mode).toBe(first.mode);
-            expect(chunk.scope).toEqual(first.scope);
-        }
-    });
-    it("refuses the delta base when the server's snapshotId drifts between chunks", async () => {
-        let call = 0;
-        const transport = vi.fn(async (chunk) => {
-            call += 1;
-            return accepted({
-                snapshotId: `snap-server-${call}`,
-                chunkIndex: chunk.chunkIndex,
-                chunkCount: chunk.chunkCount,
-                completed: chunk.chunkIndex === chunk.chunkCount - 1,
-                materialised: true,
-            });
-        });
-        const error = vi.fn();
-        const result = await runManifestUploadPass(baseOptions({ transport, maxEntriesPerChunk: 1, logger: { error } }));
-        // Two ids for one pass means the snapshot is scattered across rows that
-        // can each only ever stay partial — none of them is a legal base.
-        expect(result.nextModeFull).toBe(true);
-        expect(error).toHaveBeenCalled();
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.baseValid).toBe(false);
-    });
-    it("stops mid-pass on an abort and still burns the sequence", async () => {
-        seedSnapshot({ sequence: 30 });
-        const controller = new AbortController();
-        const seen = [];
-        const transport = vi.fn(async (chunk) => {
-            seen.push(chunk);
-            controller.abort();
-            return accepted({ chunkIndex: chunk.chunkIndex, completed: false, materialised: false });
-        });
-        const result = await runManifestUploadPass(baseOptions({
-            transport,
-            ignoreThrottle: true,
-            maxEntriesPerChunk: 1,
-            abortSignal: controller.signal,
-        }));
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("aborted");
-        // The remaining chunks were NOT sent...
-        expect(seen).toHaveLength(1);
-        expect((result.chunkCount ?? 0) > seen.length).toBe(true);
-        // ...and the half-spent sequence is never handed out again.
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(31);
-        // Nothing materialised, so this must not have armed the 24h throttle.
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.lastUploadAt).toBeUndefined();
-    });
-    it("never puts a caller-selected identity on the wire", async () => {
-        const seen = [];
-        const transport = vi.fn(async (chunk) => {
-            seen.push(chunk);
-            return accepted();
-        });
-        await runManifestUploadPass(baseOptions({ transport }));
-        for (const chunk of seen) {
-            const raw = chunk;
-            expect(raw.personUid).toBeUndefined();
-            expect(raw.person_uid).toBeUndefined();
-            expect(raw.ownerUid).toBeUndefined();
-            expect(raw.callerSub).toBeUndefined();
-        }
-    });
-});
-describe("runManifestUploadPass — resend_full", () => {
-    it("stops the pass, clears the base, and schedules a full manifest", async () => {
-        seedSnapshot();
-        const transport = transportReturning({ status: 200, body: { status: "resend_full", scopeKey: SCOPE_KEY } });
-        const result = await runManifestUploadPass(baseOptions({ ignoreThrottle: true, transport }));
-        expect(result.status).toBe("resend_full_scheduled");
-        expect(result.nextModeFull).toBe(true);
-        expect(transport).toHaveBeenCalledTimes(1);
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.baseValid).toBe(false);
-        expect(stored?.entries).toEqual({});
-    });
-    it("abandons the pass on snapshot_abandoned without retrying the same snapshot", async () => {
-        const transport = transportReturning({
-            status: 200,
-            body: { status: "resend_full", scopeKey: SCOPE_KEY, reason: "snapshot_abandoned" },
-        });
-        const result = await runManifestUploadPass(baseOptions({ transport }));
-        expect(result.status).toBe("resend_full_scheduled");
-        expect(result.error?.detail).toBe("snapshot_abandoned");
-        expect(transport).toHaveBeenCalledTimes(1);
-    });
-    it("does NOT read a non-2xx as resend_full (the server's 409 is VAULT_NOT_PROVISIONED)", async () => {
-        const result = await runManifestUploadPass(baseOptions({
-            transport: transportReturning({
-                status: 409,
-                body: { error: "Vault bucket is not provisioned", code: "VAULT_NOT_PROVISIONED" },
-            }),
-        }));
-        // A hard misconfiguration must surface as a failure, and must NOT arm the
-        // 24h throttle — otherwise each attempt hides the fault for a day.
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("rejected");
-        expect(result.error?.status).toBe(409);
-        expect(result.error?.detail).toBe("VAULT_NOT_PROVISIONED");
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.lastUploadAt).toBeUndefined();
-    });
-    it("still reads a 200 body that says resend_full", async () => {
-        const result = await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 200, body: { status: "resend_full" } }) }));
-        expect(result.status).toBe("resend_full_scheduled");
-    });
-    it("makes the NEXT pass full after the base is invalidated", async () => {
-        seedSnapshot();
-        await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: transportReturning({ status: 200, body: { status: "resend_full", scopeKey: SCOPE_KEY } }),
-        }));
-        const seen = [];
-        const second = await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: vi.fn(async (chunk) => {
-                seen.push(chunk);
-                return accepted();
-            }),
-        }));
-        expect(second.mode).toBe("full");
-        expect(seen[0].mode).toBe("full");
-        expect(seen[0].baseSnapshotId).toBeUndefined();
-    });
-});
-describe("runManifestUploadPass — soft skip and size limits", () => {
-    it("treats 404 as a soft skip with no error and no delta base", async () => {
-        const info = vi.fn();
-        const result = await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 404 }), logger: { info } }));
-        expect(result.status).toBe("soft_skipped");
-        expect(result.error).toBeUndefined();
-        expect(info).toHaveBeenCalled();
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.baseValid).toBe(false);
-    });
-    /**
-     * THE 6.16.21 CANARY REGRESSION, PINNED.
-     *
-     * `chunk_too_large` used to take `recordUploadAttempt`, which writes
-     * `lastUploadAt` — the field the 24h throttle reads. A scope that could not
-     * physically upload therefore reported a healthy last-upload time and then
-     * refused to try again for a day. These cases assert the opposite of the
-     * three things that made that possible: no `lastUploadAt`, a real failure
-     * count, and a smaller budget waiting for the next pass.
-     */
-    it("treats chunk_too_large as a CLIENT fault: failure backoff, never the 24h throttle", async () => {
-        const result = await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 413, body: { reason: "chunk_too_large" } }) }));
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("chunk_too_large");
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        // The load-bearing assertion. `lastUploadAt` means "the server has a
-        // picture from this time"; a 413 is proof that it does not.
-        expect(stored?.lastUploadAt).toBeUndefined();
-        expect(stored?.lastAttemptAt).toBe(new Date(NOW_MS).toISOString());
-        expect(stored?.consecutiveFailures).toBe(1);
-    });
-    it("halves the byte budget on a 413 and persists it for the NEXT pass", async () => {
-        const first = await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 413, body: { reason: "chunk_too_large" } }) }));
-        const halved = SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET / 2;
-        expect(first.chunkByteBudget).toBe(halved);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.chunkByteBudget).toBe(halved);
-        // The next pass PLANS against the reduced budget rather than re-deriving
-        // the default and failing identically forever. `ignoreThrottle` stands in
-        // for the hour the failure backoff would otherwise impose.
-        const second = await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: transportReturning({ status: 413, body: { reason: "chunk_too_large" } }),
-        }));
-        expect(second.chunkByteBudget).toBe(halved / 2);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.chunkByteBudget).toBe(halved / 2);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.consecutiveFailures).toBe(2);
-    });
-    it("halves only ONCE per pass — never retries a resized plan mid-flight", async () => {
-        // A mid-pass re-plan would move `chunkCount`, which the server hashes into
-        // the snapshotId, so one 413 must end the pass rather than shrink and
-        // resend. Asserted on the transport: exactly one POST, not two.
-        const transport = transportReturning({ status: 413, body: { reason: "chunk_too_large" } });
-        const result = await runManifestUploadPass(baseOptions({ transport }));
-        expect(transport).toHaveBeenCalledTimes(1);
-        expect(result.chunkByteBudget).toBe(SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET / 2);
-    });
-    it("stops halving at the floor rather than shrinking towards zero", async () => {
-        const result = await runManifestUploadPass(baseOptions({
-            chunkByteBudget: MANIFEST_CHUNK_BYTE_BUDGET_FLOOR,
-            transport: transportReturning({ status: 413, body: { reason: "chunk_too_large" } }),
-        }));
-        expect(result.chunkByteBudget).toBe(MANIFEST_CHUNK_BYTE_BUDGET_FLOOR);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.chunkByteBudget).toBe(MANIFEST_CHUNK_BYTE_BUDGET_FLOOR);
-    });
-    it("treats a bare 413 with no reason (the gateway's own answer) as a sizing fault", async () => {
-        // API Gateway refuses an oversized body BEFORE the handler runs and
-        // answers with an opaque error carrying no reason code. That is the exact
-        // shape the operator's canary hit, so it must self-heal identically.
-        const result = await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 413, body: { message: "Request Entity Too Large" } }) }));
-        expect(result.error?.kind).toBe("chunk_too_large");
-        expect(result.chunkByteBudget).toBe(SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET / 2);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.lastUploadAt).toBeUndefined();
-    });
-    it("distinguishes manifest_too_large on a 413 — non-retryable, so it backs off without shrinking", async () => {
-        const result = await runManifestUploadPass(baseOptions({
-            transport: transportReturning({
-                status: 413,
-                body: { reason: "manifest_too_large", maxTotalEntries: 10, scopeKey: SCOPE_KEY },
-            }),
-        }));
-        expect(result.error?.kind).toBe("manifest_too_large");
-        expect(result.nextModeFull).toBe(true);
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.baseValid).toBe(false);
-        // Re-sending at ANY chunk size gets the same answer — the ceiling counts
-        // entries, not bytes — so this one must NOT shrink the budget. It is still
-        // a failure, so it takes the escalating backoff (1h, climbing to the same
-        // 24h ceiling) rather than claiming an upload that never landed.
-        expect(stored?.lastUploadAt).toBeUndefined();
-        expect(stored?.lastAttemptAt).toBe(new Date(NOW_MS).toISOString());
-        expect(stored?.consecutiveFailures).toBe(1);
-        expect(stored?.chunkByteBudget).toBeUndefined();
-    });
-});
-describe("runManifestUploadPass — sequence", () => {
-    it("starts at 1 with no snapshot and strictly increases across passes", async () => {
-        const seen = [];
-        const transport = vi.fn(async (chunk) => {
-            seen.push(chunk);
-            return accepted();
-        });
-        await runManifestUploadPass(baseOptions({ transport }));
-        await runManifestUploadPass(baseOptions({ transport, ignoreThrottle: true }));
-        await runManifestUploadPass(baseOptions({ transport, ignoreThrottle: true }));
-        const sequences = seen.map((chunk) => chunk.sequence);
-        expect(sequences[0]).toBe(1);
-        for (let index = 1; index < sequences.length; index += 1) {
-            expect(sequences[index]).toBeGreaterThan(sequences[index - 1]);
-        }
-    });
-    it("advances the sequence even when the pass did not materialise", async () => {
-        seedSnapshot({ sequence: 9 });
-        await runManifestUploadPass(baseOptions({ ignoreThrottle: true, transport: transportReturning({ status: 404 }) }));
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(10);
-    });
-});
-describe("runManifestUploadPass — failure containment", () => {
-    it("returns a failed result rather than rejecting when the transport throws", async () => {
-        const result = await runManifestUploadPass(baseOptions({
-            transport: vi.fn(async () => {
-                throw new TypeError("fetch failed");
-            }),
-        }));
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("transport_error");
-        expect(result.error?.detail).toBe("TypeError");
-        // A network blip must not be recorded as an upload, or the throttle would
-        // suppress the retry for a day...
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.lastUploadAt).toBeUndefined();
-        expect(stored?.baseValid).toBe(false);
-        // ...but the sequence it burned must never be handed out a second time.
-        expect(stored?.sequence).toBe(1);
-    });
-    it("advances the sequence on a transport failure so the next pass cannot replay it", async () => {
-        seedSnapshot({ sequence: 7 });
-        await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: vi.fn(async () => {
-                throw new TypeError("fetch failed");
-            }),
-        }));
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(8);
-        const seen = [];
-        await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: vi.fn(async (chunk) => {
-                seen.push(chunk);
-                return accepted();
-            }),
-        }));
-        expect(seen[0].sequence).toBe(9);
-    });
-    it("advances the sequence on an unexpected status and on an abort", async () => {
-        seedSnapshot({ sequence: 20 });
-        await runManifestUploadPass(baseOptions({ ignoreThrottle: true, transport: transportReturning({ status: 500 }) }));
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(21);
-        // An abort that trips before the first chunk still burned sequence 22.
-        const controller = new AbortController();
-        controller.abort();
-        await runManifestUploadPass(baseOptions({ ignoreThrottle: true, abortSignal: controller.signal }));
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(22);
-    });
-    it("returns a failed result on an unexpected status", async () => {
-        const result = await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 500, body: { code: "INTERNAL" } }) }));
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("rejected");
-        expect(result.error?.status).toBe(500);
-    });
-    it("returns a non-throwing result when the pass is aborted before the walk finishes", async () => {
-        const controller = new AbortController();
-        controller.abort();
-        const result = await runManifestUploadPass(baseOptions({ abortSignal: controller.signal }));
-        // An abort raised before/during the walk truncates it, and a truncated
-        // walk is now refused at the upload gate rather than sent as a (possibly
-        // empty) full manifest. Either way the contract that matters is unchanged:
-        // it resolves, it never throws, and nothing was uploaded.
-        expect(["walk_truncated", "failed"]).toContain(result.status);
-        expect(result.uploadedChunks ?? 0).toBe(0);
-    });
-    it("throws only for programmer errors (invalid options)", async () => {
-        await expect(runManifestUploadPass(baseOptions({ installationId: "" }))).rejects.toThrow(/installationId is required/);
-    });
-});
-describe("runManifestUploadPass — staleness", () => {
-    it("forces a full manifest when the persisted base is older than the max age", async () => {
-        seedSnapshot({
-            generatedAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-            lastUploadAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-        });
-        const seen = [];
-        const result = await runManifestUploadPass(baseOptions({
-            // A tracked ledger, because this scope demonstrably HAS synced before
-            // (it has a snapshot); a 100%-disk full manifest here would be the
-            // implausible picture the guard exists to refuse.
-            listJournalsImpl: ledgerTracking("notes/a.md", "notes/b.md", "notes/c.md"),
-            transport: vi.fn(async (chunk) => {
-                seen.push(chunk);
-                return accepted();
-            }),
-        }));
-        expect(result.mode).toBe("full");
-        expect(seen[0].baseSnapshotId).toBeUndefined();
-    });
-    it("quotes the SERVER's snapshotId as baseSnapshotId, never the local snap-* handle", async () => {
-        const first = await runManifestUploadPass(baseOptions({ transport: transportReturning(accepted({ snapshotId: "0123456789abcdef0123456789abcdef" })) }));
-        expect(first.snapshotId).toBe("0123456789abcdef0123456789abcdef");
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.snapshotId).toBe("0123456789abcdef0123456789abcdef");
-        expect(stored?.snapshotId?.startsWith("snap-")).toBe(false);
-        const seen = [];
-        await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: vi.fn(async (chunk) => {
-                seen.push(chunk);
-                return accepted();
-            }),
-        }));
-        // The server compares this against the snapshotId on its materialised
-        // view. A local `snap-*` id can never match, so a delta would be answered
-        // resend_full on every single pass.
-        expect(seen[0].mode).toBe("delta");
-        expect(seen[0].baseSnapshotId).toBe("0123456789abcdef0123456789abcdef");
-    });
-    it("does NOT persist a base when an accepted response carries no snapshotId", async () => {
-        const result = await runManifestUploadPass(baseOptions({
-            transport: transportReturning({
-                status: 200,
-                body: { status: "accepted", completed: true, materialised: true },
-            }),
-        }));
-        expect(result.nextModeFull).toBe(true);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.baseValid).toBe(false);
-    });
-    it("sends a delta against a fresh, materialised base", async () => {
-        const first = await runManifestUploadPass(baseOptions());
-        const seen = [];
-        const second = await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: vi.fn(async (chunk) => {
-                seen.push(chunk);
-                return accepted();
-            }),
-        }));
-        expect(second.mode).toBe("delta");
-        expect(seen[0].baseSnapshotId).toBe(first.snapshotId);
-    });
-});
-describe("readManifestUploadStatus", () => {
-    it("reports never-uploaded for a missing snapshot", () => {
-        expect(readManifestUploadStatus(stateDir, [{ kind: "personal" }])).toEqual([
-            { scopeKey: SCOPE_KEY, lastUploadAt: null, snapshotId: null, sequence: 0, baseUsable: false },
-        ]);
-    });
-    it("reports never-uploaded for a snapshot written by an older version", () => {
-        seedSnapshot();
-        expect(readManifestUploadStatus(stateDir, [{ kind: "personal" }])[0]).toEqual({
-            scopeKey: SCOPE_KEY,
-            lastUploadAt: null,
-            snapshotId: "snap-previous",
-            sequence: 4,
-            baseUsable: true,
-        });
-    });
-    it("reports the last upload time after a successful pass", async () => {
-        const result = await runManifestUploadPass(baseOptions());
-        expect(readManifestUploadStatus(stateDir, [{ kind: "personal" }])[0]).toEqual({
-            scopeKey: SCOPE_KEY,
-            lastUploadAt: new Date(NOW_MS).toISOString(),
-            snapshotId: result.snapshotId,
-            sequence: 1,
-            baseUsable: true,
-        });
-    });
-});
-describe("runManifestUploadPass — persistence failures", () => {
-    /**
-     * `writeManifestSnapshot` swallows disk errors and returns `false`. Making
-     * the snapshot DIRECTORY a regular file is the cheapest faithful way to
-     * reproduce that (mkdir/rename both fail) without stubbing the store.
-     */
-    function blockSnapshotWrites() {
-        fs.mkdirSync(stateDir, { recursive: true });
-        fs.writeFileSync(path.join(stateDir, MANIFEST_SNAPSHOT_DIRNAME), "not a directory", "utf8");
-    }
-    it("reports a full next pass and logs when the delta base cannot be written", async () => {
-        blockSnapshotWrites();
-        const error = vi.fn();
-        const result = await runManifestUploadPass(baseOptions({ logger: { error } }));
-        expect(result.status).toBe("uploaded");
-        // No base on disk means the next pass CANNOT be a delta. Reporting
-        // `false` here would promise the caller a base that does not exist.
-        expect(result.nextModeFull).toBe(true);
-        // And it must be loud: an unwritable snapshot silently disables both the
-        // 24h throttle and the monotonic sequence.
-        expect(error).toHaveBeenCalled();
-    });
-    it("logs when a failure path cannot burn the sequence", async () => {
-        blockSnapshotWrites();
-        const error = vi.fn();
-        const result = await runManifestUploadPass(baseOptions({
-            logger: { error },
-            transport: vi.fn(async () => {
-                throw new TypeError("fetch failed");
-            }),
-        }));
-        expect(result.status).toBe("failed");
-        expect(error).toHaveBeenCalled();
-    });
-});
-describe("runManifestUploadPass — failure paths all advance the sequence", () => {
-    it("burns the sequence when the BUILD fails before anything is uploaded", async () => {
-        // A company scope that carries a companyUid but no slug: the snapshot key
-        // derives fine, then the builder rejects it. That is the one shape of
-        // build failure this seam can actually see — the walk itself degrades
-        // rather than throwing.
-        const scope = { kind: "company", companyUid: "co-alpha" };
-        const companyScopeKey = manifestSnapshotScopeKey({ kind: "company", companyUid: "co-alpha" });
-        writeManifestSnapshot(stateDir, companyScopeKey, {
-            snapshotId: "snap-previous",
-            generatedAt: new Date(NOW_MS - 60_000).toISOString(),
-            sequence: 40,
-            entries: {},
-        });
-        const result = await runManifestUploadPass(baseOptions({ ignoreThrottle: true, scope }));
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("build_error");
-        // The rule is unconditional: EVERY outcome advances the sequence, so no
-        // future edit to this path can silently reuse one.
-        expect(readManifestSnapshot(stateDir, companyScopeKey)?.sequence).toBe(41);
-        // ...but a build failure uploaded nothing, so the throttle must not arm.
-        expect(readManifestSnapshot(stateDir, companyScopeKey)?.lastUploadAt).toBeUndefined();
-    });
-    it("keeps a usable base across a transport blip instead of forcing a full re-send", async () => {
-        // A materialised pass first, so there IS a base to preserve.
-        await runManifestUploadPass(baseOptions());
-        const result = await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: vi.fn(async () => {
-                throw new TypeError("fetch failed");
-            }),
-        }));
-        expect(result.status).toBe("failed");
-        // Nothing reached the server, so its materialised view still matches the
-        // base we hold: forcing a full 70k re-send on every network hiccup would
-        // be a self-inflicted outage.
-        expect(result.nextModeFull).toBe(false);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.baseValid).not.toBe(false);
-    });
-});
-// ─── Fix 1: a wedged transport must not wedge the pass ───────────────────────
-/** A promise the test settles by hand — stands in for a black-holed socket. */
-function deferred() {
-    let resolve;
-    let reject;
-    const promise = new Promise((res, rej) => {
-        resolve = res;
-        reject = rej;
-    });
-    return { promise, resolve, reject };
-}
-describe("runManifestUploadPass — the pass is bounded", () => {
-    it("returns (rather than hanging) when the transport never settles, and burns the sequence", async () => {
-        // A materialised pass first, so there IS a delta base for the wedged pass
-        // to leave alone.
-        await runManifestUploadPass(baseOptions());
-        const pending = deferred();
-        const transport = vi.fn(() => pending.promise);
-        const result = await runManifestUploadPass(baseOptions({ transport, uploadWallMs: 50, ignoreThrottle: true }));
-        // The daemon `await`s this after every sync cycle; the ONLY thing that
-        // matters here is that the await completed at all.
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("upload_timeout");
-        expect(result.uploadedChunks).toBe(0);
-        expect(transport).toHaveBeenCalledTimes(1);
-        // Nothing reached the server's materialised view, so the base it holds is
-        // still right — a wall-clock stop must not force a full re-send.
-        expect(result.nextModeFull).toBe(false);
-        // The sequence is burned even though nothing was uploaded: the server may
-        // already have folded a chunk under it, and handing it out twice is the
-        // collision this module exists to avoid.
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(2);
-        // `lastUploadAt` still names the FIRST pass — the wedged one recorded no
-        // upload, so the 24h throttle cannot suppress its retry.
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.lastUploadAt).toBe(new Date(NOW_MS).toISOString());
-    });
-    it("does not produce an unhandled rejection when the abandoned transport later fails", async () => {
-        const seen = [];
-        const onUnhandled = (reason) => seen.push(reason);
-        process.on("unhandledRejection", onUnhandled);
-        try {
-            const pending = deferred();
-            const result = await runManifestUploadPass(baseOptions({ transport: vi.fn(() => pending.promise), uploadWallMs: 50 }));
-            expect(result.status).toBe("failed");
-            // The pass has already returned; the socket it walked away from now
-            // dies. On a long-lived daemon an unhandled rejection here is a crash.
-            pending.reject(new TypeError("socket hang up"));
-            await new Promise((resolve) => setTimeout(resolve, 20));
-            expect(seen).toEqual([]);
-        }
-        finally {
-            process.off("unhandledRejection", onUnhandled);
-        }
-    });
-    it("stops sending when the caller aborts while a chunk is in flight", async () => {
-        const controller = new AbortController();
-        const pending = deferred();
-        const transport = vi.fn(() => {
-            // Abort only once the call is genuinely in flight — the pre-loop check
-            // cannot catch this, which is the whole point of the race.
-            setTimeout(() => controller.abort(), 5);
-            return pending.promise;
-        });
-        const result = await runManifestUploadPass(baseOptions({ transport, abortSignal: controller.signal, uploadWallMs: 60_000 }));
-        expect(result.status).toBe("failed");
-        expect(result.error?.kind).toBe("aborted");
-        expect(transport).toHaveBeenCalledTimes(1);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(1);
-    });
-    it("leaves no pending timer behind after a pass that finished normally", async () => {
-        // `shouldAdvanceTime` keeps real time flowing (the builder's fs work still
-        // completes) while making the timer queue observable.
-        vi.useFakeTimers({ shouldAdvanceTime: true });
-        const result = await runManifestUploadPass(baseOptions({ uploadWallMs: 10 * 60_000 }));
-        expect(result.status).toBe("uploaded");
-        // A 10-minute deadline timer left armed would keep a short-lived `hq sync
-        // manifest` process alive long after it printed its result.
-        expect(vi.getTimerCount()).toBe(0);
-    });
-});
-// ─── Fix 2: the per-scope sequence is not a read-modify-write race ───────────
-describe("runManifestUploadPass — per-scope serialisation", () => {
-    it("cannot let two concurrent passes derive the same sequence", async () => {
-        const sent = [];
-        const transport = vi.fn(async (chunk) => {
-            sent.push(chunk);
-            return accepted();
-        });
-        // The exact production collision: a daemon pass and a `hq sync manifest`
-        // (which sets `ignoreThrottle`, so nothing spaces them out) starting
-        // together on one scope.
-        const [a, b] = await Promise.all([
-            runManifestUploadPass(baseOptions({ transport, source: "desktop" })),
-            runManifestUploadPass(baseOptions({ transport, source: "cli", ignoreThrottle: true })),
-        ]);
-        expect([a.status, b.status].sort()).toEqual(["locked", "uploaded"]);
-        // The refused pass is a benign skip, not a throw and not an error result:
-        // an audit must never block a sync pass.
-        const skipped = a.status === "locked" ? a : b;
-        expect(skipped.error).toBeUndefined();
-        expect(skipped.scopeKey).toBe(SCOPE_KEY);
-        // ONE sequence on the wire. Two passes sharing a sequence (with the same
-        // pinned `generatedAt` and chunk count) is exactly what makes the server
-        // derive a single snapshotId and merge both chunk sets into it.
-        expect([...new Set(sent.map((chunk) => chunk.sequence))]).toEqual([1]);
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(1);
-        // And the next pass moves on rather than replaying.
-        const next = await runManifestUploadPass(baseOptions({ transport, ignoreThrottle: true, now: NOW_MS + 1000 }));
-        expect(next.status).toBe("uploaded");
-        expect(readManifestSnapshot(stateDir, SCOPE_KEY)?.sequence).toBe(2);
-    });
-    it("reclaims a lock held by a crashed process rather than wedging the scope", async () => {
-        const lockPath = lockPathFor(hqRoot, `manifest-${manifestSnapshotScopeSlug(SCOPE_KEY)}`);
-        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-        fs.writeFileSync(lockPath, JSON.stringify({
-            // No such process: above every platform's pid ceiling, so `kill(pid,0)`
-            // answers ESRCH and the holder reads as dead.
-            pid: 999_999,
-            command: MANIFEST_UPLOAD_LOCK_COMMAND,
-            startedAt: new Date(NOW_MS - 3_600_000).toISOString(),
-            hqRoot,
-            mode: "exclusive",
-        }), "utf8");
-        const result = await runManifestUploadPass(baseOptions());
-        expect(result.status).toBe("uploaded");
-    });
-    it("does not serialise `--print`, which uploads nothing and burns no sequence", async () => {
-        const transport = vi.fn(async () => accepted());
-        const [printed, uploaded] = await Promise.all([
-            runManifestUploadPass(baseOptions({ transport, dryRun: true })),
-            runManifestUploadPass(baseOptions({ transport })),
-        ]);
-        expect(printed.status).toBe("printed");
-        expect(uploaded.status).toBe("uploaded");
-    });
-});
-/**
- * A truncated walk describes only the part of the scope the walker reached.
- * It must never go on the wire.
- *
- * Found on a real 690k-file personal vault: the 30s walk budget expired after
- * ~179k files with ZERO entries assembled, and the pass POSTed that as a FULL
- * manifest. A full manifest is a complete statement — "this is everything I
- * hold" — so the server's materialised view for the scope became empty and
- * every file the client actually held would read as missing. Suppressing the
- * delta base (which the builder already did) does not help: the damage is done
- * server-side by the upload itself.
- */
-describe("runManifestUploadPass — a truncated walk is never uploaded", () => {
-    /**
-     * Force truncation by putting the walk's deadline in the PAST.
-     *
-     * `0` is not enough: the walk compares `Date.now() > deadlineMs`, and a
-     * three-file fixture finishes inside the same millisecond, so a zero budget
-     * completes normally and the test silently exercises the happy path instead.
-     */
-    function truncatingOptions(overrides = {}) {
-        return baseOptions({ maxWallMs: -1, ...overrides });
-    }
-    it("refuses the POST entirely and reports walk_truncated", async () => {
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(truncatingOptions({ transport }));
-        expect(result.status).toBe("walk_truncated");
-        expect(result.uploadedChunks).toBe(0);
-        expect(transport).not.toHaveBeenCalled();
-    });
-    it("does not become the delta base, and does not arm the 24h throttle", async () => {
-        await runManifestUploadPass(truncatingOptions());
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.baseValid).toBe(false);
-        // `lastUploadAt` means "the server has a picture from this time". Nothing
-        // was sent, so claiming one would hide a scope that can never complete.
-        expect(stored?.lastUploadAt).toBeUndefined();
-        expect(stored?.lastAttemptAt).toBe(new Date(NOW_MS).toISOString());
-    });
-    it("leaves an existing, complete delta base intact", async () => {
-        // A base captured from a COMPLETE walk is still the right thing to delta
-        // against; a later truncated pass says nothing about it.
-        seedSnapshot({ lastUploadAt: undefined });
-        const result = await runManifestUploadPass(truncatingOptions());
-        expect(result.status).toBe("walk_truncated");
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(Object.keys(stored?.entries ?? {})).toContain("notes/a.md");
-    });
-    it("the next pass is a full walk, not a delta with mass removedPaths", async () => {
-        // The regression this guards: a truncated walk persisted as the base would
-        // make the following pass emit every unreached file as REMOVED.
-        seedSnapshot({ lastUploadAt: undefined });
-        await runManifestUploadPass(truncatingOptions());
-        const sent = [];
-        await runManifestUploadPass(baseOptions({
-            // Past this scope's failure floor, so the retry is allowed to run.
-            now: NOW_MS + MANIFEST_FAILURE_BACKOFF_BASE_MS + 1,
-            transport: vi.fn(async (chunk) => {
-                sent.push(chunk);
-                return accepted();
-            }),
-        }));
-        expect(sent).toHaveLength(1);
-        expect(sent[0]?.removedPaths).toEqual([]);
-        expect(sent[0]?.entries.map((entry) => entry.path)).toContain("notes/a.md");
-    });
-    it("still PRINTS a truncated manifest for --print, which is what a debugger needs", async () => {
-        const result = await runManifestUploadPass(truncatingOptions({ dryRun: true }));
-        expect(result.status).toBe("printed");
-    });
-});
-/**
- * A pass that fails before the server answers must back off.
- *
- * `lastUploadAt` — the field arming the 24h throttle — is only written by a
- * pass the server ANSWERED. That is deliberate (a network blip must not
- * suppress the audit for a day), but on its own it means a scope that can
- * never succeed re-walks (and, under the old default, re-HASHED) the entire
- * tree on every single sync cycle, forever, to produce an upload guaranteed to
- * fail again.
- */
-describe("runManifestUploadPass — failure backoff", () => {
-    it("records a retry floor after a 403 without claiming an upload", async () => {
-        const result = await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 403, body: { code: "INSTALLATION_NOT_ENROLLED" } }) }));
-        expect(result.status).toBe("failed");
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.lastAttemptAt).toBe(new Date(NOW_MS).toISOString());
-        expect(stored?.consecutiveFailures).toBe(1);
-        expect(stored?.lastUploadAt).toBeUndefined();
-    });
-    it("skips the next pass inside the floor — no walk, no POST", async () => {
-        await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 403, body: { code: "INSTALLATION_NOT_ENROLLED" } }) }));
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ now: NOW_MS + MANIFEST_FAILURE_BACKOFF_BASE_MS - 1, transport }));
-        expect(result.status).toBe("throttled");
-        expect(transport).not.toHaveBeenCalled();
-    });
-    it("retries once the floor expires", async () => {
-        await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 500, body: {} }) }));
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ now: NOW_MS + MANIFEST_FAILURE_BACKOFF_BASE_MS + 1, transport }));
-        expect(result.status).toBe("uploaded");
-        expect(transport).toHaveBeenCalled();
-    });
-    it("doubles the floor on each consecutive failure", async () => {
-        const failing = () => transportReturning({ status: 500, body: {} });
-        await runManifestUploadPass(baseOptions({ transport: failing() }));
-        await runManifestUploadPass(baseOptions({ now: NOW_MS + MANIFEST_FAILURE_BACKOFF_BASE_MS + 1, transport: failing() }));
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.consecutiveFailures).toBe(2);
-        expect(manifestFailureBackoffMs(2)).toBe(MANIFEST_FAILURE_BACKOFF_BASE_MS * 2);
-    });
-    it("caps the floor at 24h however many times it has failed", () => {
-        expect(manifestFailureBackoffMs(0)).toBe(0);
-        expect(manifestFailureBackoffMs(1)).toBe(MANIFEST_FAILURE_BACKOFF_BASE_MS);
-        expect(manifestFailureBackoffMs(50)).toBe(24 * 60 * 60 * 1000);
-        // A corrupt count must not produce a floor that never expires.
-        expect(manifestFailureBackoffMs(Number.POSITIVE_INFINITY)).toBe(0);
-    });
-    it("clears the floor as soon as the server answers", async () => {
-        await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 500, body: {} }) }));
-        await runManifestUploadPass(baseOptions({ now: NOW_MS + MANIFEST_FAILURE_BACKOFF_BASE_MS + 1, transport: transportReturning(accepted()) }));
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.lastAttemptAt).toBeUndefined();
-        expect(stored?.consecutiveFailures).toBeUndefined();
-    });
-    it("KEEPS escalating the floor on a 404 soft skip — an answer is not an upload", async () => {
-        // A 404 means the route is not deployed on this server yet. That is a
-        // healthy machine, but it is emphatically not an upload: stamping
-        // `lastUploadAt` for it (as the old "the endpoint answered" rule did) told
-        // `hq doctor` the scope was audited when nothing had ever been sent.
-        await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 500, body: {} }) }));
-        await runManifestUploadPass(baseOptions({
-            now: NOW_MS + MANIFEST_FAILURE_BACKOFF_BASE_MS + 1,
-            transport: transportReturning({ status: 404, body: {} }),
-        }));
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(stored?.consecutiveFailures).toBe(2);
-        expect(stored?.lastUploadAt).toBeUndefined();
-    });
-    it("is bypassed by an explicit human invocation", async () => {
-        await runManifestUploadPass(baseOptions({ transport: transportReturning({ status: 500, body: {} }) }));
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ now: NOW_MS + 1000, ignoreThrottle: true, transport }));
-        expect(result.status).toBe("uploaded");
-        expect(transport).toHaveBeenCalled();
-    });
-    it("does not trust a floor stamped in the future", async () => {
-        // Clock skew or a restored backup must not wedge a scope off the audit.
-        writeManifestSnapshot(stateDir, SCOPE_KEY, {
-            snapshotId: "snap-none",
-            generatedAt: new Date(NOW_MS).toISOString(),
-            sequence: 1,
-            entries: {},
-            baseValid: false,
-            lastAttemptAt: new Date(NOW_MS + 60 * 60 * 1000).toISOString(),
-            consecutiveFailures: 3,
-        });
-        const result = await runManifestUploadPass(baseOptions());
-        expect(result.status).toBe("uploaded");
-    });
-});
-/**
- * The incident: a machine whose v3 ledger was corrupt in EVERY generation
- * reported all 188,997 of its files as `source: "disk"` — on-disk,
- * never-tracked — and uploaded that as a complete FULL manifest. `full` is a
- * total statement, so the server's materialised view for the scope became
- * "this client tracks nothing", and every file the user actually held read as
- * drift.
- *
- * The ledger read is fixed upstream (an unreadable ledger is no longer an
- * empty one). These pin the BACKSTOP: whatever makes a ledger disappear next
- * time, a scope that was tracked yesterday does not become untracked today.
- */
-describe("runManifestUploadPass — implausible ledger guard", () => {
-    it("refuses to upload a 100%-disk FULL manifest for a scope with a tracked snapshot", async () => {
-        // The scope HAS synced: the server materialised a snapshot for it.
-        seedSnapshot({
-            generatedAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-            lastUploadAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-        });
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(
-        // The stale base forces `full`; the empty ledger stub is the corrupt
-        // machine's view of itself.
-        baseOptions({ transport, listJournalsImpl: () => [] }));
-        expect(result.status).toBe("ledger_implausible");
-        expect(result.uploadedChunks).toBe(0);
-        // The load-bearing assertion: not one byte reached the server.
-        expect(transport).not.toHaveBeenCalled();
-    });
-    it("leaves the stored delta base intact and only burns the sequence", async () => {
-        const seeded = seedSnapshot({
-            generatedAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-            lastUploadAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-        });
-        await runManifestUploadPass(baseOptions({ listJournalsImpl: () => [] }));
-        const stored = readManifestSnapshot(stateDir, SCOPE_KEY);
-        // The base still describes a real, tracked scope — refusing this pass must
-        // not also destroy the good record that proved it was wrong.
-        expect(stored?.entries).toEqual(seeded.entries);
-        expect(stored?.lastUploadAt).toBe(seeded.lastUploadAt);
-        // The sequence advances on every outcome, including this one.
-        expect(readManifestUploadStatus(stateDir, [{ kind: "personal" }])[0].sequence).toBe(seeded.sequence + 1);
-    });
-    it("allows a fresh install: no prior snapshot, so a disk-only manifest is the truth", async () => {
-        // A genuinely first-ever pass has nothing to contradict. Refusing it would
-        // mean no machine could ever enrol.
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, listJournalsImpl: () => [] }));
-        expect(result.status).toBe("uploaded");
-        expect(result.mode).toBe("full");
-        expect(transport).toHaveBeenCalled();
-    });
-    it("allows a full manifest whose entries the ledger actually knows", async () => {
-        seedSnapshot({
-            generatedAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-            lastUploadAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-        });
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, listJournalsImpl: ledgerTracking("notes/a.md", "notes/b.md", "notes/c.md") }));
-        expect(result.status).toBe("uploaded");
-        expect(transport).toHaveBeenCalled();
-    });
-    it("still PRINTS the refused manifest under dryRun, which is what debugging it needs", async () => {
-        seedSnapshot({
-            generatedAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-            lastUploadAt: new Date(NOW_MS - 8 * 24 * 60 * 60 * 1000).toISOString(),
-        });
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, dryRun: true, listJournalsImpl: () => [] }));
-        expect(result.status).toBe("printed");
-        expect(transport).not.toHaveBeenCalled();
-        expect(result.chunks?.[0].entries.every((entry) => entry.source === "disk")).toBe(true);
-    });
-});
-/**
- * The chunk set is streamed, not materialised (see `ManifestChunkPlan`). These
- * pin the two properties that makes that safe on the wire: the header fields
- * the server hashes into the snapshotId are identical across a multi-chunk
- * pass, and every chunk still validates against the contract.
- */
-describe("runManifestUploadPass — streamed chunks", () => {
-    it("sends byte-identical headers across a multi-chunk pass", async () => {
-        const seen = [];
-        const result = await runManifestUploadPass(baseOptions({
-            maxEntriesPerChunk: 1,
-            transport: vi.fn(async (chunk) => {
-                // Snapshot the chunk as it was SENT: the plan is free to discard the
-                // object afterwards, so a late read would prove nothing.
-                seen.push(JSON.parse(JSON.stringify(chunk)));
-                return accepted({ chunkCount: 3, receivedChunks: seen.length, completed: seen.length === 3 });
-            }),
-        }));
-        expect(result.status).toBe("uploaded");
-        expect(seen.length).toBe(3);
-        expect(seen.map((chunk) => chunk.chunkIndex)).toEqual([0, 1, 2]);
-        for (const chunk of seen) {
-            validateSyncManifestUpload(chunk);
-            // Every field the server hashes into its derived snapshotId.
-            expect(chunk.chunkCount).toBe(seen[0].chunkCount);
-            expect(chunk.generatedAt).toBe(seen[0].generatedAt);
-            expect(chunk.sequence).toBe(seen[0].sequence);
-            expect(chunk.machineId).toBe(seen[0].machineId);
-            expect(chunk.mode).toBe(seen[0].mode);
-            expect(chunk.scope).toEqual(seen[0].scope);
-        }
-        // `removedPaths` ride the first chunk only, still.
-        expect(seen.slice(1).every((chunk) => chunk.removedPaths.length === 0)).toBe(true);
-    });
-});
-// ─── Failure reasons are DURABLE (2026-09-07 personal-scope incident) ────────
-//
-// The failure state used to be write-only: `lastAttemptAt` and
-// `consecutiveFailures` were persisted, but WHY the pass failed survived only
-// as the label on a log line that fires when the snapshot write itself fails.
-// A scope stuck failing every cycle was therefore indistinguishable from any
-// other stuck scope, and the 2026-09-07 incident had to be diagnosed by
-// eliminating branches and re-executing the pass.
-//
-// These tests pin the invariant that replaces that: NO pass arms the failure
-// backoff without also recording, on disk, the reason it failed.
-describe("runManifestUploadPass — persists a failure reason on every path", () => {
-    /**
-     * Each case drives one distinct failure branch and names the tokens it must
-     * leave behind. `status` is asserted only where the failure came from an
-     * answered request — a failure that never reached the wire must NOT invent
-     * an HTTP status.
-     */
-    const cases = [
-        {
-            name: "transport threw",
-            options: () => ({
-                transport: vi.fn(async () => {
-                    throw new Error("ECONNRESET");
-                }),
-            }),
-            reason: "transport_error",
-            kind: "transport_error",
-        },
-        {
-            name: "server answered non-2xx",
-            options: () => ({ transport: transportReturning({ status: 500, body: {} }) }),
-            reason: "http_error",
-            kind: "rejected",
-            httpStatus: 500,
-        },
-        {
-            name: "route not deployed (404 soft skip)",
-            options: () => ({ transport: transportReturning({ status: 404, body: {} }) }),
-            reason: "soft_skip",
-            httpStatus: 404,
-        },
-        {
-            name: "server refused the fold",
-            options: () => ({ transport: transportReturning(accepted({ materialised: false })) }),
-            reason: "not_materialised",
-            kind: "not_materialised",
-        },
-        {
-            name: "server asked for a full resend",
-            options: () => ({
-                transport: transportReturning({
-                    status: 200,
-                    body: { status: "resend_full", scopeKey: SCOPE_KEY },
-                }),
-            }),
-            reason: "resend_full",
-            kind: "rejected",
-            httpStatus: 200,
-        },
-        {
-            name: "chunk too large (413 sizing fault)",
-            options: () => ({
-                transport: transportReturning({ status: 413, body: { reason: "chunk_too_large" } }),
-            }),
-            reason: "chunk_too_large",
-            kind: "chunk_too_large",
-            httpStatus: 413,
-        },
-        {
-            name: "scope over the server's entry ceiling (413)",
-            options: () => ({
-                transport: transportReturning({
-                    status: 413,
-                    body: { reason: SYNC_MANIFEST_TOO_LARGE_REASON_CODE },
-                }),
-            }),
-            reason: "too_large",
-            kind: "manifest_too_large",
-            httpStatus: 413,
-        },
-    ];
-    it.each(cases)("records $reason when $name", async ({ options, reason, kind, httpStatus }) => {
-        const result = await runManifestUploadPass(baseOptions(options()));
-        // Guard the premise: these cases must actually be failures, otherwise the
-        // assertions below would pass vacuously against a healthy pass.
-        expect(result.status).not.toBe("uploaded");
-        const snapshot = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(snapshot).not.toBeNull();
-        expect(snapshot?.lastFailureReason).toBe(reason);
-        // The backoff and the reason must be armed together — a reason without a
-        // failure count (or vice versa) is the half-written state this replaces.
-        expect(snapshot?.consecutiveFailures).toBe(1);
-        expect(snapshot?.lastAttemptAt).toBeDefined();
-        if (kind === undefined)
-            expect(snapshot?.lastFailureKind).toBeUndefined();
-        else
-            expect(snapshot?.lastFailureKind).toBe(kind);
-        if (httpStatus === undefined)
-            expect(snapshot?.lastFailureStatus).toBeUndefined();
-        else
-            expect(snapshot?.lastFailureStatus).toBe(httpStatus);
-    });
-    it("records a reason for a walk that never completed", async () => {
-        // The walk budget is the branch the 2026-09-07 investigation had to rule
-        // out by re-execution precisely because this field did not exist.
-        //
-        // A pre-raised abort is the suite's established way to cut the walk short.
-        // Whether it lands as `walk_truncated` (the walk noticed) or `failed`
-        // with `aborted` (the chunk loop noticed first) is a race this test does
-        // not care about — the INVARIANT is that whichever branch wins persists
-        // its own reason, and that neither is allowed to be silent.
-        const controller = new AbortController();
-        controller.abort();
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, abortSignal: controller.signal }));
-        const expectedReason = result.status === "walk_truncated" ? "walk_truncated" : "aborted";
-        const snapshot = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(snapshot?.lastFailureReason).toBe(expectedReason);
-        expect(snapshot?.lastFailureStatus).toBeUndefined();
-        expect(snapshot?.consecutiveFailures).toBe(1);
-        // Neither branch may reach the wire.
-        expect(transport).not.toHaveBeenCalled();
-        expect(result.uploadedChunks ?? 0).toBe(0);
-    });
-    it("records walk_truncated with no status when the builder reports a truncated walk", async () => {
-        // Pinned directly on the branch rather than through a timing race: a
-        // truncated walk is the failure the incident report had to eliminate by
-        // hand, so it gets an assertion that cannot go vacuous.
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({
-            transport,
-            // Budget spent before the first directory is read.
-            maxWallMs: -1,
-        }));
-        expect(result.status).toBe("walk_truncated");
-        const snapshot = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(snapshot?.lastFailureReason).toBe("walk_truncated");
-        expect(snapshot?.lastFailureKind).toBeUndefined();
-        expect(snapshot?.lastFailureStatus).toBeUndefined();
-        expect(transport).not.toHaveBeenCalled();
-    });
-    it("records ledger_implausible when a tracked scope reads back as disk-only", async () => {
-        // A prior snapshot proves the scope WAS tracked; the stubbed-away ledger
-        // (`listJournalsImpl: () => []`) makes every entry disk-only.
-        seedSnapshot({ sequence: 7 });
-        const transport = transportReturning(accepted());
-        const result = await runManifestUploadPass(baseOptions({ transport, forceFull: true, listJournalsImpl: () => [] }));
-        expect(result.status).toBe("ledger_implausible");
-        {
-            const snapshot = readManifestSnapshot(stateDir, SCOPE_KEY);
-            expect(snapshot?.lastFailureReason).toBe("ledger_implausible");
-            expect(transport).not.toHaveBeenCalled();
-        }
-    });
-    it("clears the failure reason once a pass succeeds", async () => {
-        // A stale reason is worse than none: it would describe a fault the scope
-        // has already recovered from.
-        seedSnapshot({
-            sequence: 3,
-            lastFailureReason: "transport_error",
-            lastFailureKind: "transport_error",
-            lastFailureStatus: 500,
-            consecutiveFailures: 4,
-            lastAttemptAt: new Date(NOW_MS - 60_000).toISOString(),
-        });
-        const result = await runManifestUploadPass(baseOptions({
-            // The seeded failure state arms the backoff; this test is about what a
-            // SUCCESS clears, not about the backoff itself.
-            ignoreThrottle: true,
-            transport: transportReturning(accepted()),
-            listJournalsImpl: ledgerTracking("notes/a.md", "notes/b.md", "notes/c.md"),
-        }));
-        expect(result.status).toBe("uploaded");
-        const snapshot = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(snapshot?.lastFailureReason).toBeUndefined();
-        expect(snapshot?.lastFailureKind).toBeUndefined();
-        expect(snapshot?.lastFailureStatus).toBeUndefined();
-        expect(snapshot?.consecutiveFailures).toBeUndefined();
-        expect(snapshot?.lastUploadAt).toBeDefined();
-    });
-    it("replaces a previous reason rather than leaving a stale kind/status behind", async () => {
-        // The earlier failure carried an HTTP status; the new one never reached
-        // the wire, so the status must be GONE, not carried forward.
-        seedSnapshot({
-            sequence: 3,
-            lastFailureReason: "http_error",
-            lastFailureKind: "rejected",
-            lastFailureStatus: 500,
-            consecutiveFailures: 1,
-        });
-        await runManifestUploadPass(baseOptions({
-            ignoreThrottle: true,
-            transport: vi.fn(async () => {
-                throw new Error("ECONNRESET");
-            }),
-        }));
-        const snapshot = readManifestSnapshot(stateDir, SCOPE_KEY);
-        expect(snapshot?.lastFailureReason).toBe("transport_error");
-        expect(snapshot?.lastFailureKind).toBe("transport_error");
-        expect(snapshot?.lastFailureStatus).toBeUndefined();
-        expect(snapshot?.consecutiveFailures).toBe(2);
-    });
-});
-//# sourceMappingURL=upload-manifest.test.js.map