@indigoai-us/hq-cli 5.345.137 → 5.345.138

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+## [5.345.138] — 2026-10-15
+- `hq storage offload --current` can now free company files larger than the 50 MB sync limit. It uploads each one to its company vault, checks the vault copy against the file's sha256 and size, records it as cloud-only, writes the `.hqcloud` placeholder, and only then removes the local copy. An interrupted upload leaves the file in place and resumes on the next run. The dry run shows `upload+offload` with the byte count and the vault key. A path the `.hqinclude` allowlist excludes is refused with the line to add. `hq storage fetch` checks the vault copy's sha256 before restoring it. The upload path turns on once the bundled hq-cloud includes the new upload exports; until then these files report that HQ sync needs an update.
+
 ## [5.345.137] — 2026-10-15
 - The bundled sync engine now uses hq-cloud 6.18.76. On Windows, the hq-core update and rescue lay down native links after the overlay, turn git symlink stubs from Windows clones into real links, and upload symlinks with the correct target. Sync merges `board.json` by entry id instead of replacing it, merges append-only `.jsonl` conflicts instead of parking them, keeps any `.hqcloud` placeholder on pull, and no longer syncs live-meeting runtime state or server sync manifests.
 

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

@@ -1,38 +1,49 @@
 /**
- * `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 { GetObjectCommand, HeadObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
 import type { ScriptRunner } from "./storage.js";
@@ -47,6 +58,13 @@ export declare const ORPHANED_MESSAGE = "This file was deleted by a teammate. It
 export declare const UPDATE_SYNC = "update HQ sync";
 /** Reason on company files HQ sync has not stored in the company vault yet. */
 export declare 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 declare const SYNC_MAX_FILE_BYTES: number;
+/** Object metadata key holding the sha256 of a company-vault offload upload. */
+export declare const VAULT_SHA256_METADATA_KEY = "hq-sha256";
 /** Top-level HQ-root folder that holds offloaded blobs in the personal vault. */
 export declare const OFFLOAD_TOP_LEVEL = ".hq-offload";
 /**
@@ -120,10 +138,14 @@ export interface OffloadS3Client {
 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 {
-    /** Size and unquoted ETag of `key`, or null when it is not there. */
+    /**
+     * Size and unquoted ETag of `key`, or null when it is not there. `sha256` is
+     * the object's `hq-sha256` metadata, set on company-vault offload uploads.
+     */
     head(key: string): Promise<{
         size: number;
         etag: string;
+        sha256?: string;
     } | null>;
     /** Download `key` to `dest` only if its ETag is `etag`; returns the served ETag. */
     download(key: string, dest: string, etag: string): Promise<string>;
@@ -169,6 +191,55 @@ export interface OffloadDeps {
     syncRecord?: (target: OffloadTarget) => Promise<SyncRecord | null>;
     /** File operations for current-file offload (tests inject to see the order). */
     placeholderFs?: PlaceholderFs;
+    /** HQ sync's per-file limit in bytes. Defaults to SYNC_MAX_FILE_BYTES. */
+    syncMaxFileBytes?: number;
+    /**
+     * Whether HQ sync's ignore rules exclude an HQ-root-relative path, and which
+     * rule does (hq-cloud createIgnoreExplainer). Null or absent: not excluded.
+     */
+    syncExclusion?: (rel: string) => SyncExclusion | null;
+    /**
+     * Open a multipart uploader for a company vault. Called only for a company
+     * the caller is an active member of. Absent: company files over the sync
+     * limit report "update HQ sync".
+     */
+    openCompanyUploader?: (slug: string) => Promise<CompanyUploader>;
+    /**
+     * Record `target` in the sync journal as synced and cloud-only (hq-cloud
+     * recordOffloadedObject), so sync neither re-uploads it nor pulls it back.
+     */
+    recordCloudOnly?: (target: OffloadTarget, object: VerifiedUpload) => Promise<void>;
+    /** Folder for resumable multipart upload state. Defaults to ~/.hq/offload-uploads. */
+    uploadStateDir?: () => string;
+}
+/** Why HQ sync skips a path: the ignore layer that excludes it. */
+export interface SyncExclusion {
+    excluded: boolean;
+    /** "built-in", "defaults", ".hqignore", ".hqsyncignore" or ".hqinclude allowlist". */
+    layer: string | null;
+    /** For the .hqinclude allowlist: the line that would include the path. */
+    includeLine?: string;
+}
+/** A vault object whose size and sha256 were verified after upload. */
+export interface VerifiedUpload {
+    etag: string;
+    size: number;
+    sha256: string;
+}
+/**
+ * Resumable, checksum-verified multipart upload into one company vault
+ * (hq-cloud uploadLargeObjectVerified). `upload` resumes from `stateFile`
+ * when it holds an upload for the same file, and resolves only after the
+ * object's size, part count and sha256 metadata are verified.
+ */
+export interface CompanyUploader {
+    slug: string;
+    bucket: string;
+    upload(input: {
+        key: string;
+        file: string;
+        stateFile: string;
+    }): Promise<VerifiedUpload>;
 }
 /** The vault that owns a working-tree path, and the object key there. */
 export type OffloadTarget = {
@@ -273,7 +344,15 @@ export interface CurrentFilePlan {
     company?: string;
     /** HQ sync already stored this exact version in the owning vault. */
     synced: boolean;
-    action: "point-at-vault" | "upload" | "skip";
+    /**
+     * upload+offload: a company file over the sync limit, uploaded to the
+     * company vault at `vault_key`, then replaced by a placeholder.
+     */
+    action: "point-at-vault" | "upload" | "upload+offload" | "skip";
+    /** Company vault key for upload+offload. */
+    vault_key?: string;
+    /** The HQ sync ignore layer that excludes this path. */
+    excluded_by?: string;
     reason?: string;
 }
 export interface CurrentOffloaded {
@@ -281,7 +360,7 @@ export interface CurrentOffloaded {
     bytes: number;
     vault: "personal" | "company";
     company?: string;
-    action: "point-at-vault" | "upload";
+    action: "point-at-vault" | "upload" | "upload+offload";
 }
 export interface OffloadOptions {
     minBytes: number;

package/dist/commands/storage-offload.js

@@ -1,38 +1,49 @@
 /**
- * `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";
@@ -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. */
@@ -251,7 +269,14 @@ export function s3VaultObjectStore(bucket, s3) {
         async head(key) {
             try {
                 const res = (await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key })));
-                return { size: res.ContentLength ?? -1, etag: normalizeEtag(res.ETag) };
+                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))
@@ -516,6 +541,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 +756,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 +835,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,22 +847,32 @@ 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);
@@ -1057,6 +1236,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 +1244,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);