@indigoai-us/hq-cli 5.345.154 → 5.345.156

package/CHANGELOG.md

@@ -2,6 +2,144 @@
 
 ## [Unreleased]
 
+## [5.345.156] — 2026-10-21
+- `hq doctor --fix` stops pulling a company the sync service could not find
+  for your HQ account. When a pull fails because the company does not exist
+  for you or access is refused, the next check shows that company's stale
+  sync journal as "not on this machine" with one next step: check you are
+  signed in to the right account and ask to be re-invited, or delete the old
+  journal. It is no longer auto-fixable, so the client-health hook stops
+  reporting it. This classification requires another company pull to succeed
+  in the same run; an outage affecting every company remains visible. Any
+  later successful sync invalidates the cached failure, and `--fix` retries
+  unresolved companies after 14 days.
+- The same company's stale sync manifest now follows its journal: it shows as
+  "not on this machine" and `--fix` stops re-uploading it. A manifest upload
+  that fails with "No membership found" counts as the same evidence, under the
+  same rule that another company must succeed in that run. A later successful
+  sync or manifest upload clears it.
+- One `hq doctor --fix` run now refreshes up to 10 stale sync journals
+  instead of 2. Unattended runs (`--yes`) stop starting new pulls after 120
+  seconds so they still finish inside the health hook's time limit. When a
+  run stops early it says how many are left and asks you to run it again.
+- `hq files cat` / `get` and the agent file tools now say why a signed vault download failed after access was granted: a response that did not come from the storage host is reported as a likely proxy or egress block naming the host to allow, and a storage refusal shows S3's error code and request id. These failures no longer send you to `hq access`, which only re-checked the grant that had already passed.
+- `hq agent inbox --json` and the agent `hq_inbox_read` tool now include `source`: `server` when the server inbox was read, `local-mirror` when the server could not be reached and the list may be stale, so automation can tell a stale fallback from a real empty inbox.
+- Fix company knowledge and project index rebuilds to honor help and explicit
+  company arguments. Invalid arguments fail before writing, and a
+  company-scoped project rebuild leaves the personal index untouched.
+- `hq integrations call` has a new `--timeout <seconds>` option (default 270,
+  max 1800) that sets how long it waits for a call the gateway runs as a
+  background job. When a call that asked for background execution instead
+  comes back as an inline HTTP 500, 502 or 504, the error now says the call
+  likely hit the gateway's 30-second inline limit and that async integration
+  jobs must be enabled for the company, instead of only suggesting a retry.
+  Feedback 4b2573d6-fab7-4b63-8fa6-f50b472a887f.
+- Every `hq` command (including `hq secrets exec`) sends a client-health
+  heartbeat, and about once every 15 minutes that heartbeat re-reads the local
+  sync journals. That read loads the whole local sync state store into memory,
+  and on a large store it took the `hq` process itself to several GB. Commands
+  that are not sync commands now do this read in a separate child process
+  capped at a 512 MB heap and 20 seconds. If the child hits a cap, the command
+  keeps the last known sync time and does not retry the read for 15 minutes.
+  Sync commands still read the journals in-process.
+  Feedback d70e9d63-7b46-42bc-8c28-a545235cd7c6.
+- `hq secrets script approve --remote-path` now accepts a path relative to the
+  HQ root (for example `companies/<co>/skills/<skill>/<file>.mjs`). Once
+  hq-pro has the matching change deployed, that one approval matches the
+  script on every HQ root, including a hosted agent's. For a relative path a
+  leading `./` is dropped and `\` becomes `/`. Approve refuses, with a plain
+  error and no API call, a relative path that could never match: a bare file
+  name with no folder, a `.`, `..` or empty segment, a trailing `/`, a leading
+  `~`, a drive letter without a separator, or surrounding whitespace. An
+  absolute path is sent exactly as typed and must match exactly. If the
+  server answers without an active approval for the id (for example the id was
+  revoked earlier), approve now fails with a hint to use a new `--id` instead
+  of printing success. The success line names the stored path.
+  Feedback 6e0a1040-4d8e-4743-863e-386eb98aa0a4.
+- Installing the native hook engine no longer fails with `ERR_FS_CP_EEXIST` on
+  Node 24.22 and later. The engine is now copied into a new directory inside the
+  staging folder instead of onto the staging folder itself.
+
+## [5.345.155] — 2026-10-21
+- `hq secrets exec --personal` now works in a session locked to one company.
+  It injects your own personal-vault secrets into the command, read-only, and
+  appends one line per use to `workspace/audit/personal-secrets-use.jsonl`
+  (timestamp, session id, locked company, secret names; never values). If the
+  audit line cannot be written, nothing is read. In a company-locked session
+  every other personal-vault command (`set`, `get`, `list`, `env`, `delete`,
+  `share`, `generate-link`, `sandbox --personal` and the rest) is refused, as
+  is personal scope next to more than one locked company, API-key auth, or
+  another person's `prs_` scope. A `prs_`/`agt_` value passed as `--company`
+  is treated as personal scope and gets the same rules. Owner decision dq_20261020234444_f1b1ea4185;
+  feedback 5b6c67f7-59b1-410a-a4ee-b5db27fe7051.
+- Lanes flag reads now retry once on a timeout, network error or 5xx, and refresh the token once on a 401. When the registry is still unreachable (timeout, network error or 5xx), the read falls back to the last value the registry confirmed within the past 24 hours (kept in the HQ state dir) before the hard-coded default, so a brief registry outage no longer turns `monitor.enabled` off. A 401 after the refresh, a 403 or other 4xx, or a missing token never uses that cached value. `flag_read_failed` events now include the HTTP status, a redacted error message, the duration, and whether the cache was used.
+- `hq library add` now works on an `HQ_API_KEY` with upload rights
+  (`hq api-keys create --preset library-agent --allow-upload`) and no login.
+  `--company` takes the company's slug or its uid (`cmp_…`), and the
+  placeholder always goes under `companies/<slug>/library` (or a `--to` folder
+  inside `companies/<slug>/`), never a `companies/cmp_…` folder. On a key the
+  slug and uid are matched through `companies/manifest.yaml`, because a key
+  cannot read memberships. Before this, a key got "Could not load your
+  companies (HTTP 404). Run `hq login`." `hq library describe` had the same
+  problem and is fixed the same way. `hq library link` on a key now also
+  accepts `--company <slug>`, and with no `--company` it uses the
+  placeholder's company (`HQ_COMPANY_UID` still wins when set); before, both
+  failed and only `--company cmp_…` worked. A key without `files:write` now
+  gets "This API key cannot upload (missing files:write)" instead of the login
+  message. Signed-in use is unchanged, except that `--company` also accepts
+  the uid there.
+- `hq library add` and `hq library describe` now caption a HEIC/HEIF photo from
+  its primary image. Before, ffmpeg's default stream was used, which for an
+  iPhone HEIC is a single tile of the photo or, for Portrait-mode photos, the
+  black-and-white depth/segmentation matte, so captions described a blurry
+  fragment or "a segmentation mask". The primary image is decoded with `sips`
+  on macOS, then ImageMagick (`magick`, or `convert` outside Windows), then by
+  assembling ffmpeg's primary tile grid, and each result must be a valid JPEG
+  of at most 1024px before it is used; otherwise the previous ffmpeg behavior
+  is kept. HEIC/HEIF is detected by content as well as by a `.heic`, `.heif`
+  or `.hif` name in any case. Photos shot upside down or sideways are turned
+  upright on the `sips` and ImageMagick paths, and the `sips` frame has its
+  EXIF/XMP removed before it is sent for captioning. `.heif` files are now
+  uploaded as `image/heif` and captioned. Other image formats and videos are
+  unchanged, and captioning still never blocks an upload.
+- `hq library rm <placeholder-or-original> [more...]` (alias `remove`) removes
+  company library assets. It deletes the local original if one was fetched
+  (only when its sha256 matches the library copy), then the local placeholder,
+  then the placeholder's vault copy, in that order so sync cannot bring the
+  placeholder back midway. It previews and asks first; `--yes` skips the
+  question, `--dry-run` changes nothing, and `--json` prints the result as
+  JSON. The shared blob `.hq-offload/blobs/<sha256>` is kept by default,
+  because other placeholders (including teammates') may use the same bytes.
+  `--purge` also deletes the blob, and is refused if any other placeholder in
+  the local tree or the company vault points at it. The vault check lists
+  every placeholder you can see, so it can take a few minutes on a large
+  vault. Personal placeholders, plain offload placeholders and placeholders
+  keyed to a synced path are refused. An `HQ_API_KEY` needs files:write (and
+  files:read for `--purge`); it is refused before any local file is touched.
+  The vault is versioned, so `hq files restore <key>` undoes the vault side.
+- `hq auth machine-session --output -` prints a machine identity session to a
+  pipe instead of a file, for example
+  `hq auth machine-session --output - --field refreshToken | gh secret set NAME`.
+  It signs in fresh in memory and writes no token cache, lock, or temp file
+  (the CLI may still write its usual non-secret state files). Before printing,
+  it checks the minted tokens against the machine identity the same way
+  hq-cloud does for every machine mint (client, subject, entity type and uid,
+  and no company-outpost claims on a non-company identity), and prints nothing
+  if they do not match. Without `--field` it prints the same JSON as the file
+  mode (`accessToken`, `idToken`, `expiresAt`) followed by a newline.
+  `--field <name>` prints one value raw with no trailing newline;
+  `refreshToken` is available only this way. A refresh token outlives the
+  machine secret: revoke a leaked one with a Cognito global sign-out for the
+  machine user or `RevokeToken`. The creds file is `HQ_MACHINE_CREDS_FILE`,
+  else `~/.hq-agent/machine-creds.json`; `HQ_AGENT_DIR` does not select it.
+  It refuses to print to a terminal unless `--force-tty` is given, and
+  supports hosted agent and outpost identities (not external or
+  company-outpost ones). `--output <path>` is unchanged. Behavior change:
+  `--output -` used to write a file literally named `-` in the current
+  directory; it now means stdout. To write a file with that name, use
+  `--output ./-`.
+- `hq storage offload --current` can turn a library asset restored with `hq library fetch` back into a placeholder. It used to skip the file with "run hq sync first", because fetch never records the file in the sync journal. Offload now checks the company vault for the asset's blob at `.hq-offload/blobs/<sha256>`, which is the placeholder's own key, so nothing is uploaded. Before removing the local file it confirms that the blob's size and recorded sha256 match the file, and it hashes the file again. When the library placeholder sits beside the file, offload leaves the placeholder as is. When fetch removed it, offload writes back the vault's own placeholder for that path (keeping its tags and caption), or a plain library pointer when the vault no longer has one. Files the sync journal knows, and placeholders keyed by the file's own path, work as before. A file whose bytes differ from the library copy is kept, with the reason shown.
+
 ## [5.345.154] — 2026-10-21
 - `hq sync status` now lists local files that sit under a vault prefix you can
   only read and that were never synced. Sync will never upload these files, for

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

@@ -1764,17 +1764,28 @@ export declare const COMMAND_CATALOG: readonly [{
     readonly options: readonly [];
     readonly subcommands: readonly [{
         readonly name: "machine-session";
-        readonly description: "Write the existing machine identity session to a private file";
+        readonly description: "Write the existing machine identity session to a private file, or to a pipe with --output -";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
         readonly helpCommand: false;
         readonly usage: "[options]";
-        readonly helpText: readonly [];
+        readonly helpText: readonly [{
+            readonly position: "after";
+            readonly text: "\nStdout format (--output -):\n  no --field   one JSON line {\"accessToken\",\"idToken\",\"expiresAt\"} then a newline\n  --field X    the raw value of X with no trailing newline\n\nCreds come from HQ_MACHINE_CREDS_FILE, else ~/.hq-agent/machine-creds.json.\nHQ_AGENT_DIR does not select them; set HQ_MACHINE_CREDS_FILE on hosts with several agents.\n\n--field refreshToken prints a long-lived Cognito refresh token. Rotating the machine\nsecret does not revoke it; revoke a leaked one with a Cognito global sign-out for the\nmachine user (AdminUserGlobalSignOut) or RevokeToken.";
+        }];
         readonly arguments: readonly [];
         readonly options: readonly [{
             readonly flags: "--output <path>";
-            readonly description: "path for the private machine session JSON";
+            readonly description: "path for the private machine session JSON, or - for stdout (pipe only). Creds come from HQ_MACHINE_CREDS_FILE, else ~/.hq-agent/machine-creds.json";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--field <name>";
+            readonly description: "with --output -, print one field raw with no trailing newline (accessToken, idToken, expiresAt, refreshToken)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--force-tty";
+            readonly description: "with --output -, allow printing to a terminal";
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];
@@ -2055,7 +2066,7 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly hidden: false;
             }, {
                 readonly flags: "--remote-path <path>";
-                readonly description: "Script path reported by the target runtime (defaults to the local path)";
+                readonly description: "Script path to approve instead of the local path. A path relative to the HQ root (for example companies/<co>/skills/<skill>/<file>) matches on every HQ root; an absolute path must match the runtime's path exactly";
                 readonly hidden: false;
             }, {
                 readonly flags: "--attestation <level>";
@@ -5064,6 +5075,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--idempotency-key <key>";
             readonly description: "Stable key so retries execute at most once (default: generated)";
             readonly hidden: false;
+        }, {
+            readonly flags: "--timeout <seconds>";
+            readonly description: "How long to wait for a long call that runs as a background job (default 270, max 1800)";
+            readonly hidden: false;
         }, {
             readonly flags: "--json";
             readonly description: "Machine-readable output";
@@ -10564,8 +10579,8 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Asset description";
             readonly hidden: false;
         }, {
-            readonly flags: "--company <slug>";
-            readonly description: "Company whose vault receives the files";
+            readonly flags: "--company <company>";
+            readonly description: "Company slug or uid (cmp_…) whose vault receives the files";
             readonly hidden: false;
         }, {
             readonly flags: "--no-caption";
@@ -10693,7 +10708,7 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
         readonly options: readonly [{
             readonly flags: "--company <company>";
-            readonly description: "Company uid (cmp_…), or a slug on a session; default: the placeholder's company or the key's";
+            readonly description: "Company slug or uid (cmp_…); default: the placeholder's company or the key's";
             readonly hidden: false;
         }, {
             readonly flags: "--expires <minutes>";
@@ -10705,6 +10720,43 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "rm";
+        readonly description: "Remove library assets: the local original (if fetched), the placeholder, and its vault copy. Keeps the shared blob unless --purge. Previews and asks first unless --yes";
+        readonly aliases: readonly ["remove"];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options] <targets...>";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [{
+            readonly name: "targets";
+            readonly required: true;
+            readonly variadic: true;
+            readonly description: "Library .hqcloud placeholders (or their original paths)";
+        }];
+        readonly options: readonly [{
+            readonly flags: "--company <company>";
+            readonly description: "Company slug (or cmp_ uid); default: the targets' companies/<slug>/";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--purge";
+            readonly description: "Also delete the blob, after checking no other placeholder (local or in the vault) uses it";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--dry-run";
+            readonly description: "Show what would be removed without changing anything";
+            readonly hidden: false;
+        }, {
+            readonly flags: "-y, --yes";
+            readonly description: "Skip the confirmation prompt";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print machine-readable JSON (the preview goes to stderr)";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
     }];
 }, {
     readonly name: "index";

package/dist/command-catalog.generated.js

@@ -2117,18 +2117,33 @@ export const COMMAND_CATALOG = [
         "subcommands": [
             {
                 "name": "machine-session",
-                "description": "Write the existing machine identity session to a private file",
+                "description": "Write the existing machine identity session to a private file, or to a pipe with --output -",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
                 "helpCommand": false,
                 "usage": "[options]",
-                "helpText": [],
+                "helpText": [
+                    {
+                        "position": "after",
+                        "text": "\nStdout format (--output -):\n  no --field   one JSON line {\"accessToken\",\"idToken\",\"expiresAt\"} then a newline\n  --field X    the raw value of X with no trailing newline\n\nCreds come from HQ_MACHINE_CREDS_FILE, else ~/.hq-agent/machine-creds.json.\nHQ_AGENT_DIR does not select them; set HQ_MACHINE_CREDS_FILE on hosts with several agents.\n\n--field refreshToken prints a long-lived Cognito refresh token. Rotating the machine\nsecret does not revoke it; revoke a leaked one with a Cognito global sign-out for the\nmachine user (AdminUserGlobalSignOut) or RevokeToken."
+                    }
+                ],
                 "arguments": [],
                 "options": [
                     {
                         "flags": "--output <path>",
-                        "description": "path for the private machine session JSON",
+                        "description": "path for the private machine session JSON, or - for stdout (pipe only). Creds come from HQ_MACHINE_CREDS_FILE, else ~/.hq-agent/machine-creds.json",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--field <name>",
+                        "description": "with --output -, print one field raw with no trailing newline (accessToken, idToken, expiresAt, refreshToken)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--force-tty",
+                        "description": "with --output -, allow printing to a terminal",
                         "hidden": false
                     }
                 ],
@@ -2466,7 +2481,7 @@ export const COMMAND_CATALOG = [
                             },
                             {
                                 "flags": "--remote-path <path>",
-                                "description": "Script path reported by the target runtime (defaults to the local path)",
+                                "description": "Script path to approve instead of the local path. A path relative to the HQ root (for example companies/<co>/skills/<skill>/<file>) matches on every HQ root; an absolute path must match the runtime's path exactly",
                                 "hidden": false
                             },
                             {
@@ -6130,6 +6145,11 @@ export const COMMAND_CATALOG = [
                         "description": "Stable key so retries execute at most once (default: generated)",
                         "hidden": false
                     },
+                    {
+                        "flags": "--timeout <seconds>",
+                        "description": "How long to wait for a long call that runs as a background job (default 270, max 1800)",
+                        "hidden": false
+                    },
                     {
                         "flags": "--json",
                         "description": "Machine-readable output",
@@ -12811,8 +12831,8 @@ export const COMMAND_CATALOG = [
                         "hidden": false
                     },
                     {
-                        "flags": "--company <slug>",
-                        "description": "Company whose vault receives the files",
+                        "flags": "--company <company>",
+                        "description": "Company slug or uid (cmp_…) whose vault receives the files",
                         "hidden": false
                     },
                     {
@@ -12970,7 +12990,7 @@ export const COMMAND_CATALOG = [
                 "options": [
                     {
                         "flags": "--company <company>",
-                        "description": "Company uid (cmp_…), or a slug on a session; default: the placeholder's company or the key's",
+                        "description": "Company slug or uid (cmp_…); default: the placeholder's company or the key's",
                         "hidden": false
                     },
                     {
@@ -12985,6 +13005,54 @@ export const COMMAND_CATALOG = [
                     }
                 ],
                 "subcommands": []
+            },
+            {
+                "name": "rm",
+                "description": "Remove library assets: the local original (if fetched), the placeholder, and its vault copy. Keeps the shared blob unless --purge. Previews and asks first unless --yes",
+                "aliases": [
+                    "remove"
+                ],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <targets...>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "targets",
+                        "required": true,
+                        "variadic": true,
+                        "description": "Library .hqcloud placeholders (or their original paths)"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--company <company>",
+                        "description": "Company slug (or cmp_ uid); default: the targets' companies/<slug>/",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--purge",
+                        "description": "Also delete the blob, after checking no other placeholder (local or in the vault) uses it",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--dry-run",
+                        "description": "Show what would be removed without changing anything",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "-y, --yes",
+                        "description": "Skip the confirmation prompt",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON (the preview goes to stderr)",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
             }
         ]
     },

package/dist/commands/agent-inbox.js

@@ -26,7 +26,7 @@ export function registerAgentInboxCommand(agent) {
         // 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 } = await mergeAgentInbox(paths, async () => {
+        const { entries, note, source } = await mergeAgentInbox(paths, async () => {
             const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
             const res = await vaultApiFetch({
                 token,
@@ -39,7 +39,7 @@ export function registerAgentInboxCommand(agent) {
             .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, messages: rows, ...(note ? { note } : {}) }, null, 2));
+            console.log(JSON.stringify({ count: rows.length, source, messages: rows, ...(note ? { note } : {}) }, null, 2));
             return;
         }
         if (note)

package/dist/commands/auth.d.ts

@@ -7,6 +7,8 @@
  *   hq auth refresh   — ensure a valid cached Cognito session (non-interactive)
  *   hq auth status    — show whether a valid session is cached + expiry
  *   hq auth machine-session --output <path> — write machine tokens to a private file
+ *   hq auth machine-session --output - [--field <name>] — print a fresh machine
+ *     session to a pipe; nothing is written to disk
  *
  * Sign-up is owned by the onboarding web app at
  * https://onboarding.hq.computer. `hq auth login` signs an existing account

package/dist/commands/auth.js

@@ -7,6 +7,8 @@
  *   hq auth refresh   — ensure a valid cached Cognito session (non-interactive)
  *   hq auth status    — show whether a valid session is cached + expiry
  *   hq auth machine-session --output <path> — write machine tokens to a private file
+ *   hq auth machine-session --output - [--field <name>] — print a fresh machine
+ *     session to a pipe; nothing is written to disk
  *
  * Sign-up is owned by the onboarding web app at
  * https://onboarding.hq.computer. `hq auth login` signs an existing account
@@ -21,7 +23,8 @@ import * as fs from "node:fs";
 import { open, realpath } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { clearCachedTokens, loadCachedTokens, isExpiring, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
+import { clearCachedTokens, loadCachedTokens, isExpiring, loadMachineCreds, isExternalMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
+import { authenticateMachineSession, MachineLoginError } from "../lib/daemon/machine-login.js";
 import { DEFAULT_COGNITO, refreshCachedSession, resolveCognitoTokenSource, ensureMachineSessionTokens, personTokenCacheFile, machineTokenCacheFile, loadMachineCachedTokens, } from "../utils/cognito-session.js";
 // Static (node builtins only): a lazy import here would need a resident
 // preload entry for the auth-login path.
@@ -134,15 +137,101 @@ function machineIdentityLabel() {
     const creds = loadMachineCreds();
     return creds ? `machine identity ${creds.username}` : "machine identity";
 }
+const MACHINE_SESSION_FIELDS = ["accessToken", "idToken", "expiresAt", "refreshToken"];
+/**
+ * `hq auth machine-session --output -`: mint a fresh machine session in memory
+ * and write it to stdout. No token cache, lock, or temp file is written. The
+ * full JSON has the same shape as the file mode; the refresh token is printed
+ * only when asked for with `--field refreshToken`.
+ */
+async function writeMachineSessionToStdout(options) {
+    const fail = (message) => {
+        console.error(message);
+        process.exitCode = 1;
+    };
+    const field = options.field;
+    if (field !== undefined && !MACHINE_SESSION_FIELDS.includes(field)) {
+        fail(`Unknown --field. Use one of: ${MACHINE_SESSION_FIELDS.join(", ")}.`);
+        return;
+    }
+    if (process.stdout.isTTY && !options.forceTty) {
+        fail("Refusing to print a machine session to a terminal. Pipe it to a command, or pass --force-tty.");
+        return;
+    }
+    const creds = loadMachineCreds();
+    if (!creds) {
+        fail("Machine credentials are unavailable.");
+        return;
+    }
+    if (isExternalMachineCreds(creds) || creds.entityType === "company-outpost") {
+        fail("--output - supports hosted agent and outpost machine identities only.");
+        return;
+    }
+    let tokens;
+    try {
+        tokens = await authenticateMachineSession(creds);
+    }
+    catch (error) {
+        // The identity check runs on the token claims, so a creds file with no or
+        // a wrong entityType still cannot print a company-scoped or foreign session.
+        fail(error instanceof MachineLoginError && error.code === "identity_mismatch"
+            ? "Refusing to print a machine session: the minted tokens do not match this machine identity."
+            : "Could not obtain machine session.");
+        return;
+    }
+    let contents;
+    if (field === undefined) {
+        contents = JSON.stringify({
+            accessToken: tokens.accessToken,
+            idToken: tokens.idToken,
+            expiresAt: tokens.expiresAt,
+        }) + "\n";
+    }
+    else {
+        const value = tokens[field];
+        if (value === undefined || value === "") {
+            fail(`The machine sign-in did not return ${field}.`);
+            return;
+        }
+        contents = String(value);
+    }
+    await new Promise((resolve, reject) => {
+        process.stdout.write(contents, (error) => (error ? reject(error) : resolve()));
+    }).catch(() => fail("Could not write machine session to stdout."));
+}
 export function registerAuthCommands(program) {
     const authCmd = program
         .command("auth")
         .description("Manage the local HQ Cognito session");
     authCmd
         .command("machine-session")
-        .description("Write the existing machine identity session to a private file")
-        .requiredOption("--output <path>", "path for the private machine session JSON")
+        .description("Write the existing machine identity session to a private file, or to a pipe with --output -")
+        .requiredOption("--output <path>", "path for the private machine session JSON, or - for stdout (pipe only). Creds come from HQ_MACHINE_CREDS_FILE, else ~/.hq-agent/machine-creds.json")
+        .option("--field <name>", `with --output -, print one field raw with no trailing newline (${MACHINE_SESSION_FIELDS.join(", ")})`)
+        .option("--force-tty", "with --output -, allow printing to a terminal")
+        .addHelpText("after", [
+        "",
+        "Stdout format (--output -):",
+        '  no --field   one JSON line {"accessToken","idToken","expiresAt"} then a newline',
+        "  --field X    the raw value of X with no trailing newline",
+        "",
+        "Creds come from HQ_MACHINE_CREDS_FILE, else ~/.hq-agent/machine-creds.json.",
+        "HQ_AGENT_DIR does not select them; set HQ_MACHINE_CREDS_FILE on hosts with several agents.",
+        "",
+        "--field refreshToken prints a long-lived Cognito refresh token. Rotating the machine",
+        "secret does not revoke it; revoke a leaked one with a Cognito global sign-out for the",
+        "machine user (AdminUserGlobalSignOut) or RevokeToken.",
+    ].join("\n"))
         .action(async (options) => {
+        if (options.output === "-") {
+            await writeMachineSessionToStdout(options);
+            return;
+        }
+        if (options.field !== undefined || options.forceTty) {
+            console.error("--field and --force-tty require --output -.");
+            process.exitCode = 1;
+            return;
+        }
         const requestedPath = path.resolve(options.output);
         let handle;
         try {

package/dist/commands/core.js

@@ -663,7 +663,7 @@ export function registerCoreCommands(program) {
         const rendererArgs = passthrough.filter((arg) => arg !== "--accept");
         const isCompaniesTarget = entry.renderer === "companies";
         const wantsHelp = rendererArgs.some((arg) => arg === "--help" || arg === "-h");
-        if (isCompaniesTarget && wantsHelp) {
+        if (wantsHelp && ["companies", "company-knowledge", "projects"].includes(entry.renderer)) {
             renderIndexTarget(entry.renderer, { root: "", output: (message) => process.stdout.write(message) }, rendererArgs);
             return;
         }

package/dist/commands/files-browse.d.ts

@@ -443,6 +443,22 @@ export declare const PRESIGN_BUFFER_MAX_BYTES: number;
  * access token + companyUid are captured here; the orchestrator just calls
  * `send(...)` as if it held an S3 client.
  */
+/** Error code for a presigned storage download that failed after the API authorized it. */
+export declare const STORAGE_DOWNLOAD_FAILED_CODE = "FILES_STORAGE_DOWNLOAD_FAILED";
+/**
+ * Build the error for a failed presigned download. The API already checked the
+ * caller's ACL before it signed the URL, so a failure here is a storage or
+ * network outcome, not a missing grant. The error carries no `status: 403` and
+ * a code that `isAccessDeniedError` treats as not an access denial, so the CLI
+ * does not send the caller to `hq access` (which only re-checks the ACL that
+ * already passed).
+ *
+ * A response that really came from S3 carries `x-amz-request-id`; we report
+ * S3's error code from the XML body. A response without it came from something
+ * between this machine and the storage host, usually a sandbox egress proxy or
+ * firewall that does not allow the bucket host, and we say so.
+ */
+export declare function presignedDownloadError(key: string, url: string, dl: Response): Promise<Error>;
 export declare function createCompanyPresignClient(input: {
     token: string;
     companyUid: string;

package/dist/commands/files-browse.js

@@ -709,6 +709,57 @@ export const PRESIGN_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
  * access token + companyUid are captured here; the orchestrator just calls
  * `send(...)` as if it held an S3 client.
  */
+/** Error code for a presigned storage download that failed after the API authorized it. */
+export const STORAGE_DOWNLOAD_FAILED_CODE = "FILES_STORAGE_DOWNLOAD_FAILED";
+/**
+ * Build the error for a failed presigned download. The API already checked the
+ * caller's ACL before it signed the URL, so a failure here is a storage or
+ * network outcome, not a missing grant. The error carries no `status: 403` and
+ * a code that `isAccessDeniedError` treats as not an access denial, so the CLI
+ * does not send the caller to `hq access` (which only re-checks the ACL that
+ * already passed).
+ *
+ * A response that really came from S3 carries `x-amz-request-id`; we report
+ * S3's error code from the XML body. A response without it came from something
+ * between this machine and the storage host, usually a sandbox egress proxy or
+ * firewall that does not allow the bucket host, and we say so.
+ */
+export async function presignedDownloadError(key, url, dl) {
+    let host = "the storage host";
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        // keep the generic label
+    }
+    const requestId = dl.headers.get("x-amz-request-id");
+    const bodyText = (await dl.text().catch(() => "")).slice(0, 4096);
+    const fromStorage = requestId !== null && requestId.length > 0;
+    let message;
+    let storageCode;
+    if (fromStorage) {
+        storageCode = /<Code>([^<]{1,100})<\/Code>/.exec(bodyText)?.[1];
+        message =
+            `Failed to download '${key}' (HTTP ${dl.status}` +
+                (storageCode ? `, storage error ${storageCode}` : "") +
+                `, request id ${requestId}). Your file access was granted; the storage ` +
+                `service refused the signed download. Report this with: hq feedback bug`;
+    }
+    else {
+        message =
+            `Failed to download '${key}' (HTTP ${dl.status}). Your file access was ` +
+                `granted, but the response did not come from ${host}. A proxy or network ` +
+                `egress rule on this machine likely blocked it. Allow outbound HTTPS to ` +
+                `${host} (HQ vault files are served from *.s3.us-east-1.amazonaws.com).`;
+    }
+    return Object.assign(new Error(message), {
+        code: STORAGE_DOWNLOAD_FAILED_CODE,
+        key,
+        httpStatus: dl.status,
+        fromStorage,
+        ...(storageCode ? { storageCode } : {}),
+    });
+}
 export function createCompanyPresignClient(input) {
     const { token, companyUid, companySlug, baseUrl } = input;
     const denied = (message, key, extra) => Object.assign(new Error(message), {
@@ -780,7 +831,7 @@ export function createCompanyPresignClient(input) {
         }
         const dl = await fetch(first.url, { signal: AbortSignal.timeout(120_000) });
         if (!dl.ok) {
-            throw new Error(`Failed to download '${key}' (HTTP ${dl.status})`);
+            throw await presignedDownloadError(key, first.url, dl);
         }
         // HQ-CLI-5: when the response declares a length at or below the ceiling,
         // DRAIN it here — read the whole body before send() resolves and replay it