@indigoai-us/hq-cli 5.311.3 → 5.312.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [5.312.0] — 2026-10-02
+- The desktop app can turn event-driven daemon sync on or off with its Instant Sync setting. The daemon stores the preference and restarts when a running daemon needs to apply it.
+- `hq dm channel` now explains empty channels and displays a readable fallback for bodyless system notifications.
+
+- Personal vault browsing now treats slash and dot paths as the root and normalizes leading slashes on nested paths.
+- Personal and company file browsing normalize root markers before listing.
+- Schedule the first eligible lead keep-alive check from the lane terminal watcher when the opt-in flags are enabled.
+- Add default-off KPI freshness reporting and deduplicated re-measurement nudges to lane autopilot.
+- Add company-scoped Outpost owner lookup for hostless lane ULIDs used by `hq lanes message`.
+- Add opt-in autopilot nudges and operator escalation for missed lead deadlines.
+- Report the bounded host BASH_ENV class for hook telemetry so HQ-CLI-2C startup timing can be distinguished accurately.
+- Add gated `hq vault retention get|set` commands for the per-vault default retention period.
+
+## [5.311.4] — 2026-10-02
+- Preserve existing local company starter files during cloud provisioning by having the CLI request that hq-pro skip blank starter seeding; older servers are detected before company creation.
+
 ## [5.311.3] — 2026-10-01
 - Match company file access checks against the company-anchored paths printed by `hq files browse`.
 - Record a placement resolved to the current host as local so the lane starts without dispatching back through Outpost pickup.

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

@@ -5071,6 +5071,49 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly subcommands: readonly [];
         }];
     }];
+}, {
+    readonly name: "vault";
+    readonly description: "Manage HQ vault settings";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly usage: "[options] [command]";
+    readonly arguments: readonly [];
+    readonly options: readonly [];
+    readonly subcommands: readonly [{
+        readonly name: "retention";
+        readonly description: "Get or set the default retention for future vault object versions";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--company <slug>";
+            readonly description: "Company vault slug (omit for your personal vault)";
+        }];
+        readonly subcommands: readonly [{
+            readonly name: "get";
+            readonly description: "Show the vault's default retention in days";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "set";
+            readonly description: "Set the vault's default retention in days (1-30)";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <days>";
+            readonly arguments: readonly [{
+                readonly name: "days";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }];
+    }];
 }, {
     readonly name: "core";
     readonly description: "HQ scaffold scripts hosted by the CLI (core; not a stable surface)";
@@ -8630,6 +8673,9 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly options: readonly [{
             readonly flags: "--text <msg>";
             readonly description: "Message text";
+        }, {
+            readonly flags: "--text-file <path>";
+            readonly description: "Read message text from a file";
         }, {
             readonly flags: "--project <slug>";
             readonly description: "Re-point project attribution; a changed story is named in the resumed prompt";
@@ -9292,6 +9338,30 @@ export declare const COMMAND_CATALOG: readonly [{
             }];
             readonly subcommands: readonly [];
         }];
+    }, {
+        readonly name: "_keep-alive-terminal-trigger";
+        readonly description: "";
+        readonly aliases: readonly [];
+        readonly hidden: true;
+        readonly usage: "[options] <laneId> <version> <dueAt>";
+        readonly arguments: readonly [{
+            readonly name: "laneId";
+            readonly required: true;
+            readonly variadic: false;
+        }, {
+            readonly name: "version";
+            readonly required: true;
+            readonly variadic: false;
+        }, {
+            readonly name: "dueAt";
+            readonly required: true;
+            readonly variadic: false;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--json";
+            readonly description: "JSON on stdout (always)";
+        }];
+        readonly subcommands: readonly [];
     }];
 }, {
     readonly name: "monitor";
@@ -9551,6 +9621,31 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "Print machine-readable JSON";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "instant-sync";
+            readonly description: "Control daemon Instant Sync";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] [command]";
+            readonly arguments: readonly [];
+            readonly options: readonly [];
+            readonly subcommands: readonly [{
+                readonly name: "set";
+                readonly description: "Set whether daemon sync uses Instant Sync";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] <state>";
+                readonly arguments: readonly [{
+                    readonly name: "state";
+                    readonly required: true;
+                    readonly variadic: false;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--json";
+                    readonly description: "Print machine-readable JSON";
+                }];
+                readonly subcommands: readonly [];
+            }];
         }, {
             readonly name: "pause";
             readonly description: "Pause daemon sync until resumed";

package/dist/command-catalog.generated.js

@@ -6559,6 +6559,59 @@ export const COMMAND_CATALOG = [
             }
         ]
     },
+    {
+        "name": "vault",
+        "description": "Manage HQ vault settings",
+        "aliases": [],
+        "hidden": false,
+        "usage": "[options] [command]",
+        "arguments": [],
+        "options": [],
+        "subcommands": [
+            {
+                "name": "retention",
+                "description": "Get or set the default retention for future vault object versions",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Company vault slug (omit for your personal vault)"
+                    }
+                ],
+                "subcommands": [
+                    {
+                        "name": "get",
+                        "description": "Show the vault's default retention in days",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "set",
+                        "description": "Set the vault's default retention in days (1-30)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <days>",
+                        "arguments": [
+                            {
+                                "name": "days",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    }
+                ]
+            }
+        ]
+    },
     {
         "name": "core",
         "description": "HQ scaffold scripts hosted by the CLI (core; not a stable surface)",
@@ -11124,6 +11177,10 @@ export const COMMAND_CATALOG = [
                         "flags": "--text <msg>",
                         "description": "Message text"
                     },
+                    {
+                        "flags": "--text-file <path>",
+                        "description": "Read message text from a file"
+                    },
                     {
                         "flags": "--project <slug>",
                         "description": "Re-point project attribution; a changed story is named in the resumed prompt"
@@ -11986,6 +12043,37 @@ export const COMMAND_CATALOG = [
                         "subcommands": []
                     }
                 ]
+            },
+            {
+                "name": "_keep-alive-terminal-trigger",
+                "description": "",
+                "aliases": [],
+                "hidden": true,
+                "usage": "[options] <laneId> <version> <dueAt>",
+                "arguments": [
+                    {
+                        "name": "laneId",
+                        "required": true,
+                        "variadic": false
+                    },
+                    {
+                        "name": "version",
+                        "required": true,
+                        "variadic": false
+                    },
+                    {
+                        "name": "dueAt",
+                        "required": true,
+                        "variadic": false
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "JSON on stdout (always)"
+                    }
+                ],
+                "subcommands": []
             }
         ]
     },
@@ -12314,6 +12402,38 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "instant-sync",
+                        "description": "Control daemon Instant Sync",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] [command]",
+                        "arguments": [],
+                        "options": [],
+                        "subcommands": [
+                            {
+                                "name": "set",
+                                "description": "Set whether daemon sync uses Instant Sync",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] <state>",
+                                "arguments": [
+                                    {
+                                        "name": "state",
+                                        "required": true,
+                                        "variadic": false
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--json",
+                                        "description": "Print machine-readable JSON"
+                                    }
+                                ],
+                                "subcommands": []
+                            }
+                        ]
+                    },
                     {
                         "name": "pause",
                         "description": "Pause daemon sync until resumed",

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

@@ -370,6 +370,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/billing.js";
     readonly exportName: "registerBillingCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "vault";
+    readonly parent: "program";
+    readonly module: "./commands/vault-retention.js";
+    readonly exportName: "registerVaultRetentionCommand";
 }, {
     readonly type: "registrar";
     readonly root: "core";

package/dist/command-registration-plan.js

@@ -64,6 +64,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "agent", parent: "program", module: "./commands/agent.js", exportName: "registerAgentCommand" },
     { type: "registrar", root: "outposts", parent: "program", module: "./commands/outposts.js", exportName: "registerOutpostsCommand" },
     { type: "registrar", root: "billing", parent: "program", module: "./commands/billing.js", exportName: "registerBillingCommand" },
+    { type: "registrar", root: "vault", parent: "program", module: "./commands/vault-retention.js", exportName: "registerVaultRetentionCommand" },
     { type: "registrar", root: "core", parent: "program", module: "./commands/core.js", exportName: "registerCoreCommands" },
     { type: "registrar", root: "search", parent: "program", module: "./commands/search.js", exportName: "registerSearchCommand" },
     { type: "registrar", root: "index", parent: "program", module: "./commands/index-cmd.js", exportName: "registerIndexCommand" },

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

@@ -135,6 +135,8 @@ export interface VaultClient {
     checkSlugInMyNamespace(slug: string): Promise<{
         available: boolean;
         conflictingCompanyUid?: string;
+        /** Older hq-pro servers omit this field; absence means unsupported. */
+        skipStarterSeedSupported?: boolean;
     }>;
     /** Fetch a company entity by uid. Used to materialize the entity
      * after `checkSlugInMyNamespace` reports a same-namespace collision. */
@@ -143,6 +145,7 @@ export interface VaultClient {
         slug: string;
         name: string;
         ownerUid?: string;
+        skipStarterSeed?: boolean;
     }): Promise<VaultEntity>;
     /**
      * Soft-tombstone a company (`DELETE /entity/{uid}`). Owner-only. Leaves the

package/dist/commands/cloud-provision.js

@@ -34,6 +34,25 @@ import * as yaml from "js-yaml";
 import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { createSyncProgressRecorder, share, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+const SHARED_COMPANY_STARTER_PATHS = [
+    "README.md",
+    "board.json",
+    "knowledge/README.md",
+    "knowledge/design-styles/packs/.gitkeep",
+    "people/.gitkeep",
+    "policies/.gitkeep",
+    "projects/.gitkeep",
+    "repos/.gitkeep",
+    "skills/.gitkeep",
+    "sources/meetings/source.yaml",
+    "workspace/.gitignore",
+    "workspace/index.jsonl",
+    "workspace/sessions/.gitkeep",
+];
+function hasLocalSharedStarterPath(hqRoot, slug) {
+    const companyDir = path.join(hqRoot, "companies", slug);
+    return SHARED_COMPANY_STARTER_PATHS.some((relativePath) => fs.existsSync(path.join(companyDir, relativePath)));
+}
 /** Custom error class so the CLI runner can map to exit codes. */
 export class ProvisionError extends Error {
     code;
@@ -333,7 +352,11 @@ export function createDefaultVaultClient(apiUrl, accessToken) {
                     const body = await safeBody(res);
                     throw new ProvisionError(1, `Vault GET /entity/check-slug/me failed: ${res.status} ${res.statusText} — ${body}`);
                 }
-                return (await res.json());
+                const data = (await res.json());
+                return {
+                    ...data,
+                    skipStarterSeedSupported: data.skipStarterSeedSupported === true,
+                };
             });
         },
         async getCompanyByUid(uid) {
@@ -359,6 +382,8 @@ export function createDefaultVaultClient(apiUrl, accessToken) {
             };
             if (input.ownerUid)
                 body.ownerUid = input.ownerUid;
+            if (input.skipStarterSeed)
+                body.skipStarterSeed = true;
             return withVaultRequest(url, {
                 method: "POST",
                 headers,
@@ -548,6 +573,7 @@ export async function provisionCompany(options) {
     // match the caller's own person UID(s) from `listMyPersonEntities`.
     const callerOwnedUids = new Set(persons.map((p) => p.uid));
     const callerIsOwner = !options.ownerUid || callerOwnedUids.has(options.ownerUid);
+    const hasLocalSharedStarterFiles = hasLocalSharedStarterPath(options.hqRoot, options.slug);
     let entity;
     let createdEntity = false;
     if (callerIsOwner) {
@@ -557,17 +583,24 @@ export async function provisionCompany(options) {
             entity = await vaultClient.getCompanyByUid(slugCheck.conflictingCompanyUid);
         }
         else {
+            if (hasLocalSharedStarterFiles && !slugCheck.skipStarterSeedSupported) {
+                throw new ProvisionError(1, "This hq-pro server does not support preserving local starter files during cloud provisioning; update hq-pro and retry");
+            }
             log(`slug available in caller's namespace — creating vault entity`);
             entity = await vaultClient.createCompanyEntity({
                 slug: options.slug,
                 name: options.name ?? options.slug,
                 ownerUid: options.ownerUid,
+                ...(hasLocalSharedStarterFiles ? { skipStarterSeed: true } : {}),
             });
             createdEntity = true;
             log(`created vault entity uid=${entity.uid}`);
         }
     }
     else {
+        if (hasLocalSharedStarterFiles) {
+            throw new ProvisionError(1, "Cannot preserve local starter files when provisioning for a different owner");
+        }
         log(`--owner ${options.ownerUid} differs from caller's person(s); skipping namespace pre-check (server authoritatively gates per-target-namespace)`);
         entity = await vaultClient.createCompanyEntity({
             slug: options.slug,

package/dist/commands/daemon.js

@@ -474,6 +474,18 @@ async function runDaemonSyncNow(d, opts) {
     const result = { accepted: true, action: "restart-sync-runner", daemonRunning: running };
     d.out(opts.json ? JSON.stringify(result, null, 2) : running ? "Asked the daemon to start a fresh sync pass." : "Queued a fresh sync pass for the next daemon start.");
 }
+async function runDaemonSyncInstantSyncSet(d, enabled, opts) {
+    const host = currentHost(d);
+    const config = readDaemonConfig(host.paths.configPath);
+    const changed = config.instantSyncEnabled !== enabled;
+    if (changed)
+        writeDaemonConfig(host.paths.configPath, { ...config, instantSyncEnabled: enabled });
+    const daemonRunning = runningDaemonPid(host.paths.lockPath, d.daemonAlive) !== null;
+    if (changed && daemonRunning)
+        queueDaemonSyncControl(d, { action: "restart-daemon" });
+    const result = { instantSyncEnabled: enabled, persisted: true, daemonRestartRequested: changed && daemonRunning };
+    d.out(opts.json ? JSON.stringify(result, null, 2) : `Instant Sync ${enabled ? "enabled" : "disabled"}${daemonRunning ? "; asked the daemon to restart" : "; saved for the next daemon start"}.`);
+}
 async function runDaemonSyncPause(d, paused, opts) {
     const host = currentHost(d);
     const config = readDaemonConfig(host.paths.configPath);
@@ -772,6 +784,16 @@ export function registerDaemonCommand(program, over = {}) {
         .description("Start a fresh sync pass immediately")
         .option("--json", "Print machine-readable JSON")
         .action(wrap((d, opts) => runDaemonSyncNow(d, opts)));
+    const instantSync = sync.command("instant-sync").description("Control daemon Instant Sync");
+    instantSync
+        .command("set <state>")
+        .description("Set whether daemon sync uses Instant Sync")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, state, opts) => {
+        if (state !== "on" && state !== "off")
+            throw new DaemonCommandError("Use on or off for Instant Sync.");
+        return runDaemonSyncInstantSyncSet(d, state === "on", opts);
+    }));
     sync
         .command("pause")
         .description("Pause daemon sync until resumed")

package/dist/commands/dm.js

@@ -872,7 +872,12 @@ export function formatChannelMessage(m, nowMs, opts = {}) {
     const id = opts.showEventId ? (m.eventId ?? m.messageId) : undefined;
     const idPart = id ? `  ${chalk.dim(id)}` : "";
     const bodyIndent = `${indent}    `;
-    return `${indent}${who} ${when}${idPart}\n${bodyIndent}${firstLine(m.body)}${formatAttachments(m, bodyIndent)}`;
+    const body = firstLine(m.body);
+    const readableBody = body ||
+        (senderLabel(m).toLowerCase() === "hq"
+            ? "System notification (no text provided)."
+            : "(no message text)");
+    return `${indent}${who} ${when}${idPart}\n${bodyIndent}${readableBody}${formatAttachments(m, bodyIndent)}`;
 }
 /**
  * Read the caller's person/agent uid and email from a JWT we already hold.
@@ -1227,26 +1232,27 @@ async function runDmThread(identifier, opts) {
  * `hq channels`). Throws a user-facing message when nothing matches or a name is
  * ambiguous.
  */
-async function resolveChannelId(token, target) {
+async function resolveChannel(token, target) {
     const raw = target.trim().replace(/^#/, "");
     if (!raw)
         throw new Error("A channel name or id is required.");
     const channels = await fetchChannels(token);
     const named = matchChannelsByName(channels, raw);
     if (named.length === 1)
-        return named[0].channelId;
+        return named[0];
     if (named.length > 1) {
         throw new Error(`'${raw}' matches ${named.length} channels — pass the channel id instead (see \`hq channels\`).`);
     }
     const byId = channels.find((c) => c.channelId === raw);
     if (byId)
-        return byId.channelId;
+        return byId;
     throw new Error(`No channel named or with id '${raw}' — run \`hq channels\` to see yours.`);
 }
 async function runDmChannel(target, opts) {
     try {
         const token = await ensureCognitoToken();
-        const channelId = await resolveChannelId(token, target);
+        const channel = await resolveChannel(token, target);
+        const channelId = channel.channelId;
         const query = {};
         if (opts.limit)
             query.limit = opts.limit;
@@ -1268,7 +1274,17 @@ async function runDmChannel(target, opts) {
             console.log(JSON.stringify(ordered, null, 2));
         }
         else if (ordered.length === 0) {
-            console.log(chalk.dim("No messages in this channel yet."));
+            const channelType = channel.scope === "personal"
+                ? "personal"
+                : channel.scope === "group"
+                    ? "group"
+                    : "shared";
+            const channelName = channel.name?.trim() || channel.slug?.trim() || channelId;
+            const requestedTarget = target.trim().replace(/^#/, "");
+            const sendTarget = requestedTarget === channelId
+                ? channelId
+                : channel.slug?.trim() || requestedTarget;
+            console.log(chalk.dim(`No messages in ${channelType} channel "${channelName}" yet.\nSend a message with: hq dm ${sendTarget} "Hello"`));
         }
         else {
             console.log(chalk.green(`${ordered.length} message${ordered.length === 1 ? "" : "s"}:`));

package/dist/commands/files-browse.js

@@ -63,6 +63,11 @@ export function parseCompanySlugFromPath(prefix) {
     }
     return parts[1];
 }
+// Normalize personal paths before using them as S3 list prefixes.
+function normalizePersonalBrowsePrefix(pathPrefix) {
+    const normalized = pathPrefix.replace(/^\/+/, "");
+    return /^[/.]+$/.test(normalized) ? "" : normalized;
+}
 /**
  * Translate a CLI `companies/<slug>/…` path into the company-relative S3 key
  * the vault bucket actually stores. Company vault buckets are already
@@ -277,10 +282,17 @@ export async function runBrowse(input) {
     }
     // Company vault keys are company-relative (no `companies/<slug>/` prefix), so
     // translate the CLI's anchored prefix into the bucket-relative form before
-    // listing. Personal-mode paths are already bucket-relative.
-    const listPrefix = personalMode || slug === undefined
-        ? pathPrefix
-        : toBucketRelative(pathPrefix, slug);
+    // listing. Personal-mode paths are normalized in bucket-relative form.
+    const bucketPrefix = personalMode
+        ? normalizePersonalBrowsePrefix(pathPrefix)
+        : slug === undefined
+            ? pathPrefix
+            : toBucketRelative(pathPrefix, slug);
+    // Company callers can spell the bucket root as `/` or `.`. S3's empty
+    // Prefix is the root; passing either literal would list under that key.
+    const listPrefix = !personalMode && (bucketPrefix === "/" || bucketPrefix === ".")
+        ? ""
+        : bucketPrefix;
     // Pull the caller's explicit-grant graph once so per-key classification is
     // O(grants) without N round-trips. Retain the raw pattern after stripping
     // only the redundant company anchor: `foo/` and `foo/*` have different

package/dist/commands/lanes-message.js

@@ -220,9 +220,23 @@ export function createLaneMessageHandlers(deps) {
             storySwitchDeliveryStarted = true;
             opts.onAccepted?.();
         };
+        if (opts.text !== undefined && opts.textFile !== undefined) {
+            throw new LanesError("message_text_source_conflict", "Pass either --text or --text-file, not both", { lane_id: laneId });
+        }
         let text = opts.text;
-        if (!text) {
-            throw new LanesError("missing_text", "--text is required", {});
+        if (opts.textFile !== undefined) {
+            const textPath = path.isAbsolute(opts.textFile)
+                ? opts.textFile
+                : path.resolve(ctx.callerCwd(), opts.textFile);
+            try {
+                text = ctx.readFileSync(textPath, "utf8");
+            }
+            catch (err) {
+                throw new LanesError("message_text_file_unreadable", `Could not read message text file ${opts.textFile}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: laneId, path: textPath });
+            }
+        }
+        if (text === undefined || text.length === 0) {
+            throw new LanesError("missing_text", "Pass non-empty message text with --text or --text-file", { lane_id: laneId });
         }
         let resolution;
         try {
@@ -261,6 +275,7 @@ export function createLaneMessageHandlers(deps) {
                 : undefined;
             await dispatchOutpostLaneCommand(ctx, lane, "message", {
                 ...opts,
+                text,
                 ...(supersededMessageCallerId === undefined ? {} : { supersededMessageCallerId }),
                 ...(supersededMessageSessionId === undefined ? {} : { supersededMessageSessionId }),
             }, {

package/dist/commands/lanes-shared.d.ts

@@ -35,6 +35,7 @@ export interface ResumeProfileRepinAuthorization {
 }
 export interface LaneMessageOptions {
     text?: string;
+    textFile?: string;
     project?: string;
     story?: string;
     compact?: boolean;