@indigoai-us/hq-cli 5.345.187 → 5.345.189

package/CHANGELOG.md

@@ -2,6 +2,117 @@
 
 ## [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
+  numeric `Retry-After` up to 5 s, when the token mint is held by another process, the request times out or
+  fails in transport, or the server answers 408, 425, 429, 500, 502 or 503. A 504 is left to the existing
+  single retry inside the API client, and a 401, 403, 404 or an invalid 200 body is not retried. The
+  deadline now reaches the hq-cloud mint, so a retry no longer queues behind a first mint that is still
+  waiting on another process's lock. The list command sets `HQ_MACHINE_CREDS_FILE`,
+  `HQ_REQUIRE_MACHINE_IDENTITY` and `HQ_VAULT_API_URL` before minting, as `hq agent inbox done` already did.
+  The JSON output gains `stale: true|false` next to `source`; whenever a retry happened, including one that
+  succeeded, it also carries `attempts: 2`, and a note that still reports a fallback ends with
+  "(after 2 attempts)", so automation can tell a hard failure from a single blip (DEV-4065).
+- Keep downloaded revisions current and retry locally deleted files until the cloud confirms their removal.
+
 ## [5.345.187] — 2026-10-30
 - The HQ Anywhere person gate now follows the desktop Settings key `hq-anywhere-opt-out`. Turning HQ Anywhere on in the app enables `hq mcp serve` without a separate `hq-anywhere` write. Older servers that only have `hq-anywhere` still work.
 

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/agent-inbox.js

@@ -8,6 +8,7 @@ import chalk from "chalk";
 import * as os from "node:os";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { annotateInboxAttempts, fetchServerInboxWithRetry, parseRetryAfterSeconds, resolveAgentInboxTimeoutMs } from "../lib/agent-kit/inbox-fetch.js";
 import { redactAgentInboxItem } from "../lib/agent-kit/inbox-redact.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../lib/agent-kit/inbox-state.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
@@ -23,25 +24,56 @@ export function registerAgentInboxCommand(agent) {
         const paths = agentKitPaths(os.homedir(), process.env);
         const creds = requireExternalCreds(paths);
         const done = readDoneIds(paths);
+        // Pin the enrolled machine identity and API, as `done` does below, so the
+        // mint cannot fall through to a person session or another API base.
+        process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
+        process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+        process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
         // Merged with the server, never the local mirror alone: a dead kit
         // poller would otherwise make this command answer confidently with
-        // yesterday's mail and no sign anything was wrong.
-        const { entries, note, source } = await mergeAgentInbox(paths, async () => {
-            const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
-            const res = await vaultApiFetch({
-                token,
-                baseUrl: creds.apiBaseUrl,
-                path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`,
+        // yesterday's mail and no sign anything was wrong. The server read is
+        // bounded and retried once (inbox-fetch.ts) so a shared-lock mint, a
+        // 503 with Retry-After or a hung socket does not become a fallback.
+        let attempts = 1;
+        const merged = await mergeAgentInbox(paths, async () => {
+            const outcome = await fetchServerInboxWithRetry({
+                timeoutMs: resolveAgentInboxTimeoutMs(process.env),
+                mint: (signal) => ensureCognitoToken({ tokenSource: "machine", interactive: false, signal }),
+                fetch: async (token, signal) => {
+                    const res = await vaultApiFetch({
+                        token,
+                        baseUrl: creds.apiBaseUrl,
+                        path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`,
+                        signal,
+                    });
+                    const retryAfterSeconds = parseRetryAfterSeconds(res.headers?.get?.("retry-after"));
+                    // Preserve a decode failure as an invalid body for mergeAgentInbox to
+                    // classify. Parser errors can contain response bytes: do not echo them.
+                    return {
+                        status: res.status,
+                        body: await res.json().catch(() => undefined),
+                        ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+                    };
+                },
             });
-            // Preserve a decode failure as an invalid body for mergeAgentInbox to
-            // classify. Parser errors can contain response bytes: do not echo them.
-            return { status: res.status, body: await res.json().catch(() => undefined) };
+            attempts = outcome.attempts;
+            if (!outcome.ok)
+                throw outcome.error;
+            return outcome.response;
         });
+        const { entries, note, source, stale, attempts: attemptsMade } = annotateInboxAttempts(merged, attempts);
         const rows = entries
             .filter((e) => opts.all || !done.has(e.id))
             .map((e) => summarizeInboxEntry(redactAgentInboxItem(e), done.has(e.id)));
         if (opts.json) {
-            console.log(JSON.stringify({ count: rows.length, source, messages: rows, ...(note ? { note } : {}) }, null, 2));
+            console.log(JSON.stringify({
+                count: rows.length,
+                source,
+                stale,
+                ...(attemptsMade !== undefined ? { attempts: attemptsMade } : {}),
+                messages: rows,
+                ...(note ? { note } : {}),
+            }, null, 2));
             return;
         }
         if (note)

package/dist/commands/agent-mcp.js

@@ -13,6 +13,7 @@ import * as os from "node:os";
 import { CLI_VERSION } from "../cli-version.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { parseRetryAfterSeconds } from "../lib/agent-kit/inbox-fetch.js";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { buildAgentMcpTools } from "../lib/agent-kit/mcp/tools.js";
@@ -59,7 +60,7 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
         HQ_VAULT_API_URL: creds.apiBaseUrl,
         NO_COLOR: "1",
     };
-    const getToken = () => ensureCognitoToken({ tokenSource: "machine", interactive: false });
+    const getToken = (signal) => ensureCognitoToken({ tokenSource: "machine", interactive: false, signal });
     let companyUid;
     return {
         creds,
@@ -89,9 +90,11 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
                 method: init?.method,
                 body: init?.body,
                 query: init?.query,
+                signal: init?.signal,
             });
             const body = await res.json().catch(() => ({}));
-            return { status: res.status, body };
+            const retryAfterSeconds = parseRetryAfterSeconds(res.headers.get("retry-after"));
+            return { status: res.status, body, ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}) };
         },
     };
 }

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