@indigoai-us/hq-cli 5.345.80 → 5.345.81

package/dist/commands/storage-core.js

@@ -0,0 +1,223 @@
+/**
+ * Shared calls into core `hq-storage.sh` for `hq storage` status, prune and
+ * offload.
+ *
+ * - `runCoreScript` turns one script run into a JSON report. Exit 4 from
+ *   `prune` ("would free nothing") becomes a structured refusal with the
+ *   branches, tags or stash that hold the old history, never raw stderr.
+ * - `dropExpiredBackups` runs core `drop-backups --expired` right before a
+ *   real prune or offload (never for status, dry runs or fetch). With no
+ *   expired backup it takes no lock and runs no gc; it never expires reflogs.
+ *   A failure is reported but never blocks the command.
+ * - `checkPreconditions` runs core `check` so offload can refuse before it
+ *   uploads anything. Exit 5 from a core rewrite (a failed precondition)
+ *   becomes a structured refusal with plain text, never raw stderr.
+ * - Backups: by default core keeps a backup ref for 24 h after prune or
+ *   strip-large, so space comes back after `reclaim_after`, not at once.
+ *   `withReclaim` adds `backup_ref`, `reclaim_after` and
+ *   `pending_reclaim_bytes` to a result so a UI can say when space is freed.
+ */
+import * as fs from "node:fs";
+/** Core's default backup grace period (`HQ_STORAGE_BACKUP_GRACE_HOURS`). */
+export const BACKUP_GRACE_HOURS = 24;
+/**
+ * Git's default expiry for reflog entries that point at rewritten history
+ * (gc.reflogExpireUnreachable). Core that keeps undo history frees the space
+ * a prune or offload rewrote only after these entries age out.
+ */
+export const UNDO_WINDOW_DAYS = 30;
+/** Whether the installed core keeps git's undo history (never expires reflogs early). */
+export function coreKeepsUndo(script) {
+    return coreHasFlag(script, "hq-storage-undo-pending");
+}
+/** Hours after a rewrite until its space is freed, for this core. */
+export function reclaimWindowHours(script) {
+    return coreKeepsUndo(script) ? UNDO_WINDOW_DAYS * 24 : BACKUP_GRACE_HOURS;
+}
+/** Whether the installed core script has a `case` arm for `sub`. */
+export function coreSupports(script, sub) {
+    if (!fs.existsSync(script))
+        return false;
+    const text = fs.readFileSync(script, "utf8");
+    return new RegExp(`(^|[\\s|(])${sub}\\)`, "m").test(text);
+}
+/** Whether the installed core script mentions a flag, e.g. `--no-backup`. */
+export function coreHasFlag(script, flag) {
+    return fs.existsSync(script) && fs.readFileSync(script, "utf8").includes(flag);
+}
+function normalizeHoldingRefs(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const refs = [];
+    for (const r of raw) {
+        if (typeof r === "string")
+            refs.push({ name: r, commit_date: null });
+        else if (r && typeof r === "object") {
+            const o = r;
+            const name = typeof o.name === "string" ? o.name : typeof o.ref === "string" ? o.ref : undefined;
+            if (!name)
+                continue;
+            const date = typeof o.commit_date === "string" ? o.commit_date : null;
+            refs.push({ name, commit_date: date });
+        }
+    }
+    return refs;
+}
+/**
+ * Structured exit-4 refusal. Newer core prints
+ * `{"refused":"nothing_to_free","holding_refs":[...],"holding_refs_count":N}`
+ * on stdout. Older core printed only a stderr line naming `(ref, ref)`; the
+ * ref names are taken from it and the line itself (which tells the user to
+ * delete them) is dropped.
+ */
+export function parseRefusal(stdout, stderr) {
+    let refs = [];
+    let count;
+    try {
+        const parsed = JSON.parse(stdout);
+        refs = normalizeHoldingRefs(parsed.holding_refs);
+        if (typeof parsed.holding_refs_count === "number")
+            count = parsed.holding_refs_count;
+    }
+    catch {
+        const m = /\(([^()]*refs\/[^()]*)\)/.exec(stderr);
+        if (m) {
+            refs = m[1]
+                .split(/[,\s]+/)
+                .filter((s) => s.startsWith("refs/"))
+                .map((name) => ({ name, commit_date: null }));
+        }
+    }
+    return {
+        available: true,
+        refused: "nothing_to_free",
+        holding_refs: refs,
+        holding_refs_count: count ?? refs.length,
+    };
+}
+/** Core exit code for a failed precondition (remote-tracking branches, ...). */
+export const CORE_PRECONDITION_EXIT = 5;
+/** Plain text for a precondition refusal from core that printed no message. */
+export const PRECONDITION_FALLBACK = "HQ is not in a state where its history can be rewritten. Nothing was changed.";
+/** `{"refused":"<code>","message":".."}` on stdout, or a plain fallback. */
+export function parsePreconditionRefusal(stdout) {
+    try {
+        const o = JSON.parse(stdout);
+        if (typeof o.refused === "string") {
+            return { refused: o.refused, message: typeof o.message === "string" ? o.message : PRECONDITION_FALLBACK };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { refused: "precondition", message: PRECONDITION_FALLBACK };
+}
+/** Run one core subcommand and return its JSON as a report. */
+export async function runCoreScript(runScript, script, args) {
+    const res = await runScript(script, args);
+    if (res.code === 4 && args[0] === "prune")
+        return parseRefusal(res.stdout, res.stderr);
+    if (res.code === CORE_PRECONDITION_EXIT) {
+        return { available: true, ...parsePreconditionRefusal(res.stdout) };
+    }
+    // strip-large exit 4: nothing to free (linked worktrees still use every
+    // listed file). Structured, never raw stderr.
+    if (res.code === 4 && args[0] === "strip-large") {
+        let extra = {};
+        try {
+            extra = JSON.parse(res.stdout);
+        }
+        catch {
+            // fall through
+        }
+        return {
+            ...extra,
+            available: true,
+            refused: "nothing_to_free",
+            message: typeof extra.message === "string" ? extra.message : "Offloading would free nothing. Nothing was changed.",
+        };
+    }
+    if (res.code !== 0) {
+        return {
+            available: false,
+            reason: (res.stderr.trim() || `hq-storage.sh exited ${res.code}`).slice(0, 500),
+        };
+    }
+    try {
+        return { available: true, ...JSON.parse(res.stdout) };
+    }
+    catch (err) {
+        return { available: false, reason: `hq-storage.sh returned invalid JSON: ${err.message}` };
+    }
+}
+/**
+ * Run core `drop-backups --expired` when the script has it; undefined when it
+ * does not. Call only right before a real prune or offload.
+ */
+export async function dropExpiredBackups(runScript, script) {
+    if (!coreSupports(script, "drop-backups"))
+        return undefined;
+    const r = await runCoreScript(runScript, script, ["drop-backups", "--expired"]);
+    if (r.available === false)
+        return { available: false, reason: r.reason };
+    return {
+        available: true,
+        dropped: typeof r.dropped === "number" ? r.dropped : 0,
+        freed_bytes: typeof r.freed_bytes === "number" ? r.freed_bytes : 0,
+    };
+}
+/**
+ * Core `check`: undefined when core lacks it (or it fails to run), else null
+ * when every precondition holds, or the refusal.
+ */
+export async function checkPreconditions(runScript, script, forCmd) {
+    if (!coreSupports(script, "check"))
+        return undefined;
+    const res = await runScript(script, ["check", "--for", forCmd]);
+    if (res.code !== 0)
+        return undefined;
+    try {
+        const o = JSON.parse(res.stdout);
+        if (o.ok === true)
+            return null;
+        if (typeof o.refused === "string") {
+            return { refused: o.refused, message: typeof o.message === "string" ? o.message : PRECONDITION_FALLBACK };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
+export function reclaimEstimate(now, hours = BACKUP_GRACE_HOURS) {
+    return new Date(now.getTime() + hours * 3600_000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Backup fields for a prune or strip-large result.
+ * - dry run: `reclaim_after` is an estimate (now + `windowHours`: 24 h for
+ *   the backup, or 30 days when core keeps undo history) and all of
+ *   `expectedBytes` is pending.
+ * - real run: core's `backup_ref` / `reclaim_after`; `pending_reclaim_bytes`
+ *   is core's value when it reports one, else `expectedBytes - freed` while a
+ *   backup is held, else 0.
+ */
+export function reclaimFields(core, opts) {
+    if (opts.dryRun) {
+        // Nothing to free means no date to promise.
+        const pending = Math.max(0, opts.expectedBytes);
+        return {
+            backup_ref: null,
+            reclaim_after: pending > 0 ? reclaimEstimate(opts.now, opts.windowHours) : null,
+            pending_reclaim_bytes: pending,
+        };
+    }
+    const backupRef = typeof core.backup_ref === "string" ? core.backup_ref : null;
+    const reclaimAfter = typeof core.reclaim_after === "string" ? core.reclaim_after : null;
+    const pending = typeof core.pending_reclaim_bytes === "number"
+        ? core.pending_reclaim_bytes
+        : backupRef
+            ? Math.max(0, opts.expectedBytes - opts.freedBytes)
+            : 0;
+    return { backup_ref: backupRef, reclaim_after: reclaimAfter, pending_reclaim_bytes: pending };
+}
+//# sourceMappingURL=storage-core.js.map

package/dist/commands/storage-gate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Live HQ Storage gate and refusal surface for `hq storage`.
+ *
+ * Allowlist gate, fails closed (owner decision 2026-10-11, Indigo-only until
+ * the owner widens it; see the storage-feature-flag module in src/lib). This
+ * is the deliberate exception to the default-on kill-switch rule: any error,
+ * a signed-out caller, an API-key caller, a membership read failure, or an
+ * unreadable registry all mean Storage is OFF.
+ *
+ * Resolved before the command tree is registered, because that path is
+ * already async; the registrar and every subcommand stay synchronous.
+ */
+import { Command } from "commander";
+import { hideStorageInCatalog } from "../lib/storage-feature-flag.js";
+export interface StorageGateDeps {
+    /** Synchronous cached answer; true short-circuits the network. */
+    cached?: () => boolean;
+    /** Signed-in Cognito token, or null when signed out / API-key auth. */
+    token?: () => Promise<string | null>;
+    /** Active company uids for the caller (from the membership API). */
+    companyUids?: (token: string) => Promise<string[]>;
+    /** Resolve the flag for one company the caller belongs to. */
+    resolveForCompany?: (companyUid: string, token: string) => Promise<boolean>;
+}
+/** True when `hq-storage` resolves on for the caller. Never throws. */
+export declare function storageFeatureEnabled(deps?: StorageGateDeps): Promise<boolean>;
+/** Print the refusal: JSON on stdout for `--json`, plain text on stderr otherwise. */
+export declare function printStorageRefusal(argv: readonly string[]): void;
+/**
+ * Register a hidden `storage` root that refuses every invocation, including
+ * `--help` and every subcommand, without describing what Storage does.
+ */
+export declare function registerStorageRefusal(program: Command, argv?: readonly string[]): Command;
+export { hideStorageInCatalog };
+//# sourceMappingURL=storage-gate.d.ts.map

package/dist/commands/storage-gate.js

@@ -0,0 +1,85 @@
+/**
+ * Live HQ Storage gate and refusal surface for `hq storage`.
+ *
+ * Allowlist gate, fails closed (owner decision 2026-10-11, Indigo-only until
+ * the owner widens it; see the storage-feature-flag module in src/lib). This
+ * is the deliberate exception to the default-on kill-switch rule: any error,
+ * a signed-out caller, an API-key caller, a membership read failure, or an
+ * unreadable registry all mean Storage is OFF.
+ *
+ * Resolved before the command tree is registered, because that path is
+ * already async; the registrar and every subcommand stay synchronous.
+ */
+import { Command } from "commander";
+import { resolveCompanyFlagGate } from "../lib/flag-registry.js";
+import { HQ_STORAGE_FLAG, STORAGE_FEATURE_DISABLED_MESSAGE, storageFeatureDisabledJson, storageFeatureEnabledFromCache, hideStorageInCatalog, } from "../lib/storage-feature-flag.js";
+const MEMBERSHIP_TIMEOUT_MS = 3_000;
+async function defaultToken() {
+    const { resolveVaultCredential } = await import("../utils/resolve-vault-credential.js");
+    const cred = await resolveVaultCredential({ interactive: false });
+    return cred.kind === "api-key" ? null : cred.token;
+}
+async function defaultCompanyUids(token) {
+    const [{ vaultApiFetch }, { companiesFromMemberships }] = await Promise.all([
+        import("../utils/vault-api.js"),
+        import("./storage.js"),
+    ]);
+    const res = await vaultApiFetch({
+        token,
+        path: "/membership/me",
+        signal: AbortSignal.timeout(MEMBERSHIP_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        return [];
+    return companiesFromMemberships(await res.json()).map((company) => company.uid);
+}
+function defaultResolveForCompany(companyUid, token) {
+    // Shared evaluator, bounded client (1.2 s transport timeout). Fallback is
+    // false: an unreadable or absent row keeps Storage off.
+    return resolveCompanyFlagGate(companyUid, token, HQ_STORAGE_FLAG, { fallback: false }, () => false);
+}
+/** True when `hq-storage` resolves on for the caller. Never throws. */
+export async function storageFeatureEnabled(deps = {}) {
+    try {
+        if ((deps.cached ?? storageFeatureEnabledFromCache)())
+            return true;
+        const token = await (deps.token ?? defaultToken)();
+        if (!token)
+            return false;
+        const uids = await (deps.companyUids ?? defaultCompanyUids)(token);
+        if (uids.length === 0)
+            return false;
+        const resolve = deps.resolveForCompany ?? defaultResolveForCompany;
+        const answers = await Promise.all(uids.map((uid) => resolve(uid, token).then((value) => value === true, () => false)));
+        return answers.some(Boolean);
+    }
+    catch {
+        return false;
+    }
+}
+/** Print the refusal: JSON on stdout for `--json`, plain text on stderr otherwise. */
+export function printStorageRefusal(argv) {
+    if (argv.includes("--json"))
+        console.log(storageFeatureDisabledJson());
+    else
+        console.error(STORAGE_FEATURE_DISABLED_MESSAGE);
+    process.exitCode = 1;
+}
+/**
+ * Register a hidden `storage` root that refuses every invocation, including
+ * `--help` and every subcommand, without describing what Storage does.
+ */
+export function registerStorageRefusal(program, argv = process.argv) {
+    const storage = new Command("storage")
+        .helpOption(false)
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .argument("[args...]")
+        .action(() => printStorageRefusal(argv));
+    // `hq help storage` prints help instead of running the action.
+    storage.helpInformation = () => `${STORAGE_FEATURE_DISABLED_MESSAGE}\n`;
+    program.addCommand(storage, { hidden: true });
+    return storage;
+}
+export { hideStorageInCatalog };
+//# sourceMappingURL=storage-gate.js.map

package/dist/commands/storage-offload.d.ts

@@ -0,0 +1,342 @@
+/**
+ * `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 { GetObjectCommand, HeadObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
+import type { ScriptRunner } from "./storage.js";
+import { type ReclaimReport } from "./storage-core.js";
+export declare const PLACEHOLDER_SUFFIX = ".hqcloud";
+export declare const OFFLOAD_PREFIX = ".hq-offload/blobs/";
+export declare const POINTER_HEADER = "HQ-CLOUD-FILE v1";
+export declare const POINTER_FOOTER = "This file is stored in HQ cloud storage. Open it in HQ, or run the command above to download it.";
+export declare const DEFAULT_MIN_BYTES: number;
+export declare const DEFAULT_IDLE_DAYS = 14;
+export declare 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 declare const CURRENT_OFFLOAD_ENABLED = false;
+export declare const ORPHANED_MESSAGE = "This file was deleted by a teammate. It's no longer in the cloud for your team.";
+export declare const UPDATE_SYNC = "update HQ sync";
+/** Top-level HQ-root folder that holds offloaded blobs in the personal vault. */
+export declare 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 declare function syncExcludesOffload(excludedTopLevel: readonly string[] | undefined): boolean;
+export declare function offloadKey(gitBlobSha: string): string;
+export declare function parseSize(value: string): number;
+export declare function resolveMinBytes(flag: string | undefined, env: NodeJS.ProcessEnv): number;
+export interface Pointer {
+    path: string;
+    size: number;
+    /** Hex sha256, or null when recorded as `unknown` (sync-updated placeholders). */
+    sha256: string | null;
+    gitBlob?: string;
+    vault: "personal" | "company";
+    key: string;
+    offloadedAt?: string;
+    /** Vault object ETag, written by sync when it records a teammate's version. */
+    remoteEtag?: string;
+    /** Set by sync when a teammate deleted the remote file. */
+    orphaned?: boolean;
+}
+export declare function renderPointer(p: Pointer): string;
+/** ETags compare without the surrounding quotes S3 returns. */
+export declare function normalizeEtag(etag: string | undefined): string;
+/**
+ * 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 declare function parsePointer(text: string): Pointer | null;
+export interface FileDigest {
+    size: number;
+    sha256: string;
+    gitBlob: string;
+}
+/** sha256 and git blob id (sha1 of "blob <size>\0" + bytes) in one pass. */
+export declare function digestFile(file: string): Promise<FileDigest>;
+export interface StoredObject {
+    size: number;
+    /** Hex sha256, from object metadata or the S3 full-object checksum. */
+    sha256?: string;
+}
+export interface BlobStore {
+    readonly vault: "personal";
+    head(key: string): Promise<StoredObject | null>;
+    put(key: string, file: string, digest: FileDigest): Promise<void>;
+    download(key: string, dest: string): Promise<void>;
+}
+export interface OffloadS3Client {
+    send(cmd: PutObjectCommand | HeadObjectCommand | GetObjectCommand): Promise<unknown>;
+}
+/**
+ * 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 declare function s3BlobStore(bucket: string, s3: OffloadS3Client): BlobStore;
+/** Read-only access to vault objects at their sync keys, pinned to an ETag. */
+export interface VaultObjectStore {
+    /** Download `key` to `dest` only if its ETag is `etag`; returns the served ETag. */
+    download(key: string, dest: string, etag: string): Promise<string>;
+}
+export interface VaultObjectS3Client {
+    send(cmd: GetObjectCommand): Promise<unknown>;
+}
+export declare function s3VaultObjectStore(bucket: string, s3: VaultObjectS3Client): VaultObjectStore;
+export interface OffloadDeps {
+    hqRoot: string;
+    now: () => Date;
+    runScript: ScriptRunner;
+    confirm: (message: string) => Promise<boolean>;
+    log: (line: string) => void;
+    /** Open the caller's personal vault store. The only store offload uses. */
+    openPersonal: () => Promise<BlobStore>;
+    /** Write git blob `sha` from the HQ root repo to `dest`. */
+    exportBlob: (sha: string, dest: string) => Promise<void>;
+    /** HQ-root-relative paths of `*.hqcloud` placeholders. */
+    listPlaceholders: () => Promise<string[]>;
+    tmpDir: () => string;
+    /** Whether the installed HQ sync skips `.hq-offload/` (see syncExcludesOffload). */
+    syncExcludesOffload: () => boolean;
+    /** Slugs of companies where the caller is an active member. */
+    activeCompanySlugs?: () => Promise<string[]>;
+    /**
+     * Open a vault for objects recorded by sync. Company vaults are vended
+     * through the caller's membership; runFetch checks membership first.
+     */
+    openVaultObjects?: (target: {
+        vault: "personal";
+    } | {
+        vault: "company";
+        slug: string;
+    }) => Promise<VaultObjectStore>;
+}
+export declare function storageScriptPath(hqRoot: string): string;
+/** Whether the installed core script has a `case` arm for `sub`. */
+export declare function scriptSupports(hqRoot: string, sub: "large" | "strip-large"): boolean;
+export interface LargeBlob {
+    sha: string;
+    bytes: number;
+    paths: string[];
+    in_head: boolean;
+    /** Linked worktrees (paths) whose HEAD still reaches this blob. */
+    held_by: string[];
+}
+/** A linked worktree that keeps old history alive. HQ never changes it. */
+export interface WorktreeHolder {
+    path: string;
+    branch: string | null;
+}
+export interface LargeCurrent {
+    path: string;
+    bytes: number;
+    idle_days: number;
+}
+export interface LargeReport {
+    available: boolean;
+    reason?: string;
+    blobs: LargeBlob[];
+    current: LargeCurrent[];
+    worktree_holders: WorktreeHolder[];
+}
+export declare function getLarge(deps: OffloadDeps, minBytes: number): Promise<LargeReport>;
+/** Eligible history blobs split into ones offload can free and ones a linked worktree keeps. */
+export declare function splitHeld(blobs: LargeBlob[]): {
+    free: LargeBlob[];
+    held: LargeBlob[];
+};
+/** Distinct worktree paths that hold any of `held`, in first-seen order. */
+export declare function heldWorktrees(held: LargeBlob[]): string[];
+/** Plain refusal when every eligible old file is still used by a linked worktree. */
+export declare function worktreeHoldsAllCopy(held: LargeBlob[]): string;
+/**
+ * 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 declare function selectHistoryBlobs(blobs: LargeBlob[], minBytes: number): LargeBlob[];
+export declare function matchesDigest(obj: StoredObject | null, digest: FileDigest): boolean;
+/**
+ * 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 declare function uploadBlob(blob: LargeBlob, store: BlobStore, deps: OffloadDeps): Promise<{
+    digest: FileDigest;
+    uploaded: boolean;
+}>;
+/** File operations for current-file offload, injectable so tests can see the order. */
+export interface PlaceholderFs {
+    /** Create the placeholder (never replacing one) and fsync it and its folder. */
+    writePlaceholder(file: string, text: string): Promise<void>;
+    removeOriginal(file: string): Promise<void>;
+}
+export declare const durablePlaceholderFs: PlaceholderFs;
+/**
+ * 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 declare function offloadCurrentFile(rel: string, store: BlobStore, deps: Pick<OffloadDeps, "hqRoot" | "now">, fsOps?: PlaceholderFs): Promise<{
+    path: string;
+    bytes: number;
+}>;
+export interface OffloadOptions {
+    minBytes: number;
+    idleDays: number;
+    history: boolean;
+    current: boolean;
+    dryRun: boolean;
+    yes: boolean;
+}
+export interface OffloadResult {
+    history: {
+        uploaded: number;
+        bytes: number;
+        freed_bytes: number;
+        available?: boolean;
+        reason?: string;
+        candidates?: number;
+        candidate_bytes?: number;
+        /** Backup kept by strip-large; space it holds is freed after reclaim_after. */
+        backup_ref?: string | null;
+        reclaim_after?: string | null;
+        pending_reclaim_bytes?: number;
+        /** Old versions a linked worktree still uses: left in place, not counted as freed. */
+        held_by_worktrees?: {
+            count: number;
+            bytes: number;
+        };
+        /** Worktrees (paths) that still use old history. */
+        worktree_holders?: string[];
+        /**
+         * Set when a precondition stops the history rewrite (e.g.
+         * remote_tracking_branches). Checked before any upload, so nothing was
+         * uploaded; a dry run sets it when the real run would stop.
+         */
+        refused?: string;
+        message?: string;
+    };
+    current: {
+        offloaded: {
+            path: string;
+            bytes: number;
+        }[];
+        freed_bytes: number;
+        available?: boolean;
+        reason?: string;
+    };
+    errors: string[];
+    dry_run: boolean;
+    /** Expired backups dropped before a real offload; absent otherwise. */
+    reclaim?: ReclaimReport;
+}
+export declare function runOffload(opts: OffloadOptions, deps: OffloadDeps): Promise<OffloadResult | undefined>;
+/**
+ * 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 declare function containedPath(hqRoot: string, rel: string): string;
+/** Restore targets that fetch must never write: git internals and agent hooks. */
+export declare function assertRestorable(rel: string): void;
+/** Resolve a fetch argument (original path or placeholder path) to its placeholder file. */
+export declare function resolvePlaceholder(hqRoot: string, arg: string): string;
+export interface FetchResult {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export interface FetchOptions {
+    /** Restore the caller's own personal-vault copy of a teammate-deleted file. */
+    forceOrphan?: boolean;
+    /** Destination for --force-orphan; must be outside HQ. */
+    out?: string;
+}
+/** Company slug for a company-vault placeholder, checked against its key. */
+export declare function companyForPointer(pointer: Pointer): string;
+export declare function runFetch(arg: string, deps: OffloadDeps, opts?: FetchOptions): Promise<FetchResult>;
+export declare function runFetchGitBlob(sha: string, out: string, deps: OffloadDeps): Promise<FetchResult>;
+export interface CountBytes {
+    count: number;
+    bytes: number;
+}
+export interface OffloadStatus {
+    /** Old versions offload can move and free (not used by another worktree). */
+    history_candidates: CountBytes;
+    /** Old versions linked worktrees still use: offload leaves them. */
+    history_held?: CountBytes & {
+        worktrees: string[];
+    };
+    current_candidates: CountBytes;
+    placeholders: CountBytes;
+    /** Whether `offload --current` can run. The desktop shows the current-files row only when true. */
+    current_available: boolean;
+    current_reason?: string;
+    available?: boolean;
+    reason?: string;
+}
+/** Current-file offload availability, shared by status and its error fallback. */
+export declare function currentAvailability(syncReady: boolean): Pick<OffloadStatus, "current_available" | "current_reason">;
+export declare function getOffloadStatus(deps: OffloadDeps, opts: {
+    minBytes: number;
+    idleDays: number;
+}): Promise<OffloadStatus>;
+export declare function gitExportBlob(hqRoot: string): (sha: string, dest: string) => Promise<void>;
+export declare function gitListPlaceholders(hqRoot: string): () => Promise<string[]>;
+export declare function defaultTmpDir(): string;
+export declare function personalS3Store(input: {
+    bucket: string;
+    region: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken: string;
+    };
+}): BlobStore;
+//# sourceMappingURL=storage-offload.d.ts.map