@indigoai-us/hq-cli 5.345.169 → 5.345.171

package/dist/command-catalog.generated.js

@@ -1252,6 +1252,16 @@ export const COMMAND_CATALOG = [
                         "flags": "--force-scope-shrink",
                         "description": "When a scope shrink would un-track locally-modified files, proceed anyway. Dirty files are KEPT on disk (only un-tracked); clean out-of-scope files are quarantined under .hq/scope-quarantine/.",
                         "hidden": false
+                    },
+                    {
+                        "flags": "--max-idle <seconds>",
+                        "description": "For scheduled or unattended runs: stop with exit code 124 after this many seconds with no file planned, transferred or skipped. The remote listing and planning phase of a leg reports no progress, so set this longer than your slowest planning phase. Laptop sleep does not count. (default: HQ_SYNC_MAX_IDLE, else off)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--max-runtime <seconds>",
+                        "description": "For scheduled or unattended runs: stop with exit code 124 if the run has not finished after this many seconds, even while it is making progress. Laptop sleep does not count. (default: HQ_SYNC_MAX_RUNTIME, else off)",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []
@@ -1399,6 +1409,11 @@ export const COMMAND_CATALOG = [
                         "description": "Build and print the chunks as JSON; upload nothing",
                         "hidden": false
                     },
+                    {
+                        "flags": "--json",
+                        "description": "Print the pass outcome as one JSON line instead of a summary",
+                        "hidden": false
+                    },
                     {
                         "flags": "--respect-throttle",
                         "description": "Honour the 24h per-scope upload throttle instead of forcing a pass (for scheduled callers)",
@@ -2745,6 +2760,16 @@ export const COMMAND_CATALOG = [
                         "description": "Token expiry duration (e.g. 24h, 2d, 30m)",
                         "hidden": false,
                         "defaultValue": "24h"
+                    },
+                    {
+                        "flags": "--format <format>",
+                        "description": "Output format: text (default; OSC-8 hyperlink on a supporting TTY, plain URL otherwise; FORCE_HYPERLINK=1/0 overrides detection on a TTY only), markdown (one Markdown link line on stdout, details on stderr), json",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print { url, expiresAt, secretName } as JSON (same as --format json)",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []
@@ -3693,6 +3718,11 @@ export const COMMAND_CATALOG = [
                         "description": "Permission level (only with --with): read | write",
                         "hidden": false
                     },
+                    {
+                        "flags": "--exact",
+                        "description": "With --with: grant exactly the object named by <prefix>, even when it looks like a folder (by default a bare folder name such as 'knowledge' is granted as the folder glob 'knowledge/*').",
+                        "hidden": false
+                    },
                     {
                         "flags": "--full",
                         "description": "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.",
@@ -3724,7 +3754,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "unshare",
-                "description": "Remove a named file access grant, or remove an empty ACL row or grantee-less entries without --with.",
+                "description": "Remove a named file access grant, or remove an empty ACL row or grantee-less entries without --with. With --with, a bare name such as 'knowledge' first removes the exact 'knowledge' grant (rows from older `hq files share` versions) and, when none matches, the folder-glob 'knowledge/*' grant. Without --with, the prefix is used exactly as typed: pass 'knowledge/*' (quoted) to clean up the folder-glob row.",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -3744,6 +3774,11 @@ export const COMMAND_CATALOG = [
                         "flags": "--with <principal>",
                         "description": "Person uid, agent uid, company Outpost id (out_...), email address, group id, or '@all' to remove the grant",
                         "hidden": false
+                    },
+                    {
+                        "flags": "--exact",
+                        "description": "With --with: remove the grant on exactly the object named by <prefix>. By default a bare folder name such as 'knowledge' resolves to the folder glob 'knowledge/*', the same way `hq files share` resolves it.",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []
@@ -4080,7 +4115,7 @@ export const COMMAND_CATALOG = [
         "helpText": [
             {
                 "position": "after",
-                "text": "\nExit codes:\n  0  local or not-synced (file exists and you can read it)\n  2  never-existed (the path was never created)\n  3  no-access (the file exists but you cannot read it)\n  4  ambiguous (several keys matched; pick one)\n\nWith several paths, each gets its own result block and the exit code is the\nhighest one across the paths.\n"
+                "text": "\nExit codes:\n  0  local or not-synced (file exists and you can read it)\n  2  never-existed (the path was never created)\n  3  no-access (the file exists but you cannot read it), or\n     no-write-access (the file is on disk, not in the vault, and you cannot\n     write to it, so a push cannot upload it)\n  4  ambiguous (several keys matched; pick one)\n\nWith several paths, each gets its own result block and the exit code is the\nhighest one across the paths.\n"
             }
         ],
         "arguments": [
@@ -4827,7 +4862,7 @@ export const COMMAND_CATALOG = [
     },
     {
         "name": "dm",
-        "description": "Send and read direct messages, and manage connection requests. Messages to a person send to them; messages to an agent, a channel or a group are tagged for agents and folded away from people by default. Pass --for-human or --audience human|agent|both to override.",
+        "description": "Send and read direct messages, and manage connection requests. Messages sent from a person login are always tagged for people. When an agent or bot sends, messages to an agent, a channel or a group are tagged for agents and folded away from people by default. Pass --for-human or --audience human to tag a message for people; --audience agent|both is for agents and bots only.",
         "aliases": [],
         "hidden": false,
         "helpOption": true,
@@ -4908,7 +4943,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--audience <human|agent|both>",
-                        "description": "Tag who this message is for: human (a person must read it), agent (progress/status, hidden from humans by default), or both. Default: human for a person, agent for an agent, a channel or a group. Wins over --for-human.",
+                        "description": "Tag who this message is for: human (a person must read it), agent (progress/status, hidden from humans by default), or both. agent and both are for agents and bots only; a person login always sends human. Default for agents and bots: human for a person, agent for an agent, a channel or a group. Wins over --for-human.",
                         "hidden": false
                     },
                     {
@@ -5529,13 +5564,23 @@ export const COMMAND_CATALOG = [
                 "options": [
                     {
                         "flags": "--state <state>",
-                        "description": "One of: triaged, in-progress, shipped, verified, resolved",
+                        "description": "One of: triaged, in-progress, stalled, shipped, verified, resolved",
                         "hidden": false
                     },
                     {
                         "flags": "--note <text>",
                         "description": "What the customer should read (plain text, up to 2000 characters)",
                         "hidden": false
+                    },
+                    {
+                        "flags": "--pr <url>",
+                        "description": "Open pull request for this ticket (required with --state in-progress unless --lane is given)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--lane <id>",
+                        "description": "Live lane working this ticket (required with --state in-progress unless --pr is given)",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []
@@ -5613,6 +5658,32 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "claim",
+                "description": "Assign a ticket to yourself (sets the assignee only, never the status)",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <id>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "id",
+                        "required": true,
+                        "variadic": false,
+                        "description": "Feedback id (feedback_<uuid>)"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "Print { id, assignee } as JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "list",
                 "description": "List feedback: untriaged (default), yours, or one person's",
@@ -5629,6 +5700,11 @@ export const COMMAND_CATALOG = [
                         "description": "Items nobody has triaged yet (the default)",
                         "hidden": false
                     },
+                    {
+                        "flags": "--open",
+                        "description": "Every item not resolved, won't-fix or accepted, triaged or not",
+                        "hidden": false
+                    },
                     {
                         "flags": "--mine",
                         "description": "Items assigned to you",
@@ -5641,7 +5717,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--status <status>",
-                        "description": "Only items with this status",
+                        "description": "Only items with this status (new, triaging, accepted, wont_fix, in_progress, resolved, waiting_on_customer, reopened, stalled, needs_info). Without --untriaged, --mine or --assignee it lists every item in that status",
                         "hidden": false
                     },
                     {
@@ -5656,7 +5732,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--json",
-                        "description": "Print { items, count } as JSON",
+                        "description": "Print { items, count } as JSON, plus truncated: true when more items match",
                         "hidden": false
                     }
                 ],
@@ -6422,6 +6498,11 @@ export const COMMAND_CATALOG = [
                         "description": "Company slug, e.g. indigo",
                         "hidden": false
                     },
+                    {
+                        "flags": "--account <id-or-label>",
+                        "description": "Which account of the app: its connection id or account label",
+                        "hidden": false
+                    },
                     {
                         "flags": "--describe <tool>",
                         "description": "Print the full input schema for one tool",
@@ -6463,6 +6544,11 @@ export const COMMAND_CATALOG = [
                         "description": "Connection id (acct_…)",
                         "hidden": false
                     },
+                    {
+                        "flags": "--account <id-or-label>",
+                        "description": "Which account of the app: its connection id or account label",
+                        "hidden": false
+                    },
                     {
                         "flags": "--company <slug>",
                         "description": "Company slug, e.g. indigo",
@@ -6784,6 +6870,16 @@ export const COMMAND_CATALOG = [
                         "description": "Connect again even if this app is already connected",
                         "hidden": false
                     },
+                    {
+                        "flags": "--personal",
+                        "description": "Connect it as your own personal connection (not --company <slug>, which picks the company)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--company-owned",
+                        "description": "Connect it as a connection the whole company owns (needs permission to add company apps)",
+                        "hidden": false
+                    },
                     {
                         "flags": "--json",
                         "description": "Machine-readable output",
@@ -6870,6 +6966,16 @@ export const COMMAND_CATALOG = [
                         "description": "For a revoked row, run `connect <domain>` to re-add and revive it",
                         "hidden": false
                     },
+                    {
+                        "flags": "--personal",
+                        "description": "With --connect: re-add it as your own personal connection",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--company-owned",
+                        "description": "With --connect: re-add it as a connection the whole company owns",
+                        "hidden": false
+                    },
                     {
                         "flags": "--json",
                         "description": "Machine-readable output",
@@ -7642,7 +7748,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--repo <dir>",
-                        "description": "With files: apply this repo's committed .gitleaks.toml allowlists, matching repo-relative paths",
+                        "description": "With files: apply this repo's committed .gitleaks.toml allowlists, matching repo-relative paths. With --range: the repo to scan (default: the current directory)",
                         "hidden": false
                     },
                     {
@@ -7654,6 +7760,11 @@ export const COMMAND_CATALOG = [
                         "flags": "--allowlist-rev <rev>",
                         "description": "With --repo: read .gitleaks.toml from this commit instead of HEAD",
                         "hidden": false
+                    },
+                    {
+                        "flags": "--range <range>",
+                        "description": "Scan the lines added in <base>..<head> (head defaults to HEAD), every commit included, with the base's .gitleaks.toml allowlists and the repo's [[rules]]",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []
@@ -10314,6 +10425,49 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "pull",
+                "description": "Download one file from an Outpost through a short-lived download link (for files too large for exec output). <outpost> is the Outpost id (`primary` for your first box). The remote path must be inside the Outpost user's home or HQ dir; relative and ~ paths start at the home dir. The file is saved to [local-path], or to the remote file name in the current directory.",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <outpost> <remote-path> [local-path]",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "outpost",
+                        "required": true,
+                        "variadic": false,
+                        "description": ""
+                    },
+                    {
+                        "name": "remote-path",
+                        "required": true,
+                        "variadic": false,
+                        "description": ""
+                    },
+                    {
+                        "name": "local-path",
+                        "required": false,
+                        "variadic": false,
+                        "description": ""
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--force",
+                        "description": "Replace the local file if it already exists",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Emit raw JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "terminal",
                 "description": "Open an interactive terminal on an Outpost — a real TTY over SSM Session Manager (no SSH, no local AWS credentials). Requires the AWS session-manager-plugin installed locally. With --forward, tunnels a port on the box to your machine instead of opening a shell.",
@@ -22540,8 +22694,12 @@ export const COMMAND_CATALOG = [
                     {
                         "flags": "--runtime <runtime>",
                         "description": "Model CLI to run the bot with: claude|codex|grok",
-                        "hidden": false,
-                        "defaultValue": "claude"
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--hq-fleet-runtime",
+                        "description": "Create this personal bot with the local HQ Fleet Runtime",
+                        "hidden": false
                     },
                     {
                         "flags": "--model <model>",
@@ -22877,6 +23035,62 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "auth",
+                "description": "Sign a runtime-backed personal bot in to ChatGPT, Grok, Claude, or another supported provider",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <name>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "name",
+                        "required": true,
+                        "variadic": false,
+                        "description": ""
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--provider <provider>",
+                        "description": "Provider: chatgpt, grok, claude, or a runtime provider id",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--model <model>",
+                        "description": "Model id; required for providers without a built-in personal-bot default",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--api-key",
+                        "description": "Read an API key from stdin instead of starting device authorization",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--base-url <url>",
+                        "description": "Provider API base URL; required for custom runtime providers",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--transport <transport>",
+                        "description": "Provider transport: chat_completions, anthropic_messages, or codex_responses",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--no-browser",
+                        "description": "Do not open a browser during device authorization",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "logs",
                 "description": "Show the bot's log",

package/dist/commands/access.d.ts

@@ -16,7 +16,7 @@
 import { Command } from "commander";
 import { type CompanyBrowseClientFactory, type FilesBrowseVaultClient, type RunGetResult } from "./files-browse.js";
 import { type AclLock } from "./acl-lock.js";
-export type AccessOutcome = "never-existed" | "local" | "not-synced" | "no-access" | "ambiguous" | "pending-confirmation";
+export type AccessOutcome = "never-existed" | "local" | "not-synced" | "no-access" | "no-write-access" | "ambiguous" | "pending-confirmation";
 export interface AccessAclTree {
     prefix: string;
     direct: Array<{
@@ -151,6 +151,15 @@ export interface RunAccessResult {
      * grants (including a root `*` company-wide grant) do not apply.
      */
     lockedBy?: AclLock;
+    /**
+     * Set with outcome "no-write-access": the ACL row that blocks writes to a
+     * path that is on disk but not in the vault, so a push cannot upload it.
+     * Anchored as companies/<slug>/<prefix>; absent when only the effective
+     * permission is known.
+     */
+    writeBlockedBy?: string;
+    /** Effective permission on the path when outcome is "no-write-access". */
+    permission?: string | null;
 }
 export interface AccessAsResult {
     personUid: string;
@@ -164,6 +173,28 @@ export interface AccessAsResult {
 export declare function outcomeExitCode(outcome: AccessOutcome): 0 | 2 | 3 | 4;
 export declare function formatAccessOutcome(result: RunAccessResult): string;
 export declare function resolveGrantor(tree: AccessAclTree | null, members: AccessMember[]): AccessGrantor | null;
+/**
+ * ACL evidence for one key. `tree` is the full acl/tree response (which keeps
+ * the deny / no-record distinction and the ACL creator for grantor lookup).
+ * `resolved` is a non-null permission from the batch acl/resolve route.
+ */
+export type AclVerdict = {
+    kind: "tree";
+    tree: AccessAclTree | null;
+} | {
+    kind: "resolved";
+    permission: string;
+};
+/**
+ * Why the caller cannot write `relative`, or null when it can or the ACL says
+ * nothing (no record: membership-distributed access decides, which this
+ * command cannot see). The tree is fetched when the fast resolve path gave
+ * only a permission, so the blocking row can be named.
+ */
+export declare function writeBlocker(verdict: AclVerdict, relative: string, deps: Pick<AccessDeps, "fetchAclTree" | "companySlug">): Promise<{
+    permission: string | null;
+    blockedBy?: string;
+} | null>;
 export declare function runAccess(input: RunAccessInput): Promise<RunAccessResult>;
 export interface RunAccessBatchInput {
     targets: string[];

package/dist/commands/access.js

@@ -26,6 +26,7 @@ import { listActiveMembers } from "./members.js";
 import { aclLockedBy } from "./acl-lock.js";
 import { buildDmBody } from "./dm.js";
 import { defaultAudienceFor, recipientKindOf } from "../lib/notify-recipient.js";
+import { callerIsMachinePrincipal } from "../lib/caller-principal.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { findRecentAccessRequest, formatTimeAgo, recordAccessRequest, } from "../utils/access-requests.js";
 import { recordAccessOutcome } from "../utils/access-outcomes.js";
@@ -34,8 +35,11 @@ export function outcomeExitCode(outcome) {
         return 0;
     if (outcome === "never-existed")
         return 2;
-    if (outcome === "no-access" || outcome === "pending-confirmation")
+    if (outcome === "no-access" ||
+        outcome === "no-write-access" ||
+        outcome === "pending-confirmation") {
         return 3;
+    }
     return 4;
 }
 export function formatAccessOutcome(result) {
@@ -57,6 +61,16 @@ export function formatAccessOutcome(result) {
             lines.push(`You do not have read access to this path.`);
             lines.push(result.path);
             break;
+        case "no-write-access":
+            lines.push(`The file is on this computer but not in the ${result.company} vault, and you cannot write to it, so a push cannot upload it.`);
+            lines.push(result.path);
+            if (result.writeBlockedBy) {
+                lines.push(`Write is blocked by the ACL on ${result.writeBlockedBy} (your permission: ${result.permission ?? "none"}). Ask its creator or a company admin for write access.`);
+            }
+            else {
+                lines.push(`Your permission on this path is ${result.permission ?? "none"}. Ask a company admin for write access.`);
+            }
+            break;
         case "pending-confirmation":
             lines.push(`Ask the grantor for read access to this path.`);
             lines.push(result.path);
@@ -243,6 +257,69 @@ function startEarly(promise) {
     promise.catch(() => undefined);
     return promise;
 }
+const WRITE_PERMISSIONS = new Set(["write", "admin", "owner"]);
+/**
+ * Why the caller cannot write `relative`, or null when it can or the ACL says
+ * nothing (no record: membership-distributed access decides, which this
+ * command cannot see). The tree is fetched when the fast resolve path gave
+ * only a permission, so the blocking row can be named.
+ */
+export async function writeBlocker(verdict, relative, deps) {
+    const resolvedPermission = verdict.kind === "resolved" ? verdict.permission : undefined;
+    if (resolvedPermission && WRITE_PERMISSIONS.has(resolvedPermission))
+        return null;
+    let tree = verdict.kind === "tree" ? verdict.tree : null;
+    if (verdict.kind === "resolved") {
+        try {
+            tree = await deps.fetchAclTree(relative);
+        }
+        catch {
+            tree = null;
+        }
+    }
+    const permission = resolvedPermission ?? tree?.effectivePermission ?? null;
+    if (permission && WRITE_PERMISSIONS.has(permission))
+        return null;
+    const covering = tree?.coveringAclPath;
+    if (typeof covering === "string" && covering !== "") {
+        return {
+            permission,
+            blockedBy: toBucketRelative(covering, deps.companySlug),
+        };
+    }
+    // A row on the path itself with a known non-write permission blocks it.
+    // With no permission reported, nothing proves the path is blocked.
+    if (permission && tree?.directRow) {
+        return { permission, blockedBy: toBucketRelative(tree.prefix, deps.companySlug) };
+    }
+    // No ACL row covers the path. A known non-write permission still blocks.
+    if (resolvedPermission)
+        return { permission };
+    return null;
+}
+/**
+ * Owners and admins write past ACL rows on the server (role bypass), which
+ * the ACL tree does not always show. Treat a lookup failure as no bypass only
+ * when the member list loads; if it cannot be read, assume a bypass so the
+ * command keeps its old "never-existed" answer instead of a wrong blocker.
+ */
+async function callerHasRoleBypass(deps) {
+    try {
+        const [members, requester] = await Promise.all([
+            deps.listMembers(),
+            resolveRequester(deps.requester),
+        ]);
+        const email = (requester.email ?? "").trim().toLowerCase();
+        // An unknown caller cannot be matched; keep the old answer.
+        if (email === "")
+            return true;
+        return members.some((m) => (m.personEmail ?? "").trim().toLowerCase() === email &&
+            (m.role === "owner" || m.role === "admin"));
+    }
+    catch {
+        return true;
+    }
+}
 function verdictDenied(verdict) {
     return verdict.kind === "tree" ? aclDenied(verdict.tree) : false;
 }
@@ -388,6 +465,31 @@ async function locateTarget(target, deps, ctx) {
                         },
                     };
                 }
+                // feedback_5baccb9e: a file that is on disk but absent from the vault
+                // is usually one a push could not upload. When the ACL blocks writes,
+                // say so instead of "never existed".
+                if (relative !== "" &&
+                    fs.existsSync(path.join(deps.hqRoot, "companies", slug, relative))) {
+                    steps.push("disk: present");
+                    const blocker = await writeBlocker(verdict, relative, deps);
+                    if (blocker && !(await callerHasRoleBypass(deps))) {
+                        steps.push(blocker.blockedBy
+                            ? `acl: write blocked by ${anchored(blocker.blockedBy)} (${blocker.permission ?? "none"})`
+                            : `acl: no write (${blocker.permission ?? "none"})`);
+                        return {
+                            kind: "terminal",
+                            outcome: "no-write-access",
+                            fields: {
+                                path: anchored(relative),
+                                company: slug,
+                                exists: false,
+                                steps,
+                                permission: blocker.permission,
+                                ...(blocker.blockedBy ? { writeBlockedBy: anchored(blocker.blockedBy) } : {}),
+                            },
+                        };
+                    }
+                }
                 return {
                     kind: "terminal",
                     outcome: "never-existed",
@@ -611,7 +713,12 @@ async function completeTarget(input, deps, located) {
             }
             else {
                 grantor = resolved;
-                const grantorLine = `Grantor: ${grantorLabel(resolved)} (${resolved.source})`;
+                const contactRole = resolved.source === "acl-creator"
+                    ? "ACL creator"
+                    : resolved.source === "owner"
+                        ? "company owner fallback"
+                        : "company admin fallback";
+                const grantorLine = `Access contact: ${grantorLabel(resolved)} (${contactRole}; file authorship not verified)`;
                 // The recipient is always shown BEFORE any send. Under --json stdout is
                 // reserved for the single JSON object, so the line goes to stderr.
                 if (json)
@@ -659,7 +766,7 @@ async function completeTarget(input, deps, located) {
                     }
                     if (approved && outcome === "no-access") {
                         const message = `${requester.email} is asking for read access to ${resolvedKey} in ${slug}.`;
-                        const prompt = `hq files share ${resolvedKey} --with ${requester.email} --permission read --company ${slug}`;
+                        const prompt = `hq files share ${resolvedKey} --exact --with ${requester.email} --permission read --company ${slug}`;
                         const sent = await deps.dm.send({
                             recipient: resolved.email,
                             message,
@@ -852,6 +959,11 @@ function jsonPayload(result) {
         payload.alreadyAskedAt = result.alreadyAskedAt;
     if (result.lockedBy)
         payload.lockedBy = result.lockedBy;
+    if (result.outcome === "no-write-access") {
+        payload.permission = result.permission ?? null;
+        if (result.writeBlockedBy)
+            payload.writeBlockedBy = result.writeBlockedBy;
+    }
     return payload;
 }
 function emit(input, result, log) {
@@ -928,7 +1040,9 @@ export function registerAccessCommand(program) {
 Exit codes:
   0  local or not-synced (file exists and you can read it)
   2  never-existed (the path was never created)
-  3  no-access (the file exists but you cannot read it)
+  3  no-access (the file exists but you cannot read it), or
+     no-write-access (the file is on disk, not in the vault, and you cannot
+     write to it, so a push cannot upload it)
   4  ambiguous (several keys matched; pick one)
 
 With several paths, each gets its own result block and the exit code is the
@@ -1156,7 +1270,7 @@ async function buildLiveAccessDeps(slug, hqRoot) {
                 prompt: msg.prompt,
                 details: msg.details,
                 now: Date.now(),
-                audience: defaultAudienceFor(recipientKindOf(msg.recipient)),
+                audience: defaultAudienceFor(recipientKindOf(msg.recipient), callerIsMachinePrincipal()),
             });
             const res = await vaultApiFetch({
                 token,

package/dist/commands/agent-kit.d.ts

@@ -75,7 +75,7 @@ export interface KitRuntime {
     paths: AgentKitPaths;
     creds: ExternalMachineCreds;
     config: KitConfig;
-    getToken: () => Promise<string>;
+    getToken: (signal?: AbortSignal) => Promise<string>;
     log: KitLogger;
     credsSource?: HeartbeatCredsSource;
 }