@indigoai-us/hq-cli 5.345.80 → 5.345.81

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.345.81] — 2026-10-11
+- HQ Storage (`hq storage status|prune|offload|fetch`) is available behind the Indigo-only `hq-storage` flag and fails closed when the flag is off. Requires @indigoai-us/hq-cloud 6.18.61, whose sync skips `.hq-offload/` and supports cloud-only `.hqcloud` placeholders.
+- `hq storage status` reports local autosave history and cloud file-version usage per company, grouped by age. `hq storage prune` deletes old noncurrent cloud file versions in companies where you are an owner or admin, and never touches the current version. A version's age counts from when it was replaced, so a recent undo copy of an old file is kept. `status --json` marks each company with `can_delete`, and still shows local usage when you are signed out.
+- `hq storage offload` moves old versions of big files out of local autosave history into your personal HQ cloud storage, checks each upload, then replaces them in history with a small link. `hq storage fetch` downloads a moved file and checks it before putting it back, and `--git-blob <sha> --out <file>` gets an old version from history. `hq storage status` now shows how much could be moved. Moving idle current files (`--current`) reports unavailable for now, because HQ sync would treat the replaced file as deleted. Offload also reports "update HQ sync" until the installed HQ sync skips the offload folder. Without a terminal, prune and offload need `--yes` and exit with an error otherwise.
+- `hq storage fetch` also restores files whose placeholder HQ sync updated after a teammate changed them. It downloads the newer version from the company's cloud storage, only if you are an active member of that company, and checks its size and version tag before putting it back. If a teammate deleted the file, fetch stops and says so. `--force-orphan --out <file>` gets your own earlier copy from your personal HQ cloud storage into a file outside your HQ folder, so it is never synced back to the team. `hq storage status --json` now reports `offload.current_available` and `offload.current_reason`, which stay false while moving current files is turned off.
+- `hq storage status`, `prune` and `offload` first clear expired local backups when HQ supports it. Results now say when space held by the 24-hour prune backup is freed (`reclaim_after`, `pending_reclaim_bytes`); a preview includes the expected time. History offload frees space right away, since every moved file is already checked in the cloud. When old branches or tags keep old history, prune reports them as a list instead of an error message. A cloud prune refused by permissions now says only owners and admins can delete old versions for that company.
+
 ## [5.345.80] — 2026-10-11
 - The version gate no longer treats a pnpm global install that Node resolved
   into `store/v11/links` as a local dependency, so it can self-update instead

package/dist/command-catalog.generated.d.ts

@@ -2902,6 +2902,148 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly defaultValue: "<runtime-path>";
     }];
     readonly subcommands: readonly [];
+}, {
+    readonly name: "storage";
+    readonly description: "See how much space HQ backups use and delete old ones";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly helpOption: true;
+    readonly helpCommand: true;
+    readonly usage: "[options] [command]";
+    readonly helpText: readonly [];
+    readonly arguments: readonly [];
+    readonly options: readonly [];
+    readonly subcommands: readonly [{
+        readonly name: "status";
+        readonly description: "Show local autosave history and cloud file history sizes";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--json";
+            readonly description: "Print JSON";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--company <slug>";
+            readonly description: "Only this company (must be one of yours)";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "prune";
+        readonly description: "Delete local autosave history and old cloud file versions before a date";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--local-before <date>";
+            readonly description: "Prune local autosave history before YYYY-MM-DD";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--cloud-before <date>";
+            readonly description: "Delete old (noncurrent) cloud file versions before YYYY-MM-DD";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--company <slug>";
+            readonly description: "Only this company (must be one of yours)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--dry-run";
+            readonly description: "Show what would be deleted without deleting";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--yes";
+            readonly description: "Skip the confirmation prompt";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print JSON";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "offload";
+        readonly description: "Move big files to your personal HQ cloud storage and leave links behind (old versions in history; idle current files)";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--min-size <size>";
+            readonly description: "Only files at least this big, e.g. 50MB (env HQ_OFFLOAD_MIN_BYTES)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--idle-days <days>";
+            readonly description: "Current files must be untouched this many days";
+            readonly hidden: false;
+            readonly defaultValue: "14";
+        }, {
+            readonly flags: "--history";
+            readonly description: "Only old versions in local autosave history";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--current";
+            readonly description: "Only idle files in the working tree";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--dry-run";
+            readonly description: "Show what would move without uploading or changing anything";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--yes";
+            readonly description: "Skip the confirmation prompt";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print JSON";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "fetch";
+        readonly description: "Download a file moved to HQ cloud storage, check it, and put it back in place";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options] [path]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [{
+            readonly name: "path";
+            readonly required: false;
+            readonly variadic: false;
+            readonly description: "";
+        }];
+        readonly options: readonly [{
+            readonly flags: "--git-blob <sha>";
+            readonly description: "Download an old version from history by its git blob id";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--out <file>";
+            readonly description: "Where to write the --git-blob or --force-orphan download";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--force-orphan";
+            readonly description: "For a file a teammate deleted: write your own personal-vault copy to --out (outside HQ). It is never synced back to your team.";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print JSON";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
+    }];
 }, {
     readonly name: "skill";
     readonly description: "Create, stage, promote, and discuss company skills";

package/dist/command-catalog.generated.js

@@ -3501,6 +3501,179 @@ export const COMMAND_CATALOG = [
         ],
         "subcommands": []
     },
+    {
+        "name": "storage",
+        "description": "See how much space HQ backups use and delete old ones",
+        "aliases": [],
+        "hidden": false,
+        "helpOption": true,
+        "helpCommand": true,
+        "usage": "[options] [command]",
+        "helpText": [],
+        "arguments": [],
+        "options": [],
+        "subcommands": [
+            {
+                "name": "status",
+                "description": "Show local autosave history and cloud file history sizes",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "Print JSON",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Only this company (must be one of yours)",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "prune",
+                "description": "Delete local autosave history and old cloud file versions before a date",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--local-before <date>",
+                        "description": "Prune local autosave history before YYYY-MM-DD",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--cloud-before <date>",
+                        "description": "Delete old (noncurrent) cloud file versions before YYYY-MM-DD",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Only this company (must be one of yours)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--dry-run",
+                        "description": "Show what would be deleted without deleting",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--yes",
+                        "description": "Skip the confirmation prompt",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "offload",
+                "description": "Move big files to your personal HQ cloud storage and leave links behind (old versions in history; idle current files)",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--min-size <size>",
+                        "description": "Only files at least this big, e.g. 50MB (env HQ_OFFLOAD_MIN_BYTES)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--idle-days <days>",
+                        "description": "Current files must be untouched this many days",
+                        "hidden": false,
+                        "defaultValue": "14"
+                    },
+                    {
+                        "flags": "--history",
+                        "description": "Only old versions in local autosave history",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--current",
+                        "description": "Only idle files in the working tree",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--dry-run",
+                        "description": "Show what would move without uploading or changing anything",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--yes",
+                        "description": "Skip the confirmation prompt",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "fetch",
+                "description": "Download a file moved to HQ cloud storage, check it, and put it back in place",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] [path]",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "path",
+                        "required": false,
+                        "variadic": false,
+                        "description": ""
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--git-blob <sha>",
+                        "description": "Download an old version from history by its git blob id",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--out <file>",
+                        "description": "Where to write the --git-blob or --force-orphan download",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--force-orphan",
+                        "description": "For a file a teammate deleted: write your own personal-vault copy to --out (outside HQ). It is never synced back to your team.",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            }
+        ]
+    },
     {
         "name": "skill",
         "description": "Create, stage, promote, and discuss company skills",

package/dist/command-help.js

@@ -8,6 +8,8 @@ export async function runCommandHelp(argv) {
         .version(CLI_VERSION)
         .option("--verbose", "Show verbose diagnostics, including SDK runtime warnings");
     registerCommandCatalog(program);
+    const { hideStorageInCatalog } = await import("./lib/storage-feature-flag.js");
+    hideStorageInCatalog(program);
     await program.parseAsync([...argv]);
 }
 //# sourceMappingURL=command-help.js.map

package/dist/command-registration-plan.d.ts

@@ -280,6 +280,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/access.js";
     readonly exportName: "registerAccessCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "storage";
+    readonly parent: "program";
+    readonly module: "./commands/storage.js";
+    readonly exportName: "registerStorageCommand";
 }, {
     readonly type: "registrar";
     readonly root: "skill";

package/dist/command-registration-plan.js

@@ -49,6 +49,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "files", parent: "program", module: "./commands/files.js", exportName: "registerFilesCommand", result: "files" },
     { type: "registrar", root: "files", parent: "files", module: "./commands/files-browse.js", exportName: "registerFilesBrowseCommands" },
     { type: "registrar", root: "access", parent: "program", module: "./commands/access.js", exportName: "registerAccessCommand" },
+    { type: "registrar", root: "storage", parent: "program", module: "./commands/storage.js", exportName: "registerStorageCommand" },
     { type: "registrar", root: "skill", parent: "program", module: "./commands/skill.js", exportName: "registerSkillCommand" },
     { type: "registrar", root: "members", parent: "program", module: "./commands/members.js", exportName: "registerMembersCommand" },
     { type: "registrar", root: "people", parent: "program", module: "./commands/people.js", exportName: "registerPeopleCommand" },

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

@@ -0,0 +1,98 @@
+/**
+ * Shared calls into core `hq-storage.sh` for `hq storage` status, prune and
+ * offload.
+ *
+ * - `runCoreScript` turns one script run into a JSON report. Exit 4 from
+ *   `prune` ("would free nothing") becomes a structured refusal with the
+ *   branches, tags or stash that hold the old history, never raw stderr.
+ * - `dropExpiredBackups` runs core `drop-backups --expired` right before a
+ *   real prune or offload (never for status, dry runs or fetch). With no
+ *   expired backup it takes no lock and runs no gc; it never expires reflogs.
+ *   A failure is reported but never blocks the command.
+ * - `checkPreconditions` runs core `check` so offload can refuse before it
+ *   uploads anything. Exit 5 from a core rewrite (a failed precondition)
+ *   becomes a structured refusal with plain text, never raw stderr.
+ * - Backups: by default core keeps a backup ref for 24 h after prune or
+ *   strip-large, so space comes back after `reclaim_after`, not at once.
+ *   `withReclaim` adds `backup_ref`, `reclaim_after` and
+ *   `pending_reclaim_bytes` to a result so a UI can say when space is freed.
+ */
+import type { LocalReport, ScriptRunner } from "./storage.js";
+/** Core's default backup grace period (`HQ_STORAGE_BACKUP_GRACE_HOURS`). */
+export declare const BACKUP_GRACE_HOURS = 24;
+/**
+ * Git's default expiry for reflog entries that point at rewritten history
+ * (gc.reflogExpireUnreachable). Core that keeps undo history frees the space
+ * a prune or offload rewrote only after these entries age out.
+ */
+export declare const UNDO_WINDOW_DAYS = 30;
+/** Whether the installed core keeps git's undo history (never expires reflogs early). */
+export declare function coreKeepsUndo(script: string): boolean;
+/** Hours after a rewrite until its space is freed, for this core. */
+export declare function reclaimWindowHours(script: string): number;
+export interface HoldingRef {
+    name: string;
+    commit_date: string | null;
+}
+export interface ReclaimReport {
+    available: boolean;
+    dropped?: number;
+    freed_bytes?: number;
+    reason?: string;
+}
+/** Whether the installed core script has a `case` arm for `sub`. */
+export declare function coreSupports(script: string, sub: string): boolean;
+/** Whether the installed core script mentions a flag, e.g. `--no-backup`. */
+export declare function coreHasFlag(script: string, flag: string): boolean;
+/**
+ * Structured exit-4 refusal. Newer core prints
+ * `{"refused":"nothing_to_free","holding_refs":[...],"holding_refs_count":N}`
+ * on stdout. Older core printed only a stderr line naming `(ref, ref)`; the
+ * ref names are taken from it and the line itself (which tells the user to
+ * delete them) is dropped.
+ */
+export declare function parseRefusal(stdout: string, stderr: string): LocalReport;
+/** Core exit code for a failed precondition (remote-tracking branches, ...). */
+export declare const CORE_PRECONDITION_EXIT = 5;
+/** Plain text for a precondition refusal from core that printed no message. */
+export declare const PRECONDITION_FALLBACK = "HQ is not in a state where its history can be rewritten. Nothing was changed.";
+export interface PreconditionRefusal {
+    refused: string;
+    message: string;
+}
+/** `{"refused":"<code>","message":".."}` on stdout, or a plain fallback. */
+export declare function parsePreconditionRefusal(stdout: string): PreconditionRefusal;
+/** Run one core subcommand and return its JSON as a report. */
+export declare function runCoreScript(runScript: ScriptRunner, script: string, args: string[]): Promise<LocalReport>;
+/**
+ * Run core `drop-backups --expired` when the script has it; undefined when it
+ * does not. Call only right before a real prune or offload.
+ */
+export declare function dropExpiredBackups(runScript: ScriptRunner, script: string): Promise<ReclaimReport | undefined>;
+/**
+ * Core `check`: undefined when core lacks it (or it fails to run), else null
+ * when every precondition holds, or the refusal.
+ */
+export declare function checkPreconditions(runScript: ScriptRunner, script: string, forCmd: "prune" | "strip-large"): Promise<PreconditionRefusal | null | undefined>;
+export declare function reclaimEstimate(now: Date, hours?: number): string;
+/**
+ * Backup fields for a prune or strip-large result.
+ * - dry run: `reclaim_after` is an estimate (now + `windowHours`: 24 h for
+ *   the backup, or 30 days when core keeps undo history) and all of
+ *   `expectedBytes` is pending.
+ * - real run: core's `backup_ref` / `reclaim_after`; `pending_reclaim_bytes`
+ *   is core's value when it reports one, else `expectedBytes - freed` while a
+ *   backup is held, else 0.
+ */
+export declare function reclaimFields(core: Record<string, unknown>, opts: {
+    dryRun: boolean;
+    now: Date;
+    expectedBytes: number;
+    freedBytes: number;
+    windowHours?: number;
+}): {
+    backup_ref: string | null;
+    reclaim_after: string | null;
+    pending_reclaim_bytes: number;
+};
+//# sourceMappingURL=storage-core.d.ts.map