@indigoai-us/hq-cli 5.345.154 → 5.345.155

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 ## [Unreleased]
 
+## [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 [];
@@ -10564,8 +10575,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 +10704,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 +10716,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
                     }
                 ],
@@ -12811,8 +12826,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 +12985,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 +13000,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/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/library-add.d.ts

@@ -23,8 +23,12 @@ export interface PutResponse {
 export interface LibraryAddDeps {
     hqRoot: string;
     now: () => Date;
-    /** Resolve the slug to an active company membership. */
-    resolveCompany: (slug: string) => Promise<LibraryCompany>;
+    /**
+     * Resolve `--company` (a slug or a cmp_ uid) to the company. `folderSlug` is
+     * the companies/<slug>/ of an explicit `--to`, for callers that cannot map a
+     * uid to its folder on their own (an HQ_API_KEY).
+     */
+    resolveCompany: (ref: string, folderSlug?: string) => Promise<LibraryCompany>;
     /** POST /v1/files/presign. */
     presign: (body: Record<string, unknown>) => Promise<Response>;
     /** Open a fresh byte stream of a source. Called once to hash and once to upload. */

package/dist/commands/library-add.js

@@ -29,10 +29,10 @@ import https from "node:https";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { formatCloudAssetBlock, formatCloudPlaceholder, isCoveredByAny, parseCloudPlaceholder, resolvePullScope, } from "@indigoai-us/hq-cloud";
-import { PLACEHOLDER_SUFFIX, companyOffloadKey, containedPath, durablePlaceholderFs, renderPointer, resolvePlaceholder, } from "./storage-offload.js";
+import { CONTENT_SHA256_METADATA_KEY, PLACEHOLDER_SUFFIX, companyOffloadKey, containedPath, durablePlaceholderFs, renderPointer, resolvePlaceholder, } from "./storage-offload.js";
 import { formatPlanGateError, formatUpgradeRefusal, planGateErrorFromResponse, } from "../utils/plan-gate-error.js";
 /** Metadata key hq-pro binds to `checksumSha256` (sync's content hash). */
-const CONTENT_SHA256_META_KEY = "hq-content-sha256";
+const CONTENT_SHA256_META_KEY = CONTENT_SHA256_METADATA_KEY;
 const MEDIA_TYPES = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -42,6 +42,7 @@ const MEDIA_TYPES = {
     ".svg": "image/svg+xml",
     ".avif": "image/avif",
     ".heic": "image/heic",
+    ".heif": "image/heif",
     ".mp4": "video/mp4",
     ".mov": "video/quicktime",
     ".webm": "video/webm",
@@ -136,6 +137,41 @@ export function resolveLibraryDir(hqRoot, options) {
     }
     return { slug, dirRel, dirAbs };
 }
+/**
+ * The company and library folder for `add`. `--company` may be a slug or a
+ * cmp_ uid; the folder always uses the company's slug, so a uid never becomes
+ * a companies/cmp_…/ folder. A slug that disagrees with `--to` is refused
+ * before any lookup, as it always was.
+ */
+async function resolveLibraryTarget(options, deps) {
+    const companyIsUid = options.company !== undefined && isCompanyUid(options.company);
+    if (!companyIsUid)
+        resolveLibraryDir(deps.hqRoot, options);
+    const folderSlug = options.to === undefined ? undefined : resolveLibraryDir(deps.hqRoot, { to: options.to }).slug;
+    const company = await deps.resolveCompany((options.company ?? folderSlug), folderSlug);
+    if (isCompanyUid(company.slug)) {
+        throw new Error(`No company folder is known for ${company.uid}; library folders are companies/<slug>/. ` +
+            "Pass --company <slug> or --to companies/<slug>/<dir>.");
+    }
+    if (folderSlug !== undefined && company.slug !== folderSlug) {
+        throw new Error(`--to is inside companies/${folderSlug}/, but --company ${options.company} is ${company.slug}.`);
+    }
+    return { company, ...resolveLibraryDir(deps.hqRoot, { company: company.slug, to: options.to }) };
+}
+function isCompanyUid(ref) {
+    return ref.startsWith("cmp_");
+}
+/**
+ * Capabilities an API key lacks, from hq-pro's keyed-route 403
+ * (`{ error, granted, missing }`). Empty for any other response.
+ */
+function missingKeyCapabilities(status, body) {
+    if (status !== 403)
+        return [];
+    if (typeof body.missing === "string" && body.missing)
+        return [body.missing];
+    return Array.isArray(body.missing) ? body.missing.filter((c) => typeof c === "string") : [];
+}
 async function hashStream(stream) {
     const hash = crypto.createHash("sha256");
     let size = 0;
@@ -212,8 +248,7 @@ async function uploadVerified(source, digest, grant, deps) {
 export async function runLibraryAdd(inputs, options, deps) {
     if (inputs.length === 0)
         throw new Error("Pass at least one file or URL.");
-    const { slug, dirRel, dirAbs } = resolveLibraryDir(deps.hqRoot, options);
-    const company = await deps.resolveCompany(slug);
+    const { company, slug, dirRel, dirAbs } = await resolveLibraryTarget(options, deps);
     const items = [];
     const planned = [];
     const claimed = new Set();
@@ -268,9 +303,13 @@ export async function runLibraryAdd(inputs, options, deps) {
     }
     const body = (await response.json().catch(() => ({})));
     if (!response.ok) {
-        const msg = typeof body.error === "string" ? body.error : `HTTP ${response.status}`;
+        const missing = missingKeyCapabilities(response.status, body);
+        const msg = missing.length > 0
+            ? `This API key cannot upload (missing ${missing.join(", ")}). Use a key made with ` +
+                "`hq api-keys create --preset library-agent --allow-upload`, or unset HQ_API_KEY and run signed in."
+            : `Could not get an upload URL: ${typeof body.error === "string" ? body.error : `HTTP ${response.status}`}`;
         for (const p of planned)
-            p.item.error = `Could not get an upload URL: ${msg}`;
+            p.item.error = msg;
         return { company: slug, items };
     }
     const rows = Array.isArray(body.results) ? body.results : [];

package/dist/commands/library-caption.d.ts

@@ -105,8 +105,45 @@ export declare function runLibraryDescribe(target: string, deps: LibraryDescribe
 export type RunTool = (command: string, args: string[]) => Promise<{
     stdout: string;
 }>;
+/**
+ * HEIC / HEIF by content, or by a .heic/.heif/.hif name (any case) when the
+ * bytes are not a format Claude Code reads directly. AVIF (also a HEIF
+ * container) is not included.
+ */
+export declare function isHeifImage(head: Buffer, name: string): boolean;
+/** Width and height from a JPEG's start-of-frame marker, or null. */
+export declare function jpegDimensions(bytes: Buffer): {
+    width: number;
+    height: number;
+} | null;
+/** A decoded frame is a non-empty JPEG within the frame byte and edge limits. */
+export declare function isUsableJpegFrame(bytes: Buffer): boolean;
+/** The EXIF orientation (1-8) in a JPEG's APP1 segment, or 1 when there is none. */
+export declare function jpegExifOrientation(bytes: Buffer): number;
+/** The JPEG without its APP1 (EXIF and XMP) segments. */
+export declare function stripJpegApp1(bytes: Buffer): Buffer;
+interface TileGrid {
+    width: number;
+    height: number;
+    left: number;
+    top: number;
+    tiles: Array<{
+        stream: number;
+        x: number;
+        y: number;
+    }>;
+}
+/**
+ * The primary tile grid from `ffprobe -show_stream_groups -of json`: the
+ * "Tile Grid" group marked default, else the first one. Null when the output
+ * does not have the expected shape (older ffmpeg has no tile grid groups).
+ */
+export declare function primaryTileGrid(ffprobeJson: string): TileGrid | null;
+/** ffmpeg filter graph that assembles a tile grid, crops it and scales it to the frame size. */
+export declare function tileGridFilter(grid: TileGrid): string;
 /** Seek points at 10%, 35%, 60% and 85% of a known duration. */
 export declare function videoSeekPoints(durationSeconds: number | null): number[];
 /** Frames for captioning: the image itself when it fits, otherwise ffmpeg JPEGs. */
-export declare function extractCaptionFrames(file: string, mediaKind: CaptionMediaKind, run?: RunTool): Promise<Buffer[]>;
+export declare function extractCaptionFrames(file: string, mediaKind: CaptionMediaKind, run?: RunTool, platform?: NodeJS.Platform): Promise<Buffer[]>;
+export {};
 //# sourceMappingURL=library-caption.d.ts.map