@indigoai-us/hq-cli 5.345.188 → 5.345.189

package/CHANGELOG.md

@@ -2,6 +2,103 @@
 
 ## [Unreleased]
 
+## [5.345.189] — 2026-11-01
+- A local bot that cannot reach HQ when it starts now retries the identity check up to five times
+  (waits of 5 s, 15 s, 45 s and 2 min) on a network error (connection refused, reset, DNS failure,
+  timeout), 408, 429 or 5xx. Before, one network error at startup failed the bot with exit 0, which
+  launchd never restarts, so bots stayed down until someone restarted them. After the last try the bot
+  stops in the failed state with a plain reason that says to check the network and run
+  `hq bot start <name>`. Other 4xx answers, sign-in errors and internal errors fail at once, as before.
+  A stop during a retry wait ends the bot cleanly as stopped.
+- Hosted agent Docker image now runs on Node 26 (was Node 22).
+- Updated 16 bundled libraries to their latest minor and patch releases. The local search engine stays on its current version so installing HQ still works on machines without build tools.
+- On Windows, the CLI's last-resort HQ folder is now `C:\hq` (`%SystemDrive%\hq`) instead of
+  `%USERPROFILE%\hq`. `$HQ_ROOT`, the HQ folder you are inside, and the location recorded in
+  `~/.hq/menubar.json` or `~/.hq/config.json` still win. Discovery checks the home folders first
+  (`C:\Users\<you>\hq` and the usual variants), then `C:\hq`, then `%LOCALAPPDATA%\hq`, so an
+  existing home install keeps working and is preferred over a stray `C:\hq`.
+  macOS and Linux are unchanged.
+- `hq bot create` no longer hangs before it reaches the server. The Fleet
+  Runtime setup steps (`gh auth token`, `tar`, `uv python install`,
+  `uv python find`) now time out and report "timed out after Ns".
+  - Under `--json`, any create failure prints a `{ ok: false, reason:
+    "create-failed" }` document on stdout, so HQ Desktop can show it.
+- `hq bot probe` and bot failure messages now recognize a coding tool's plan
+  usage limit (for example Claude Code's "You've hit your weekly limit · resets
+  9pm"). They used to call it `unknown`. It is now classed `transient`, the
+  probe's JSON gains `usageLimit: true` and `resetsAt` when the tool gives a
+  reset time, and the detail says the plan hit its limit and when it resets.
+- `hq dm attachment <eventId|vaultPath>` downloads a file attached to a DM.
+  - The recipient can now open a file held in the sender's vault.
+  - The sender can open its own attachment.
+  - Several files with the same name on one message are saved as
+    name.ext, name-1.ext, and so on.
+  - Every destination is checked before any file is written.
+- A company's `INDEX.md` now shows a project's own recorded status instead of listing every unfinished project as active. `hq core rebuild-index companies` reads the project's `state.json` status first, then `prd.json` `status` or `metadata.status`, and only then falls back to the story-pass check.
+- `hq core rebuild-index companies` in a company-bound session now rebuilds only that session's companies, even when the company-scope kill switch is off. Before, it could rewrite every company's INDEX.md. `--company <slug>` works again for a company inside the bound set.
+- `hq sources schedule --at HH:MM` now turns the daily hot-channel sync on when a company doesn't have it yet. It registers the sync on your personal setup bot and sets the time. Before this change, the command failed with "No hot-channel sync job", so the desktop's Change time couldn't start the sync.
+- `hq-hook dispatch <EVENT>` runs a hook event the way master-hook.sh does,
+  in one process (US-007).
+  - Registry hooks come from the compiled index, through the hook-gate
+    profiles, `HQ_DISABLED_HOOKS` and the prefilters. Folder hooks run after
+    them in master-hook's order.
+  - A fail-closed PreToolUse guard that is missing, crashes or times out
+    blocks the event and names the guard. Every hook failure is recorded in
+    `~/.hq/logs/hook-engine.jsonl`.
+  - Built-in hook ports run in-process under the bridge flags; a port that
+    panics makes the bash hook run.
+  - Events the engine cannot reproduce exactly (session start, per-agent
+    scope, the timeout sentry, HQ Anywhere routing) run through
+    master-hook.sh with the same input.
+  - Nothing is registered to use it yet; exec-form registration (US-015) and
+    the cutover (US-017) come later.
+- `hq-hook` gains a compiled hook index (US-006): one memory-mapped file per
+  HQ root and policy-directory list with the hook registry rows, the
+  `policy_vocab` prefilter vocabulary and the policy injector's parsed records.
+  - It rebuilds only when a source file's metadata changes. A symlink is
+    tracked by the file it points to, so re-linking the personal overlay does
+    not rebuild it.
+  - Each company's index holds only that company's policies.
+  - `hq-hook index records|vocab|registry` print the same bytes as the shell
+    code they replace, which the new parity test checks.
+  - `hq-hook index probe|bench` measure the per-event cost for the
+    go/no-go report. Nothing in the hook path uses the index yet; the
+    dispatcher (US-007) will.
+- `hq-hook run block-credential-file-read` is now a full native port of the
+  bash guard and its arithmetic library, under flag
+  `hook-engine-port-block-credential-file-read`, which stays off.
+  - It answers every call itself and never exits 75 (hand back to bash).
+  - Exit code, stdout and stderr match the guard byte for byte on the guard's
+    corpus (about 1,500 payloads), 330 recorded real calls and about 6,800
+    fuzz payloads.
+  - The bridge now also pins `bash-arith-subst-guard-lib.sh`. A changed or
+    missing library sends the call to bash, as a changed guard does.
+- `hq-hook run block-credential-file-read` is the second hook port
+  master-hook.sh can bridge (US-022, flag
+  `hook-engine-port-block-credential-file-read`, default off).
+  - It answers natively the Read and Bash calls that the guard's own fast path
+    allows and that name no credential file, pass through no symlink and use
+    no substitution.
+  - Every other call exits 75 and the bash guard decides, keeping its
+    fail-closed behavior.
+  - The port never blocks.
+  - It is pinned to the guard version it was checked against.
+  - The guard's 400-payload corpus shows zero verdict differences with the
+    port in front.
+- `hq-hook`: the `block-credential-file-read` port accepts the guard script on
+  hq-core-staging main (9be16758, #1727). The guard's fast path gained the
+  arithmetic guard, the split-name rule, the `git show <ref>:<path>` rule and
+  an xargs/parallel prefilter term since the port was written; the port now
+  declines every command those can refuse (`$`, `((`, declaration keywords,
+  the new prefilter term) and keeps answering only what bash's fast path
+  allows. The vendored fixture and corpus are refreshed to that version.
+- `hq-hook`: the `policy-enforcement-gate` port accepts the gate script from
+  hq-core-staging #1717 (read-only `hq dm` subcommands skipped by the outbound
+  scan). Without this pin the bridge logged `script-mismatch` on every current
+  HQ and ran bash alone. The port's allow set is unchanged: it already leaves
+  every command naming `hq` and `dm` to bash. The vendored fixture is refreshed
+  to that version and the pin test covers it.
+
 ## [5.345.188] — 2026-10-30
 - `hq agent inbox` and the `hq_inbox_read` MCP tool now bound the server read (token mint plus GET) at 30 s
   (`HQ_AGENT_INBOX_TIMEOUT_MS`, floor 1000) and retry it once after a short delay, honouring the server's

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

@@ -4175,6 +4175,40 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "attachment";
+        readonly description: "Download a file attached to a DM. REF is the message eventId from `hq dm inbox` (downloads every file on it) or the attachment's vault path (chat/attachments/...). The file is read from the sender's vault; only the two people in the conversation can open a DM attachment.";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options] <ref>";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [{
+            readonly name: "ref";
+            readonly required: true;
+            readonly variadic: false;
+            readonly description: "";
+        }];
+        readonly options: readonly [{
+            readonly flags: "--out <path>";
+            readonly description: "Where to write: a file path for one attachment, else a directory (default: current directory)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--company <uid>";
+            readonly description: "Vault scope the file lives in (the companyUid shown on the message). Derived from the DM pair when omitted";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--force";
+            readonly description: "Overwrite an existing file";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--limit <n>";
+            readonly description: "How many recent inbox messages to search for the eventId";
+            readonly hidden: false;
+            readonly defaultValue: "100";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "thread";
         readonly description: "Show your two-way conversation with a person (email, personUid, or agentUid). Reads oldest-first and marks their messages read unless --no-ack.";

package/dist/command-catalog.generated.js

@@ -5059,6 +5059,48 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "attachment",
+                "description": "Download a file attached to a DM. REF is the message eventId from `hq dm inbox` (downloads every file on it) or the attachment's vault path (chat/attachments/...). The file is read from the sender's vault; only the two people in the conversation can open a DM attachment.",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <ref>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "ref",
+                        "required": true,
+                        "variadic": false,
+                        "description": ""
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--out <path>",
+                        "description": "Where to write: a file path for one attachment, else a directory (default: current directory)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--company <uid>",
+                        "description": "Vault scope the file lives in (the companyUid shown on the message). Derived from the DM pair when omitted",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--force",
+                        "description": "Overwrite an existing file",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--limit <n>",
+                        "description": "How many recent inbox messages to search for the eventId",
+                        "hidden": false,
+                        "defaultValue": "100"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "thread",
                 "description": "Show your two-way conversation with a person (email, personUid, or agentUid). Reads oldest-first and marks their messages read unless --no-ack.",

package/dist/commands/bot.js

@@ -665,8 +665,20 @@ async function promptFleetProvider() {
  * its half-written folder.
  */
 export async function runBotCreate(nameArg, opts) {
-    const name = validateBotName(nameArg);
-    await withBotLock(name, () => runBotCreateLocked(name, opts), { command: "hq bot create" });
+    try {
+        const name = validateBotName(nameArg);
+        await withBotLock(name, () => runBotCreateLocked(name, opts), { command: "hq bot create" });
+    }
+    catch (err) {
+        // Under --json the desktop app reads stdout: a failure, including one in
+        // the local steps before the create reaches HQ, must leave a document
+        // there too, not only a line on stderr.
+        if (opts.json && !err?.jsonReported) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.log(JSON.stringify({ ok: false, name: nameArg, reason: "create-failed", message }, null, 2));
+        }
+        throw err;
+    }
 }
 /**
  * Write a bot's new name to the cloud. Never fails the caller's command when
@@ -880,7 +892,7 @@ async function runBotCreateLocked(name, opts) {
                 return false;
             if (opts.json)
                 console.log(JSON.stringify({ ok: false, ...failure }, null, 2));
-            throw Object.assign(new Error(failure.message), { expected: true });
+            throw Object.assign(new Error(failure.message), { expected: true, jsonReported: opts.json === true });
         }
         const matches = matchRemoteBots(mine, name);
         if (matches.length > 1) {

package/dist/commands/core-company-index-scope-flag.d.ts

@@ -4,7 +4,8 @@ export { CORE_COMPANY_INDEX_SCOPE_FLAG };
  * Kill switch for company-scoped index rebuilds, default ON
  * (indigo-feature-flags-default-on-as-fail-safes). An absent, archived or
  * unreadable flag row keeps scoping on; only an explicit false turns it off,
- * and then `companies` rebuilds every company as it did before scoping.
+ * and then an unbound `companies` rebuild writes every company as it did
+ * before scoping. A bound session stays scoped either way.
  */
 export declare function coreCompanyIndexScopeEnabled(): boolean;
 //# sourceMappingURL=core-company-index-scope-flag.d.ts.map

package/dist/commands/core-company-index-scope-flag.js

@@ -5,7 +5,8 @@ export { CORE_COMPANY_INDEX_SCOPE_FLAG };
  * Kill switch for company-scoped index rebuilds, default ON
  * (indigo-feature-flags-default-on-as-fail-safes). An absent, archived or
  * unreadable flag row keeps scoping on; only an explicit false turns it off,
- * and then `companies` rebuilds every company as it did before scoping.
+ * and then an unbound `companies` rebuild writes every company as it did
+ * before scoping. A bound session stays scoped either way.
  */
 export function coreCompanyIndexScopeEnabled() {
     return resolveProcessFlagGate(CORE_COMPANY_INDEX_SCOPE_FLAG, { fallback: true }, () => true, undefined, { acceptStaleSnapshot: true, killSwitchWithoutCompany: true });

package/dist/commands/core.js

@@ -668,7 +668,6 @@ export function registerCoreCommands(program) {
         const passthrough = operands.slice(1);
         const force = passthrough.includes("--accept");
         const rendererArgs = passthrough.filter((arg) => arg !== "--accept");
-        const isCompaniesTarget = entry.renderer === "companies";
         const wantsHelp = rendererArgs.some((arg) => arg === "--help" || arg === "-h");
         if (wantsHelp && ["companies", "company-knowledge", "projects"].includes(entry.renderer)) {
             renderIndexTarget(entry.renderer, { root: "", output: (message) => process.stdout.write(message) }, rendererArgs);
@@ -681,10 +680,6 @@ export function registerCoreCommands(program) {
             process.stdout.write(`Usage: hq core rebuild-index ${entry.target} [--accept]\n\n${entry.summary}. Help performs no writes.\n`);
             return;
         }
-        const requestsCompanyScope = isCompaniesTarget && rendererArgs.some((arg) => arg === "--company" || arg.startsWith("--company="));
-        if (requestsCompanyScope && !coreCompanyIndexScopeEnabled()) {
-            throw expectedUserError("rebuild-index companies --company is disabled; enable cli.rebuild-index-company-scope for a canary.");
-        }
         const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
         const refused = [];
         try {

package/dist/commands/dm-attach.d.ts

@@ -103,4 +103,77 @@ export declare function attachmentScopeForChannel(channel: {
 export declare function personalScopeForCaller(callerUid: string | undefined): string;
 /** Render the confirmation lines listing where each attachment landed. */
 export declare function formatUploadedAttachments(files: readonly DmAttachmentWire[]): string;
+/** A parsed chat attachment key: chat/attachments/<dm|chan>/<scopeId>/<file>. */
+export interface ParsedChatAttachmentKey {
+    scope: "dm" | "chan";
+    scopeId: string;
+    file: string;
+}
+/**
+ * Parse a chat attachment vault key. Returns null for anything that is not a
+ * single file directly under a conversation folder (no nesting, no `..`). Pure.
+ */
+export declare function parseChatAttachmentKey(key: string): ParsedChatAttachmentKey | null;
+/** One attachment reference as it appears on a message row. */
+export interface AttachmentRef {
+    vaultPath: string;
+    companyUid?: string;
+    name?: string;
+    /** Who sent the message carrying this attachment, when known. */
+    senderUid?: string;
+}
+/**
+ * The vault scopes to try, in order, for a READ of a chat attachment. An
+ * explicit `companyUid` (message metadata or `--company`) wins. Otherwise a
+ * 1:1 DM attachment lives in the SENDER's personal vault (see
+ * `personalScopeForCaller`): when `senderUid` is known and in the pair, that
+ * is the only scope. With no sender (a bare vault path), the pair id is sorted
+ * and does not say who sent it, so the counterparty's vault is tried first and
+ * then the caller's own (the caller may be the sender). The server enforces
+ * that the caller is one of the two; this only picks the vault. Throws when no
+ * scope can be decided. Pure.
+ */
+export declare function attachmentReadScopes(args: {
+    vaultPath: string;
+    companyUid?: string;
+    callerUid?: string;
+    senderUid?: string;
+}): string[];
+/** The first (most likely) read scope from `attachmentReadScopes`. Pure. */
+export declare function attachmentReadScope(args: {
+    vaultPath: string;
+    companyUid?: string;
+    callerUid?: string;
+    senderUid?: string;
+}): string;
+/**
+ * The attachments on the message with `eventId` (or `messageId`) in a list of
+ * message rows. Returns null when no row matches. Pure.
+ */
+export declare function findMessageAttachments(rows: ReadonlyArray<{
+    eventId?: string;
+    messageId?: string;
+    fromPersonUid?: string;
+    attachments?: AttachmentRef[];
+    attachment?: AttachmentRef;
+}>, eventId: string): AttachmentRef[] | null;
+export interface AttachmentDownloadDeps {
+    /** POST /v1/files/presign with `{ company, keys }`. */
+    presign: (token: string, body: Record<string, unknown>) => Promise<Response>;
+    /** GET the presigned URL. */
+    get: (url: string) => Promise<Response>;
+}
+export declare const defaultAttachmentDownloadDeps: AttachmentDownloadDeps;
+/**
+ * Presign a GET for one chat attachment in `scopeUid` and return its bytes.
+ * hq-pro files-presign admits a counterparty read of the sender's personal
+ * vault only when the caller is a member of the DM pair; a refusal (whole
+ * request or per key) surfaces as an Error.
+ */
+export declare function downloadChatAttachment(args: {
+    token: string;
+    scopeUid: string;
+    vaultPath: string;
+    deps?: AttachmentDownloadDeps;
+}): Promise<Buffer>;
 //# sourceMappingURL=dm-attach.d.ts.map

package/dist/commands/dm-attach.js

@@ -193,4 +193,108 @@ export function formatUploadedAttachments(files) {
         .map((f) => `  [file] ${f.name} (${formatBytes(f.sizeBytes)})\n     vault: ${f.vaultPath}`)
         .join("\n");
 }
+/**
+ * Parse a chat attachment vault key. Returns null for anything that is not a
+ * single file directly under a conversation folder (no nesting, no `..`). Pure.
+ */
+export function parseChatAttachmentKey(key) {
+    const parts = key.trim().split("/");
+    if (parts.length !== 5)
+        return null;
+    const [a, b, scope, scopeId, file] = parts;
+    if (a !== "chat" || b !== "attachments")
+        return null;
+    if (scope !== "dm" && scope !== "chan")
+        return null;
+    if (!scopeId || scopeId === "." || scopeId === "..")
+        return null;
+    if (!file || file === "." || file === "..")
+        return null;
+    return { scope, scopeId, file };
+}
+/**
+ * The vault scopes to try, in order, for a READ of a chat attachment. An
+ * explicit `companyUid` (message metadata or `--company`) wins. Otherwise a
+ * 1:1 DM attachment lives in the SENDER's personal vault (see
+ * `personalScopeForCaller`): when `senderUid` is known and in the pair, that
+ * is the only scope. With no sender (a bare vault path), the pair id is sorted
+ * and does not say who sent it, so the counterparty's vault is tried first and
+ * then the caller's own (the caller may be the sender). The server enforces
+ * that the caller is one of the two; this only picks the vault. Throws when no
+ * scope can be decided. Pure.
+ */
+export function attachmentReadScopes(args) {
+    const parsed = parseChatAttachmentKey(args.vaultPath);
+    if (!parsed) {
+        throw new Error(`Not a chat attachment path: ${args.vaultPath}. Expected chat/attachments/dm/<uidA--uidB>/<file> or chat/attachments/chan/<channelId>/<file>.`);
+    }
+    const explicit = args.companyUid?.trim();
+    if (explicit)
+        return [explicit];
+    if (parsed.scope === "chan") {
+        throw new Error("A channel attachment needs its vault scope. Pass --company <uid> with the companyUid shown on the message.");
+    }
+    const pair = parsed.scopeId.split("--").filter(Boolean);
+    const me = args.callerUid?.trim();
+    if (pair.length !== 2 || !me || !pair.includes(me)) {
+        throw new Error("This DM attachment is not from a conversation you are part of, or your uid could not be read. Pass --company <uid> with the companyUid shown on the message.");
+    }
+    const sender = args.senderUid?.trim();
+    if (sender && pair.includes(sender))
+        return [sender];
+    const other = pair[0] === me ? pair[1] : pair[0];
+    return [other, me];
+}
+/** The first (most likely) read scope from `attachmentReadScopes`. Pure. */
+export function attachmentReadScope(args) {
+    return attachmentReadScopes(args)[0];
+}
+/**
+ * The attachments on the message with `eventId` (or `messageId`) in a list of
+ * message rows. Returns null when no row matches. Pure.
+ */
+export function findMessageAttachments(rows, eventId) {
+    const id = eventId.trim();
+    const row = rows.find((r) => r.eventId === id || r.messageId === id);
+    if (!row)
+        return null;
+    const list = row.attachments?.length ? row.attachments : row.attachment ? [row.attachment] : [];
+    const sender = row.fromPersonUid?.trim();
+    return list
+        .filter((a) => Boolean(a?.vaultPath))
+        .map((a) => (sender && !a.senderUid ? { ...a, senderUid: sender } : a));
+}
+export const defaultAttachmentDownloadDeps = {
+    presign: (token, body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
+    get: (url) => fetch(url),
+};
+/**
+ * Presign a GET for one chat attachment in `scopeUid` and return its bytes.
+ * hq-pro files-presign admits a counterparty read of the sender's personal
+ * vault only when the caller is a member of the DM pair; a refusal (whole
+ * request or per key) surfaces as an Error.
+ */
+export async function downloadChatAttachment(args) {
+    const deps = args.deps ?? defaultAttachmentDownloadDeps;
+    const res = await deps.presign(args.token, {
+        company: args.scopeUid,
+        keys: [{ key: args.vaultPath, op: "get" }],
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        const message = typeof err.error === "string" ? err.error : typeof err.message === "string" ? err.message : res.statusText;
+        throw new Error(`Could not open the attachment (HTTP ${res.status}): ${message}`);
+    }
+    const data = (await res.json().catch(() => ({})));
+    const row = (data.results ?? []).find((r) => Boolean(r) && typeof r === "object" && r.key === args.vaultPath);
+    if (!row || typeof row.url !== "string") {
+        const reason = typeof row?.error === "string" ? row.error : "the vault refused the read";
+        throw new Error(`Attachment refused: ${args.vaultPath}: ${reason}`);
+    }
+    const got = await deps.get(row.url);
+    if (!got.ok) {
+        throw new Error(`Download failed for ${args.vaultPath} (HTTP ${got.status}).`);
+    }
+    return Buffer.from(await got.arrayBuffer());
+}
 //# sourceMappingURL=dm-attach.js.map

package/dist/commands/dm.d.ts

@@ -443,5 +443,15 @@ export declare function formatChannelTranscript(messages: ChannelMessageItem[],
  */
 export declare function agentCallerUid(token: string, machine?: () => boolean): string | null;
 export declare const AGENT_THREAD_UNAVAILABLE: string;
+/**
+ * Where to write each downloaded attachment. One file and an `--out` that is
+ * not an existing directory: write exactly there. Otherwise `--out` (default
+ * cwd) is a directory and each file keeps its sanitized name. Pure apart from
+ * the injected `isDir`.
+ */
+export declare function attachmentOutputPaths(refs: ReadonlyArray<{
+    vaultPath: string;
+    name?: string;
+}>, out: string | undefined, isDir: (p: string) => boolean): string[];
 export declare function registerDmCommand(program: Command): void;
 //# sourceMappingURL=dm.d.ts.map

package/dist/commands/dm.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join as pathJoin } from "node:path";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { resolveCallerPersonUid, resolveDestinationCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { isMachineIdentity } from "@indigoai-us/hq-cloud";
@@ -10,7 +11,7 @@ import { EMAIL_PATTERN, RECIPIENT_UID_PATTERN, PERSON_AGENT_AUDIENCE_MESSAGE, PE
 import { callerIsMachinePrincipal } from "../lib/caller-principal.js";
 export { defaultAudienceFor, recipientKindOf };
 import { dmForwardCliEnabled } from "./dm-forward-flag.js";
-import { attachmentScopeForChannel, formatUploadedAttachments, personalScopeForCaller, uploadDmAttachments, validateAttachmentPaths, } from "./dm-attach.js";
+import { attachmentReadScopes, attachmentScopeForChannel, downloadChatAttachment, findMessageAttachments, parseChatAttachmentKey, sanitizeAttachmentName, formatUploadedAttachments, personalScopeForCaller, uploadDmAttachments, validateAttachmentPaths, } from "./dm-attach.js";
 import { ChannelNotFoundError, suggestChannels, withChannelSuggestions, } from "./channel-suggest.js";
 /**
  * Classify a recipient arg as an email or a person/agent uid. Mirrors the
@@ -1679,6 +1680,107 @@ async function runDmInbox(opts) {
         process.exit(1);
     }
 }
+/**
+ * Where to write each downloaded attachment. One file and an `--out` that is
+ * not an existing directory: write exactly there. Otherwise `--out` (default
+ * cwd) is a directory and each file keeps its sanitized name. Pure apart from
+ * the injected `isDir`.
+ */
+export function attachmentOutputPaths(refs, out, isDir) {
+    const nameOf = (r) => sanitizeAttachmentName(r.name?.trim() || r.vaultPath.split("/").pop() || "file");
+    if (refs.length === 1 && out && !isDir(out))
+        return [out];
+    const dir = out ?? ".";
+    // Two files with the same sanitized name get distinct targets: name-1.ext, name-2.ext.
+    const used = new Set();
+    return refs.map((r) => {
+        const base = nameOf(r);
+        let name = base;
+        for (let n = 1; used.has(name); n++) {
+            const dot = base.lastIndexOf(".");
+            name = dot > 0 ? `${base.slice(0, dot)}-${n}${base.slice(dot)}` : `${base}-${n}`;
+        }
+        used.add(name);
+        return pathJoin(dir, name);
+    });
+}
+async function runDmAttachment(ref, opts) {
+    try {
+        const token = await ensureCognitoToken();
+        const callerUid = agentCallerUid(token) ?? (await callerUidForAttach(token));
+        let refs;
+        if (parseChatAttachmentKey(ref)) {
+            refs = [{ vaultPath: ref.trim() }];
+        }
+        else {
+            if (agentCallerUid(token)) {
+                throw new Error("Agents cannot look up an eventId in the person inbox. Pass the attachment's vault path instead.");
+            }
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/notify/inbox",
+                query: { limit: opts.limit ?? "100" },
+            });
+            if (!res.ok) {
+                const err = (await res.json().catch(() => ({})));
+                throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
+            }
+            const data = (await res.json());
+            const found = findMessageAttachments(data.events ?? [], ref);
+            if (found === null) {
+                throw new Error(`No message ${ref} in your last ${opts.limit ?? "100"} inbox messages. Raise --limit, or pass the attachment's vault path.`);
+            }
+            if (found.length === 0)
+                throw new Error(`Message ${ref} has no attachments.`);
+            refs = found;
+        }
+        const targets = attachmentOutputPaths(refs, opts.out, (p) => {
+            try {
+                return statSync(p).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        // Check every destination before writing anything, so a clash never leaves
+        // a partial download behind.
+        if (!opts.force) {
+            const clash = targets.find((dest) => existsSync(dest));
+            if (clash) {
+                throw new Error(`${clash} already exists. Pass --force to overwrite, or --out to choose another path.`);
+            }
+        }
+        const scopes = refs.map((r) => attachmentReadScopes({
+            vaultPath: r.vaultPath,
+            companyUid: opts.company ?? r.companyUid,
+            callerUid,
+            senderUid: r.senderUid,
+        }));
+        for (let i = 0; i < refs.length; i++) {
+            const r = refs[i];
+            const dest = targets[i];
+            let bytes;
+            let lastErr;
+            for (const scopeUid of scopes[i]) {
+                try {
+                    bytes = await downloadChatAttachment({ token, scopeUid, vaultPath: r.vaultPath });
+                    break;
+                }
+                catch (e) {
+                    lastErr = e;
+                }
+            }
+            if (!bytes)
+                throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+            writeFileSync(dest, bytes);
+            console.log(chalk.green(`Saved ${dest}`) + chalk.dim(` (${bytes.length} bytes)`));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
 async function runDmThread(identifier, opts) {
     try {
         const query = buildThreadQuery(identifier);
@@ -1879,6 +1981,16 @@ export function registerDmCommand(program) {
         .action(async (opts) => {
         await runDmInbox(opts);
     });
+    dm
+        .command("attachment <ref>")
+        .description("Download a file attached to a DM. REF is the message eventId from `hq dm inbox` (downloads every file on it) or the attachment's vault path (chat/attachments/...). The file is read from the sender's vault; only the two people in the conversation can open a DM attachment.")
+        .option("--out <path>", "Where to write: a file path for one attachment, else a directory (default: current directory)")
+        .option("--company <uid>", "Vault scope the file lives in (the companyUid shown on the message). Derived from the DM pair when omitted")
+        .option("--force", "Overwrite an existing file")
+        .option("--limit <n>", "How many recent inbox messages to search for the eventId", "100")
+        .action(async (ref, opts) => {
+        await runDmAttachment(ref, opts);
+    });
     dm
         .command("thread <person>")
         .alias("read")

package/dist/commands/sources.js

@@ -43,6 +43,7 @@ import { createPersonVaultReader } from "../lib/hot-channels/person-vault-reader
 import { S3Client } from "@aws-sdk/client-s3";
 import { resolveCanonicalPersonUid } from "./cloud.js";
 import { botsRoot as defaultBotsRoot } from "../lib/bot/paths.js";
+import { ensureHotSignalSyncJob } from "../lib/bot/jobs/hot-signal-sync.js";
 import { findHotSignalSyncJobs, lastRunsPerAdapter, parseDailyAt, renderScheduleReport, rescheduleDaily, toJobView, } from "../lib/hot-channels/schedule.js";
 import { listActiveMembers } from "./members.js";
 import { runOnDemandSync, } from "../lib/hot-channels/run.js";
@@ -619,6 +620,20 @@ export async function runSchedule(options, overrides = {}) {
         parseDailyAt(options.at);
     let found = findHotSignalSyncJobs(overrides.botsRoot ?? defaultBotsRoot(), company);
     if (options.at !== undefined) {
+        if (found.length === 0) {
+            // Setting a time turns the daily sync on: register it on the personal setup bot.
+            const root = overrides.botsRoot ?? defaultBotsRoot();
+            const setupDir = path.join(root, "setup");
+            if (fs.existsSync(setupDir)) {
+                const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+                const otherBotDirs = fs
+                    .readdirSync(root, { withFileTypes: true })
+                    .filter((d) => d.isDirectory())
+                    .map((d) => path.join(root, d.name));
+                ensureHotSignalSyncJob(setupDir, { company, timezone, otherBotDirs }, now);
+                found = findHotSignalSyncJobs(root, company);
+            }
+        }
         if (found.length === 0)
             throw new NoHotSignalSyncJobError(company);
         found = rescheduleDaily(found, options.at, now);