@indigoai-us/hq-cli 5.345.188 → 5.345.190

package/CHANGELOG.md

@@ -2,6 +2,137 @@
 
 ## [Unreleased]
 
+## [5.345.190] — 2026-11-01
+- `hq files purge <path> --version-id <id>` permanently deletes one old version of a vault file, after a confirmation prompt.
+- `hq bot create` / `hq bot start` on Windows: the shared HQ Fleet Runtime now
+  installs under `%USERPROFILE%\.hq-fleet\runtimes\<16 hex>\{v,s\r,s\d}` instead
+  of the 64-character identity plus `sources\runtime`, so the runtime's deepest
+  files stay under the 260-character Windows path limit when long paths are
+  off. Before, extraction stopped partway with "HQ Fleet Local runtime
+  extraction failed." Runtimes already installed under the old layout keep
+  working, and a half-extracted old one is removed. macOS and Linux paths are
+  unchanged.
+- HQ Fleet Local install steps now include the last lines of the failing
+  command's stderr in their error, and on Windows the CLI checks the runtime
+  archive's longest path before extracting and names the path limit and
+  `LongPathsEnabled` setting when it would not fit.
+- The CLI now warns on stderr when the HQ Fleet Local release manifest's
+  `compatibility.minimum_hq_cli_version` is newer than the running CLI. It does
+  not block the install.
+- `hq-hook`: the `block-credential-file-read` port follows the fixed bash guard
+  (hq-core-staging #1753, sha256 7c6a8cfa) and its pin moves to that version.
+  Zero-padded brace ranges are read in base 10 and long or stepped ranges
+  block; letter ranges expand exactly; the mktemp scan replacement is literal
+  (no `patsub_replacement`) with capped loops; `function name { ... }` bodies
+  are analysed; extglob groups are an unknown word part; and `ls`, `stat` and
+  the other metadata commands are not trusted after an alias, hash, enable,
+  PATH change, a write into a bin directory, or when named by a path outside
+  /bin, /usr/bin, /sbin and /usr/sbin. The port also picks up the guard's
+  cygpath and `upstream-pin.env` changes. The vendored fixture and corpus are
+  refreshed. The port flag stays off.
+- `hq sync now`: when the push leg holds files after an account sign-in change
+  on this computer, the push line now shows the held count, prints how to
+  release them (`hq sync held`, `hq sync release-held`), skips the "Sync now
+  complete" line and exits 1. Before, it printed "0 uploaded, 0 skipped" and a
+  success line (feedback_2356e54f).
+
+## [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

@@ -3243,6 +3243,35 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "purge";
+        readonly description: "Permanently delete ONE retained (noncurrent) version of an exact vault key, for example a version that held data which must not live in HQ. Owner only; audited; cannot be undone. Delete the file first if the version is current. Use --personal for your personal vault.";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options] <path>";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [{
+            readonly name: "path";
+            readonly required: true;
+            readonly variadic: false;
+            readonly description: "";
+        }];
+        readonly options: readonly [{
+            readonly flags: "--personal";
+            readonly description: "Target your own personal vault instead of a company vault (mutually exclusive with --company)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--version-id <id>";
+            readonly description: "Exact version ID to purge (see `hq files versions`)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "-y, --yes";
+            readonly description: "Skip the confirmation prompt (for scripts)";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "trash";
         readonly description: "List deleted vault keys retained as tombstones. Use --personal for your personal vault.";
@@ -4175,6 +4204,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

@@ -3912,6 +3912,42 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "purge",
+                "description": "Permanently delete ONE retained (noncurrent) version of an exact vault key, for example a version that held data which must not live in HQ. Owner only; audited; cannot be undone. Delete the file first if the version is current. Use --personal for your personal vault.",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <path>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "path",
+                        "required": true,
+                        "variadic": false,
+                        "description": ""
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--personal",
+                        "description": "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--version-id <id>",
+                        "description": "Exact version ID to purge (see `hq files versions`)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "-y, --yes",
+                        "description": "Skip the confirmation prompt (for scripts)",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "trash",
                 "description": "List deleted vault keys retained as tombstones. Use --personal for your personal vault.",
@@ -5059,6 +5095,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/cloud.js

@@ -2351,12 +2351,19 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         }
         const pushProgressCompany = personalMode ? null : (pushSlug ?? null);
         const planLimitTracker = createPlanLimitRefusalTracker(companySlugForBilling(pushProgressCompany));
+        // feedback_2356e54f: the push leg held files after an account switch and
+        // still printed "0 uploaded, 0 skipped" and "Sync now complete".
+        const pushIdentityHeld = createIdentityHeldTracker();
+        const pushRecord = trackingProgressRecorder(planLimitTracker, pushProgressCompany);
         const pushResult = await share({
             paths: pushPaths,
             company: targetCompany,
             vaultConfig,
             hqRoot,
-            progressRecorder: trackingProgressRecorder(planLimitTracker, pushProgressCompany),
+            progressRecorder: (event) => {
+                pushIdentityHeld.observe(event);
+                pushRecord(event);
+            },
             skipUnchanged: true,
             serverOwnedPathPolicy: "skip",
             propagateDeletes: true,
@@ -2370,7 +2377,9 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         });
         const pushRefused = planLimitTracker.summary();
         const pushUploadFailed = readUploadFailures(pushResult);
+        const pushHeldCount = pushIdentityHeld.count();
         const pushStatus = pushResult.aborted ||
+            pushHeldCount > 0 ||
             pushResult.filesExcludedByScope > 0 ||
             (pushResult.filesRefusedStale ?? 0) > 0 ||
             pushUploadFailed.count > 0 ||
@@ -2380,6 +2389,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         console.log(`    ${pushStatus} ` +
             `${pushResult.filesUploaded} uploaded, ${pushResult.filesSkipped} skipped, ` +
             `${pushResult.filesDeleted} deleted, ${pushResult.filesExcludedByScope} scope-excluded` +
+            (pushHeldCount > 0 ? `, ${pushHeldCount} held` : "") +
             (pushResult.aborted ? " — aborted" : "") +
             (pushRefused
                 ? ` — ${describeRefusedCount(pushRefused)} refused (new files paused)`
@@ -2397,6 +2407,9 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         for (const line of uploadFailedLines(pushUploadFailed.count, pushUploadFailed.paths)) {
             console.log(chalk.yellow(line));
         }
+        for (const line of identityHeldLines(pushHeldCount)) {
+            console.log(chalk.yellow(line));
+        }
         if (pushResult.aborted) {
             console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
             throw new SyncExitError(1);
@@ -2519,7 +2532,8 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         }
         if (pushResult.filesExcludedByScope > 0 ||
             (pushResult.filesRefusedStale ?? 0) > 0 ||
-            pushUploadFailed.count > 0) {
+            pushUploadFailed.count > 0 ||
+            pushHeldCount > 0) {
             console.log(chalk.yellow("\n⚠ Sync now finished, but one or more requested uploads were refused."));
             throw new SyncExitError(1, { health: "succeeded" });
         }

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