@indigoai-us/hq-cli 5.345.155 → 5.345.156

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 ## [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

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

@@ -2066,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>";
@@ -5075,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";

package/dist/command-catalog.generated.js

@@ -2481,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
                             },
                             {
@@ -6145,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",

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/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

package/dist/commands/integrations-core.d.ts

@@ -120,6 +120,16 @@ interface GatewayMessage {
 }
 export type GatewayErrorShape = "string_error" | "object_no_code" | "object_code" | "string_code" | "nested_code" | "empty" | "redacted_empty";
 export type GatewayFailureCode = "invalid_envelope";
+/** Default client wait for a background (202) integration job. */
+export declare const ASYNC_GATEWAY_DEADLINE_MS: number;
+/** Upper bound for `hq integrations call --timeout`, in seconds. */
+export declare const MAX_CALL_TIMEOUT_SECONDS: number;
+/**
+ * Parse `--timeout <seconds>` for `hq integrations call` into milliseconds.
+ * Bounds how long the CLI waits for a background job; it never shortens the
+ * gateway's own limits.
+ */
+export declare function parseCallTimeoutMs(raw: string | undefined): number;
 export declare class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -338,7 +348,9 @@ export declare function resolveConnection(token: string, companyUid: string, app
 }, recoveryOpts?: {
     allowSingleRevoked?: boolean;
 }): Promise<AdminConnection>;
-export declare function callGateway(token: string, params: Record<string, unknown>, idempotencyKey?: string, method?: "tools/call" | "tools/list"): Promise<GatewayMessage>;
+export declare function callGateway(token: string, params: Record<string, unknown>, idempotencyKey?: string, method?: "tools/call" | "tools/list", opts?: {
+    waitMs?: number;
+}): Promise<GatewayMessage>;
 /**
  * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`
  * where `text` is the provider's JSON. Unwrap to the inner payload; fall back

package/dist/commands/integrations-core.js

@@ -19,7 +19,43 @@ import { connectionHealthNotice } from "../lib/integrations/health.js";
 import { bareProvider } from "../lib/integrations/provider-slug.js";
 export { bareProvider } from "../lib/integrations/provider-slug.js";
 const ASYNC_GATEWAY_POLL_INTERVAL_MS = 1_000;
-const ASYNC_GATEWAY_DEADLINE_MS = 4 * 60_000 + 30_000;
+/** Default client wait for a background (202) integration job. */
+export const ASYNC_GATEWAY_DEADLINE_MS = 4 * 60_000 + 30_000;
+/** Upper bound for `hq integrations call --timeout`, in seconds. */
+export const MAX_CALL_TIMEOUT_SECONDS = 30 * 60;
+/**
+ * Parse `--timeout <seconds>` for `hq integrations call` into milliseconds.
+ * Bounds how long the CLI waits for a background job; it never shortens the
+ * gateway's own limits.
+ */
+export function parseCallTimeoutMs(raw) {
+    if (raw === undefined)
+        return ASYNC_GATEWAY_DEADLINE_MS;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new IntegrationsCliError(`--timeout must be a whole number of seconds (got "${raw}").`, { expected: true });
+    }
+    const seconds = Number(trimmed);
+    if (seconds < 1 || seconds > MAX_CALL_TIMEOUT_SECONDS) {
+        throw new IntegrationsCliError(`--timeout must be between 1 and ${MAX_CALL_TIMEOUT_SECONDS} seconds (got ${seconds}).`, { expected: true });
+    }
+    return seconds * 1_000;
+}
+/**
+ * Statuses the gateway returns when an inline (non-background) tools/call ran
+ * into the IntegrationMcpFunction 30s wall or its provider budget.
+ */
+function isInlineTimeoutStatus(status) {
+    return status === 500 || status === 502 || status === 504;
+}
+function inlineTimeoutHint(status) {
+    return (`${upstreamUnavailableMessage(status)} ` +
+        "If this was a long-running call (for example a large analytical read), it may have hit the " +
+        "gateway's 30-second limit: the gateway ran it inline, not as a background job. Long calls " +
+        "run as background jobs only when async integration jobs are enabled for your company; ask " +
+        "HQ support to enable them. Once enabled, hq integrations call waits for the result " +
+        "automatically (see --timeout).");
+}
 export class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -627,9 +663,9 @@ function gatewaySubcommandFor(params, method) {
         return "tools_call";
     return "other";
 }
-export async function callGateway(token, params, idempotencyKey, method = "tools/call") {
+export async function callGateway(token, params, idempotencyKey, method = "tools/call", opts = {}) {
     const gatewaySubcommand = gatewaySubcommandFor(params, method);
-    const deadline = Date.now() + ASYNC_GATEWAY_DEADLINE_MS;
+    const deadline = Date.now() + (opts.waitMs ?? ASYNC_GATEWAY_DEADLINE_MS);
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/mcp",
@@ -663,6 +699,15 @@ export async function callGateway(token, params, idempotencyKey, method = "tools
     }
     if (res.status !== 202 && (!res.ok || !terminalMessage)) {
         raiseIfUnauthorized(res);
+        if (method === "tools/call" &&
+            params.acceptAsync === true &&
+            isInlineTimeoutStatus(res.status)) {
+            throw new IntegrationsCliError(inlineTimeoutHint(res.status), {
+                expected: true,
+                status: res.status,
+                gatewaySubcommand,
+            });
+        }
         raiseIfUpstreamUnavailable(res);
         // Carry the HTTP status so a reportable transport failure (e.g. a 501 that
         // is neither 401 nor an upstream-availability status, so it is captured)
@@ -773,7 +818,7 @@ async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, dea
             break;
         await new Promise((resolve) => setTimeout(resolve, Math.min(ASYNC_GATEWAY_POLL_INTERVAL_MS, remainingMs)));
     }
-    throw new IntegrationsCliError(`Timed out waiting for integration job ${jobId}; the server job may still finish. To safely retry, rerun with --idempotency-key ${idempotencyKey}.`, { expected: true });
+    throw new IntegrationsCliError(`Timed out waiting for integration job ${jobId}; the server job may still finish. To safely retry, rerun with --idempotency-key ${idempotencyKey} (add --timeout <seconds> to wait longer).`, { expected: true });
 }
 /**
  * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`

package/dist/commands/integrations.js

@@ -56,7 +56,7 @@ import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { redactSensitiveUrl, redactSensitiveUrls, redactUrlsInText } from "../utils/redact-url.js";
-import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, fetchUsableApps, isBuiltInGatewayProvider, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, parseCallTimeoutMs, fetchConnections, fetchUsableApps, isBuiltInGatewayProvider, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
 import { registerConnectCommands } from "./integrations-connect.js";
 import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
@@ -483,8 +483,10 @@ export function registerIntegrationsCommand(program) {
         .option("--args <json>", "Tool arguments as a JSON object (default {}); use - to read the JSON from stdin")
         .option("--args-file <path>", "Read tool arguments from a JSON file (use - for stdin); avoids shell quoting of apostrophes and parentheses")
         .option("--idempotency-key <key>", "Stable key so retries execute at most once (default: generated)")
+        .option("--timeout <seconds>", "How long to wait for a long call that runs as a background job (default 270, max 1800)")
         .option("--json", "Machine-readable output")
         .action(async (tool, opts) => {
+        const waitMs = parseCallTimeoutMs(opts.timeout);
         const parsedArgs = await resolveCallArgs(opts);
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
@@ -522,7 +524,7 @@ export function registerIntegrationsCommand(program) {
                 },
             };
         }
-        const message = await callGateway(token, gatewayParams, idempotencyKey);
+        const message = await callGateway(token, gatewayParams, idempotencyKey, "tools/call", { waitMs });
         const payload = unwrapGatewayResult(message.result);
         const queued = queuedOutcome(payload);
         if (queued) {

package/dist/commands/secrets.d.ts

@@ -45,5 +45,21 @@ export declare function parseDestinationUrl(raw: string): {
 };
 export declare function collectSecretNames(value: string, previous?: string[]): string[];
 export declare function scrubSandboxOutput(text: string, secretNames?: string[]): string;
+/**
+ * Check a `--remote-path` value and return the path to store, or the reason it
+ * can never match.
+ *
+ * An absolute path is sent exactly as typed: the server compares absolute
+ * approvals byte for byte with the path `hq secrets exec` reports. A relative
+ * path names the script from the HQ root. `\` becomes `/` and a leading `./`
+ * is dropped, then the same rules the server applies are checked: at least one
+ * folder before the file name, no `.`, `..` or empty segments, no `~`, no
+ * drive letter, and no surrounding whitespace.
+ */
+export declare function normalizeApprovedScriptPath(input: string): {
+    path: string;
+} | {
+    error: string;
+};
 export declare function registerSecretsCommand(program: Command): void;
 //# sourceMappingURL=secrets.d.ts.map

package/dist/commands/secrets.js

@@ -462,6 +462,61 @@ function normalizePolicyRecord(secretPath, data) {
         scripts,
     };
 }
+/**
+ * Check a `--remote-path` value and return the path to store, or the reason it
+ * can never match.
+ *
+ * An absolute path is sent exactly as typed: the server compares absolute
+ * approvals byte for byte with the path `hq secrets exec` reports. A relative
+ * path names the script from the HQ root. `\` becomes `/` and a leading `./`
+ * is dropped, then the same rules the server applies are checked: at least one
+ * folder before the file name, no `.`, `..` or empty segments, no `~`, no
+ * drive letter, and no surrounding whitespace.
+ */
+export function normalizeApprovedScriptPath(input) {
+    if (input.length === 0 || input.trim().length === 0) {
+        return { error: "the path is empty" };
+    }
+    if (input !== input.trim()) {
+        return { error: "the path starts or ends with whitespace" };
+    }
+    if (input.startsWith("/") || input.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(input)) {
+        return { path: input };
+    }
+    if (input.startsWith("~")) {
+        return {
+            error: "the path starts with ~, which is never expanded; give the absolute path or a path relative to the HQ root",
+        };
+    }
+    if (/^[A-Za-z]:/.test(input)) {
+        return { error: "the path starts with a drive letter but is not absolute" };
+    }
+    const relative = input.replace(/\\/g, "/").replace(/^(\.\/)+/, "");
+    const segments = relative.split("/");
+    if (segments.some((segment) => segment === "")) {
+        return {
+            error: "the path has an empty segment (a trailing or doubled /)",
+        };
+    }
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+        return { error: "the path has a . or .. segment" };
+    }
+    if (segments.length < 2) {
+        return {
+            error: "a bare file name would match that file in any folder; include at least one folder, for example skills/<skill>/<file>",
+        };
+    }
+    return { path: relative };
+}
+function approvalIsActive(policy, scriptId) {
+    const approved = policy.scriptLock?.approvedScripts;
+    if (!Array.isArray(approved))
+        return true;
+    return approved.some((script) => script !== null &&
+        typeof script === "object" &&
+        script.scriptId === scriptId &&
+        !script.revokedAt);
+}
 function isSecretPolicyScript(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -988,7 +1043,7 @@ export function registerSecretsCommand(program) {
         .description("Approve a script for a secret path")
         .requiredOption("--id <scriptId>", "Stable script identifier")
         .requiredOption("--script <path>", "Path to the local script file")
-        .option("--remote-path <path>", "Script path reported by the target runtime (defaults to the local path)")
+        .option("--remote-path <path>", "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")
         .option("--attestation <level>", "Attestation level", "self-asserted-hash")
         .action(async (secretPath, opts) => {
         try {
@@ -997,7 +1052,16 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
+            const checkedRemotePath = opts.remotePath === undefined
+                ? undefined
+                : normalizeApprovedScriptPath(opts.remotePath);
+            if (checkedRemotePath && "error" in checkedRemotePath) {
+                console.error(chalk.red(`Invalid --remote-path '${opts.remotePath}': ${checkedRemotePath.error}.`));
+                process.exit(1);
+            }
+            const remotePath = checkedRemotePath?.path;
             const usage = await buildSecretUsage("exec", opts.script, opts.id, opts.attestation);
+            const approvedPath = remotePath ?? usage.script?.path;
             const token = await requireCognitoTokenForSecrets("secrets script approve", "secrets:write");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
@@ -1007,7 +1071,7 @@ export function registerSecretsCommand(program) {
                 body: {
                     path: secretPath,
                     scriptId: usage.script?.scriptId,
-                    scriptPath: opts.remotePath ?? usage.script?.path,
+                    scriptPath: approvedPath,
                     sha256: usage.script?.sha256,
                     attestationLevel: usage.script?.attestationLevel,
                 },
@@ -1018,7 +1082,12 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             removeCacheEntry(companyUid, secretPath);
-            console.log(chalk.green(`Approved script '${opts.id}' for '${secretPath}'.`));
+            const data = (await res.json().catch(() => ({})));
+            if (data.policy && !approvalIsActive(data.policy, opts.id)) {
+                console.error(chalk.red(`Failed to approve script: the server did not store an active approval for '${opts.id}' on '${secretPath}'. If this id was revoked before, approve the script under a new --id and pass that id to --script-id.`));
+                process.exit(1);
+            }
+            console.log(chalk.green(`Approved script '${opts.id}' for '${secretPath}' (path: ${approvedPath}).`));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));

package/dist/lib/agent-kit/inbox-state.d.ts

@@ -75,6 +75,13 @@ export interface MergedInbox {
     entries: MirroredInboxEntry[];
     /** Set when the server could not be consulted, so the caller can say so. */
     note?: string;
+    /**
+     * Machine-readable origin of the answer. `server` means the server inbox was
+     * read (merged with the mirror); `local-mirror` means the server could not be
+     * consulted and the entries may be stale. Lets an automated consumer tell a
+     * stale fallback from a verified empty inbox without parsing `note`.
+     */
+    source: "server" | "local-mirror";
 }
 export declare function mergeAgentInbox(paths: Pick<AgentKitPaths, "inboxDir">, fetchServerInbox: () => Promise<{
     status: number;

package/dist/lib/agent-kit/inbox-state.js

@@ -163,6 +163,10 @@ export async function mergeAgentInbox(paths, fetchServerInbox) {
     catch (err) {
         note = `server inbox unavailable (${err instanceof Error ? err.message : String(err)}); showing the local mirror only, which may be stale`;
     }
-    return { entries: [...byId.values()], ...(note ? { note } : {}) };
+    return {
+        entries: [...byId.values()],
+        source: note ? "local-mirror" : "server",
+        ...(note ? { note } : {}),
+    };
 }
 //# sourceMappingURL=inbox-state.js.map

package/dist/lib/agent-kit/mcp/tools.js

@@ -280,7 +280,7 @@ export function buildAgentMcpTools(clients) {
                 const limit = int(args, "limit", { min: 1, max: 100, fallback: 20 });
                 const includeDone = args.include_done === true;
                 const done = readDoneIds(clients.paths);
-                const { entries, note: serverNote } = await mergeAgentInbox(clients.paths, async () => {
+                const { entries, note: serverNote, source } = await mergeAgentInbox(clients.paths, async () => {
                     const token = await clients.getToken();
                     return clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
                 });
@@ -292,6 +292,7 @@ export function buildAgentMcpTools(clients) {
                 const hasFiles = rows.some((r) => r.attachments?.length);
                 return textResult(clampOutput(JSON.stringify({
                     count: rows.length,
+                    source,
                     messages: rows,
                     ...(serverNote ? { note: serverNote } : {}),
                     ...(hasFiles ? { attachmentsHint: ATTACHMENTS_HINT } : {}),

package/dist/lib/doctor/checks/sync-health.d.ts

@@ -100,6 +100,15 @@ export interface SyncHealthDeps {
      * unhealthy-sync signal, and `hq doctor --fix` has nothing local to refresh.
      */
     localCompanyExists?: (slug: string) => boolean;
+    /**
+     * Whether the sync service can resolve the company for this machine's
+     * identity. Defaults to true unless a recent `hq doctor --fix` pull of it
+     * failed because the service has no such company for the caller or refused
+     * access (see company-resolution-state.ts). A stale journal for a company
+     * that fails this has nothing `--fix` can pull, so it is NA ("not on this
+     * machine") rather than an auto-fixable WARN.
+     */
+    companySyncResolvable?: (slug: string, lastSync?: string | null) => boolean;
     /**
      * Whether HQ_SYNC_MANIFEST_DISABLED turns manifest uploads off on this
      * machine. Defaults to reading the environment the way `hq sync manifest`