@indigoai-us/hq-cli 5.345.134 → 5.345.136

package/dist/commands/mesh.js

@@ -174,6 +174,42 @@ async function requireAssignableSelf(token, verb) {
     }
     return resolved;
 }
+/** 400 PROJECT_VIEW_INVALID "Unknown story ..." from a story PATCH. */
+export function isUnknownBoardStory(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return (httpStatus(error) === 400 &&
+        (candidate.code === "PROJECT_VIEW_INVALID" ||
+            (typeof candidate.message === "string" && candidate.message.includes("PROJECT_VIEW_INVALID"))) &&
+        typeof candidate.message === "string" &&
+        candidate.message.includes("Unknown story"));
+}
+/** The local PRD for this project when it lists `storyId`; null otherwise. */
+export function localPrdWithStory(company, projectId, storyId, hqRoot = process.env.HQ_ROOT?.trim() || findHqRoot() || undefined) {
+    const prdPath = findLocalPrd(hqRoot, company.companySlug, projectId);
+    if (!prdPath)
+        return null;
+    let source;
+    try {
+        source = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath, { requireUserStories: true });
+    }
+    catch {
+        return null;
+    }
+    return source.stories.some((story) => story.id === storyId) ? { prdPath, source } : null;
+}
+function unknownStoryHint(error, company, projectId, storyId, prdPath) {
+    const base = error instanceof Error ? error.message : String(error);
+    const command = `hq mesh project ensure ${projectId} --company ${company.companySlug ?? company.companyUid} --stories-file ${prdPath ?? "<prd.json>"}`;
+    const hint = prdPath
+        ? `${storyId} is in ${prdPath} but not on the Board. Register it with: ${command}`
+        : `${storyId} is not on the ${projectId} Board. Add it to the project PRD, then run: ${command}`;
+    return Object.assign(new Error(`${base}\n${hint}`), {
+        status: httpStatus(error),
+        code: error?.code,
+    });
+}
 async function runStory(opts) {
     const storyId = opts.story?.trim();
     const status = opts.status?.trim();
@@ -203,14 +239,46 @@ async function runStory(opts) {
         }
         assigneeUid = assignee;
     }
+    const patch = {
+        ...(status ? { status } : {}),
+        ...(assigneeUid ? { assigneeUid } : {}),
+        ...(clearAssignee ? { clearAssignee: true } : {}),
+        ...(opts.force ? { force: true } : {}),
+    };
     let patched;
+    let registeredFrom;
     try {
-        patched = await patchStory(token, company.companyUid, projectId, storyId, {
-            ...(status ? { status } : {}),
-            ...(assigneeUid ? { assigneeUid } : {}),
-            ...(clearAssignee ? { clearAssignee: true } : {}),
-            ...(opts.force ? { force: true } : {}),
-        });
+        try {
+            patched = await patchStory(token, company.companyUid, projectId, storyId, patch);
+        }
+        catch (err) {
+            if (!isUnknownBoardStory(err))
+                throw err;
+            // The story is in the local PRD but not on the Board yet: register the
+            // PRD (the same merge `hq mesh project ensure` does), then retry once.
+            const recovery = localPrdWithStory(company, projectId, storyId);
+            if (!recovery)
+                throw unknownStoryHint(err, company, projectId, storyId);
+            if (opts.ensure === false) {
+                throw unknownStoryHint(err, company, projectId, storyId, recovery.prdPath);
+            }
+            await ensureProjectFromSource({
+                token,
+                company,
+                projectId,
+                source: recovery.source,
+                current: await getProjectView(token, company.companyUid, projectId).catch((viewErr) => {
+                    if (httpStatus(viewErr) === 404)
+                        return undefined;
+                    throw viewErr;
+                }),
+            });
+            registeredFrom = recovery.prdPath;
+            if (!opts.json) {
+                console.error(`Work mesh: ${storyId} was not on the ${projectId} Board; registered the project from ${recovery.prdPath}.`);
+            }
+            patched = await patchStory(token, company.companyUid, projectId, storyId, patch);
+        }
     }
     catch (err) {
         const conflict = storyConflictFromError(err);
@@ -219,7 +287,14 @@ async function runStory(opts) {
         throw err;
     }
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, action: "story", company, ...patched, storyId }, null, 2));
+        console.log(JSON.stringify({
+            ok: true,
+            action: "story",
+            company,
+            ...patched,
+            storyId,
+            ...(registeredFrom ? { registeredFrom } : {}),
+        }, null, 2));
         return;
     }
     const assignment = assignee === "none"
@@ -590,67 +665,13 @@ async function runProjectMemberAdd(projectId, personUid, opts) {
         ? `Work mesh: added ${personUid} to project ${projectId}`
         : `Work mesh: ${personUid} is already a member of project ${projectId}`);
 }
-async function runProjectEnsure(projectId, opts) {
-    if (!opts.storiesFile?.trim())
-        fail("`--stories-file <prd.json>` is required.");
-    let source;
-    try {
-        source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { requireUserStories: true });
-    }
-    catch (err) {
-        if (!(err instanceof RejectedProjectStoryStatesError) || !opts.json)
-            throw err;
-        failProjectStoryStates(err.rejected, true);
-        return;
-    }
-    const { token, company } = await withCompany(opts);
-    let current;
-    try {
-        current = await getProjectView(token, company.companyUid, projectId);
-    }
-    catch (err) {
-        if (httpStatus(err) !== 404)
-            throw err;
-    }
-    if (opts.dryRun) {
-        if (current && (current.companyUid !== company.companyUid || current.projectId !== projectId)) {
-            fail("Work mesh project ensure dry-run: Board company or project id did not match the request.");
-        }
-        const stories = current ? mergeProjectStories(current.stories, source.stories) : source.stories;
-        const sourceStatuses = source.stories.map((story) => ({
-            id: story.id,
-            title: story.title,
-            status: boardStoryStatus(story),
-        }));
-        const boardStatuses = stories.map((story) => ({
-            id: story.id,
-            title: story.title,
-            status: boardStoryStatus(story),
-        }));
-        if (opts.json) {
-            console.log(JSON.stringify({
-                ok: source.rejectedStories.length === 0,
-                action: "project.ensure.dry-run",
-                projectId,
-                companyUid: company.companyUid,
-                sourceStatuses,
-                stories: boardStatuses,
-                ...(source.rejectedStories.length ? { errors: projectStateErrors(source.rejectedStories) } : {}),
-            }, null, 2));
-        }
-        else {
-            console.log(`Work mesh: project ${projectId} dry run (${sourceStatuses.length} source stories)`);
-            console.log("Source statuses:");
-            for (const story of sourceStatuses)
-                console.log(`${story.id}\t${story.status}`);
-            console.log("Merged Board statuses:");
-            for (const story of boardStatuses)
-                console.log(`${story.id}\t${story.status}`);
-        }
-        if (source.rejectedStories.length)
-            process.exitCode = 1;
-        return;
-    }
+/**
+ * Create or merge the project Board view from a parsed PRD, register the
+ * project, and verify every PRD story and repo is on the Board. Shared by
+ * `hq mesh project ensure` and the `hq mesh story` unknown-story recovery.
+ */
+async function ensureProjectFromSource(input) {
+    const { token, company, projectId, source, current } = input;
     // Genesis thread, then the view, then register. Register returns 403
     // PROJECT_NOT_IN_COMPANY until both exist. A missing view uses that chain
     // from ensureProjectBoard; an existing view is merged, then registered.
@@ -726,12 +747,78 @@ async function runProjectEnsure(projectId, opts) {
     if (verified.version === undefined) {
         fail("Work mesh project ensure: verified view has no version.");
     }
-    const payload = {
+    return {
         projectId: verified.projectId,
         threadId: registration.threadId,
         channelId: registration.channelId,
         version: verified.version,
         stories: verified.stories,
+    };
+}
+async function runProjectEnsure(projectId, opts) {
+    if (!opts.storiesFile?.trim())
+        fail("`--stories-file <prd.json>` is required.");
+    let source;
+    try {
+        source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { requireUserStories: true });
+    }
+    catch (err) {
+        if (!(err instanceof RejectedProjectStoryStatesError) || !opts.json)
+            throw err;
+        failProjectStoryStates(err.rejected, true);
+        return;
+    }
+    const { token, company } = await withCompany(opts);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) !== 404)
+            throw err;
+    }
+    if (opts.dryRun) {
+        if (current && (current.companyUid !== company.companyUid || current.projectId !== projectId)) {
+            fail("Work mesh project ensure dry-run: Board company or project id did not match the request.");
+        }
+        const stories = current ? mergeProjectStories(current.stories, source.stories) : source.stories;
+        const sourceStatuses = source.stories.map((story) => ({
+            id: story.id,
+            title: story.title,
+            status: boardStoryStatus(story),
+        }));
+        const boardStatuses = stories.map((story) => ({
+            id: story.id,
+            title: story.title,
+            status: boardStoryStatus(story),
+        }));
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: source.rejectedStories.length === 0,
+                action: "project.ensure.dry-run",
+                projectId,
+                companyUid: company.companyUid,
+                sourceStatuses,
+                stories: boardStatuses,
+                ...(source.rejectedStories.length ? { errors: projectStateErrors(source.rejectedStories) } : {}),
+            }, null, 2));
+        }
+        else {
+            console.log(`Work mesh: project ${projectId} dry run (${sourceStatuses.length} source stories)`);
+            console.log("Source statuses:");
+            for (const story of sourceStatuses)
+                console.log(`${story.id}\t${story.status}`);
+            console.log("Merged Board statuses:");
+            for (const story of boardStatuses)
+                console.log(`${story.id}\t${story.status}`);
+        }
+        if (source.rejectedStories.length)
+            process.exitCode = 1;
+        return;
+    }
+    const ensured = await ensureProjectFromSource({ token, company, projectId, source, current });
+    const payload = {
+        ...ensured,
         ...(source.rejectedStories.length ? { ok: false, errors: projectStateErrors(source.rejectedStories) } : {}),
     };
     noteCallingSessionBound(payload.projectId, company);
@@ -2520,7 +2607,8 @@ export function registerMeshCommand(program, deps = {}) {
         .requiredOption("--story <id>", "Story id, e.g. US-001")
         .option("--status <status>", "queued|in_progress|review|done")
         .option("--assignee <uid|me|none>", "Assign a person or agent uid, yourself, or clear")
-        .option("--force", "Override another holder's assignment")).action((opts) => wrap(() => runStory(opts))());
+        .option("--force", "Override another holder's assignment")
+        .option("--no-ensure", "Do not register the project from its local prd.json when the story is not on the Board")).action((opts) => wrap(() => runStory(opts))());
     addSharedFlags(mesh
         .command("claim")
         .description("Assign a story to yourself and move it to in_progress")

package/dist/commands/reindex.js

@@ -33,6 +33,7 @@ import { reindex, rescue } from '@indigoai-us/hq-cloud';
 import { trustHqRuntimeHooks } from '../utils/hook-trust.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { guardLargeFiles } from '../utils/large-file-guard.js';
+import { liveProcessCwds, recentTranscriptCwds, sessionOwnerReason, } from '../lib/core-utils/worktree-session-owner.js';
 const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse'];
 const BYPASS_MODE = 'bypassPermissions';
 const HOOK_CHECK_RELATIVE_PATH = path.join('core', 'scripts', 'check-hq-hooks.sh');
@@ -296,6 +297,34 @@ function hasRecentWorktreeActivity(worktree, gitDir, cutoff, deadline = Number.P
     });
     return latestContentChange(dirtyPaths) >= cutoff;
 }
+/**
+ * Why removing this worktree could lose work, or undefined when it is clean
+ * and every commit on HEAD is on its upstream and on a remote. A Git failure
+ * (including a deadline hit) is a reason too, so the worktree is retained.
+ */
+function unpreservedWorkReason(worktree, deadline) {
+    const status = runGit(worktree, ['status', '--porcelain', '--untracked-files=all', '--ignored=no'], deadline);
+    if (status?.status !== 0)
+        return 'git-error';
+    if (status.stdout.trim() !== '')
+        return 'dirty';
+    const upstream = runGit(worktree, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], deadline);
+    if (upstream === undefined)
+        return 'git-error';
+    if (upstream.status !== 0 || !upstream.stdout.trim())
+        return 'no-upstream';
+    const ahead = runGit(worktree, ['rev-list', '--count', '@{u}..HEAD'], deadline);
+    if (ahead?.status !== 0)
+        return 'git-error';
+    if (ahead.stdout.trim() !== '0')
+        return 'unpushed';
+    const offRemote = runGit(worktree, ['rev-list', '--count', 'HEAD', '--not', '--remotes'], deadline);
+    if (offRemote?.status !== 0)
+        return 'git-error';
+    if (offRemote.stdout.trim() !== '0')
+        return 'unpushed';
+    return undefined;
+}
 /**
  * Remove inactive worktrees created by `hq worktree` without ever deleting
  * directories directly. This runs on the hook path, so it uses a shallow
@@ -305,6 +334,11 @@ export function removeStaleHqWorktrees(hqRoot, now = Date.now(), deadline = Numb
     if (!isHqRoot(hqRoot))
         return;
     const cutoff = now - WORKTREE_STALE_AFTER_MS;
+    const kept = (worktree, reason) => {
+        console.log(`reindex: kept stale worktree ${worktree} (${reason})`);
+    };
+    // Pass 1: cheap local checks. Only clean, pushed, idle worktrees go on.
+    const eligible = [];
     for (const worktree of managedWorktreeCandidates(hqRoot)) {
         if (Date.now() >= deadline)
             break;
@@ -313,18 +347,59 @@ export function removeStaleHqWorktrees(hqRoot, now = Date.now(), deadline = Numb
         const gitDir = linkedWorktreeGitDir(worktree, deadline);
         if (!gitDir || hasRecentWorktreeActivity(worktree, gitDir, cutoff, deadline))
             continue;
+        const unsafe = unpreservedWorkReason(worktree, deadline);
+        if (unsafe) {
+            kept(worktree, unsafe);
+            continue;
+        }
+        eligible.push(worktree);
+    }
+    if (eligible.length === 0)
+        return;
+    // Pass 2: session ownership. A session working in the worktree may have no
+    // process parked there between tool calls, so recent transcripts count too.
+    // A probe that cannot finish inside the budget retains everything.
+    const processCwds = liveProcessCwds(Math.max(1, Math.min(WORKTREE_GIT_TIMEOUT_MS, deadline - Date.now())));
+    const transcriptCwds = processCwds === undefined
+        ? undefined
+        : recentTranscriptCwds({ nowMs: now, deadline });
+    if (processCwds === undefined || transcriptCwds === undefined) {
+        for (const worktree of eligible)
+            kept(worktree, 'session-check-incomplete');
+        return;
+    }
+    for (const worktree of eligible) {
+        if (Date.now() >= deadline)
+            break;
+        let real = worktree;
+        try {
+            real = fs.realpathSync(worktree);
+        }
+        catch { /* compare the literal spelling */ }
+        const owner = sessionOwnerReason(processCwds, transcriptCwds, worktree, real);
+        if (owner) {
+            kept(worktree, owner);
+            continue;
+        }
         // Narrow the destructive TOCTOU window: re-resolve the linked-worktree
-        // identity and re-measure activity immediately before asking Git to remove
-        // it. Git remains the only component that deletes the directory.
+        // identity and re-measure activity and preservation immediately before
+        // asking Git to remove it. Git remains the only component that deletes the
+        // directory.
         const confirmedGitDir = linkedWorktreeGitDir(worktree, deadline);
         if (!confirmedGitDir || hasRecentWorktreeActivity(worktree, confirmedGitDir, cutoff, deadline))
             continue;
+        const confirmedUnsafe = unpreservedWorkReason(worktree, deadline);
+        if (confirmedUnsafe) {
+            kept(worktree, confirmedUnsafe);
+            continue;
+        }
         // Recursive removal is not transactional. Only start it inside the sweep
         // budget, then let Git finish so a timeout cannot leave a registered,
-        // partially deleted worktree behind.
-        const removal = runGit(worktree, ['worktree', 'remove', '--force', worktree], deadline, true);
+        // partially deleted worktree behind. No --force: Git itself refuses a
+        // worktree that gained changes since the checks above.
+        const removal = runGit(worktree, ['worktree', 'remove', worktree], deadline, true);
         if (removal?.status === 0) {
-            console.log(`reindex: removed stale worktree ${worktree} (branch preserved; stale uncommitted files are not recoverable)`);
+            console.log(`reindex: removed stale worktree ${worktree} (clean and pushed; branch kept)`);
             continue;
         }
         const reason = removal?.stderr.trim() || removal?.stdout.trim() || 'Git could not remove it';

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

@@ -8,13 +8,18 @@
  *     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.
+ *   - 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".
  *
  * Fetch also reads placeholders that HQ sync rewrote after a teammate changed
  * the file (`vault: company`, the company vault key, `sha256: unknown`,
@@ -24,9 +29,10 @@
  * 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.
+ * 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.
  */
 import { GetObjectCommand, HeadObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
 import type { ScriptRunner } from "./storage.js";
@@ -37,14 +43,10 @@ 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";
+/** Reason on company files HQ sync has not stored in the company vault yet. */
+export declare const RUN_SYNC_FIRST = "run hq sync first";
 /** Top-level HQ-root folder that holds offloaded blobs in the personal vault. */
 export declare const OFFLOAD_TOP_LEVEL = ".hq-offload";
 /**
@@ -56,7 +58,7 @@ export declare const OFFLOAD_TOP_LEVEL = ".hq-offload";
  * @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.
+ * "update HQ sync". Current-file offload also needs syncHoldsPlaceholders.
  */
 export declare function syncExcludesOffload(excludedTopLevel: readonly string[] | undefined): boolean;
 export declare function offloadKey(gitBlobSha: string): string;
@@ -118,11 +120,16 @@ 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. */
+    head(key: string): Promise<{
+        size: number;
+        etag: 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>;
 }
 export interface VaultObjectS3Client {
-    send(cmd: GetObjectCommand): Promise<unknown>;
+    send(cmd: GetObjectCommand | HeadObjectCommand): Promise<unknown>;
 }
 export declare function s3VaultObjectStore(bucket: string, s3: VaultObjectS3Client): VaultObjectStore;
 export interface OffloadDeps {
@@ -152,7 +159,40 @@ export interface OffloadDeps {
         vault: "company";
         slug: string;
     }) => Promise<VaultObjectStore>;
+    /**
+     * Whether the installed HQ sync treats every `x.hqcloud` sibling as a hold
+     * on `x` in push and pull (hq-cloud CLOUD_PLACEHOLDER_HOLDS_ANY_SIBLING).
+     * Current-file offload stays off unless this returns true.
+     */
+    syncHoldsPlaceholders?: () => boolean;
+    /** What HQ sync last recorded for `target` (its journal entry), or null. */
+    syncRecord?: (target: OffloadTarget) => Promise<SyncRecord | null>;
+    /** File operations for current-file offload (tests inject to see the order). */
+    placeholderFs?: PlaceholderFs;
 }
+/** The vault that owns a working-tree path, and the object key there. */
+export type OffloadTarget = {
+    vault: "personal";
+    key: string;
+} | {
+    vault: "company";
+    slug: string;
+    key: string;
+};
+/** A sync journal entry: the version HQ sync last pushed or pulled. */
+export interface SyncRecord {
+    /** Hex sha256 of the synced bytes. */
+    hash?: string;
+    size: number;
+    remoteEtag?: string;
+}
+/**
+ * `companies/<slug>/<rest>` belongs to that company's vault at key `<rest>`.
+ * Every other path belongs to the personal vault at its HQ-root-relative path.
+ */
+export declare function resolveOffloadTarget(rel: string): OffloadTarget;
+/** Whether current-file offload can run with the installed HQ sync. */
+export declare function currentSyncReady(deps: Pick<OffloadDeps, "syncExcludesOffload" | "syncHoldsPlaceholders">): boolean;
 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;
@@ -215,17 +255,34 @@ export interface PlaceholderFs {
 }
 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.
+ * Offload one personal-scope current file by upload: 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. Company files never take this path (see pointCurrentFileAtVault).
  */
 export declare function offloadCurrentFile(rel: string, store: BlobStore, deps: Pick<OffloadDeps, "hqRoot" | "now">, fsOps?: PlaceholderFs): Promise<{
     path: string;
     bytes: number;
 }>;
+/** One current file in a `--current` plan (dry run and real run). */
+export interface CurrentFilePlan {
+    path: string;
+    bytes: number;
+    idle_days: number;
+    vault: "personal" | "company";
+    company?: string;
+    /** HQ sync already stored this exact version in the owning vault. */
+    synced: boolean;
+    action: "point-at-vault" | "upload" | "skip";
+    reason?: string;
+}
+export interface CurrentOffloaded {
+    path: string;
+    bytes: number;
+    vault: "personal" | "company";
+    company?: string;
+    action: "point-at-vault" | "upload";
+}
 export interface OffloadOptions {
     minBytes: number;
     idleDays: number;
@@ -233,12 +290,16 @@ export interface OffloadOptions {
     current: boolean;
     dryRun: boolean;
     yes: boolean;
+    /** With `current`: offload files at or under these HQ paths instead of the large-file list. */
+    paths?: string[];
 }
 export interface OffloadResult {
     history: {
         uploaded: number;
         bytes: number;
         freed_bytes: number;
+        /** True when this run did not ask for history. */
+        skipped?: boolean;
         available?: boolean;
         reason?: string;
         candidates?: number;
@@ -273,13 +334,17 @@ export interface OffloadResult {
         } | null;
     };
     current: {
-        offloaded: {
-            path: string;
-            bytes: number;
-        }[];
+        offloaded: CurrentOffloaded[];
         freed_bytes: number;
         available?: boolean;
         reason?: string;
+        /** Every candidate with its target vault, sync state, and action. */
+        files?: CurrentFilePlan[];
+        /** True when this run did not ask for current files. */
+        skipped?: boolean;
+        /** Company files skipped because HQ sync has not stored this version yet. */
+        unsynced?: string[];
+        message?: string;
     };
     errors: string[];
     dry_run: boolean;