@indigoai-us/hq-cli 5.345.32 → 5.345.33

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.345.33] — 2026-10-06
+- Map each PRD ledger state to a Board column and send its original value in `ledgerState`; `hq mesh project reconcile` reports status drift and notes when the Board omits that field.
+
+- Prevent pnpm self-updates from changing Corepack's project-selected version, and restore and verify the existing CLI after an unsuccessful update.
+- Let creators and company admins remove empty file-sharing ACL patterns without naming a grantee. Creating a private folder now clears an empty conflicting sharing pattern automatically.
+- `hq db provision` now creates the company's remote database and reports whether it is ready or already exists. `hq db sql --app <app>` runs read-only SQL in an app's remote schema (add `--write` to change data), `hq db usage` shows this month's compute and storage against both caps, and `hq db dump --app <app>` exports the schema and data to a local SQL file. No command prints tokens, passwords, or connection strings.
+- `hq lanes message` now lets an active keep-alive lane record win over a stale retired-registry entry, warns with the exact registry row, and `hq lanes doctor` reports retired, superseded, and awaiting-input recovery findings.
+
 ## [5.345.32] — 2026-10-06
 - `hq integrations list --usable` lists only the apps you can use right now: connected, shared with you under the same access rule the HQ gateway applies, and backed by a provider the gateway has registered. Each row shows the app name, its website domain, and the flag that selects exactly that connection in `hq integrations tools` and `call` (`--provider <slug>`, or `--connection <id>` when two connections share a provider). `--json` returns `{companyUid, viewerAccessKnown, apps}`. `--no-login` makes `list` fail instead of opening a browser sign-in, for hooks and scripts.
 

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

@@ -1875,7 +1875,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "sql";
-        readonly description: "Run SQL against the company vault DB (local; read-only by default)";
+        readonly description: "Run SQL against the company vault DB (local) or an app's remote database (--app); read-only by default";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -1892,6 +1892,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--company <slug>";
             readonly description: "Company slug (tenant scope; required)";
             readonly hidden: false;
+        }, {
+            readonly flags: "--app <app>";
+            readonly description: "Run against this app's remote database schema";
+            readonly hidden: false;
         }, {
             readonly flags: "--write";
             readonly description: "Allow write/DDL statements (discouraged for ad-hoc DDL)";
@@ -1953,7 +1957,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "provision";
-        readonly description: "Provision (or re-bind) the company remote vault DB via HQ control plane (HQ Workforce plan)";
+        readonly description: "Create the company remote database (Team plan)";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -1972,6 +1976,46 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly defaultValue: "us-east-1";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "usage";
+        readonly description: "Show this month's remote database usage against the compute and storage caps";
+        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: "--company <slug>";
+            readonly description: "Company slug";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "dump";
+        readonly description: "Export an app's remote database schema and data to a SQL file";
+        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: "--company <slug>";
+            readonly description: "Company slug";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--app <app>";
+            readonly description: "App id";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--out <file>";
+            readonly description: "Output file (default: <app>.sql)";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
     }];
 }, {
     readonly name: "api-keys";
@@ -2441,7 +2485,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "unshare";
-        readonly description: "Remove a file access grant. A trailing slash targets the private-folder row exactly.";
+        readonly description: "Remove a named file access grant, or remove an empty ACL row without --with.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -9320,6 +9364,35 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly hidden: false;
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "reconcile";
+            readonly description: "Read the project Board and report drift from a PRD ledger";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly helpOption: true;
+            readonly helpCommand: false;
+            readonly usage: "[options] <projectId>";
+            readonly helpText: readonly [];
+            readonly arguments: readonly [{
+                readonly name: "projectId";
+                readonly required: true;
+                readonly variadic: false;
+                readonly description: "";
+            }];
+            readonly options: readonly [{
+                readonly flags: "--company <slug|uid>";
+                readonly description: "Company slug or cloud uid";
+                readonly hidden: false;
+            }, {
+                readonly flags: "--stories-file <path>";
+                readonly description: "PRD JSON file with userStories";
+                readonly hidden: false;
+            }, {
+                readonly flags: "--json";
+                readonly description: "Print machine-readable mismatch records";
+                readonly hidden: false;
+            }];
+            readonly subcommands: readonly [];
         }, {
             readonly name: "register";
             readonly description: "Register an existing Board and bind its project channel; use project ensure to create or repair a Board";
@@ -11613,6 +11686,22 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "doctor";
+        readonly description: "Report active keep-alive lanes blocked by retired, superseded, or pending-question state";
+        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: "JSON on stdout (always)";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "list";
         readonly description: "List lanes";

package/dist/command-catalog.generated.js

@@ -2249,7 +2249,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "sql",
-                "description": "Run SQL against the company vault DB (local; read-only by default)",
+                "description": "Run SQL against the company vault DB (local) or an app's remote database (--app); read-only by default",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -2270,6 +2270,11 @@ export const COMMAND_CATALOG = [
                         "description": "Company slug (tenant scope; required)",
                         "hidden": false
                     },
+                    {
+                        "flags": "--app <app>",
+                        "description": "Run against this app's remote database schema",
+                        "hidden": false
+                    },
                     {
                         "flags": "--write",
                         "description": "Allow write/DDL statements (discouraged for ad-hoc DDL)",
@@ -2344,7 +2349,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "provision",
-                "description": "Provision (or re-bind) the company remote vault DB via HQ control plane (HQ Workforce plan)",
+                "description": "Create the company remote database (Team plan)",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -2366,6 +2371,54 @@ export const COMMAND_CATALOG = [
                     }
                 ],
                 "subcommands": []
+            },
+            {
+                "name": "usage",
+                "description": "Show this month's remote database usage against the compute and storage caps",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Company slug",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "dump",
+                "description": "Export an app's remote database schema and data to a SQL file",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Company slug",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--app <app>",
+                        "description": "App id",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--out <file>",
+                        "description": "Output file (default: <app>.sql)",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
             }
         ]
     },
@@ -2932,7 +2985,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "unshare",
-                "description": "Remove a file access grant. A trailing slash targets the private-folder row exactly.",
+                "description": "Remove a named file access grant, or remove an empty ACL row without --with.",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -11303,6 +11356,42 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "reconcile",
+                        "description": "Read the project Board and report drift from a PRD ledger",
+                        "aliases": [],
+                        "hidden": false,
+                        "helpOption": true,
+                        "helpCommand": false,
+                        "usage": "[options] <projectId>",
+                        "helpText": [],
+                        "arguments": [
+                            {
+                                "name": "projectId",
+                                "required": true,
+                                "variadic": false,
+                                "description": ""
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--company <slug|uid>",
+                                "description": "Company slug or cloud uid",
+                                "hidden": false
+                            },
+                            {
+                                "flags": "--stories-file <path>",
+                                "description": "PRD JSON file with userStories",
+                                "hidden": false
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable mismatch records",
+                                "hidden": false
+                            }
+                        ],
+                        "subcommands": []
+                    },
                     {
                         "name": "register",
                         "description": "Register an existing Board and bind its project channel; use project ensure to create or repair a Board",
@@ -14114,6 +14203,25 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "doctor",
+                "description": "Report active keep-alive lanes blocked by retired, superseded, or pending-question state",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "JSON on stdout (always)",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "list",
                 "description": "List lanes",

package/dist/commands/db-dump.d.ts

@@ -0,0 +1,8 @@
+/**
+ * hq db dump — export one app's remote schema (DDL) and data (INSERTs) to a local file.
+ */
+import { Command } from "commander";
+import { type DbRemoteCommandDeps } from "./db-remote-deps.js";
+export declare function describeSessionGap(error: unknown): string | null;
+export declare function registerDbDumpCommand(db: Command, depsFactory?: () => DbRemoteCommandDeps): void;
+//# sourceMappingURL=db-dump.d.ts.map

package/dist/commands/db-dump.js

@@ -0,0 +1,50 @@
+/**
+ * hq db dump — export one app's remote schema (DDL) and data (INSERTs) to a local file.
+ */
+import chalk from "chalk";
+import fs from "node:fs";
+import { safeErrorMessage } from "../lib/db/redact.js";
+import { dumpRemoteSchema, openRemoteAppConnection } from "../lib/db/remote-engine.js";
+import { isPlanGateError } from "../utils/plan-gate-error.js";
+import { defaultRemoteDeps, describeRemoteError, remoteEngineDeps, } from "./db-remote-deps.js";
+export function describeSessionGap(error) {
+    const status = error.status;
+    if (status === 404 || status === 405) {
+        return "Remote database access for apps is not available yet. The HQ API has no database session route.";
+    }
+    return null;
+}
+export function registerDbDumpCommand(db, depsFactory = defaultRemoteDeps) {
+    db.command("dump")
+        .description("Export an app's remote database schema and data to a SQL file")
+        .requiredOption("--company <slug>", "Company slug")
+        .requiredOption("--app <app>", "App id")
+        .option("--out <file>", "Output file (default: <app>.sql)")
+        .action(async (opts) => {
+        try {
+            const deps = depsFactory();
+            const resolved = await deps.resolveCompany(String(opts.company ?? "").trim());
+            const conn = await openRemoteAppConnection(remoteEngineDeps(deps), {
+                companyUid: resolved.companyUid,
+                appId: opts.app,
+            });
+            const outPath = opts.out ?? `${opts.app}.sql`;
+            const fd = fs.openSync(outPath, "w");
+            try {
+                const summary = await dumpRemoteSchema(conn, (text) => fs.writeSync(fd, text));
+                console.log(`Wrote ${summary.tables} table(s) and ${summary.rows} row(s) to ${outPath}.`);
+            }
+            finally {
+                fs.closeSync(fd);
+                await conn.close();
+            }
+        }
+        catch (error) {
+            if (isPlanGateError(error))
+                throw error;
+            console.error(chalk.red("Error:"), describeSessionGap(error) ?? describeRemoteError(error) ?? safeErrorMessage(error));
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=db-dump.js.map

package/dist/commands/db-provision.d.ts

@@ -1,15 +1,8 @@
 /**
- * hq db provision — request remote vault DB binding (US-009).
+ * hq db provision — create the company remote database through the HQ control plane.
  */
 import { Command } from "commander";
-export interface DbProvisionCommandDeps {
-    resolveCompany: (slug: string) => Promise<{
-        companyUid: string;
-        companySlug: string;
-    }>;
-    getAccessToken: () => Promise<string>;
-    apiBaseUrl: string;
-    fetchImpl?: typeof fetch;
-}
+import { type DbRemoteCommandDeps } from "./db-remote-deps.js";
+export type DbProvisionCommandDeps = DbRemoteCommandDeps;
 export declare function registerDbProvisionCommand(db: Command, depsFactory?: () => DbProvisionCommandDeps): void;
 //# sourceMappingURL=db-provision.d.ts.map

package/dist/commands/db-provision.js

@@ -1,34 +1,15 @@
 /**
- * hq db provision — request remote vault DB binding (US-009).
+ * hq db provision — create the company remote database through the HQ control plane.
  */
 import chalk from "chalk";
 import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
-import { DEFAULT_VAULT_API_URL, ensureCognitoToken, } from "../utils/cognito-session.js";
+import { safeErrorMessage } from "../lib/db/redact.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
-import { getCompanyUid } from "../utils/vault-api.js";
-const defaultDeps = () => ({
-    async resolveCompany(slug) {
-        if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
-            return { companyUid: `cmp_${slug}`, companySlug: slug };
-        }
-        const token = await ensureCognitoToken({ interactive: false });
-        const companyUid = await getCompanyUid(token, slug);
-        return { companyUid, companySlug: slug.trim().toLowerCase() };
-    },
-    async getAccessToken() {
-        if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
-            return "mock-token";
-        }
-        return ensureCognitoToken({ interactive: false });
-    },
-    apiBaseUrl: process.env.HQ_VAULT_API_URL ||
-        process.env.HQ_API_BASE_URL ||
-        process.env.HQ_CLOUD_API_URL ||
-        DEFAULT_VAULT_API_URL,
-});
+import { defaultRemoteDeps, describeRemoteError, } from "./db-remote-deps.js";
+const defaultDeps = defaultRemoteDeps;
 export function registerDbProvisionCommand(db, depsFactory = defaultDeps) {
     db.command("provision")
-        .description("Provision (or re-bind) the company remote vault DB via HQ control plane (HQ Workforce plan)")
+        .description("Create the company remote database (Team plan)")
         .requiredOption("--company <slug>", "Company slug")
         .option("--region <region>", "AWS region", "us-east-1")
         .action(async (opts) => {
@@ -51,38 +32,36 @@ export function registerDbProvisionCommand(db, depsFactory = defaultDeps) {
                 companySlug: resolved.companySlug,
                 region: opts.region,
             });
-            console.log(`company: ${result.companySlug}`);
-            console.log(`remote: ${result.status}`);
-            console.log(`engine: ${result.engineId}`);
-            console.log(`region: ${result.region}`);
-            console.log(`resourceArn: ${result.resourceArn}`);
-            console.log(`secretRef: ${result.secretRef}`);
-            console.log(`idempotent: ${result.idempotent ? "yes" : "no"}`);
+            if (result.status === "provisioning") {
+                console.log(`The remote database for ${result.companySlug} is still being set up. Run this again in a minute.`);
+            }
+            else if (result.idempotent || result.status === "existing") {
+                console.log(`The remote database for ${result.companySlug} already exists and is ready (${result.region}).`);
+            }
+            else {
+                console.log(`The remote database for ${result.companySlug} is ready (${result.region}).`);
+            }
         }
         catch (error) {
             // Let main.ts render the shared, non-stacktrace plan-gate message.
             if (isPlanGateError(error))
                 throw error;
-            const msg = error instanceof Error ? error.message : "Unknown error";
+            const described = describeRemoteError(error);
             const status = error.status;
-            const code = error.code;
-            if (code === "REMOTE_DB_NOT_AVAILABLE" || status === 501) {
-                console.error(chalk.red("Error:"), "Remote databases are not available yet.");
-                console.error(chalk.dim("Local hq db status|sql|migrate still work offline."));
+            if (described) {
+                console.error(chalk.red("Error:"), described);
+                if (status === 501 || error.code === "REMOTE_DB_NOT_AVAILABLE") {
+                    console.error(chalk.dim("Local hq db status|sql|migrate still work offline."));
+                }
+                else {
+                    console.error(chalk.dim("Local databases still work: hq db status|sql|migrate."));
+                }
             }
-            else if (status === 402 || /PLAN_REQUIRED|Team plan|Workforce|\$500/i.test(msg)) {
-                console.error(chalk.red("Error:"), "Remote vault DB requires the HQ Workforce plan ($500/mo).");
-                console.error(chalk.dim("Local databases still work: hq db status|sql|migrate — no HQ Workforce plan required."));
-            }
-            else if (status === 404 || /Unknown route|Not Found/i.test(msg)) {
-                console.error(chalk.red("Error:"), "Remote DB control plane is not available yet (routes not deployed).");
-                console.error(chalk.dim("Local hq db status|sql|migrate still work offline."));
+            else if (status === 404) {
+                console.error(chalk.red("Error:"), "The HQ API does not know the remote database routes. Update the CLI or check HQ_VAULT_API_URL.");
             }
             else {
-                console.error(chalk.red("Error:"), msg);
-            }
-            if (/postgres:\/\//i.test(msg)) {
-                console.error(chalk.red("Error: refused to print secret material"));
+                console.error(chalk.red("Error:"), safeErrorMessage(error));
             }
             process.exitCode = 1;
         }

package/dist/commands/db-remote-deps.d.ts

@@ -0,0 +1,18 @@
+import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
+import { type RemoteEngineDeps } from "../lib/db/remote-engine.js";
+export interface DbRemoteCommandDeps {
+    resolveCompany: (slug: string) => Promise<{
+        companyUid: string;
+        companySlug: string;
+    }>;
+    getAccessToken: () => Promise<string>;
+    apiBaseUrl: string;
+    fetchImpl?: typeof fetch;
+    engine?: Partial<Pick<RemoteEngineDeps, "tokenFactory" | "clientFactory" | "provider">>;
+}
+export declare function defaultRemoteDeps(): DbRemoteCommandDeps;
+export declare function controlPlaneClient(deps: DbRemoteCommandDeps): ControlPlaneDbClient;
+export declare function remoteEngineDeps(deps: DbRemoteCommandDeps): RemoteEngineDeps;
+/** Plain-language message for a failed remote call, or null when the error is not recognized. */
+export declare function describeRemoteError(error: unknown): string | null;
+//# sourceMappingURL=db-remote-deps.d.ts.map

package/dist/commands/db-remote-deps.js

@@ -0,0 +1,59 @@
+import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
+import { controlPlaneCredentialProvider, } from "../lib/db/remote-engine.js";
+import { DEFAULT_VAULT_API_URL, ensureCognitoToken, } from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
+export function defaultRemoteDeps() {
+    return {
+        async resolveCompany(slug) {
+            if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
+                return { companyUid: `cmp_${slug}`, companySlug: slug };
+            }
+            const token = await ensureCognitoToken({ interactive: false });
+            const companyUid = await getCompanyUid(token, slug);
+            return { companyUid, companySlug: slug.trim().toLowerCase() };
+        },
+        async getAccessToken() {
+            if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1")
+                return "mock-token";
+            return ensureCognitoToken({ interactive: false });
+        },
+        apiBaseUrl: process.env.HQ_VAULT_API_URL ||
+            process.env.HQ_API_BASE_URL ||
+            process.env.HQ_CLOUD_API_URL ||
+            DEFAULT_VAULT_API_URL,
+    };
+}
+export function controlPlaneClient(deps) {
+    return new ControlPlaneDbClient({
+        baseUrl: deps.apiBaseUrl,
+        getAccessToken: deps.getAccessToken,
+        fetchImpl: deps.fetchImpl,
+    });
+}
+export function remoteEngineDeps(deps) {
+    return {
+        provider: deps.engine?.provider ?? controlPlaneCredentialProvider(controlPlaneClient(deps)),
+        tokenFactory: deps.engine?.tokenFactory,
+        clientFactory: deps.engine?.clientFactory,
+    };
+}
+/** Plain-language message for a failed remote call, or null when the error is not recognized. */
+export function describeRemoteError(error) {
+    const status = error.status;
+    const code = error.code;
+    if (code === "REMOTE_DB_NOT_AVAILABLE" || status === 501) {
+        return "Remote databases are not available yet.";
+    }
+    if (status === 402 || code === "PLAN_REQUIRED") {
+        return "Remote databases require the Team plan.";
+    }
+    if (status === 403)
+        return "You are not a member of this company, or this app belongs to another company.";
+    if (status === 409)
+        return "This company has no remote database yet. Run hq db provision first.";
+    if (status === 404 && code === "DB_USAGE_NOT_PROVISIONED") {
+        return "This company has no remote database yet. Run hq db provision first.";
+    }
+    return null;
+}
+//# sourceMappingURL=db-remote-deps.js.map

package/dist/commands/db-sql.d.ts

@@ -5,5 +5,6 @@
  * Never prints remote connection strings.
  */
 import { Command } from "commander";
-export declare function registerDbSqlCommand(db: Command): void;
+import { type DbRemoteCommandDeps } from "./db-remote-deps.js";
+export declare function registerDbSqlCommand(db: Command, remoteDepsFactory?: () => DbRemoteCommandDeps): void;
 //# sourceMappingURL=db-sql.d.ts.map