@indigoai-us/hq-cli 5.345.137 → 5.345.139

package/dist/commands/storage-offload.js

@@ -1,45 +1,56 @@
 /**
- * `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.
+ * `hq storage offload` / `hq storage fetch` — move big files out of the HQ
+ * folder into HQ cloud storage and leave small linked placeholders behind.
+ * Shared contract: owner-approved offload design, 2026-10-09; company upload
+ * for files over the sync limit approved 2026-10-15.
  *
  * 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.
+ *     uploads each blob to the caller's PERSONAL vault, 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 (`--current [paths...]`, idle big files in the working
- *     tree). Each file goes to the vault that owns its path. A file under
- *     `companies/<slug>/` is never uploaded: when HQ sync already stored this
- *     exact version in that company's vault (journal hash + size, and the vault
- *     object still has the journal's ETag), the file is replaced by a
- *     placeholder pointing at that object. Otherwise it is skipped with "run
- *     hq sync first", so sync stays the only writer of company vault keys. Any
- *     other file points at its personal-vault sync object the same way, or is
- *     uploaded to the personal vault's `.hq-offload/blobs/`. Current-file
- *     offload runs only when the installed HQ sync holds every `.hqcloud`
- *     sibling (hq-cloud CLOUD_PLACEHOLDER_HOLDS_ANY_SIBLING) and skips
- *     `.hq-offload/`; otherwise it reports "update HQ sync".
+ *     tree). Each file goes to the vault that owns its path:
+ *       - A file in a company folder belongs to that company's vault, and only
+ *         an active member can offload it. When HQ sync already stored this
+ *         exact version (journal hash + size, and the vault object still has
+ *         the journal's ETag), the file is replaced by a placeholder pointing
+ *         at that object. A file over the sync limit (SYNC_MAX_FILE_BYTES),
+ *         which sync never uploads, is uploaded to the company vault at its
+ *         sync key by a resumable, checksum-verified multipart upload
+ *         (`upload+offload`). Once the vault copy is verified the file is
+ *         recorded in the sync journal as synced and cloud-only, then the
+ *         placeholder is written, then the local file is removed. A path the
+ *         sync ignore rules exclude is refused and the excluding rule is named
+ *         (for `.hqinclude`, with the exact line to add). Other unsynced
+ *         company files are skipped with "run hq sync first".
+ *       - Any other file points at its personal-vault sync object the same
+ *         way, or is uploaded to the personal vault's `.hq-offload/blobs/`.
+ *     Current-file offload runs only when the installed HQ sync holds every
+ *     `.hqcloud` sibling (hq-cloud CLOUD_PLACEHOLDER_HOLDS_ANY_SIBLING) and
+ *     skips `.hq-offload/`; otherwise it reports "update HQ sync".
  *
- * 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.
+ * Fetch also reads placeholders that HQ sync wrote on a teammate's machine
+ * (`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, ETag and, when the object carries it, its `hq-sha256`
+ * metadata. 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: uploads only ever go to the caller's personal vault, and
- * the personal store refuses a company vault bucket. A company vault is opened
- * read-only (HEAD and ETag-pinned GET), and only for a company the caller is
- * an active member of.
+ * Tenant isolation: history and personal uploads only ever go to the caller's
+ * personal vault, and the personal store refuses a company vault bucket. A
+ * company vault is opened only for a company the caller is an active member
+ * of, and only for a file in that company's folder; the company uploader must
+ * name that company and refuses a personal bucket.
  */
 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 { 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";
@@ -53,6 +64,13 @@ const UPDATE_HQ = "update HQ";
 export const UPDATE_SYNC = "update HQ sync";
 /** Reason on company files HQ sync has not stored in the company vault yet. */
 export const RUN_SYNC_FIRST = "run hq sync first";
+/**
+ * HQ sync's per-file limit (hq-cloud SYNC_MAX_FILE_BYTES; sync skips files
+ * strictly larger). storage.ts passes hq-cloud's value when it exports one.
+ */
+export const SYNC_MAX_FILE_BYTES = 50 * 1024 * 1024;
+/** Object metadata key holding the sha256 of a company-vault offload upload. */
+export const VAULT_SHA256_METADATA_KEY = "hq-sha256";
 const DAY_MS = 86_400_000;
 const PERSONAL_BUCKET_PREFIX = "hq-vault-prs-";
 /** Top-level HQ-root folder that holds offloaded blobs in the personal vault. */
@@ -193,96 +211,268 @@ function isNotFound(err) {
     const e = err;
     return e?.name === "NotFound" || e?.name === "NoSuchKey" || e?.$metadata?.httpStatusCode === 404;
 }
+// ── Vault request errors and credential refresh ─────────────────────────────
+/** Error codes S3 and STS return when the request's credentials are refused. */
+const CREDENTIAL_ERROR_HINTS = {
+    ExpiredToken: "credentials expired",
+    ExpiredTokenException: "credentials expired",
+    TokenRefreshRequired: "credentials expired",
+    RequestExpired: "credentials expired",
+    InvalidToken: "credentials rejected",
+    InvalidAccessKeyId: "credentials rejected",
+    InvalidSecurityToken: "credentials rejected",
+    InvalidClientTokenId: "credentials rejected",
+    AccessDenied: "access denied",
+};
+/** Placeholder names the SDK uses when the response carried no error code. */
+const NO_CODE = new Set(["", "Unknown", "UnknownError", "Error"]);
+function awsErrorCode(err) {
+    const candidates = [err.Code, err.code, err.name, err.$response?.headers?.["x-amz-error-code"]];
+    return candidates.find((c) => typeof c === "string" && !NO_CODE.has(c));
+}
+function isAwsError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    return typeof e.$metadata === "object" || typeof e.$fault === "string" || e.name === "Unknown";
+}
+/**
+ * True when S3 refused the request's credentials: an expired, invalid or
+ * denied token, or a 403 with no error body (what S3 sends for HEAD).
+ */
+export function isCredentialRejection(err) {
+    if (!isAwsError(err))
+        return false;
+    const status = err.$metadata?.httpStatusCode;
+    const code = awsErrorCode(err);
+    if (code)
+        return code in CREDENTIAL_ERROR_HINTS && (status === undefined || status === 400 || status === 403);
+    return status === 403;
+}
+/** A failed vault request, described with its HTTP status, error code and vault. */
+export class VaultRequestError extends Error {
+    status;
+    code;
+    constructor(message, opts) {
+        super(message, { cause: opts.cause });
+        this.name = "VaultRequestError";
+        this.status = opts.status;
+        this.code = opts.code;
+    }
+}
+/**
+ * Describes an AWS error from `op` against `where` so the user sees the HTTP
+ * status, the error code and the vault, never the SDK's bare "UnknownError".
+ * Errors that did not come from AWS pass through unchanged.
+ */
+export function describeVaultError(err, op, where, retried = false) {
+    if (err instanceof VaultRequestError || !isAwsError(err))
+        return err;
+    const status = err.$metadata?.httpStatusCode;
+    const code = awsErrorCode(err);
+    let what;
+    if (code) {
+        const hint = CREDENTIAL_ERROR_HINTS[code];
+        what = hint ? `${code} (${hint})` : code;
+    }
+    else if (status === 403) {
+        what = "Forbidden (no error body: credentials expired or access denied)";
+    }
+    else {
+        what = "error with no error code";
+    }
+    let message = `${op} failed in ${where}: ${status ? `HTTP ${status} ` : ""}${what}`;
+    if (retried)
+        message += ", after re-vending credentials once";
+    const detail = err.message?.trim();
+    if (detail && !NO_CODE.has(detail) && detail !== code)
+        message += `: ${detail}`;
+    return new VaultRequestError(message, { status, code, cause: err });
+}
+/** Turns any per-file failure into one line for the run's error list. */
+export function failureMessage(err) {
+    const described = describeVaultError(err, "Request", "the vault");
+    return described instanceof Error ? described.message : String(described);
+}
+/**
+ * Runs vault requests on `initial` and, when S3 refuses the credentials,
+ * re-vends once and retries the request once on the new client. Requests
+ * refused on the same client share one re-vend. A request refused again
+ * after the re-vend fails with a described error; it is never retried twice.
+ */
+export function credentialRetry(initial, where, revend) {
+    let client = initial;
+    let generation = 0;
+    let pending;
+    return async function call(op, fn) {
+        const used = generation;
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            if (!revend || !isCredentialRejection(err))
+                throw describeVaultError(err, op, where);
+            if (generation === used) {
+                pending ??= revend()
+                    .then((fresh) => {
+                    client = fresh;
+                    generation += 1;
+                })
+                    .finally(() => {
+                    pending = undefined;
+                });
+                try {
+                    await pending;
+                }
+                catch (vendErr) {
+                    const refused = describeVaultError(err, op, where);
+                    throw new Error(`${refused.message}; re-vending credentials for ${where} failed: ${vendErr?.message ?? String(vendErr)}`, { cause: vendErr });
+                }
+            }
+            try {
+                return await fn(client);
+            }
+            catch (again) {
+                throw describeVaultError(again, op, where, true);
+            }
+        }
+    };
+}
+const CLIENT_METHOD_OPS = {
+    create: "CreateMultipartUpload",
+    uploadPart: "UploadPart",
+    listParts: "ListParts",
+    complete: "CompleteMultipartUpload",
+    abort: "AbortMultipartUpload",
+    head: "HeadObject",
+};
+/**
+ * Wraps every method of `initial` (a multipart client) so each call gets
+ * {@link credentialRetry}: one re-vend and one retry when S3 refuses the
+ * credentials, and a described error otherwise.
+ */
+export function credentialRetryingClient(initial, where, revend) {
+    const call = credentialRetry(initial, where, revend);
+    const wrapped = {};
+    for (const name of Object.keys(initial)) {
+        if (typeof initial[name] !== "function")
+            continue;
+        wrapped[name] = (...args) => call(CLIENT_METHOD_OPS[name] ?? name, (c) => c[name].apply(c, args));
+    }
+    return { ...initial, ...wrapped };
+}
+function pipeToNewFile(body, dest) {
+    return 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);
+    });
+}
 /**
  * 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) {
+export function s3BlobStore(bucket, s3, opts = {}) {
     if (!bucket || !bucket.startsWith(PERSONAL_BUCKET_PREFIX)) {
         throw new Error(`Refusing to offload into '${bucket}': offload only writes to your personal vault.`);
     }
+    const call = credentialRetry(s3, opts.where ?? `vault '${bucket}'`, opts.revend);
     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;
-            }
+        head(key) {
+            return call("HEAD", async (client) => {
+                try {
+                    const res = (await client.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 },
-            }));
+            await call("PUT", async (client) => {
+                // A fresh stream per attempt: a refused attempt may have read from the last one.
+                const body = fs.createReadStream(file);
+                try {
+                    await client.send(new PutObjectCommand({
+                        Bucket: bucket,
+                        Key: key,
+                        Body: body,
+                        ContentLength: digest.size,
+                        ChecksumSHA256: Buffer.from(digest.sha256, "hex").toString("base64"),
+                        StorageClass: "STANDARD",
+                        Metadata: { sha256: digest.sha256, "git-blob": digest.gitBlob },
+                    }));
+                }
+                finally {
+                    body.destroy();
+                }
+            });
         },
         async download(key, dest) {
-            const res = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
+            // Only the request is retried: the destination is created by the pipe below.
+            const res = await call("GET", async (client) => (await client.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);
-            });
+            await pipeToNewFile(body, dest);
         },
     };
 }
-export function s3VaultObjectStore(bucket, s3) {
+export function s3VaultObjectStore(bucket, s3, opts = {}) {
+    const call = credentialRetry(s3, opts.where ?? `vault '${bucket}'`, opts.revend);
     return {
-        async head(key) {
-            try {
-                const res = (await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key })));
-                return { size: res.ContentLength ?? -1, etag: normalizeEtag(res.ETag) };
-            }
-            catch (err) {
-                if (isNotFound(err))
-                    return null;
-                throw err;
-            }
+        head(key) {
+            return call("HEAD", async (client) => {
+                try {
+                    const res = (await client.send(new HeadObjectCommand({ Bucket: bucket, Key: key })));
+                    const head = {
+                        size: res.ContentLength ?? -1,
+                        etag: normalizeEtag(res.ETag),
+                    };
+                    const sha = res.Metadata?.[VAULT_SHA256_METADATA_KEY];
+                    if (sha && HEX64.test(sha))
+                        head.sha256 = sha;
+                    return head;
+                }
+                catch (err) {
+                    if (isNotFound(err))
+                        return null;
+                    throw err;
+                }
+            });
         },
         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.");
+            // Only the request is retried: the destination is created by the pipe below.
+            const res = await call("GET", async (client) => {
+                try {
+                    return (await client.send(new GetObjectCommand({ Bucket: bucket, Key: key, IfMatch: `"${normalizeEtag(etag)}"` })));
                 }
-                if (isNotFound(err))
-                    throw new Error(`This file is no longer in the cloud (${key}).`);
-                throw err;
-            }
+                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);
-            });
+            await pipeToNewFile(body, dest);
             return normalizeEtag(res.ETag);
         },
     };
@@ -516,6 +706,122 @@ async function pointCurrentFileAtVault(file, vault, deps, fsOps) {
     }
     await fsOps.removeOriginal(abs);
 }
+/** Resumable upload state for one company vault key. */
+function uploadStatePath(deps, target) {
+    const dir = deps.uploadStateDir ? deps.uploadStateDir() : path.join(os.homedir(), ".hq", "offload-uploads");
+    const id = crypto.createHash("sha256").update(`${target.slug}\0${target.key}`).digest("hex");
+    return path.join(dir, `${id}.json`);
+}
+/**
+ * ETag of a verified upload this machine made to the key but did not record
+ * (the file changed before it was recorded), so the next run may replace it.
+ */
+function readOwnUpload(stateFile) {
+    try {
+        const etag = JSON.parse(fs.readFileSync(`${stateFile}.uploaded`, "utf8")).etag;
+        return typeof etag === "string" ? etag : undefined;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw new Error(`Cannot read offload upload state ${stateFile}.uploaded: ${err.message}`);
+    }
+}
+/**
+ * What the company vault key allows for a local file over the sync limit:
+ * upload when the key is empty, still holds the version this machine last
+ * recorded, or holds this machine's own unrecorded upload; adopt when it
+ * already holds these exact bytes; otherwise a different copy is there.
+ */
+function companyKeyState(head, digest, record, ownEtag) {
+    if (!head)
+        return "upload";
+    if (head.sha256 === digest.sha256 && head.size === digest.size)
+        return "adopt";
+    if (record?.remoteEtag && head.etag === normalizeEtag(record.remoteEtag))
+        return "upload";
+    if (ownEtag && head.etag === normalizeEtag(ownEtag))
+        return "upload";
+    return "conflict";
+}
+const DIFFERENT_COPY = "A different copy is already in the company vault. Run hq sync to get it, then try again.";
+/**
+ * Upload one company file over the sync limit to its company vault key, then
+ * offload it. Order: verified upload, journal record (synced, cloud-only),
+ * fsynced `x.hqcloud`, and only then remove `x`. An interrupted upload leaves
+ * `x` untouched, records nothing, and keeps the state file so the next run
+ * resumes.
+ */
+async function uploadCompanyFile(file, uploader, vault, deps, fsOps) {
+    const { plan, target, stat: before, digest, record } = file;
+    if (target.vault !== "company" || !before || !digest)
+        throw new Error(`'${plan.path}' is not a company file.`);
+    if (uploader.slug !== target.slug || uploader.bucket.startsWith(PERSONAL_BUCKET_PREFIX)) {
+        throw new Error(`The upload target '${uploader.bucket}' is not the company vault for '${target.slug}'. Nothing was uploaded.`);
+    }
+    if (!deps.recordCloudOnly)
+        throw new Error(`This HQ build cannot record cloud-only files; ${UPDATE_SYNC}.`);
+    const abs = containedPath(deps.hqRoot, plan.path);
+    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(`'${plan.path}' changed while uploading. Nothing was replaced.`);
+    if (!(await unchanged()))
+        throw changed;
+    const stateFile = uploadStatePath(deps, target);
+    const head = await vault.head(target.key);
+    const state = companyKeyState(head, digest, record, readOwnUpload(stateFile));
+    if (state === "conflict")
+        throw new Error(`${DIFFERENT_COPY} Nothing was uploaded.`);
+    let object;
+    if (state === "adopt" && head) {
+        object = { etag: head.etag, size: head.size, sha256: digest.sha256 };
+    }
+    else {
+        object = await uploader.upload({ key: target.key, file: abs, stateFile });
+        if (object.sha256 !== digest.sha256 || object.size !== digest.size) {
+            throw new Error(`The uploaded copy of '${plan.path}' does not match the local file. Nothing was replaced.`);
+        }
+        if (!(await unchanged())) {
+            await fs.promises.mkdir(path.dirname(stateFile), { recursive: true });
+            await fs.promises.writeFile(`${stateFile}.uploaded`, JSON.stringify({ etag: object.etag }));
+            throw changed;
+        }
+    }
+    await deps.recordCloudOnly(target, object);
+    await fs.promises.rm(`${stateFile}.uploaded`, { force: true });
+    const placeholder = `${abs}${PLACEHOLDER_SUFFIX}`;
+    await fsOps.writePlaceholder(placeholder, renderPointer({
+        path: plan.path,
+        size: digest.size,
+        sha256: digest.sha256,
+        vault: "company",
+        key: target.key,
+        offloadedAt: deps.now().toISOString().replace(/\.\d{3}Z$/, "Z"),
+        remoteEtag: object.etag,
+    }));
+    if (!(await unchanged())) {
+        await fs.promises.rm(placeholder, { force: true });
+        throw changed;
+    }
+    await fsOps.removeOriginal(abs);
+}
+/** Plain name of an HQ sync ignore layer, for skip reasons. */
+function exclusionReason(ex) {
+    if (ex.layer === ".hqinclude allowlist") {
+        const add = ex.includeLine ? ` To sync and offload it, add this line to .hqinclude: ${ex.includeLine}` : "";
+        return `HQ sync skips this path because the .hqinclude allowlist does not list it.${add}`;
+    }
+    const by = ex.layer === "built-in"
+        ? "HQ sync's built-in exclusions"
+        : ex.layer === "defaults"
+            ? "HQ sync's default exclusions"
+            : ex.layer
+                ? `a rule in ${ex.layer}`
+                : "an HQ sync ignore rule";
+    return `HQ sync skips this path because of ${by}, so HQ will not offload it.`;
+}
 /** Whether a working-tree path is never a current-offload candidate. */
 function skippedByName(rel) {
     const parts = rel.split("/");
@@ -615,10 +921,34 @@ async function planCurrentFiles(rels, opts, deps, openVault) {
                 plan.synced = head !== null && head.etag === normalizeEtag(record.remoteEtag) && head.size === st.size;
             }
         }
-        if (plan.synced)
+        if (plan.synced) {
             plan.action = "point-at-vault";
-        else if (target.vault === "company")
-            plan.reason = RUN_SYNC_FIRST;
+        }
+        else if (target.vault === "company") {
+            const ex = deps.syncExclusion?.(rel);
+            if (ex?.excluded) {
+                plan.excluded_by = ex.layer ?? "ignore rules";
+                plan.reason = exclusionReason(ex);
+            }
+            else if (st.size <= (deps.syncMaxFileBytes ?? SYNC_MAX_FILE_BYTES)) {
+                plan.reason = RUN_SYNC_FIRST;
+            }
+            else if (!deps.openCompanyUploader || !deps.recordCloudOnly || !deps.openVaultObjects) {
+                plan.reason = UPDATE_SYNC;
+            }
+            else {
+                digest ??= await digestFile(abs);
+                const head = await (await openVault(target)).head(target.key);
+                const state = companyKeyState(head, digest, record, readOwnUpload(uploadStatePath(deps, target)));
+                if (state === "conflict") {
+                    plan.reason = DIFFERENT_COPY;
+                }
+                else {
+                    plan.action = "upload+offload";
+                    plan.vault_key = target.key;
+                }
+            }
+        }
         planned.push({ plan, target, stat: st, digest, record: record ?? undefined });
     }
     return planned;
@@ -670,7 +1000,11 @@ async function runCurrent(opts, deps, result) {
     if (opts.dryRun || todo.length === 0)
         return "ok";
     if (!opts.yes) {
-        const ok = await deps.confirm(`Replace ${todo.length} current file(s) with links to their HQ cloud copies and remove the local copies?`);
+        const uploads = todo.filter((p) => p.plan.action === "upload+offload");
+        const uploadNote = uploads.length > 0
+            ? ` ${uploads.length} of them (${uploads.reduce((n, p) => n + p.plan.bytes, 0)} bytes) are uploaded to their company vault first.`
+            : "";
+        const ok = await deps.confirm(`Replace ${todo.length} current file(s) with links to their HQ cloud copies and remove the local copies?${uploadNote}`);
         if (!ok) {
             deps.log("Aborted - nothing was uploaded or changed.");
             return "aborted";
@@ -678,29 +1012,39 @@ async function runCurrent(opts, deps, result) {
     }
     const fsOps = deps.placeholderFs ?? durablePlaceholderFs;
     let personal;
+    const uploaders = new Map();
     for (const file of todo) {
-        const { plan } = file;
+        const { plan, target } = file;
         try {
+            let action;
             if (plan.action === "point-at-vault") {
-                await pointCurrentFileAtVault(file, await openVault(file.target), deps, fsOps);
+                await pointCurrentFileAtVault(file, await openVault(target), deps, fsOps);
+                action = "point-at-vault";
+            }
+            else if (plan.action === "upload+offload") {
+                if (target.vault !== "company" || !deps.openCompanyUploader)
+                    throw new Error(UPDATE_SYNC);
+                let uploader = uploaders.get(target.slug);
+                if (!uploader) {
+                    uploader = deps.openCompanyUploader(target.slug);
+                    uploaders.set(target.slug, uploader);
+                }
+                await uploadCompanyFile(file, await uploader, await openVault(target), deps, fsOps);
+                action = "upload+offload";
             }
             else {
                 personal ??= await deps.openPersonal();
                 await offloadCurrentFile(plan.path, personal, deps, fsOps);
+                action = "upload";
             }
-            const done = {
-                path: plan.path,
-                bytes: plan.bytes,
-                vault: plan.vault,
-                action: plan.action === "point-at-vault" ? "point-at-vault" : "upload",
-            };
+            const done = { path: plan.path, bytes: plan.bytes, vault: plan.vault, action };
             if (plan.company)
                 done.company = plan.company;
             current.offloaded.push(done);
             current.freed_bytes += plan.bytes;
         }
         catch (err) {
-            result.errors.push(`${plan.path}: ${err.message}`);
+            result.errors.push(`${plan.path}: ${failureMessage(err)}`);
         }
     }
     return "ok";
@@ -844,7 +1188,7 @@ export async function runOffload(opts, deps) {
             });
         }
         catch (err) {
-            result.errors.push(`${blob.paths[0] ?? blob.sha}: ${err.message}`);
+            result.errors.push(`${blob.paths[0] ?? blob.sha}: ${failureMessage(err)}`);
         }
     }
     if (manifest.length === 0)
@@ -1057,6 +1401,7 @@ async function fetchVaultObject(pointer, target, deps) {
     if (!deps.openVaultObjects)
         throw new Error("This HQ build cannot fetch files recorded by HQ sync.");
     let store;
+    let owner;
     if (pointer.vault === "company") {
         const slug = companyForPointer(pointer);
         const active = deps.activeCompanySlugs ? await deps.activeCompanySlugs() : [];
@@ -1064,19 +1409,35 @@ async function fetchVaultObject(pointer, target, deps) {
             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 });
+        owner = { vault: "company", slug, key: pointer.key };
     }
     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" });
+        owner = { vault: "personal", key: pointer.key };
     }
     const etag = pointer.remoteEtag;
-    return downloadVerified((partial) => store.download(pointer.key, partial, etag), pointer.key, target, {
-        sha256: pointer.sha256,
+    // A teammate's placeholder has no sha256; an offload upload carries it as
+    // object metadata, so check against that when the pinned object has it.
+    let sha256 = pointer.sha256;
+    if (sha256 == null) {
+        const head = await store.head(pointer.key);
+        if (head?.sha256 && head.etag === normalizeEtag(etag))
+            sha256 = head.sha256;
+    }
+    const digest = await downloadVerified((partial) => store.download(pointer.key, partial, etag), pointer.key, target, {
+        sha256,
         size: pointer.size,
         etag,
     });
+    // Sync never transfers a file over its limit, so record the restored file
+    // as the vault's version; otherwise sync would treat it as an unknown local file.
+    if (digest.size > (deps.syncMaxFileBytes ?? SYNC_MAX_FILE_BYTES) && deps.recordCloudOnly) {
+        await deps.recordCloudOnly(owner, { etag: normalizeEtag(etag), size: digest.size, sha256: digest.sha256 });
+    }
+    return digest;
 }
 export async function runFetchGitBlob(sha, out, deps) {
     return fetchGitBlob(sha, out, deps);
@@ -1197,7 +1558,4 @@ export function gitListPlaceholders(hqRoot) {
 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