in2-agent-server 0.20260821.185429

package/dist/core/parcels.js

@@ -0,0 +1,1235 @@
+import { promises as fs } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { REPO_ROOT } from "./paths.js";
+import { log as defaultLog } from "./result.js";
+import { TelemetryGrantStore } from "./telemetrySpool.js";
+import { currentBatchContext } from "./telemetryContext.js";
+// PROVENANCE PARCELS (plan 2026-08-02-002 U6; origin 2026-08-02-001 R7).
+//
+// Each state-changing wave's evidence bundle plus the session's read segment, gzipped into one tar
+// and posted under the batch grant the transcript uploader already uses. The point is aggregation:
+// a wave's provenance is useless if it only ever exists on the consultant laptop that produced it,
+// and R24's cross-machine convergence needs somewhere for a foreign bundle to come FROM.
+//
+// WHY THIS NEEDED ITS OWN DISCLOSURE, and why the default is still on.
+//
+// Most of a parcel restructures content that already leaves the machine: transcripts are on by
+// default and carry every metadata body the model read. `pre/source/` and the pre-image JSON are
+// the exception. They are pre-existing org state retrieved TOOL-SIDE, which the model never saw,
+// so that slice is genuinely new content leaving the machine and no prior consent covers it. The
+// resolution (operator, 2026-08-02) was not to weaken the default but to correct the disclosure:
+// the install prompt now names org state retrieved by the tools, `announceParcelUpload` says the
+// same thing at startup, and `CC_MCP_PARCEL_UPLOAD=0` is the way out. A default the consent text
+// does not mention is the thing to avoid; a default it does mention is a product decision.
+//
+// FAIL-OPEN IS LOAD-BEARING, in the same sense as the org mirror (direct/orgRepo.ts): an upload
+// that cannot happen must never fail, delay, or mask a delivery that landed in the org. Every
+// entry point here returns a result instead of throwing, the apply loop only ever awaits the local
+// build-and-spool step, and the network flush is fire-and-forget. Nothing new reaches the Convex
+// event tables — a parcel is a blob and a row, exactly like a transcript.
+/** Bumped when the parcel LAYOUT changes; readers key on it before trusting the entry paths. */
+export const PARCEL_FORMAT_VERSION = 1;
+/**
+ * THE CLIENT HALF OF THE WIRE CONTRACT. The server half landed in U7 —
+ * `apps/campfire-launch/convex/parcels.ts` and `src/routes/parcelV1.ts`.
+ *
+ * `POST /api/parcel/v1`
+ *   authorization:      Bearer <batch grant>   the sole authority for batchId/installId/sessionId
+ *   content-type:       application/gzip       body is the gzipped tar
+ *   x-in2-parcel-wave:  wave label             REQUIRED — a 400 ahead of the body without it
+ *
+ * That is the whole header set, and the omissions are the interesting part. THE CLIENT DOES NOT
+ * STATE THE ORG. A parcel is fetchable by another machine, so `orgId` is a permission boundary
+ * rather than a label, and the ledger resolves it from `batches.targetOrgId` on the grant's own
+ * batch — an org header would be the client asserting an authority it does not have, and the
+ * forwarder drops one if sent. Session id comes from the grant for the same reason. Attempt and
+ * verdict travel INSIDE the tar in `parcel.json`, which is where a rebuild reads them anyway.
+ *
+ * 202  stored — `{ stored, bytes, wave, orgId }`
+ * 401  grant not valid — RETRIED (it may simply not have been redeemed on this host yet)
+ * 5xx / network — RETRIED
+ * other 4xx (400 malformed, 409 batch bound no org, 413 over the 20 MB cap) — permanent; dropped
+ *   from the spool with a logged reason rather than retried forever
+ *
+ * The launch service relays an explicit header allowlist, so anything not named above never
+ * reaches the ledger no matter what this client sends.
+ *
+ * THE READ HALF (U8; R24), on the same two routes:
+ *
+ * `GET /api/parcel/v1?limit=&cursor=`     → 200 `{ orgId, parcels[], cursor, isDone }`
+ * `GET /api/parcel/v1/blob?parcelId=`     → 200 `{ …metadata, url }` — a short-lived signed URL
+ *
+ * Same single header, `authorization: Bearer <batch grant>`, and again NO ORG ON THE WAY OUT. The
+ * org is a permission boundary the ledger resolves from `batches.targetOrgId`, and the launch
+ * forwarder deliberately refuses to pass a scope parameter along, so a client cannot ask for
+ * somebody else's history by naming it. The org therefore arrives in the RESPONSE, which makes
+ * checking it this client's job: a grant bound to another org is skipped, never united in.
+ *
+ * 401 grant not valid · 404 no parcel for this grant (also: wrong org, malformed id) · 409 the
+ * batch bound no org.
+ */
+export const PARCEL_ROUTE = "/api/parcel/v1";
+const DISABLED_VALUES = new Set(["0", "false", "off", "no"]);
+/**
+ * ON BY DEFAULT. `CC_MCP_PARCEL_UPLOAD=0` is the way out.
+ *
+ * Spellings are deliberately generous, for the same reason the transcript switch is: an operator
+ * who reaches for `false` and is still uploading org state would be the worst outcome here.
+ */
+export function parcelUploadEnabled(env = process.env) {
+    const raw = env.CC_MCP_PARCEL_UPLOAD?.trim().toLowerCase();
+    return raw === undefined || raw === "" ? true : !DISABLED_VALUES.has(raw);
+}
+/** Derive the parcel endpoint from the telemetry one — same host, same grant, different route. */
+export function parcelEndpointFrom(telemetryEndpoint) {
+    try {
+        const url = new URL(telemetryEndpoint);
+        url.pathname = PARCEL_ROUTE;
+        return url.toString();
+    }
+    catch {
+        return telemetryEndpoint.replace(/\/api\/telemetry\/v\d+$/, PARCEL_ROUTE);
+    }
+}
+let announced = false;
+/** Test seam only: the once-guard is process-wide by design. */
+export function resetParcelAnnouncementForTests() {
+    announced = false;
+}
+/**
+ * Say what leaves, and how to stop it — ONCE per process.
+ *
+ * Called at startup and again from the queue path, so a machine that never reaches startup
+ * announcement still says it before the first parcel is built, and a machine that runs forty waves
+ * says it once rather than forty times. The opt-out gets a line of its own for the same reason the
+ * default does: an operator who set the variable should be able to confirm it took effect without
+ * reading source.
+ */
+export function announceParcelUpload(opts = {}) {
+    if (announced)
+        return;
+    announced = true;
+    // `defaultLog` adds the `[cc-mcp]` prefix, so no message here carries one — both callers (startup
+    // and the first wave's build) go through the same writer and neither double-stamps it.
+    const write = opts.log ?? defaultLog;
+    if (!parcelUploadEnabled(opts.env ?? process.env)) {
+        write("provenance parcels are NOT being uploaded (CC_MCP_PARCEL_UPLOAD=0). Evidence bundles stay on this machine; org history and delivery are unaffected.");
+        return;
+    }
+    write("PROVENANCE PARCEL UPLOAD IS ON (the default). For every wave that changes the org, the " +
+        "evidence bundle — including the BEFORE state of each touched component, retrieved from the org by " +
+        `these tools rather than read in the chat — and this session's read log are sent to ${opts.endpoint ?? "the configured endpoint"}. ` +
+        "Set CC_MCP_PARCEL_UPLOAD=0 to stop this.");
+}
+// ---------------------------------------------------------------------------------------------
+// tar
+// ---------------------------------------------------------------------------------------------
+//
+// Written here rather than taken as a dependency. A parcel is an evidence artifact that has to be
+// openable by anyone with a shell years from now, so the format is plain POSIX ustar with a GNU
+// long-name fallback — and writing 60 lines of header beats adding a package to the install every
+// consultant downloads. `update.ts` already shells out to the system `tar` to EXTRACT; creating is
+// deliberately in-process because bsdtar and GNU tar disagree about defaults and a parcel that
+// depends on which tar the laptop shipped with is not a stable artifact.
+const BLOCK = 512;
+/** Octal, NUL-terminated, in the fixed-width field tar expects. */
+function octalField(value, width) {
+    return `${value.toString(8).padStart(width - 1, "0")}\0`;
+}
+/**
+ * Split a long path across ustar's `prefix` and `name` fields.
+ *
+ * Smallest prefix that leaves a name of at most 100 bytes, so the prefix has the best chance of
+ * fitting its own 155. Null when no split works — the caller falls back to a GNU long-name entry.
+ */
+function splitUstarName(name) {
+    for (let i = 0; i < name.length; i++) {
+        if (name[i] !== "/")
+            continue;
+        const prefix = name.slice(0, i);
+        const rest = name.slice(i + 1);
+        if (Buffer.byteLength(rest) <= 100 && Buffer.byteLength(prefix) <= 155)
+            return { prefix, name: rest };
+    }
+    return null;
+}
+function ustarHeader(fields) {
+    const header = Buffer.alloc(BLOCK, 0);
+    header.write(fields.name.slice(0, 100), 0, 100, "utf8");
+    header.write(octalField(0o644, 8), 100, 8, "ascii");
+    header.write(octalField(0, 8), 108, 8, "ascii"); // uid
+    header.write(octalField(0, 8), 116, 8, "ascii"); // gid
+    header.write(octalField(fields.size, 12), 124, 12, "ascii");
+    // mtime 0. Nothing downstream reads it, and a real mtime would make two builds of one bundle
+    // differ in bytes — determinism is cheap here and the local clock is not evidence.
+    header.write(octalField(0, 12), 136, 12, "ascii");
+    header.write("        ", 148, 8, "ascii"); // checksum is computed over this field as spaces
+    header.write(fields.typeflag, 156, 1, "ascii");
+    header.write("ustar\0", 257, 6, "ascii");
+    header.write("00", 263, 2, "ascii");
+    header.write(fields.prefix.slice(0, 155), 345, 155, "utf8");
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i++)
+        sum += header[i];
+    header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, 8, "ascii");
+    return header;
+}
+function padToBlock(content) {
+    const remainder = content.length % BLOCK;
+    return remainder === 0 ? content : Buffer.concat([content, Buffer.alloc(BLOCK - remainder, 0)]);
+}
+function tarEntry(name, content) {
+    const parts = [];
+    let headerName = name;
+    let prefix = "";
+    if (Buffer.byteLength(name) > 100) {
+        const split = splitUstarName(name);
+        if (split) {
+            headerName = split.name;
+            prefix = split.prefix;
+        }
+        else {
+            // GNU long name: the real path rides in its own entry ahead of the file. Read by GNU tar,
+            // bsdtar, Python's tarfile and node-tar; the truncated name in the following header is the
+            // documented placeholder those readers ignore.
+            const nameBytes = Buffer.from(`${name}\0`, "utf8");
+            parts.push(ustarHeader({ name: "././@LongLink", size: nameBytes.length, typeflag: "L", prefix: "" }));
+            parts.push(padToBlock(nameBytes));
+        }
+    }
+    parts.push(ustarHeader({ name: headerName, size: content.length, typeflag: "0", prefix }));
+    parts.push(padToBlock(content));
+    return parts;
+}
+/** Entries in, one gzipped tar out. Sorted, so the same inputs always produce the same bytes. */
+function tarGz(entries) {
+    const parts = [];
+    for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+        parts.push(...tarEntry(entry.name, entry.content));
+    }
+    parts.push(Buffer.alloc(BLOCK * 2, 0)); // end-of-archive
+    let tar = Buffer.concat(parts);
+    const remainder = tar.length % (BLOCK * 20);
+    if (remainder !== 0)
+        tar = Buffer.concat([tar, Buffer.alloc(BLOCK * 20 - remainder, 0)]);
+    return { gz: gzipSync(tar, { level: 9 }), rawBytes: tar.length };
+}
+/**
+ * The reader for the writer above. In-process for the same reason, plus one this side owns alone:
+ * a parcel arrives OVER THE NETWORK from a machine we do not control, so every entry path has to be
+ * refused before it is joined to anything (`safeParcelEntryPath`). Shelling out to the system `tar`
+ * would hand that decision to whichever tar the laptop shipped with — GNU tar strips a leading `/`
+ * and warns, bsdtar's `--strip-components` behaviour differs, and neither is a contract.
+ *
+ * Regular files only. A directory entry is implied by its members, and a symlink, device or hard
+ * link in an artifact that is supposed to be JSON and XML is not something to reproduce faithfully.
+ */
+function untar(tar) {
+    const out = [];
+    const str = (start, length) => {
+        const raw = tar.subarray(start, start + length);
+        const nul = raw.indexOf(0);
+        return raw.subarray(0, nul === -1 ? raw.length : nul).toString("utf8");
+    };
+    let offset = 0;
+    // A GNU long name rides in its own entry AHEAD of the file it names — see `tarEntry`.
+    let longName = null;
+    while (offset + BLOCK <= tar.length) {
+        const header = tar.subarray(offset, offset + BLOCK);
+        if (header.every((byte) => byte === 0))
+            break; // end-of-archive
+        const name = str(offset, 100);
+        const size = Number.parseInt(str(offset + 124, 12).trim() || "0", 8);
+        const typeflag = header.subarray(156, 157).toString("ascii");
+        const prefix = str(offset + 345, 155);
+        offset += BLOCK;
+        if (!Number.isFinite(size) || size < 0 || offset + size > tar.length) {
+            throw new Error("parcel tar declares a member longer than the archive");
+        }
+        const body = tar.subarray(offset, offset + size);
+        offset += Math.ceil(size / BLOCK) * BLOCK;
+        if (typeflag === "L") {
+            longName = body.toString("utf8").replace(/\0+$/, "");
+            continue;
+        }
+        const full = longName ?? (prefix ? `${prefix}/${name}` : name);
+        longName = null;
+        if (typeflag === "0" || typeflag === "\0" || typeflag === "")
+            out.push({ name: full, content: Buffer.from(body) });
+    }
+    return out;
+}
+/**
+ * A hard wall, not a policy. An oversized parcel still SHIPS (see `queueWaveParcel`); this exists
+ * only because the tar is assembled in memory and a pathological bundle should fail loudly rather
+ * than take the process down with it.
+ */
+const MAX_UNCOMPRESSED_BYTES = 256 * 1024 * 1024;
+/** Report a compressed parcel past this in the log. Ships regardless — retention wants the data. */
+const DEFAULT_OVERSIZE_BYTES = 8 * 1024 * 1024;
+async function collectFiles(dir, prefix) {
+    const out = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, entry.name);
+        const name = `${prefix}/${entry.name}`;
+        // Symlinks are not followed: a bundle is written by this process, and a link that escaped it
+        // would put arbitrary local files into an artifact that leaves the machine.
+        if (entry.isDirectory())
+            out.push(...(await collectFiles(full, name)));
+        else if (entry.isFile())
+            out.push({ name, content: await fs.readFile(full) });
+    }
+    return out;
+}
+/**
+ * Two org ids name the same org iff their 15-char prefixes match — the 18-char form only adds a
+ * case-insensitivity checksum suffix. Same normalization this file already applies at the manifest
+ * check and the grant check below (and sessionOrg.ts's live-binding check); kept as one named
+ * function here so the reads filter's intent reads at the call site rather than as a bare slice.
+ */
+function sameOrgPrefix(a, b) {
+    return a.slice(0, 15) === b.slice(0, 15);
+}
+/**
+ * Tar the wave's bundle and the session's read segment into one parcel.
+ *
+ * LAYOUT IS LOAD-BEARING. Entries sit at their real session-relative paths
+ * (`<sessionId>/direct/<wave>/…` and `<sessionId>/reads.jsonl`), because U8's rebuild reads a
+ * foreign parcel with the SAME `readWaveFromBundle` the live path uses, and that reader derives the
+ * session id and wave label from the bundle's own directory. Unpack a parcel over a workspace root
+ * and every path lands exactly where a locally-produced wave would have put it.
+ */
+export async function buildParcel(opts) {
+    const wave = opts.wave ?? path.basename(opts.bundleDir);
+    const sessionId = opts.sessionId ?? path.basename(path.resolve(opts.bundleDir, "..", ".."));
+    const readsFile = opts.readsFile ?? path.resolve(opts.bundleDir, "..", "..", "reads.jsonl");
+    const entries = await collectFiles(opts.bundleDir, `${sessionId}/direct/${wave}`);
+    let readsBytes = 0;
+    let readsDropped = 0;
+    try {
+        const raw = await fs.readFile(readsFile, "utf8");
+        // THE PARCEL IS FETCHABLE UNDER ONE ORG'S GRANT, so the read segment it carries is filtered to
+        // that org. The session log on disk keeps every record — this filters the export, not the
+        // history. A record naming another org (a targetOrg peek) is org content under R14's doctrine
+        // and does not travel; an unparseable line cannot be attributed and does not travel either.
+        const kept = [];
+        for (const line of raw.split("\n")) {
+            if (line.trim() === "")
+                continue;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                readsDropped += 1;
+                continue;
+            }
+            // A record's orgId comes from the jsforce reader's AuthInfo; opts.orgId comes from the sf CLI's
+            // `org display` (see auth.ts:534-538) — the same org, but the two can hand back the 15- vs
+            // 18-char form of the same id. Every other org-identity comparison in this file normalizes to
+            // the 15-char prefix (parcels.ts's own manifest check and grant check, sessionOrg.ts) before
+            // comparing; a bare `===` here would drop a legitimate same-org record as foreign. Two DIFFERENT
+            // orgs never share a 15-char prefix, so normalizing cannot reopen the leak this filter closes.
+            const belongs = (typeof record.orgId === "string" && sameOrgPrefix(record.orgId, opts.orgId)) ||
+                (record.orgId == null && (opts.orgAlias === undefined || record.orgAlias === opts.orgAlias));
+            if (belongs)
+                kept.push(line);
+            else
+                readsDropped += 1;
+        }
+        if (kept.length > 0) {
+            const content = Buffer.from(`${kept.join("\n")}\n`, "utf8");
+            readsBytes = content.length;
+            entries.push({ name: `${sessionId}/reads.jsonl`, content });
+        }
+    }
+    catch {
+        // A session that never read the org has no read log. Absent is the honest record; an empty file
+        // would claim a segment exists and say nothing.
+    }
+    const identity = {
+        orgId: opts.orgId,
+        sessionId,
+        wave,
+        attempt: opts.attempt ?? 1,
+        verdict: opts.verdict,
+        ...(opts.batchId ? { batchId: opts.batchId } : {})
+    };
+    entries.push({
+        name: "parcel.json",
+        content: Buffer.from(`${JSON.stringify({
+            parcelVersion: PARCEL_FORMAT_VERSION,
+            ...identity,
+            builtAt: opts.at ?? new Date().toISOString(),
+            bundleFiles: entries.length - (readsBytes > 0 ? 1 : 0),
+            readsBytes,
+            ...(readsDropped > 0 ? { readsDroppedLines: readsDropped } : {})
+        }, null, 1)}\n`, "utf8")
+    });
+    const uncompressed = entries.reduce((sum, entry) => sum + entry.content.length, 0);
+    if (uncompressed > MAX_UNCOMPRESSED_BYTES) {
+        throw new Error(`bundle is ${Math.round(uncompressed / 1024 / 1024)} MB uncompressed, past the ${Math.round(MAX_UNCOMPRESSED_BYTES / 1024 / 1024)} MB assembly limit — it stays on this machine at ${opts.bundleDir}`);
+    }
+    const { gz, rawBytes } = tarGz(entries);
+    const outDir = opts.outDir ?? os.tmpdir();
+    await fs.mkdir(outDir, { recursive: true });
+    const file = path.join(outDir, `in2-parcel-${sessionId}-${wave}-${identity.attempt}-${randomBytes(4).toString("hex")}.tgz`);
+    await fs.writeFile(file, gz, { mode: 0o600 });
+    return { path: file, bytes: gz.length, rawBytes, identity };
+}
+/**
+ * A durable outbox, shaped like `TelemetrySpool` — a bounded directory that survives a crash and
+ * replays on the next flush.
+ *
+ * It holds THE BUILT BLOB rather than a pointer back at the bundle, which is the one place it
+ * departs from the telemetry pattern and does so deliberately: a retry re-uses the same bundle
+ * directory (see applyLoop's `deployed/` clear), so a descriptor resolved later would tar attempt
+ * two's content under attempt one's identity and no reader could tell.
+ */
+export class ParcelSpool {
+    options;
+    maxBytes;
+    maxAgeMs;
+    dropped = 0;
+    constructor(options) {
+        this.options = options;
+        this.maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
+        this.maxAgeMs = options.maxAgeMs ?? 30 * 86_400_000;
+        mkdirSync(options.dir, { recursive: true, mode: 0o700 });
+        try {
+            // mkdir's mode is subject to umask; the outbox holds org content, so say it explicitly.
+            chmodSync(options.dir, 0o700);
+        }
+        catch {
+            // Best effort on filesystems without POSIX modes.
+        }
+        // Sweep on open, not only on write: a run that queued parcels and died leaves them here, and an
+        // install that never delivers again should not keep them past the age cap forever.
+        this.enforceCaps();
+    }
+    /** Move a built parcel into the outbox. Returns null when it could not be spooled. */
+    enqueue(built, now = new Date()) {
+        const id = `pcl_${randomBytes(8).toString("hex")}`;
+        const blob = path.join(this.options.dir, `${id}.tgz`);
+        try {
+            try {
+                renameSync(built.path, blob);
+            }
+            catch {
+                // Cross-device (a tmpdir on another filesystem): copy, then drop the original.
+                writeFileSync(blob, readFileSync(built.path), { mode: 0o600 });
+                try {
+                    unlinkSync(built.path);
+                }
+                catch {
+                    // Temp cleanup is best effort.
+                }
+            }
+            const entry = {
+                ...built.identity,
+                id,
+                file: blob,
+                bytes: built.bytes,
+                rawBytes: built.rawBytes,
+                queuedAt: now.toISOString(),
+                attempts: 0
+            };
+            writeFileSync(path.join(this.options.dir, `${id}.json`), `${JSON.stringify(entry)}\n`, { encoding: "utf8", mode: 0o600 });
+            this.enforceCaps();
+            // Null when the caps retired it on the way in. Saying "queued" for a parcel the outbox just
+            // discarded is the one answer that would make the drop invisible.
+            return this.descriptor(id);
+        }
+        catch {
+            return null;
+        }
+    }
+    pending() {
+        const out = [];
+        for (const name of this.descriptorFiles()) {
+            const entry = this.descriptor(name.replace(/\.json$/, ""));
+            if (entry)
+                out.push(entry);
+        }
+        return out.sort((a, b) => (a.queuedAt < b.queuedAt ? -1 : a.queuedAt > b.queuedAt ? 1 : 0));
+    }
+    /** Delivered (or permanently rejected) — retire the descriptor and its blob together. */
+    acknowledge(id, lost = 0) {
+        this.dropped += lost;
+        this.remove(id);
+    }
+    /** Record a failed attempt so a poisoned parcel is visible rather than silently looping. */
+    markAttempt(id) {
+        const entry = this.descriptor(id);
+        if (!entry)
+            return;
+        try {
+            writeFileSync(path.join(this.options.dir, `${id}.json`), `${JSON.stringify({ ...entry, attempts: entry.attempts + 1 })}\n`, {
+                encoding: "utf8",
+                mode: 0o600
+            });
+        }
+        catch {
+            // A lost attempt count only costs a log line's accuracy.
+        }
+    }
+    stats() {
+        const entries = this.pending();
+        let bytes = 0;
+        for (const entry of entries)
+            bytes += entry.bytes;
+        const oldest = entries[0];
+        return {
+            pendingParcels: entries.length,
+            bytes,
+            oldestAgeMs: oldest ? Math.max(0, Date.now() - Date.parse(oldest.queuedAt)) : 0,
+            droppedParcels: this.dropped
+        };
+    }
+    descriptorFiles() {
+        try {
+            return readdirSync(this.options.dir)
+                .filter((name) => name.endsWith(".json"))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    descriptor(id) {
+        try {
+            const entry = JSON.parse(readFileSync(path.join(this.options.dir, `${id}.json`), "utf8"));
+            return entry.id === id && typeof entry.file === "string" ? entry : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    remove(id) {
+        for (const file of [path.join(this.options.dir, `${id}.json`), path.join(this.options.dir, `${id}.tgz`)]) {
+            try {
+                unlinkSync(file);
+            }
+            catch {
+                // Already gone.
+            }
+        }
+    }
+    /**
+     * Bound the outbox by bytes and age, oldest first.
+     *
+     * A parcel dropped here is evidence that never shipped, so it is COUNTED: `stats()` carries the
+     * number, `flushParcels` reports it, and the exit hook prints it. A cap that silently ate the
+     * backlog would make a clean outbox and an incomplete history look the same from outside.
+     */
+    enforceCaps() {
+        const now = Date.now();
+        const entries = this.pending();
+        let total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+        for (const entry of entries) {
+            if (now - Date.parse(entry.queuedAt) <= this.maxAgeMs && total <= this.maxBytes)
+                continue;
+            this.remove(entry.id);
+            total -= entry.bytes;
+            this.dropped += 1;
+        }
+    }
+}
+/** Ship one parcel under the batch grant. Never throws; every failure is a described result. */
+export async function uploadParcel(opts) {
+    let body;
+    try {
+        body = await fs.readFile(opts.parcel.file);
+    }
+    catch (error) {
+        // The blob is gone — nothing can be retried, so say so instead of holding a descriptor that
+        // will fail identically forever.
+        return { uploaded: false, permanent: true, reason: `parcel blob unreadable: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    try {
+        const res = await (opts.fetchFn ?? fetch)(opts.endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/gzip",
+                authorization: `Bearer ${opts.credential}`,
+                // The only descriptive header the ledger takes. Everything else about this parcel's
+                // identity is either derived from the grant (batch, install, session) or inside the tar
+                // (org, attempt, verdict) — see the contract note at the top of this file.
+                "x-in2-parcel-wave": opts.parcel.wave
+            },
+            body,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 120_000)
+        });
+        if (res.ok) {
+            const parsed = (await res.json().catch(() => ({})));
+            return { uploaded: true, status: res.status, storedBytes: parsed.bytes ?? body.length };
+        }
+        // 401 is retried on purpose: the grant may not have been redeemed on this host yet, and an
+        // expired one is bounded by the spool's own caps rather than by discarding evidence early.
+        const permanent = res.status >= 400 && res.status < 500 && res.status !== 401 && res.status !== 408 && res.status !== 429;
+        return { uploaded: false, status: res.status, permanent, reason: `HTTP ${res.status}` };
+    }
+    catch (error) {
+        return { uploaded: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * The grant for a batch, from the durable store first.
+ *
+ * TWO RULES, both about attribution rather than convenience.
+ *
+ * A parcel names the batch it belongs to and resolves THAT batch's grant — never whichever batch
+ * happens to be bound right now. A spooled parcel outlives the run that made it, so the loose
+ * version of this would let a wave from one engagement upload under another's credential and land
+ * in the ledger attributed to it.
+ *
+ * A parcel with no batch (a development wave against a session that never activated) resolves
+ * nothing and stays in the outbox until the caps retire it. There is no batch to attribute it to,
+ * and the alternative — borrowing the current one — is exactly the mis-attribution above.
+ */
+export function defaultResolveGrant(batchId) {
+    if (!batchId)
+        return null;
+    try {
+        const stored = new TelemetryGrantStore(path.join(REPO_ROOT, ".local", "cc-mcp", "telemetry-grants")).get(batchId);
+        if (stored?.credential && stored.endpoint) {
+            return { endpoint: parcelEndpointFrom(stored.endpoint), credential: stored.credential };
+        }
+        // The live context covers the window before a grant reaches disk — same batch only.
+        const live = currentBatchContext();
+        if (live?.credential && live.endpoint && live.batchId === batchId) {
+            return { endpoint: parcelEndpointFrom(live.endpoint), credential: live.credential };
+        }
+    }
+    catch {
+        // A grant store that cannot be read is a reason to retry later, never to fail a caller.
+    }
+    return null;
+}
+let sharedSpool = null;
+/** The process-wide outbox, beside the telemetry one. Null only when the disk refuses it. */
+export function defaultParcelSpool() {
+    if (sharedSpool)
+        return sharedSpool;
+    try {
+        sharedSpool = new ParcelSpool({
+            dir: process.env.CC_MCP_PARCEL_OUTBOX?.trim() || path.join(REPO_ROOT, ".local", "cc-mcp", "parcel-outbox")
+        });
+    }
+    catch {
+        sharedSpool = null;
+    }
+    return sharedSpool;
+}
+const emptySummary = () => ({ uploaded: 0, retained: 0, dropped: 0, outboxDropped: 0, oldestAgeMs: 0, bytesUploaded: 0 });
+/**
+ * One flush at a time per outbox.
+ *
+ * Every wave kicks a fire-and-forget flush and the exit hook kicks another, so two can easily
+ * overlap on a fast batch — and both would read the same descriptor and upload the same parcel
+ * twice. Chained rather than skipped: a caller that arrives mid-flush waits and then runs its own
+ * pass, so a parcel queued after the first pass started is still picked up.
+ */
+const flushChain = new WeakMap();
+/**
+ * Ship everything spooled that has a usable grant.
+ *
+ * Called after each wave and again before the process exits, which is what keeps a parcel from
+ * outliving the grant that is the only thing able to attribute it (plan risk: "grant lifetime vs.
+ * parcel flush"). A parcel whose grant has gone stays in the outbox and is reported — bounded on
+ * disk, never silently dropped.
+ */
+export async function flushParcels(opts = {}) {
+    const spool = opts.spool === undefined ? defaultParcelSpool() : opts.spool;
+    if (!spool)
+        return emptySummary();
+    const previous = flushChain.get(spool) ?? Promise.resolve(null);
+    const run = previous.catch(() => null).then(() => flushOnce(spool, opts));
+    flushChain.set(spool, run);
+    try {
+        return await run;
+    }
+    finally {
+        if (flushChain.get(spool) === run)
+            flushChain.delete(spool);
+    }
+}
+async function flushOnce(spool, opts) {
+    const summary = emptySummary();
+    const write = opts.log ?? ((line) => defaultLog(line));
+    const resolve = opts.resolveGrant ?? defaultResolveGrant;
+    let pending;
+    try {
+        pending = spool.pending().slice(0, opts.limit ?? 50);
+    }
+    catch {
+        return summary;
+    }
+    for (const parcel of pending) {
+        let grant = null;
+        try {
+            grant = resolve(parcel.batchId);
+        }
+        catch {
+            grant = null;
+        }
+        if (!grant) {
+            summary.retained += 1;
+            continue;
+        }
+        const result = await uploadParcel({ endpoint: grant.endpoint, credential: grant.credential, parcel, fetchFn: opts.fetchFn });
+        if (result.uploaded) {
+            spool.acknowledge(parcel.id);
+            summary.uploaded += 1;
+            summary.bytesUploaded += result.storedBytes ?? parcel.bytes;
+            continue;
+        }
+        if (result.permanent) {
+            spool.acknowledge(parcel.id, 1);
+            summary.dropped += 1;
+            write(`parcel ${parcel.sessionId}/${parcel.wave} REJECTED and dropped from the outbox (${result.reason}) — ` +
+                `its evidence bundle is intact on this machine; org history and the delivery are unaffected.`);
+            continue;
+        }
+        spool.markAttempt(parcel.id);
+        summary.retained += 1;
+    }
+    const stats = spool.stats();
+    summary.outboxDropped = stats.droppedParcels;
+    summary.oldestAgeMs = stats.oldestAgeMs;
+    return summary;
+}
+/**
+ * Build one wave's parcel and put it in the outbox. NEVER THROWS.
+ *
+ * This is the only entry point the apply loop awaits, and it does local work only — tar, gzip,
+ * rename. The network is the flush's problem, so a slow or dead endpoint cannot delay a delivery
+ * that has already landed in the org.
+ */
+export async function queueWaveParcel(opts) {
+    const write = opts.log ?? ((line) => defaultLog(line));
+    try {
+        announceParcelUpload({ ...(opts.env ? { env: opts.env } : {}), log: write });
+        if (!parcelUploadEnabled(opts.env ?? process.env))
+            return { queued: false, suppressed: true };
+        const built = await buildParcel(opts);
+        const oversize = opts.oversizeBytes ?? DEFAULT_OVERSIZE_BYTES;
+        // Bytes are logged for EVERY parcel, not only large ones: retention is an open question in the
+        // plan and it needs measurements from the first wave onward, not an estimate later.
+        write(`parcel ${built.identity.sessionId}/${built.identity.wave} built: ${built.bytes} bytes compressed (${built.rawBytes} raw)` +
+            (built.bytes > oversize ? ` — LARGE. Shipping it anyway; the evidence is the point and the server keeps its own cap.` : ""));
+        const spool = opts.spool === undefined ? defaultParcelSpool() : opts.spool;
+        const entry = spool?.enqueue(built) ?? null;
+        if (!entry) {
+            // The build wrote a temp file; if it never made it into the outbox, take it back out. A
+            // stranded parcel in the system temp dir is org content nobody is tracking.
+            await fs.rm(built.path, { force: true }).catch(() => undefined);
+            return {
+                queued: false,
+                bytes: built.bytes,
+                rawBytes: built.rawBytes,
+                reason: spool ? "parcel could not be spooled" : "parcel outbox unavailable"
+            };
+        }
+        return { queued: true, bytes: built.bytes, rawBytes: built.rawBytes };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        write(`parcel NOT built for this wave (${reason}) — the delivery and its evidence bundle are unaffected.`);
+        return { queued: false, reason };
+    }
+}
+const READ_TIMEOUT_MS = 60_000;
+/** Headroom over the server's own 20 MB upload cap, so a legitimate parcel is never refused here. */
+const MAX_DOWNLOAD_BYTES = 64 * 1024 * 1024;
+/** `…/api/parcel/v1` → `…/api/parcel/v1/blob`, query string and all left alone. */
+function blobEndpointFrom(endpoint) {
+    const [base = endpoint] = endpoint.split("?");
+    return `${base.replace(/\/+$/, "")}/blob`;
+}
+function withQuery(endpoint, params) {
+    const pairs = Object.entries(params).filter(([, value]) => value !== undefined && value !== "");
+    if (pairs.length === 0)
+        return endpoint;
+    const query = pairs.map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
+    return `${endpoint}${endpoint.includes("?") ? "&" : "?"}${query}`;
+}
+async function getJson(opts) {
+    try {
+        const res = await (opts.fetchFn ?? fetch)(opts.url, {
+            method: "GET",
+            headers: { authorization: `Bearer ${opts.credential}`, accept: "application/json" },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? READ_TIMEOUT_MS)
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            // The ledger's own message when it has one — a 409 saying "batch has no bound org" is a
+            // materially different operator problem from a 401, and collapsing them would hide that.
+            let detail = "";
+            try {
+                detail = String(JSON.parse(text).error ?? "");
+            }
+            catch {
+                detail = text.trim().slice(0, 120);
+            }
+            return { ok: false, status: res.status, reason: `HTTP ${res.status}${detail ? `: ${detail}` : ""}` };
+        }
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** One page of the parcels this grant's org holds, newest first. */
+export async function listParcels(opts) {
+    const url = withQuery(opts.endpoint, {
+        ...(opts.limit ? { limit: String(opts.limit) } : {}),
+        ...(opts.cursor ? { cursor: opts.cursor } : {})
+    });
+    const read = await getJson({ url, credential: opts.credential, ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+    if (!read.ok)
+        return read;
+    const page = read.value;
+    // A response that does not name an org cannot be checked against the org being rebuilt, and an
+    // unchecked page is exactly how another customer's history would end up in this mirror.
+    if (typeof page?.orgId !== "string" || !Array.isArray(page?.parcels)) {
+        return { ok: false, reason: "parcel list response did not name an org and its parcels" };
+    }
+    return {
+        ok: true,
+        value: {
+            orgId: page.orgId,
+            parcels: page.parcels,
+            cursor: typeof page.cursor === "string" ? page.cursor : null,
+            isDone: page.isDone !== false
+        }
+    };
+}
+/** The signed URL for one parcel's blob, plus the metadata row that names it. */
+export async function parcelDownloadUrl(opts) {
+    const url = withQuery(blobEndpointFrom(opts.endpoint), { parcelId: opts.parcelId });
+    const read = await getJson({ url, credential: opts.credential, ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+    if (!read.ok)
+        return read;
+    const row = read.value;
+    if (typeof row?.url !== "string" || !row.url) {
+        // Convex returns a null url when the stored object is gone. A row without a blob is a row.
+        return { ok: false, reason: "the ledger has a row for this parcel but no blob behind it" };
+    }
+    return { ok: true, value: { ...row, url: row.url } };
+}
+/**
+ * The gzipped tar behind a signed URL.
+ *
+ * NO AUTHORIZATION HEADER, deliberately: the URL points at Convex's file-storage host, not at the
+ * ledger, and attaching the batch grant would hand this install's write credential to a third
+ * party. The URL's own signature and expiry are the authority — that is what makes it signed.
+ */
+export async function downloadParcelBlob(opts) {
+    const cap = opts.maxBytes ?? MAX_DOWNLOAD_BYTES;
+    try {
+        const res = await (opts.fetchFn ?? fetch)(opts.url, {
+            method: "GET",
+            signal: AbortSignal.timeout(opts.timeoutMs ?? READ_TIMEOUT_MS)
+        });
+        if (!res.ok)
+            return { ok: false, status: res.status, reason: `HTTP ${res.status} fetching the parcel blob` };
+        const declared = Number(res.headers.get("content-length") ?? "");
+        if (Number.isFinite(declared) && declared > cap) {
+            return { ok: false, reason: `parcel blob declares ${declared} bytes, past the ${cap}-byte download cap` };
+        }
+        const body = Buffer.from(await res.arrayBuffer());
+        if (body.length > cap)
+            return { ok: false, reason: `parcel blob is ${body.length} bytes, past the ${cap}-byte download cap` };
+        return { ok: true, value: body };
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// unpacking
+// ---------------------------------------------------------------------------------------------
+/**
+ * A tar member path this process is willing to join to a directory, or null.
+ *
+ * The parcel was built by another machine, so `..`, an absolute path and a Windows drive letter are
+ * all things a hostile — or merely broken — writer can put in a header, and `path.join` would
+ * happily follow every one of them out of the staging directory. Refused wholesale rather than
+ * sanitized: a name that needed rewriting is not a name this reader understands.
+ */
+function safeParcelEntryPath(name) {
+    const normalized = name.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!normalized || normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized))
+        return null;
+    const parts = normalized.split("/");
+    if (parts.some((part) => part === "" || part === "." || part === ".."))
+        return null;
+    return parts.join("/");
+}
+/** A path segment that is a whole segment — a session id or wave label, as the tar states it. */
+const isPlainSegment = (value) => typeof value === "string" && value.length > 0 && !/[/\\]/.test(value) && value !== "." && value !== "..";
+/**
+ * A parcel's bytes back into the session shape the wave was written in.
+ *
+ * Entries land at their stated paths under `destRoot` because `buildParcel` files them at their
+ * real session-relative locations for exactly this reason: `readWaveFromBundle` derives a wave's
+ * session id and label from its own directory, so an unpacked parcel is indistinguishable from a
+ * locally produced bundle — which is the whole mechanism behind identical SHAs on two machines.
+ *
+ * Throws on anything it will not vouch for: an unknown format version, a path that escapes, a
+ * manifest that names a different org than the caller is rebuilding. The caller counts those as
+ * parcels it could not stage and says so, rather than quietly building a smaller history.
+ */
+export async function unpackParcel(gz, destRoot, opts = {}) {
+    let entries;
+    try {
+        entries = untar(gunzipSync(gz, { maxOutputLength: MAX_UNCOMPRESSED_BYTES }));
+    }
+    catch (error) {
+        throw new Error(`parcel could not be unpacked: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const manifestEntry = entries.find((entry) => entry.name === "parcel.json");
+    if (!manifestEntry)
+        throw new Error("parcel has no parcel.json — nothing states what wave it is");
+    const manifest = JSON.parse(manifestEntry.content.toString("utf8"));
+    const parcelVersion = manifest.parcelVersion ?? 0;
+    // Refused, not best-efforted. A newer layout may file entries somewhere this reader does not
+    // look, and a half-read parcel materializes as a wave with pieces missing — which reads as an
+    // org that lost components rather than as an install that is out of date.
+    if (parcelVersion > PARCEL_FORMAT_VERSION) {
+        throw new Error(`parcel format v${parcelVersion} is newer than this install understands (v${PARCEL_FORMAT_VERSION}) — update, then rebuild`);
+    }
+    if (!isPlainSegment(manifest.sessionId) || !isPlainSegment(manifest.wave)) {
+        throw new Error("parcel.json does not name a plain session id and wave label");
+    }
+    if (typeof manifest.orgId !== "string" || !manifest.orgId)
+        throw new Error("parcel.json names no org");
+    // The third check on one fact, and each is worth having: the ledger scoped the LIST by grant, this
+    // checks what the producing machine wrote INSIDE the tar, and `rebuild` checks each bundle's own
+    // projection manifest. A parcel that disagrees with the grant that served it is not a parcel to
+    // file into somebody's org history.
+    // The org this parcel actually names is NOT quoted, for the reason `fetchForeignBundles` gives at
+    // its own org check: this message ends up in `problems`, and `problems` ends up in front of an
+    // operator who is entitled to see their own org id and nobody else's.
+    if (opts.expectOrgId && manifest.orgId.slice(0, 15) !== opts.expectOrgId.slice(0, 15)) {
+        throw new Error(`parcel.json names a different org than the one being rebuilt (${opts.expectOrgId})`);
+    }
+    // EVERY path is checked BEFORE the first byte is written. Checking as it goes would leave the
+    // entries ahead of a bad one on disk, and a partially unpacked parcel is a bundle that names
+    // components it does not carry — which materializes as an org that lost them.
+    const planned = [];
+    let bytes = 0;
+    for (const entry of entries) {
+        const rel = safeParcelEntryPath(entry.name);
+        if (!rel)
+            throw new Error(`parcel entry ${JSON.stringify(entry.name)} escapes the staging directory`);
+        planned.push({ abs: path.join(destRoot, rel), content: entry.content });
+        bytes += entry.content.length;
+    }
+    for (const file of planned) {
+        await fs.mkdir(path.dirname(file.abs), { recursive: true });
+        await fs.writeFile(file.abs, file.content, { mode: 0o600 });
+    }
+    const bundleDir = path.join(destRoot, manifest.sessionId, "direct", manifest.wave);
+    const present = await fs
+        .stat(bundleDir)
+        .then((stat) => stat.isDirectory())
+        .catch(() => false);
+    if (!present)
+        throw new Error(`parcel names wave ${manifest.sessionId}/${manifest.wave} but carries no bundle for it`);
+    return {
+        identity: {
+            parcelVersion,
+            orgId: manifest.orgId,
+            sessionId: manifest.sessionId,
+            wave: manifest.wave,
+            attempt: manifest.attempt ?? 1,
+            verdict: manifest.verdict ?? "",
+            ...(manifest.batchId ? { batchId: manifest.batchId } : {})
+        },
+        bundleDir,
+        files: planned.length,
+        bytes
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// grants, staging, and the one call the rebuild makes
+// ---------------------------------------------------------------------------------------------
+const grantsDir = () => path.join(REPO_ROOT, ".local", "cc-mcp", "telemetry-grants");
+/**
+ * Every live batch grant on this machine, longest-lived first.
+ *
+ * A grant does NOT record its org — the ledger resolves that from the batch — so this cannot filter
+ * by org and does not pretend to. The caller lists through each candidate in turn and keeps the one
+ * whose bound org comes back matching. That is one round trip per stale engagement on the laptop
+ * and it is the only way to answer the question without asking the client to assert an org.
+ *
+ * Read straight from the store's files rather than through `get()`, which needs the exact batch id
+ * and the id is what a listing is trying to discover — the filename is sanitized on write, so
+ * inverting it would be a guess. Expiry is checked here exactly as `get()` checks it.
+ */
+export function storedParcelGrants(dir = grantsDir(), now = Date.now()) {
+    const grants = [];
+    try {
+        for (const name of readdirSync(dir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            try {
+                const stored = JSON.parse(readFileSync(path.join(dir, name), "utf8"));
+                if (!stored?.batchId || !stored.credential || !stored.endpoint)
+                    continue;
+                if (!(Date.parse(stored.expiresAt) > now))
+                    continue;
+                grants.push({
+                    batchId: stored.batchId,
+                    endpoint: parcelEndpointFrom(stored.endpoint),
+                    credential: stored.credential,
+                    expiresAt: stored.expiresAt
+                });
+            }
+            catch {
+                // A half-written or hand-edited grant file is not a grant.
+            }
+        }
+    }
+    catch {
+        // No grant directory at all — an install that has never activated. Reported as no grant.
+    }
+    return grants.sort((a, b) => (a.expiresAt < b.expiresAt ? 1 : a.expiresAt > b.expiresAt ? -1 : 0));
+}
+/** Where fetched parcels are staged. DELIBERATELY OUTSIDE the session workspace — see below. */
+export function parcelStageDir(orgId) {
+    return process.env.CC_MCP_PARCEL_STAGE?.trim()
+        ? path.join(process.env.CC_MCP_PARCEL_STAGE.trim(), orgId)
+        : path.join(REPO_ROOT, ".local", "cc-mcp", "parcel-fetch", orgId);
+}
+/**
+ * Fetch this org's foreign parcels and stage them as replayable bundle directories.
+ *
+ * STAGED OUTSIDE THE SESSION WORKSPACE, and that placement is load-bearing. `workspaceBundleDirs`
+ * enumerates the LOCAL bundle set by walking the session root; a fetched parcel unpacked in there
+ * would be counted as this machine's own work, and "local-only" would silently become a claim about
+ * other people's machines. Each parcel gets its own directory under the stage keyed by parcel id,
+ * so two parcels from one session cannot overwrite each other's copy of `reads.jsonl` and a re-fetch
+ * is a directory replacement rather than a merge.
+ *
+ * NEVER THROWS. Every path out of here is a described result, because the caller's next move is to
+ * rebuild either way — with the foreign set if it arrived, and with an honest scope note if it did
+ * not.
+ */
+export async function fetchForeignBundles(opts) {
+    const result = {
+        ok: false,
+        orgId: opts.orgId,
+        bundles: [],
+        listed: 0,
+        downloaded: 0,
+        cached: 0,
+        failed: 0,
+        problems: []
+    };
+    const write = opts.log ?? ((line) => defaultLog(line));
+    const call = { ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) };
+    let candidates;
+    try {
+        candidates = opts.grant
+            ? [opts.grant]
+            : opts.batchId
+                ? [defaultResolveGrant(opts.batchId)].filter((grant) => grant !== null)
+                : (opts.grants ?? storedParcelGrants());
+    }
+    catch {
+        candidates = [];
+    }
+    if (candidates.length === 0) {
+        result.unavailable = opts.batchId
+            ? `no live grant for batch ${opts.batchId} on this machine`
+            : "no live batch grant on this machine — a parcel fetch is authorized by an activated session's grant";
+        return result;
+    }
+    // Which grant speaks for THIS org is the ledger's answer, not ours: list through each in turn and
+    // keep the first whose bound org matches. A grant that answers for another org is skipped without
+    // reading a single parcel out of it.
+    let grant = null;
+    let first = null;
+    const rejections = [];
+    for (const candidate of candidates) {
+        const page = await listParcels({
+            endpoint: candidate.endpoint,
+            credential: candidate.credential,
+            ...(opts.pageLimit ? { limit: opts.pageLimit } : {}),
+            ...call
+        });
+        if (!page.ok) {
+            rejections.push(page.reason);
+            continue;
+        }
+        if (page.value.orgId.slice(0, 15) !== opts.orgId.slice(0, 15)) {
+            // THE FOREIGN ORG ID IS NOT NAMED, deliberately. `rejections` becomes `unavailable`, which the
+            // rebuild prints in its scope note — so naming the org a stale grant is bound to would put
+            // ANOTHER CUSTOMER'S org id into this engagement's output, on a laptop that legitimately holds
+            // grants for several. The org being rebuilt is the operator's own and stays; the other one is
+            // not this engagement's to see, and "a different org" is all the operator needs to act on
+            // (re-activate for this org). The full id remains available in the grant files themselves.
+            rejections.push(`a grant on this machine is bound to a different org, not ${opts.orgId}`);
+            continue;
+        }
+        grant = candidate;
+        first = page.value;
+        break;
+    }
+    if (!grant || !first) {
+        result.unavailable = rejections.length > 0 ? rejections.join("; ") : "no grant on this machine is bound to this org";
+        return result;
+    }
+    result.ok = true;
+    result.orgId = first.orgId;
+    // Bound to a const before the closure below reads it: `grant` is a `let` the loop reassigns, and
+    // a narrowing that only holds at this line is not one a callback can rely on.
+    const bound = grant;
+    const stage = opts.stageDir ?? parcelStageDir(opts.orgId);
+    const maxParcels = opts.maxParcels ?? 1000;
+    const stageOne = async (entry) => {
+        result.listed += 1;
+        if (!isPlainSegment(entry.parcelId)) {
+            result.failed += 1;
+            result.problems.push(`the ledger listed a parcel whose id is not a plain identifier — skipped`);
+            return;
+        }
+        const dest = path.join(stage, "p", entry.parcelId);
+        const markerFile = path.join(stage, "p", `${entry.parcelId}.staged.json`);
+        const marker = await fs
+            .readFile(markerFile, "utf8")
+            .then((text) => JSON.parse(text))
+            .catch(() => null);
+        if (marker?.bundleDir) {
+            const still = await fs
+                .stat(marker.bundleDir)
+                .then((stat) => stat.isDirectory())
+                .catch(() => false);
+            if (still) {
+                result.cached += 1;
+                result.bundles.push({
+                    parcelId: entry.parcelId,
+                    sessionId: marker.sessionId,
+                    wave: marker.wave,
+                    bundleDir: marker.bundleDir,
+                    bytes: marker.bytes,
+                    uploadedAt: marker.uploadedAt,
+                    cached: true
+                });
+                return;
+            }
+        }
+        const signed = await parcelDownloadUrl({ endpoint: bound.endpoint, credential: bound.credential, parcelId: entry.parcelId, ...call });
+        if (!signed.ok) {
+            result.failed += 1;
+            result.problems.push(`${entry.sessionId}/${entry.wave}: ${signed.reason}`);
+            return;
+        }
+        // THE LEDGER ALREADY SAID HOW BIG THIS IS, so the download is measured against that rather than
+        // against a global ceiling alone. `present()` returns the byte count the upload was stored with,
+        // and a blob that does not match it is not the parcel the row describes — a truncated transfer,
+        // a proxy that rewrote the body, or a row pointing at the wrong object. Any of those unpacks
+        // into a wave nobody ran, which is worse than a wave that is missing: a missing wave is already
+        // counted and said out loud, and a wrong one is filed as history.
+        //
+        // The cap goes DOWN to the declared size (never up past the module's own ceiling), so an
+        // oversized body is refused off `content-length` before its bytes are read; a SHORT body gets
+        // past the cap by construction and is caught by the equality check below. Both land in `failed`
+        // and in `problems` — never a throw, because the rebuild still has to run and say what it covers.
+        //
+        // A row that declares nothing usable falls back to the module ceiling and is staged unmeasured,
+        // rather than refusing evidence over a field the ledger did not fill in.
+        const declared = Number(entry.bytes);
+        const expectBytes = Number.isFinite(declared) && declared > 0 ? declared : null;
+        const blob = await downloadParcelBlob({
+            url: signed.value.url,
+            ...(expectBytes === null ? {} : { maxBytes: Math.min(expectBytes, MAX_DOWNLOAD_BYTES) }),
+            ...call
+        });
+        if (!blob.ok) {
+            result.failed += 1;
+            result.problems.push(`${entry.sessionId}/${entry.wave}: ${blob.reason}`);
+            return;
+        }
+        if (expectBytes !== null && blob.value.length !== expectBytes) {
+            result.failed += 1;
+            result.problems.push(`${entry.sessionId}/${entry.wave}: the ledger lists ${expectBytes} bytes but ${blob.value.length} arrived — not staged`);
+            return;
+        }
+        try {
+            // Replaced, not merged: a half-written directory from an interrupted fetch must not be
+            // completed by a later one into a bundle neither parcel ever contained.
+            await fs.rm(dest, { recursive: true, force: true });
+            const unpacked = await unpackParcel(blob.value, dest, { expectOrgId: opts.orgId });
+            const record = {
+                parcelId: entry.parcelId,
+                sessionId: unpacked.identity.sessionId,
+                wave: unpacked.identity.wave,
+                bytes: entry.bytes,
+                uploadedAt: entry.uploadedAt,
+                bundleDir: unpacked.bundleDir,
+                stagedAt: new Date().toISOString()
+            };
+            await fs.mkdir(path.dirname(markerFile), { recursive: true });
+            await fs.writeFile(markerFile, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+            result.downloaded += 1;
+            result.bundles.push({ ...record, cached: false });
+        }
+        catch (error) {
+            result.failed += 1;
+            result.problems.push(`${entry.sessionId}/${entry.wave}: ${error instanceof Error ? error.message : String(error)}`);
+            await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
+        }
+    };
+    let page = first;
+    for (;;) {
+        let staged = 0;
+        for (const entry of page.parcels) {
+            if (result.listed >= maxParcels)
+                break;
+            await stageOne(entry);
+            staged += 1;
+        }
+        const moreToCome = !page.isDone && Boolean(page.cursor);
+        if (staged < page.parcels.length || (moreToCome && result.listed >= maxParcels)) {
+            // A CAP THAT TRUNCATES SAYS SO. Stopping here quietly would produce a history that looks
+            // whole and is short by however many parcels were never asked for, which is the one shape
+            // this module exists to prevent. Counted as one loss because the true number is exactly what
+            // the cap stopped us from finding out.
+            result.failed += 1;
+            result.problems.push(`stopped at the ${maxParcels}-parcel ceiling; the ledger holds more for this org`);
+            break;
+        }
+        if (!moreToCome)
+            break;
+        const next = await listParcels({
+            endpoint: bound.endpoint,
+            credential: bound.credential,
+            cursor: page.cursor,
+            ...(opts.pageLimit ? { limit: opts.pageLimit } : {}),
+            ...call
+        });
+        if (!next.ok) {
+            // The first page landed, so the fetch is not unavailable — it is INCOMPLETE, and that is a
+            // different sentence. Counted as a loss so the scope note cannot read as a whole history.
+            result.failed += 1;
+            result.problems.push(`the parcel listing stopped early: ${next.reason}`);
+            break;
+        }
+        page = next.value;
+    }
+    if (result.failed > 0) {
+        write(`${result.failed} parcel(s) for ${opts.orgId} could NOT be staged — this rebuild may still be missing waves: ${result.problems
+            .slice(0, 5)
+            .join(" | ")}`);
+    }
+    return result;
+}