@indigoai-us/hq-cli 5.345.80 → 5.345.81

package/dist/commands/storage-offload.js

@@ -0,0 +1,943 @@
+/**
+ * `hq storage offload` / `hq storage fetch` — move big files to the caller's
+ * PERSONAL vault (S3 Standard, content-addressed) and leave small linked
+ * pointers behind. Shared contract: owner-approved offload design, 2026-10-09.
+ *
+ * Two kinds of big file:
+ *   - History copies (old versions inside the HQ root git history). The CLI
+ *     uploads each blob, verifies size + sha256 + git blob id, then hands only
+ *     verified blobs to core `hq-storage.sh strip-large`, which rewrites history
+ *     to the pointer text. Working-tree files are never touched.
+ *   - Current files (idle big files in the working tree). NOT offloaded yet:
+ *     the sync delete planner lives in @indigoai-us/hq-cloud (`computePullPlan`
+ *     and the push delete planner in dist/cli/sync.js), so replacing `x.mp4`
+ *     with `x.mp4.hqcloud` would still propagate as a remote delete of `x.mp4`.
+ *     `--current` reports `{ available: false }` until hq-cloud learns about
+ *     placeholders (CURRENT_OFFLOAD_ENABLED). `offloadCurrentFile` is built
+ *     and tested but not called.
+ *
+ * Fetch also reads placeholders that HQ sync rewrote after a teammate changed
+ * the file (`vault: company`, the company vault key, `sha256: unknown`,
+ * `remote-etag`). Those download from the company vault, only for an active
+ * member, and verify by size and ETag. A placeholder marked `orphaned: true`
+ * (a teammate deleted the file) is refused unless `--force-orphan` is given,
+ * which writes the caller's own personal-vault copy to a file outside HQ so
+ * it can never sync back.
+ *
+ * Tenant isolation: bytes only ever go to the caller's personal vault. The
+ * personal store refuses a company vault bucket, and nothing here lists or
+ * opens company memberships.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { spawn, execFile } from "node:child_process";
+import { S3Client, GetObjectCommand, HeadObjectCommand, PutObjectCommand, } from "@aws-sdk/client-s3";
+import { checkPreconditions, coreHasFlag, coreSupports, dropExpiredBackups, PRECONDITION_FALLBACK, coreKeepsUndo, reclaimFields, reclaimWindowHours, runCoreScript, } from "./storage-core.js";
+// ── Constants ───────────────────────────────────────────────────────────────
+export const PLACEHOLDER_SUFFIX = ".hqcloud";
+export const OFFLOAD_PREFIX = ".hq-offload/blobs/";
+export const POINTER_HEADER = "HQ-CLOUD-FILE v1";
+export const POINTER_FOOTER = "This file is stored in HQ cloud storage. Open it in HQ, or run the command above to download it.";
+export const DEFAULT_MIN_BYTES = 50 * 1024 * 1024;
+export const DEFAULT_IDLE_DAYS = 14;
+export const CURRENT_BLOCKED_REASON = "Offloading current files is not available yet: HQ sync would treat the replaced file as deleted.";
+/**
+ * Gate for `--current`. Stays false until the owner enables current-file
+ * offload on top of hq-cloud's cloud-only placeholders (PR #919, 6.18.61).
+ */
+export const CURRENT_OFFLOAD_ENABLED = false;
+export const ORPHANED_MESSAGE = "This file was deleted by a teammate. It's no longer in the cloud for your team.";
+const UPDATE_HQ = "update HQ";
+export const UPDATE_SYNC = "update HQ sync";
+const PERSONAL_BUCKET_PREFIX = "hq-vault-prs-";
+/** Top-level HQ-root folder that holds offloaded blobs in the personal vault. */
+export const OFFLOAD_TOP_LEVEL = ".hq-offload";
+/**
+ * Whether personal-vault sync skips `.hq-offload/`. Without that exclusion a
+ * later `hq sync` pulls every offloaded blob back to disk (and to every other
+ * machine), undoing the savings. Pass hq-cloud's
+ * `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL`.
+ *
+ * @indigoai-us/hq-cloud 6.18.61 (PR #919) lists ".hq-offload" in
+ * PERSONAL_VAULT_EXCLUDED_TOP_LEVEL; storage.ts passes that export here. The
+ * check stays at runtime so an older bundled HQ sync still reports
+ * "update HQ sync". CURRENT_OFFLOAD_ENABLED is a separate owner decision.
+ */
+export function syncExcludesOffload(excludedTopLevel) {
+    return Array.isArray(excludedTopLevel) && excludedTopLevel.includes(OFFLOAD_TOP_LEVEL);
+}
+export function offloadKey(gitBlobSha) {
+    return `${OFFLOAD_PREFIX}${gitBlobSha}`;
+}
+// ── Size parsing ────────────────────────────────────────────────────────────
+const UNITS = {
+    "": 1,
+    b: 1,
+    kb: 1024,
+    k: 1024,
+    mb: 1024 ** 2,
+    m: 1024 ** 2,
+    gb: 1024 ** 3,
+    g: 1024 ** 3,
+};
+export function parseSize(value) {
+    const m = /^\s*(\d+(?:\.\d+)?)\s*([a-z]*)\s*$/i.exec(value);
+    const unit = m ? UNITS[m[2].toLowerCase()] : undefined;
+    if (!m || unit === undefined) {
+        throw new Error(`Size must look like 50MB, 1GB or a byte count, got '${value}'.`);
+    }
+    return Math.round(Number(m[1]) * unit);
+}
+export function resolveMinBytes(flag, env) {
+    if (flag !== undefined)
+        return parseSize(flag);
+    const fromEnv = env.HQ_OFFLOAD_MIN_BYTES;
+    if (fromEnv !== undefined && fromEnv.trim() !== "")
+        return parseSize(fromEnv);
+    return DEFAULT_MIN_BYTES;
+}
+export function renderPointer(p) {
+    const lines = [POINTER_HEADER, `path: ${p.path}`, `size: ${p.size}`, `sha256: ${p.sha256 ?? "unknown"}`];
+    if (p.gitBlob)
+        lines.push(`git-blob: ${p.gitBlob}`);
+    lines.push(`vault: ${p.vault}`, `key: ${p.key}`);
+    if (p.offloadedAt)
+        lines.push(`offloaded-at: ${p.offloadedAt}`);
+    if (p.remoteEtag)
+        lines.push(`remote-etag: ${p.remoteEtag}`);
+    if (p.orphaned)
+        lines.push("orphaned: true");
+    lines.push(`retrieve: hq storage fetch "${p.path}"`, POINTER_FOOTER, "");
+    return lines.join("\n");
+}
+/** ETags compare without the surrounding quotes S3 returns. */
+export function normalizeEtag(etag) {
+    return (etag ?? "").trim().replace(/^W\//, "").replace(/^"|"$/g, "");
+}
+const HEX40 = /^[0-9a-f]{40}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * Parse pointer text. Returns null for anything that is not a valid v1 pointer.
+ *
+ * Two shapes are valid:
+ *   - an offload copy: `vault: personal`, key = offloadKey(git-blob), with a
+ *     git blob id to verify against;
+ *   - a vault object recorded by sync: either vault, a non-offload key, and a
+ *     `remote-etag` to verify against (sha256 may be `unknown`).
+ */
+export function parsePointer(text) {
+    const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+    if (lines[0]?.trim() !== POINTER_HEADER)
+        return null;
+    const fields = new Map();
+    for (const line of lines.slice(1)) {
+        const m = /^([a-z0-9-]+): ?(.*)$/.exec(line);
+        if (m && !fields.has(m[1]))
+            fields.set(m[1], m[2].trim());
+    }
+    const sizeText = fields.get("size") ?? "";
+    const shaText = (fields.get("sha256") ?? "").toLowerCase();
+    const vault = fields.get("vault");
+    const gitBlob = fields.get("git-blob");
+    const remoteEtag = normalizeEtag(fields.get("remote-etag"));
+    const p = {
+        path: fields.get("path") ?? "",
+        size: Number(sizeText),
+        sha256: shaText === "unknown" ? null : shaText,
+        vault: vault === "company" ? "company" : "personal",
+        key: fields.get("key") ?? "",
+    };
+    if (gitBlob)
+        p.gitBlob = gitBlob;
+    const offloadedAt = fields.get("offloaded-at");
+    if (offloadedAt)
+        p.offloadedAt = offloadedAt;
+    if (remoteEtag)
+        p.remoteEtag = remoteEtag;
+    if (fields.get("orphaned") === "true")
+        p.orphaned = true;
+    if (!p.path ||
+        !p.key ||
+        !/^\d+$/.test(sizeText) ||
+        !Number.isSafeInteger(p.size) ||
+        (p.sha256 !== null && !HEX64.test(p.sha256)) ||
+        (vault !== "personal" && vault !== "company") ||
+        (p.gitBlob !== undefined && !HEX40.test(p.gitBlob))) {
+        return null;
+    }
+    const isOffloadCopy = p.gitBlob !== undefined && p.key === offloadKey(p.gitBlob);
+    if (isOffloadCopy)
+        return p.vault === "personal" ? p : null;
+    if (p.key.startsWith(OFFLOAD_PREFIX) || !p.remoteEtag)
+        return null;
+    return p;
+}
+/** sha256 and git blob id (sha1 of "blob <size>\0" + bytes) in one pass. */
+export async function digestFile(file) {
+    const size = (await fs.promises.stat(file)).size;
+    const sha256 = crypto.createHash("sha256");
+    const sha1 = crypto.createHash("sha1");
+    sha1.update(`blob ${size}\0`);
+    for await (const chunk of fs.createReadStream(file)) {
+        sha256.update(chunk);
+        sha1.update(chunk);
+    }
+    return { size, sha256: sha256.digest("hex"), gitBlob: sha1.digest("hex") };
+}
+function isNotFound(err) {
+    const e = err;
+    return e?.name === "NotFound" || e?.name === "NoSuchKey" || e?.$metadata?.httpStatusCode === 404;
+}
+/**
+ * S3-backed store over the caller's personal vault bucket. Accepts only
+ * personal vault buckets (`hq-vault-prs-*`) so a mis-resolved entity can never
+ * receive offloaded bytes.
+ */
+export function s3BlobStore(bucket, s3) {
+    if (!bucket || !bucket.startsWith(PERSONAL_BUCKET_PREFIX)) {
+        throw new Error(`Refusing to offload into '${bucket}': offload only writes to your personal vault.`);
+    }
+    return {
+        vault: "personal",
+        async head(key) {
+            try {
+                const res = (await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key, ChecksumMode: "ENABLED" })));
+                const fromChecksum = res.ChecksumSHA256 && !res.ChecksumSHA256.includes("-")
+                    ? Buffer.from(res.ChecksumSHA256, "base64").toString("hex")
+                    : undefined;
+                // The server-computed checksum wins; client metadata is a fallback for
+                // objects stored without one.
+                return { size: res.ContentLength ?? -1, sha256: fromChecksum ?? res.Metadata?.sha256 };
+            }
+            catch (err) {
+                if (isNotFound(err))
+                    return null;
+                throw err;
+            }
+        },
+        async put(key, file, digest) {
+            await s3.send(new PutObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                Body: fs.createReadStream(file),
+                ContentLength: digest.size,
+                ChecksumSHA256: Buffer.from(digest.sha256, "hex").toString("base64"),
+                StorageClass: "STANDARD",
+                Metadata: { sha256: digest.sha256, "git-blob": digest.gitBlob },
+            }));
+        },
+        async download(key, dest) {
+            const res = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
+            const body = res.Body;
+            if (!body)
+                throw new Error(`Empty download for ${key}.`);
+            await new Promise((resolve, reject) => {
+                const out = fs.createWriteStream(dest, { flags: "wx" });
+                body.on("error", reject);
+                out.on("error", reject);
+                out.on("finish", () => resolve());
+                body.pipe(out);
+            });
+        },
+    };
+}
+export function s3VaultObjectStore(bucket, s3) {
+    return {
+        async download(key, dest, etag) {
+            let res;
+            try {
+                res = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key, IfMatch: `"${normalizeEtag(etag)}"` })));
+            }
+            catch (err) {
+                const e = err;
+                if (e?.name === "PreconditionFailed" || e?.$metadata?.httpStatusCode === 412) {
+                    throw new Error("The cloud copy of this file changed since HQ sync last saw it. Run `hq sync`, then try again.");
+                }
+                if (isNotFound(err))
+                    throw new Error(`This file is no longer in the cloud (${key}).`);
+                throw err;
+            }
+            const body = res.Body;
+            if (!body)
+                throw new Error(`Empty download for ${key}.`);
+            await new Promise((resolve, reject) => {
+                const out = fs.createWriteStream(dest, { flags: "wx" });
+                body.on("error", reject);
+                out.on("error", reject);
+                out.on("finish", () => resolve());
+                body.pipe(out);
+            });
+            return normalizeEtag(res.ETag);
+        },
+    };
+}
+// ── Core script capability ──────────────────────────────────────────────────
+export function storageScriptPath(hqRoot) {
+    return path.join(hqRoot, "core", "scripts", "hq-storage.sh");
+}
+/** Whether the installed core script has a `case` arm for `sub`. */
+export function scriptSupports(hqRoot, sub) {
+    return coreSupports(storageScriptPath(hqRoot), sub);
+}
+/**
+ * Run a core subcommand. Callers check scriptSupports first, so a missing
+ * subcommand is already reported as "update HQ"; any failure here passes the
+ * script's own stderr through instead of guessing.
+ */
+function runCore(deps, args) {
+    return runCoreScript(deps.runScript, storageScriptPath(deps.hqRoot), args);
+}
+export async function getLarge(deps, minBytes) {
+    if (!scriptSupports(deps.hqRoot, "large")) {
+        return { available: false, reason: UPDATE_HQ, blobs: [], current: [], worktree_holders: [] };
+    }
+    const raw = await runCore(deps, ["large", "--json", "--min-bytes", String(minBytes)]);
+    if (raw.available === false) {
+        return { available: false, reason: String(raw.reason), blobs: [], current: [], worktree_holders: [] };
+    }
+    const history = (raw.history ?? {});
+    const current = (raw.current ?? {});
+    const blobs = (Array.isArray(history.blobs) ? history.blobs : [])
+        .map((b) => b)
+        .filter((b) => typeof b.sha === "string" && HEX40.test(b.sha) && typeof b.bytes === "number")
+        .map((b) => ({
+        ...b,
+        paths: Array.isArray(b.paths) ? b.paths : [],
+        in_head: b.in_head === true,
+        held_by: Array.isArray(b.held_by) ? b.held_by.filter((p) => typeof p === "string") : [],
+    }));
+    const holders = (Array.isArray(history.worktree_holders) ? history.worktree_holders : [])
+        .map((h) => h)
+        .filter((h) => typeof h.path === "string")
+        .map((h) => ({ path: h.path, branch: typeof h.branch === "string" ? h.branch : null }));
+    const files = (Array.isArray(current.files) ? current.files : [])
+        .map((f) => f)
+        .filter((f) => typeof f.path === "string" && typeof f.bytes === "number")
+        .map((f) => ({ ...f, idle_days: typeof f.idle_days === "number" ? f.idle_days : 0 }));
+    return { available: true, blobs, current: files, worktree_holders: holders };
+}
+/** Eligible history blobs split into ones offload can free and ones a linked worktree keeps. */
+export function splitHeld(blobs) {
+    return { free: blobs.filter((b) => b.held_by.length === 0), held: blobs.filter((b) => b.held_by.length > 0) };
+}
+/** Distinct worktree paths that hold any of `held`, in first-seen order. */
+export function heldWorktrees(held) {
+    return [...new Set(held.flatMap((b) => b.held_by))];
+}
+/** Plain refusal when every eligible old file is still used by a linked worktree. */
+export function worktreeHoldsAllCopy(held) {
+    const paths = heldWorktrees(held);
+    const names = paths.slice(0, 5).map((p) => `worktree ${p}`).join(", ") + (paths.length > 5 ? `, and ${paths.length - 5} more` : "");
+    return (`Nothing was uploaded or changed. ${held.length} old big file version(s) are still used by ` +
+        `${paths.length === 1 ? "another worktree" : `${paths.length} other worktrees`} (${names}), so moving them would free no space. ` +
+        "HQ never changes other worktrees; the space can be freed once they no longer use this history.");
+}
+/**
+ * History blobs eligible for offload: at least `minBytes`, and not part of the
+ * current checkout. Blobs in HEAD are current files; stripping them would
+ * leave the working tree out of step with HEAD.
+ */
+export function selectHistoryBlobs(blobs, minBytes) {
+    return blobs.filter((b) => !b.in_head && b.bytes >= minBytes && b.paths.length > 0);
+}
+// ── Upload + verify ─────────────────────────────────────────────────────────
+export function matchesDigest(obj, digest) {
+    return obj !== null && obj.size === digest.size && obj.sha256 === digest.sha256;
+}
+/**
+ * Export, hash, upload and verify one history blob. Resolves only when the
+ * stored object matches size and sha256. Dedupes on the content-addressed key:
+ * an already-verified object is not re-uploaded.
+ */
+export async function uploadBlob(blob, store, deps) {
+    const tmp = path.join(deps.tmpDir(), `hq-offload-${blob.sha}-${process.pid}`);
+    try {
+        await deps.exportBlob(blob.sha, tmp);
+        const digest = await digestFile(tmp);
+        if (digest.gitBlob !== blob.sha) {
+            throw new Error(`git blob ${blob.sha} exported with id ${digest.gitBlob}`);
+        }
+        return { digest, uploaded: await uploadVerified(store, tmp, digest) };
+    }
+    finally {
+        await fs.promises.rm(tmp, { force: true });
+    }
+}
+/**
+ * Upload `file` to its content-addressed key and verify size + sha256.
+ * Returns false when a verified copy was already there.
+ */
+async function uploadVerified(store, file, digest) {
+    const key = offloadKey(digest.gitBlob);
+    if (matchesDigest(await store.head(key), digest))
+        return false;
+    await store.put(key, file, digest);
+    const stored = await store.head(key);
+    if (!matchesDigest(stored, digest)) {
+        throw new Error(`upload verification failed for ${digest.gitBlob} (stored size ${stored?.size ?? "missing"}, expected ${digest.size})`);
+    }
+    return true;
+}
+export const durablePlaceholderFs = {
+    async writePlaceholder(file, text) {
+        const fh = await fs.promises.open(file, "wx");
+        try {
+            await fh.writeFile(text, "utf8");
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+        // Persist the directory entry too, so a crash cannot keep the delete of
+        // the original while losing the placeholder. Windows cannot fsync a
+        // directory handle.
+        if (process.platform !== "win32") {
+            const dir = await fs.promises.open(path.dirname(file), "r");
+            try {
+                await dir.sync();
+            }
+            finally {
+                await dir.close();
+            }
+        }
+    },
+    async removeOriginal(file) {
+        await fs.promises.rm(file);
+    },
+};
+/**
+ * Offload one current file: upload and verify, write `x.hqcloud` (fsynced),
+ * and only then remove `x`. With the placeholder written first, a sync
+ * watcher never sees `x` missing without its placeholder, which it would
+ * push as a delete.
+ *
+ * Not called while CURRENT_OFFLOAD_ENABLED is false.
+ */
+export async function offloadCurrentFile(rel, store, deps, fsOps = durablePlaceholderFs) {
+    if (store.vault !== "personal")
+        throw new Error("Offload only writes to your personal vault.");
+    assertRestorable(rel);
+    const abs = containedPath(deps.hqRoot, rel);
+    const before = await fs.promises.stat(abs);
+    if (!before.isFile())
+        throw new Error(`'${rel}' is not a regular file.`);
+    const digest = await digestFile(abs);
+    await uploadVerified(store, abs, digest);
+    const unchanged = async () => {
+        const st = await fs.promises.stat(abs);
+        return st.size === before.size && st.mtimeMs === before.mtimeMs && st.size === digest.size;
+    };
+    const changed = new Error(`'${rel}' changed while uploading. Nothing was replaced.`);
+    if (!(await unchanged()))
+        throw changed;
+    const placeholder = `${abs}${PLACEHOLDER_SUFFIX}`;
+    await fsOps.writePlaceholder(placeholder, renderPointer({
+        path: toPosix(rel),
+        size: digest.size,
+        sha256: digest.sha256,
+        gitBlob: digest.gitBlob,
+        vault: "personal",
+        key: offloadKey(digest.gitBlob),
+        offloadedAt: deps.now().toISOString().replace(/\.\d{3}Z$/, "Z"),
+    }));
+    if (!(await unchanged())) {
+        await fs.promises.rm(placeholder, { force: true });
+        throw changed;
+    }
+    await fsOps.removeOriginal(abs);
+    return { path: toPosix(rel), bytes: digest.size };
+}
+export async function runOffload(opts, deps) {
+    const both = !opts.history && !opts.current;
+    const doHistory = both || opts.history;
+    const doCurrent = both || opts.current;
+    const result = {
+        history: { uploaded: 0, bytes: 0, freed_bytes: 0 },
+        current: { offloaded: [], freed_bytes: 0 },
+        errors: [],
+        dry_run: opts.dryRun,
+    };
+    if (doCurrent) {
+        result.current.available = false;
+        result.current.reason = CURRENT_BLOCKED_REASON;
+    }
+    const script = storageScriptPath(deps.hqRoot);
+    if (!doHistory)
+        return result;
+    if (!deps.syncExcludesOffload()) {
+        result.history.available = false;
+        result.history.reason = UPDATE_SYNC;
+        return result;
+    }
+    const large = await getLarge(deps, opts.minBytes);
+    if (!large.available) {
+        result.history.available = false;
+        result.history.reason = large.reason;
+        return result;
+    }
+    const eligible = selectHistoryBlobs(large.blobs, opts.minBytes);
+    // Old versions a linked worktree still reaches stay on disk whatever offload
+    // does, so they are never uploaded, never counted, and the worktrees are named.
+    const { free: blobs, held } = splitHeld(eligible);
+    result.history.candidates = blobs.length;
+    result.history.candidate_bytes = blobs.reduce((s, b) => s + b.bytes, 0);
+    if (held.length > 0) {
+        result.history.held_by_worktrees = { count: held.length, bytes: held.reduce((s, b) => s + b.bytes, 0) };
+        result.history.worktree_holders = heldWorktrees(held);
+    }
+    // The rewrite's preconditions are checked before anything is uploaded, so a
+    // refusal never leaves uploads behind, and a dry run predicts it.
+    const refusal = blobs.length > 0 && fs.existsSync(script) ? await checkPreconditions(deps.runScript, script, "strip-large") : undefined;
+    if (refusal) {
+        result.history.refused = refusal.refused;
+        result.history.message = refusal.message;
+        if (!opts.dryRun)
+            return result;
+    }
+    else if (blobs.length === 0 && held.length > 0) {
+        // Same contract as prune: nothing to free is a refusal (exit 4), decided
+        // before anything is uploaded; the dry run predicts it.
+        result.history.refused = "nothing_to_free";
+        result.history.message = worktreeHoldsAllCopy(held);
+        if (!opts.dryRun)
+            return result;
+    }
+    const noBackup = coreHasFlag(script, "--no-backup");
+    if (opts.dryRun) {
+        // Dry run fills the real-run fields with estimates so a preview reads the
+        // same keys: every candidate uploaded, and history shrinks by its size.
+        const planned = refusal ? 0 : result.history.candidate_bytes;
+        result.history.uploaded = refusal ? 0 : blobs.length;
+        result.history.bytes = planned;
+        // When the space comes back:
+        // - core that keeps undo history: nothing at once; all of it once git's
+        //   30-day undo entries age out (reclaim_after);
+        // - older core with --no-backup: at once;
+        // - older core without it: after the 24 h backup.
+        if (refusal || planned === 0) {
+            result.history.freed_bytes = 0;
+            Object.assign(result.history, { backup_ref: null, reclaim_after: null, pending_reclaim_bytes: 0 });
+        }
+        else if (noBackup && !coreKeepsUndo(script)) {
+            result.history.freed_bytes = planned;
+            Object.assign(result.history, { backup_ref: null, reclaim_after: null, pending_reclaim_bytes: 0 });
+        }
+        else {
+            result.history.freed_bytes = 0;
+            Object.assign(result.history, reclaimFields({}, {
+                dryRun: true,
+                now: deps.now(),
+                expectedBytes: planned,
+                freedBytes: 0,
+                windowHours: reclaimWindowHours(script),
+            }));
+        }
+        return result;
+    }
+    if (blobs.length === 0)
+        return result;
+    if (!scriptSupports(deps.hqRoot, "strip-large")) {
+        result.history.available = false;
+        result.history.reason = UPDATE_HQ;
+        return result;
+    }
+    if (!opts.yes) {
+        const ok = await deps.confirm(`Upload ${blobs.length} old file version(s) to your personal HQ cloud storage and replace them in local history with links?`);
+        if (!ok) {
+            deps.log("Aborted - nothing was uploaded or changed.");
+            return undefined;
+        }
+    }
+    const dropped = await dropExpiredBackups(deps.runScript, script);
+    if (dropped)
+        result.reclaim = dropped;
+    const store = await deps.openPersonal();
+    if (store.vault !== "personal")
+        throw new Error("Offload only writes to your personal vault.");
+    const offloadedAt = deps.now().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const manifest = [];
+    for (const blob of blobs) {
+        try {
+            const { digest, uploaded } = await uploadBlob(blob, store, deps);
+            if (uploaded) {
+                result.history.uploaded += 1;
+                result.history.bytes += digest.size;
+            }
+            // One pointer per blob, not per path: strip-large swaps the blob by id,
+            // so every path that held it gets the same pointer text. `path:` names
+            // the first path; `hq storage fetch --git-blob <sha>` works for all.
+            manifest.push({
+                sha: blob.sha,
+                pointer_text: renderPointer({
+                    path: blob.paths[0],
+                    size: digest.size,
+                    sha256: digest.sha256,
+                    gitBlob: blob.sha,
+                    vault: "personal",
+                    key: offloadKey(blob.sha),
+                    offloadedAt,
+                }),
+            });
+        }
+        catch (err) {
+            result.errors.push(`${blob.paths[0] ?? blob.sha}: ${err.message}`);
+        }
+    }
+    if (manifest.length === 0)
+        return result;
+    const manifestFile = path.join(deps.tmpDir(), `hq-offload-manifest-${process.pid}.json`);
+    await fs.promises.writeFile(manifestFile, JSON.stringify({ blobs: manifest }));
+    try {
+        // strip-large always prints JSON; it takes no --json flag. Every listed
+        // blob is already verified in the vault (size, sha256, git id), so no
+        // local backup is kept and the disk frees now. Core that predates
+        // --no-backup is called without it.
+        const args = ["strip-large", "--manifest", manifestFile, "--yes"];
+        if (noBackup)
+            args.push("--no-backup");
+        const strip = await runCore(deps, args);
+        if (typeof strip.refused === "string") {
+            // Precondition changed between the check and the rewrite. The uploads
+            // stay in the vault; local history is unchanged.
+            result.history.refused = strip.refused;
+            result.history.message = typeof strip.message === "string" ? strip.message : PRECONDITION_FALLBACK;
+        }
+        else if (strip.available === false) {
+            result.errors.push(`history rewrite: ${plainCoreError(String(strip.reason))}`);
+        }
+        else {
+            result.history.freed_bytes = typeof strip.freed_bytes === "number" ? strip.freed_bytes : 0;
+            const replaced = new Set(manifest.map((m) => m.sha));
+            const expected = blobs.filter((b) => replaced.has(b.sha)).reduce((s, b) => s + b.bytes, 0);
+            Object.assign(result.history, reclaimFields(strip, {
+                dryRun: false,
+                now: deps.now(),
+                expectedBytes: expected,
+                freedBytes: result.history.freed_bytes,
+            }));
+        }
+    }
+    finally {
+        await fs.promises.rm(manifestFile, { force: true });
+    }
+    return result;
+}
+/** Core stderr without the script's "hq-storage: " prefix. */
+function plainCoreError(reason) {
+    return reason.replace(/^hq-storage:\s*/gm, "").trim();
+}
+// ── fetch ───────────────────────────────────────────────────────────────────
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+/**
+ * Resolve `rel` inside HQ, following symlinks: the deepest existing ancestor
+ * is realpath'd and must still be inside the realpath'd HQ root, so a
+ * symlinked folder cannot redirect a write outside HQ.
+ */
+export function containedPath(hqRoot, rel) {
+    const root = path.resolve(hqRoot);
+    const abs = path.resolve(root, rel);
+    if (abs !== root && !abs.startsWith(root + path.sep)) {
+        throw new Error(`Path '${rel}' is outside HQ.`);
+    }
+    const realRoot = fs.realpathSync(root);
+    let existing = abs;
+    const rest = [];
+    while (!fs.existsSync(existing)) {
+        rest.unshift(path.basename(existing));
+        existing = path.dirname(existing);
+    }
+    const real = path.join(fs.realpathSync(existing), ...rest);
+    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+        throw new Error(`Path '${rel}' is outside HQ.`);
+    }
+    return real;
+}
+/** Restore targets that fetch must never write: git internals and agent hooks. */
+export function assertRestorable(rel) {
+    const parts = toPosix(path.normalize(rel)).toLowerCase().split("/");
+    if (parts.includes(".git") || (parts[0] === ".claude" && parts[1] === "hooks")) {
+        throw new Error(`Refusing to restore '${rel}': HQ never writes cloud files into .git/ or .claude/hooks/.`);
+    }
+}
+function readPointerFile(file) {
+    if (!fs.existsSync(file))
+        return null;
+    const st = fs.statSync(file);
+    if (!st.isFile() || st.size >= 4096)
+        return null;
+    return parsePointer(fs.readFileSync(file, "utf8"));
+}
+/** Resolve a fetch argument (original path or placeholder path) to its placeholder file. */
+export function resolvePlaceholder(hqRoot, arg) {
+    const abs = containedPath(hqRoot, arg);
+    const candidate = abs.endsWith(PLACEHOLDER_SUFFIX) ? abs : `${abs}${PLACEHOLDER_SUFFIX}`;
+    if (readPointerFile(candidate))
+        return candidate;
+    throw new Error(`No HQ cloud placeholder found for '${arg}'. For an old version from history, use --git-blob <sha> --out <file>.`);
+}
+/**
+ * Download to a fresh partial file, verify, then hard-link it to `dest`.
+ * `link` fails if `dest` exists, so a file created between the caller's
+ * existence check and the restore is never overwritten. `download` returns
+ * the served ETag when the source is pinned to one.
+ */
+async function downloadVerified(download, key, dest, expect) {
+    const partial = `${dest}.${crypto.randomBytes(6).toString("hex")}.hqcloud-download`;
+    try {
+        const servedEtag = await download(partial);
+        const digest = await digestFile(partial);
+        if ((expect.gitBlob !== undefined && digest.gitBlob !== expect.gitBlob) ||
+            (expect.sha256 != null && digest.sha256 !== expect.sha256) ||
+            (expect.size !== undefined && digest.size !== expect.size) ||
+            (expect.etag !== undefined && normalizeEtag(servedEtag ?? "") !== normalizeEtag(expect.etag))) {
+            throw new Error(`Downloaded file does not match its checksum (${key}). Nothing was changed.`);
+        }
+        try {
+            await fs.promises.link(partial, dest);
+        }
+        catch (err) {
+            if (err.code === "EEXIST") {
+                throw new Error(`'${dest}' already exists. Move it aside first.`);
+            }
+            throw err;
+        }
+        return digest;
+    }
+    finally {
+        await fs.promises.rm(partial, { force: true });
+    }
+}
+/** Company slug for a company-vault placeholder, checked against its key. */
+export function companyForPointer(pointer) {
+    const m = /^companies\/([^/]+)\/(.+)$/.exec(pointer.path);
+    if (!m || m[2] !== pointer.key) {
+        throw new Error(`Placeholder for '${pointer.path}' names company vault key '${pointer.key}', which does not match its location. Nothing was changed.`);
+    }
+    return m[1];
+}
+/**
+ * Teammate-deleted file: write the caller's own offloaded copy to a file
+ * outside HQ. Outside HQ means sync never sees it, so it is never pushed back
+ * to the team. The placeholder stays as is.
+ */
+async function fetchOrphan(pointer, opts, deps) {
+    if (!opts.out)
+        throw new Error("--force-orphan needs --out <file> outside your HQ folder.");
+    if (!pointer.gitBlob) {
+        throw new Error(`${ORPHANED_MESSAGE} You have no personal copy of it to restore.`);
+    }
+    const dest = path.resolve(opts.out);
+    const realRoot = fs.realpathSync(path.resolve(deps.hqRoot));
+    let realParent;
+    try {
+        realParent = fs.realpathSync(path.dirname(dest));
+    }
+    catch {
+        throw new Error(`The folder for '${opts.out}' does not exist.`);
+    }
+    if (realParent === realRoot || realParent.startsWith(realRoot + path.sep)) {
+        throw new Error("--force-orphan writes outside your HQ folder, so the restored copy is never synced to your team. Pick an --out path outside HQ.");
+    }
+    return fetchGitBlob(pointer.gitBlob, path.join(realParent, path.basename(dest)), deps);
+}
+export async function runFetch(arg, deps, opts = {}) {
+    return fetchPlaceholder(arg, deps, opts);
+}
+async function fetchPlaceholder(arg, deps, opts) {
+    const placeholder = resolvePlaceholder(deps.hqRoot, arg);
+    const pointer = readPointerFile(placeholder);
+    if (!pointer)
+        throw new Error(`'${arg}' is not a valid HQ cloud placeholder.`);
+    if (pointer.orphaned) {
+        if (!opts.forceOrphan) {
+            throw new Error(`${ORPHANED_MESSAGE} To get your own copy back outside HQ, run: hq storage fetch "${pointer.path}" --force-orphan --out <file>`);
+        }
+        return fetchOrphan(pointer, opts, deps);
+    }
+    if (opts.forceOrphan)
+        throw new Error("--force-orphan is only for files a teammate deleted.");
+    const target = containedPath(deps.hqRoot, pointer.path);
+    const realRoot = fs.realpathSync(path.resolve(deps.hqRoot));
+    const placeholderRel = toPosix(path.relative(realRoot, placeholder));
+    if (`${toPosix(path.relative(realRoot, target))}${PLACEHOLDER_SUFFIX}` !== placeholderRel) {
+        throw new Error(`Placeholder '${placeholderRel}' names '${pointer.path}', which is not its own location. Nothing was changed.`);
+    }
+    assertRestorable(pointer.path);
+    if (fs.existsSync(target)) {
+        throw new Error(`'${pointer.path}' already exists locally. Move it aside first.`);
+    }
+    let digest;
+    if (pointer.remoteEtag === undefined) {
+        // Offload copy in the personal vault, verified by git blob id and sha256.
+        const store = await deps.openPersonal();
+        digest = await downloadVerified((partial) => store.download(pointer.key, partial), pointer.key, target, {
+            gitBlob: pointer.gitBlob,
+            sha256: pointer.sha256,
+            size: pointer.size,
+        });
+    }
+    else {
+        digest = await fetchVaultObject(pointer, target, deps);
+    }
+    await fs.promises.rm(placeholder, { force: true });
+    return { path: pointer.path, bytes: digest.size, sha256: digest.sha256 };
+}
+/**
+ * Placeholder that sync rewrote to a vault object: download pinned to the
+ * recorded ETag and verify size (and sha256 when known). A company vault is
+ * opened only for a company the caller is an active member of.
+ */
+async function fetchVaultObject(pointer, target, deps) {
+    if (!deps.openVaultObjects)
+        throw new Error("This HQ build cannot fetch files recorded by HQ sync.");
+    let store;
+    if (pointer.vault === "company") {
+        const slug = companyForPointer(pointer);
+        const active = deps.activeCompanySlugs ? await deps.activeCompanySlugs() : [];
+        if (!active.includes(slug)) {
+            throw new Error(`You are not an active member of '${slug}', so HQ cannot download this file for you.`);
+        }
+        store = await deps.openVaultObjects({ vault: "company", slug });
+    }
+    else {
+        if (pointer.key !== pointer.path) {
+            throw new Error(`Placeholder for '${pointer.path}' names vault key '${pointer.key}', which does not match its location. Nothing was changed.`);
+        }
+        store = await deps.openVaultObjects({ vault: "personal" });
+    }
+    const etag = pointer.remoteEtag;
+    return downloadVerified((partial) => store.download(pointer.key, partial, etag), pointer.key, target, {
+        sha256: pointer.sha256,
+        size: pointer.size,
+        etag,
+    });
+}
+export async function runFetchGitBlob(sha, out, deps) {
+    return fetchGitBlob(sha, out, deps);
+}
+async function fetchGitBlob(sha, out, deps) {
+    if (!HEX40.test(sha))
+        throw new Error(`--git-blob must be a 40-character git blob id, got '${sha}'.`);
+    const dest = path.resolve(out);
+    if (fs.existsSync(dest))
+        throw new Error(`'${out}' already exists.`);
+    const store = await deps.openPersonal();
+    const key = offloadKey(sha);
+    const head = await store.head(key);
+    if (!head)
+        throw new Error(`No offloaded copy of git blob ${sha} in your personal vault.`);
+    const digest = await downloadVerified((partial) => store.download(key, partial), key, dest, {
+        gitBlob: sha,
+        sha256: head.sha256,
+        size: head.size,
+    });
+    return { path: dest, bytes: digest.size, sha256: digest.sha256 };
+}
+/** Current-file offload availability, shared by status and its error fallback. */
+export function currentAvailability(syncReady) {
+    if (!CURRENT_OFFLOAD_ENABLED)
+        return { current_available: false, current_reason: CURRENT_BLOCKED_REASON };
+    if (!syncReady)
+        return { current_available: false, current_reason: UPDATE_SYNC };
+    return { current_available: true };
+}
+export async function getOffloadStatus(deps, opts) {
+    const status = {
+        history_candidates: { count: 0, bytes: 0 },
+        current_candidates: { count: 0, bytes: 0 },
+        placeholders: { count: 0, bytes: 0 },
+        ...currentAvailability(deps.syncExcludesOffload()),
+    };
+    for (const rel of await deps.listPlaceholders()) {
+        const pointer = readPointerFile(containedPath(deps.hqRoot, rel));
+        if (!pointer)
+            continue;
+        status.placeholders.count += 1;
+        status.placeholders.bytes += pointer.size;
+    }
+    const large = await getLarge(deps, opts.minBytes);
+    if (!large.available) {
+        status.available = false;
+        status.reason = large.reason;
+        return status;
+    }
+    if (!deps.syncExcludesOffload()) {
+        status.available = false;
+        status.reason = UPDATE_SYNC;
+    }
+    const { free, held } = splitHeld(selectHistoryBlobs(large.blobs, opts.minBytes));
+    for (const b of free) {
+        status.history_candidates.count += 1;
+        status.history_candidates.bytes += b.bytes;
+    }
+    if (held.length > 0) {
+        status.history_held = {
+            count: held.length,
+            bytes: held.reduce((s, b) => s + b.bytes, 0),
+            worktrees: heldWorktrees(held),
+        };
+    }
+    for (const f of large.current) {
+        if (f.bytes < opts.minBytes || f.idle_days < opts.idleDays)
+            continue;
+        status.current_candidates.count += 1;
+        status.current_candidates.bytes += f.bytes;
+    }
+    return status;
+}
+// ── Production deps ─────────────────────────────────────────────────────────
+export function gitExportBlob(hqRoot) {
+    return (sha, dest) => new Promise((resolve, reject) => {
+        const out = fs.createWriteStream(dest);
+        const child = spawn("git", ["-C", hqRoot, "cat-file", "blob", sha], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.stdout.pipe(out);
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code !== 0) {
+                out.destroy();
+                reject(new Error(`git cat-file ${sha} failed: ${stderr.trim()}`));
+                return;
+            }
+            if (out.writableFinished)
+                resolve();
+            else
+                out.on("finish", () => resolve());
+        });
+    });
+}
+export function gitListPlaceholders(hqRoot) {
+    return () => new Promise((resolve, reject) => {
+        execFile("git", [
+            "-C",
+            hqRoot,
+            "ls-files",
+            "-z",
+            "--cached",
+            "--others",
+            "--exclude-standard",
+            "--",
+            `*${PLACEHOLDER_SUFFIX}`,
+        ], { maxBuffer: 64 * 1024 * 1024 }, (err, stdout) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve(String(stdout).split("\0").filter(Boolean));
+        });
+    });
+}
+export function defaultTmpDir() {
+    return os.tmpdir();
+}
+export function personalS3Store(input) {
+    return s3BlobStore(input.bucket, new S3Client({ region: input.region, credentials: input.credentials }));
+}
+//# sourceMappingURL=storage-offload.js.map