@indigoai-us/hq-cli 5.345.160 → 5.345.161

package/dist/commands/core-session-journal-native.js

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 const USAGE = `session-journal.sh: usage:
   session-journal.sh write "<title>" [--files f1,f2,...] [--body-file PATH] [--session KEY]
@@ -163,6 +164,58 @@ function isAgedPidlessCounterLock(lock, now) {
         return false;
     }
 }
+function reclaimStaleCounterTempDirs(lock, now) {
+    const parent = path.dirname(lock);
+    // Publishers create <lock>.tmp.XXXXXX, matching the shell helper. Older native
+    // builds used <lock>.tmp-XXXXXX, so reclaim aged orphans with either prefix.
+    const prefixes = [`${path.basename(lock)}.tmp.`, `${path.basename(lock)}.tmp-`];
+    let names;
+    try {
+        names = fs.readdirSync(parent);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!prefixes.some((prefix) => name.startsWith(prefix)))
+            continue;
+        const temp = path.join(parent, name);
+        if (!isAgedPidlessCounterLock(temp, now))
+            continue;
+        const read = (file) => {
+            try {
+                return fs.readFileSync(path.join(temp, file), "utf8").trim();
+            }
+            catch {
+                return "";
+            }
+        };
+        const owner = read("pid");
+        const windowsOwner = read("winpid");
+        const token = read("owner-token");
+        if (owner && !/^\d+$/u.test(owner))
+            continue;
+        if (windowsOwner && !/^\d+$/u.test(windowsOwner))
+            continue;
+        if (owner && Number(owner) > 1 && counterLockOwnerIsAlive(temp, Number(owner)))
+            continue;
+        if (!owner && windowsOwner && Number(windowsOwner) > 1 && processIsAlive(Number(windowsOwner)))
+            continue;
+        if (read("pid") !== owner || read("winpid") !== windowsOwner || read("owner-token") !== token
+            || !isAgedPidlessCounterLock(temp, now))
+            continue;
+        if (owner && counterLockOwnerIsAlive(temp, Number(owner)))
+            continue;
+        if (windowsOwner && Number(windowsOwner) > 1 && processIsAlive(Number(windowsOwner)))
+            continue;
+        const stale = `${temp}.stale-${process.pid}-${Math.random().toString(16).slice(2)}`;
+        try {
+            fs.renameSync(temp, stale);
+            fs.rmSync(stale, { recursive: true, force: true });
+        }
+        catch { /* another waiter cleaned it or the owner resumed */ }
+    }
+}
 function reclaimStaleCounterLock(lock, now) {
     let rawOwner;
     try {
@@ -184,6 +237,11 @@ function reclaimStaleCounterLock(lock, now) {
         return false;
     const owner = rawOwner ? Number.parseInt(rawOwner, 10) : 0;
     const windowsOwner = rawWindowsPid ? Number.parseInt(rawWindowsPid, 10) : 0;
+    let observedToken = "";
+    try {
+        observedToken = fs.readFileSync(path.join(lock, "owner-token"), "utf8").trim();
+    }
+    catch { /* legacy lock */ }
     if (rawOwner && (owner <= 1 || counterLockOwnerIsAlive(lock, owner)))
         return false;
     if (!rawOwner && windowsOwner > 1 && processIsAlive(windowsOwner))
@@ -219,7 +277,12 @@ function reclaimStaleCounterLock(lock, now) {
     catch {
         currentRawWindowsPid = "";
     }
-    const sameOwner = currentRawOwner === rawOwner && currentRawWindowsPid === rawWindowsPid;
+    let currentToken = "";
+    try {
+        currentToken = fs.readFileSync(path.join(lock, "owner-token"), "utf8").trim();
+    }
+    catch { /* legacy lock */ }
+    const sameOwner = currentRawOwner === rawOwner && currentRawWindowsPid === rawWindowsPid && currentToken === observedToken;
     const stillStale = rawOwner
         ? sameOwner && !counterLockOwnerIsAlive(lock, owner)
         : sameOwner && !(windowsOwner > 1 && processIsAlive(windowsOwner)) && isAgedPidlessCounterLock(lock, now);
@@ -239,7 +302,15 @@ function reclaimStaleCounterLock(lock, now) {
     catch { /* best effort */ }
     return false;
 }
-function withCounterLock(lock, env, writers, now, action) {
+function readLockToken(lock) {
+    try {
+        return fs.readFileSync(path.join(lock, "owner-token"), "utf8").trim();
+    }
+    catch {
+        return "";
+    }
+}
+function withCounterLock(lock, env, writers, now, action, beforeCounterAction) {
     let i = 0;
     let acquired = false;
     let tries = env.HQ_JOURNAL_COUNTER_LOCK_TRIES ?? "250";
@@ -247,22 +318,82 @@ function withCounterLock(lock, env, writers, now, action) {
         tries = "250";
     const retryLimit = Number.parseInt(tries, 10);
     while (i < retryLimit) {
+        reclaimStaleCounterTempDirs(lock, now);
         try {
-            fs.mkdirSync(lock);
-            acquired = true;
+            const temp = fs.mkdtempSync(`${lock}.tmp.`);
+            const ownerToken = randomUUID();
             try {
                 if (process.platform === "win32")
-                    fs.writeFileSync(path.join(lock, "winpid"), `${process.pid}\n`, { flag: "wx" });
-                fs.writeFileSync(path.join(lock, "pid"), `${process.pid}\n`, { flag: "wx" });
+                    fs.writeFileSync(path.join(temp, "winpid"), `${process.pid}\n`, { flag: "wx" });
+                fs.writeFileSync(path.join(temp, "pid"), `${process.pid}\n`, { flag: "wx" });
+                fs.writeFileSync(path.join(temp, "owner-token"), `${ownerToken}\n`, { flag: "wx" });
+                const publishClaim = `${lock}.publish`;
+                try {
+                    fs.mkdirSync(publishClaim);
+                }
+                catch (error) {
+                    try {
+                        fs.rmSync(temp, { recursive: true, force: true });
+                    }
+                    catch { /* best effort */ }
+                    if (error.code === "EEXIST" && reclaimStaleCounterLock(publishClaim, now))
+                        continue;
+                    throw error;
+                }
+                try {
+                    fs.writeFileSync(path.join(publishClaim, "owner-token"), `${ownerToken}\n`, { flag: "wx" });
+                    fs.writeFileSync(path.join(publishClaim, "pid"), `${process.pid}\n`, { flag: "wx" });
+                    // renameSync can replace an existing empty PID-less directory on
+                    // POSIX. Refuse a pre-existing lock while publishers are serialized.
+                    if (readLockToken(publishClaim) !== ownerToken || fs.existsSync(lock))
+                        throw new Error("counter lock already exists");
+                    fs.renameSync(temp, lock);
+                }
+                finally {
+                    if (readLockToken(publishClaim) === ownerToken)
+                        fs.rmSync(publishClaim, { recursive: true, force: true });
+                }
+                acquired = true;
             }
-            catch {
+            catch (error) {
+                try {
+                    fs.rmSync(temp, { recursive: true, force: true });
+                }
+                catch { /* best effort */ }
+                throw error;
+            }
+            if (!acquired)
+                continue;
+            if (readLockToken(lock) !== ownerToken) {
+                acquired = false;
+                i++;
+                continue;
+            }
+            beforeCounterAction?.();
+            if (readLockToken(lock) !== ownerToken) {
+                acquired = false;
+                i++;
+                continue;
+            }
+            const completed = action(ownerToken);
+            if (!completed) {
+                if (readLockToken(lock) === ownerToken) {
+                    try {
+                        fs.rmSync(lock, { recursive: true, force: true });
+                    }
+                    catch { /* best effort */ }
+                }
+                acquired = false;
+                i++;
+                continue;
+            }
+            if (readLockToken(lock) === ownerToken) {
                 try {
                     fs.rmSync(lock, { recursive: true, force: true });
                 }
                 catch { /* best effort */ }
-                return;
             }
-            break;
+            return;
         }
         catch {
             if (reclaimStaleCounterLock(lock, now))
@@ -276,22 +407,6 @@ function withCounterLock(lock, env, writers, now, action) {
         writers.stderr("session-journal: tool-counter: lock remained busy; skipped update\n");
         return;
     }
-    try {
-        action();
-    }
-    finally {
-        let owner = 0;
-        try {
-            owner = Number.parseInt(fs.readFileSync(path.join(lock, "pid"), "utf8"), 10) || 0;
-        }
-        catch { /* lock disappeared */ }
-        if (owner === process.pid) {
-            try {
-                fs.rmSync(lock, { recursive: true, force: true });
-            }
-            catch { /* best effort */ }
-        }
-    }
 }
 function nextSequence(dir) {
     let names = [];
@@ -313,7 +428,7 @@ function options(args, valueFlags) {
     }
     return values;
 }
-function runToolCounter(root, action, sessionArg, env, now, writers) {
+function runToolCounter(root, action, sessionArg, env, now, writers, beforeCounterAction) {
     const rawKey = sessionArg || env.HQ_JOURNAL_SESSION || env.HQ_HOOK_SESSION_ID || "";
     const key = counterKey(rawKey);
     const date = now().toISOString().slice(0, 10);
@@ -335,27 +450,36 @@ function runToolCounter(root, action, sessionArg, env, now, writers) {
         writers.stderr(`${sessionJournalAsset}: line ${line}: ${printableCounter}: Is a directory\n`);
     };
     if (action === "increment") {
-        withCounterLock(lock, env, writers, now, () => {
+        withCounterLock(lock, env, writers, now, (ownerToken) => {
+            if (readLockToken(lock) !== ownerToken)
+                return false;
+            const next = readCounter(counter) + 1;
+            if (readLockToken(lock) !== ownerToken)
+                return false;
             try {
-                fs.writeFileSync(counter, `${readCounter(counter) + 1}\n`);
+                fs.writeFileSync(counter, `${next}\n`);
             }
             catch (error) {
-                reportDirectoryWriteFailure(error, 457);
+                reportDirectoryWriteFailure(error, 545);
             }
-        });
+            return true;
+        }, beforeCounterAction);
     }
     else if (action === "read") {
         writers.stdout(`${readCounter(counter)}\n`);
     }
     else if (action === "reset") {
-        withCounterLock(lock, env, writers, now, () => {
+        withCounterLock(lock, env, writers, now, (ownerToken) => {
+            if (readLockToken(lock) !== ownerToken)
+                return false;
             try {
                 fs.writeFileSync(counter, "0\n");
             }
             catch (error) {
-                reportDirectoryWriteFailure(error, 465);
+                reportDirectoryWriteFailure(error, 556);
             }
-        });
+            return true;
+        }, beforeCounterAction);
     }
     else {
         writers.stderr("session-journal: tool-counter: subcommand required (increment|read|reset)\n");
@@ -519,7 +643,7 @@ function executeSessionJournal(args, cwd, hqRoot, dependencies, writers) {
     if (command === "tool-counter") {
         const action = rest[0] ?? "";
         const session = options(rest.slice(1), ["--session"]).get("--session") ?? "";
-        runToolCounter(root, action, session, runtime.env, runtime.now, writers);
+        runToolCounter(root, action, session, runtime.env, runtime.now, writers, dependencies.beforeCounterAction);
         return 0;
     }
     writers.stderr(USAGE);

package/dist/commands/feedback.d.ts

@@ -91,5 +91,17 @@ export declare function postFeedbackUpdate(opts: {
     publicUrl: string | null;
     slack: string | null;
 }>;
+/** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
+export declare function normalizeFeedbackAssignee(value: string): string;
+/**
+ * Reassign a ticket. A person's own login may move a ticket that another
+ * person claimed; agent and operator service tokens get 409
+ * TICKET_CLAIMED_BY_HUMAN from the server for those tickets.
+ */
+export declare function assignFeedback(opts: {
+    id: string;
+    token: string;
+    assignee: string;
+}): Promise<void>;
 export declare function registerFeedbackCommand(program: Command): void;
 //# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -285,6 +285,57 @@ export async function postFeedbackUpdate(opts) {
         slack: typeof data.publicUpdateSlack === "string" ? data.publicUpdateSlack : null,
     };
 }
+const ASSIGNEE_RE = /^(?:prs_[A-Za-z0-9]+|[^\s@]+@[^\s@]+\.[^\s@]+)$/;
+/** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
+export function normalizeFeedbackAssignee(value) {
+    const trimmed = value.trim();
+    if (!ASSIGNEE_RE.test(trimmed)) {
+        throw new Error(`Invalid --to '${value}': expected an email address or a prs_ uid.`);
+    }
+    return trimmed.startsWith("prs_") ? trimmed : trimmed.toLowerCase();
+}
+/**
+ * Reassign a ticket. A person's own login may move a ticket that another
+ * person claimed; agent and operator service tokens get 409
+ * TICKET_CLAIMED_BY_HUMAN from the server for those tickets.
+ */
+export async function assignFeedback(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: { assignee: opts.assignee },
+    });
+    if (res.ok)
+        return;
+    const data = (await res.json().catch(() => ({})));
+    const message = typeof data.error === "string" ? data.error : res.statusText;
+    if (data.code === "TICKET_CLAIMED_BY_HUMAN") {
+        throw new Error(`${message} Run hq feedback assign from your own hq login (hq login), not an agent or operator token.`);
+    }
+    throw new Error(`Failed to assign ${opts.id}: ${message}`);
+}
+function registerAssignSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("assign")
+        .description("Reassign a ticket to a person, including one another person has claimed")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--to <assignee>", "New assignee: an email address or a prs_ uid")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const assignee = normalizeFeedbackAssignee(opts.to);
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            await assignFeedback({ id, token, assignee });
+            console.log(`Assigned: ${id} -> ${assignee}`);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
 function registerLinkSubcommand(feedbackCmd) {
     feedbackCmd
         .command("link")
@@ -447,5 +498,6 @@ export function registerFeedbackCommand(program) {
     registerLinkSubcommand(feedbackCmd);
     registerUpdateSubcommand(feedbackCmd);
     registerFeedbackShowCommand(feedbackCmd);
+    registerAssignSubcommand(feedbackCmd);
 }
 //# sourceMappingURL=feedback.js.map

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

@@ -459,6 +459,14 @@ export declare const STORAGE_DOWNLOAD_FAILED_CODE = "FILES_STORAGE_DOWNLOAD_FAIL
  * firewall that does not allow the bucket host, and we say so.
  */
 export declare function presignedDownloadError(key: string, url: string, dl: Response): Promise<Error>;
+/**
+ * Turn a presigned download that never got an HTTP response (connection
+ * refused or reset, DNS failure, timeout, or a TLS failure) into an error that
+ * names the storage host and tells the operator to allow it. Returns
+ * undefined for any other error so the caller rethrows it unchanged. Only the
+ * URL host is used; the signed query string never reaches the message.
+ */
+export declare function presignedDownloadTransportError(key: string, url: string, err: unknown): Error | undefined;
 export declare function createCompanyPresignClient(input: {
     token: string;
     companyUid: string;

package/dist/commands/files-browse.js

@@ -760,6 +760,82 @@ export async function presignedDownloadError(key, url, dl) {
         ...(storageCode ? { storageCode } : {}),
     });
 }
+/** Socket-level error codes that mean the storage host could not be reached. */
+const TRANSPORT_BLOCK_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EPIPE",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+/** TLS failures, usually a TLS-inspecting proxy whose certificate Node does not trust. */
+const TLS_BLOCK_CODES = new Set([
+    "CERT_HAS_EXPIRED",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+    "ERR_SSL_WRONG_VERSION_NUMBER",
+    "EPROTO",
+]);
+function errorChainCode(err) {
+    let cur = err;
+    for (let depth = 0; depth < 5 && cur && typeof cur === "object"; depth++) {
+        const code = cur.code;
+        if (typeof code === "string" && code.length > 0)
+            return code;
+        cur = cur.cause;
+    }
+    return undefined;
+}
+/**
+ * Turn a presigned download that never got an HTTP response (connection
+ * refused or reset, DNS failure, timeout, or a TLS failure) into an error that
+ * names the storage host and tells the operator to allow it. Returns
+ * undefined for any other error so the caller rethrows it unchanged. Only the
+ * URL host is used; the signed query string never reaches the message.
+ */
+export function presignedDownloadTransportError(key, url, err) {
+    const name = err?.name;
+    const timedOut = name === "TimeoutError";
+    const code = timedOut ? "TIMEOUT" : errorChainCode(err);
+    if (!code)
+        return undefined;
+    const tls = TLS_BLOCK_CODES.has(code) || code.startsWith("ERR_TLS_") || code.startsWith("ERR_SSL_");
+    if (!timedOut && !tls && !TRANSPORT_BLOCK_CODES.has(code))
+        return undefined;
+    let host = "the storage host";
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        // keep the generic label
+    }
+    const what = tls
+        ? `the TLS connection to ${host} failed (${code}). A proxy that inspects HTTPS traffic is the usual cause`
+        : timedOut
+            ? `the connection to ${host} timed out. A firewall or egress rule that drops traffic is the usual cause`
+            : `the connection to ${host} failed (${code}). A firewall, proxy or egress rule on this network is the usual cause`;
+    const message = `Failed to download '${key}': ${what}. Your file access was granted; the ` +
+        `network blocked the storage host. Ask your network operator to allow ` +
+        `outbound HTTPS (TCP 443) to ${host} (HQ vault files are served from ` +
+        `*.s3.us-east-1.amazonaws.com), then retry.`;
+    return Object.assign(new Error(message, { cause: err }), {
+        code: STORAGE_DOWNLOAD_FAILED_CODE,
+        key,
+        blockedHost: host,
+        transportCode: code,
+        fromStorage: false,
+    });
+}
 export function createCompanyPresignClient(input) {
     const { token, companyUid, companySlug, baseUrl } = input;
     const denied = (message, key, extra) => Object.assign(new Error(message), {
@@ -829,7 +905,13 @@ export function createCompanyPresignClient(input) {
             }
             throw new Error(message);
         }
-        const dl = await fetch(first.url, { signal: AbortSignal.timeout(120_000) });
+        let dl;
+        try {
+            dl = await fetch(first.url, { signal: AbortSignal.timeout(120_000) });
+        }
+        catch (err) {
+            throw presignedDownloadTransportError(key, first.url, err) ?? err;
+        }
         if (!dl.ok) {
             throw await presignedDownloadError(key, first.url, dl);
         }

package/dist/commands/install-global.d.ts

@@ -83,6 +83,8 @@ export interface GlobalCommandOpts {
     trustCodexHooks?: (cwd: string, keys: readonly string[]) => Promise<RuntimeHookTrustResult>;
     /** Test seam: is the npm hq.cmd folder on the Windows PATH? Null off Windows. */
     shimPathCheck?: () => ShimPathCheck | null;
+    /** Test seam: the Windows npm prefix holding hq.cmd. Null off Windows. */
+    ps1ShimDir?: () => string | null;
 }
 export declare function resolveInstallRoot(explicit: string | undefined, options?: {
     env?: NodeJS.ProcessEnv;

package/dist/commands/install-global.js

@@ -27,7 +27,8 @@ import { readCompaniesManifestMap } from '../lib/work-context/repo-remote.js';
 import { resolveDefaultHqRoot } from '../utils/hq-root-resolver.js';
 import { trustCodexUserHooks } from '../utils/hook-trust.js';
 import { assertProviderWrappersInstallable, installProviderWrappers, providerWrapperInstallPaths, removeProviderWrappers } from '../lib/install/provider-wrappers.js';
-import { checkShimOnPath, ensureShimOnUserPath, shimPathWarning } from '../lib/windows/user-path.js';
+import { checkShimOnPath, ensureShimOnUserPath, npmShimDir, shimPathWarning } from '../lib/windows/user-path.js';
+import { removeHqCliPs1Shims } from '../lib/windows/ps1-shims.js';
 import { addAgentsMdBlock, addCodexHooks, classifyLegacySkills, codexAdapterPath, codexCharterSource, codexHookTrustKeys, codexTargets, hasAllCodexHooks, HQ_OWNED_MARKER, LEGACY_BACKUP_NAME, LEGACY_SKILLS_NAME, removeAgentsMdBlock, removeCodexHooks, } from '../lib/install/codex-targets.js';
 import { addClaudeMdBlock, addHqHooks, charterPath, claudeTargets, hasAllHqHooks, HQ_ANYWHERE_PACK, HQ_MCP_SERVER_NAME, hqSkillsSource, lineDiff, masterHookPath, shimPath, MCP_SUBPROCESS_PATH, removeClaudeMdBlock, removeHqHooks, SKILL_LINK_PREFIX, } from '../lib/install/claude-targets.js';
 export { hookTargetFor, isDaemonInstalled } from '../lib/install/hook-target.js';
@@ -1156,6 +1157,24 @@ export function resolveInstallRoot(explicit, options = {}) {
         throw Object.assign(new Error('Run from inside your HQ checkout, or pass --hq-root <dir>.'), { expected: true });
     }
 }
+function defaultPs1ShimDir() {
+    return process.platform === 'win32' ? npmShimDir(process.argv[1], fs.existsSync) : null;
+}
+/**
+ * PowerShell picks npm's hq.ps1 over hq.cmd, and a Restricted execution policy
+ * blocks it. Remove only npm's own hq-cli launchers; never change the policy.
+ */
+function removePs1ShimsReport(dir) {
+    const result = removeHqCliPs1Shims(dir);
+    const lines = [];
+    if (result.removed.length > 0) {
+        lines.push(`  windows: removed ${result.removed.map((f) => path.win32.basename(f)).join(', ')} so PowerShell now runs hq.cmd.`);
+    }
+    for (const failure of result.failed) {
+        lines.push(`  windows: could not remove ${failure.file} (${failure.reason}). Run hq.cmd instead of hq in PowerShell.`);
+    }
+    return lines;
+}
 /** Entry used by `hq install --global` (wired from pkg-install.ts). */
 export async function runInstallGlobal(opts) {
     const runtime = assertRuntime(opts.runtime);
@@ -1201,6 +1220,10 @@ export async function runInstallGlobal(opts) {
         if (shimPath)
             for (const line of shimPathWarning(shimPath))
                 (opts.log ?? console.log)(line);
+        const ps1Dir = (opts.ps1ShimDir ?? defaultPs1ShimDir)();
+        if (ps1Dir)
+            for (const line of removePs1ShimsReport(ps1Dir))
+                (opts.log ?? console.log)(line);
     }
 }
 /**

package/dist/commands/integrations-connect.js

@@ -1449,6 +1449,7 @@ export function registerConnectCommands(integrations) {
         .option("--auth <mode>", "Force the auth mode: none, key, or oauth (default: detect)")
         .option("--client-id <id>", "Client id of an OAuth app you registered with the provider yourself")
         .option("--client-secret-stdin", "Read that app's client secret from stdin")
+        .option("--scopes <list>", "Permissions to request, space- or comma-separated (default: the permissions the app was approved for last time)")
         .option("--no-browser", "Print the sign-in URL instead of opening a browser")
         .option("--timeout <seconds>", "How long to wait for a browser sign-in (default 300)")
         .option("--connect", "For a revoked row, run `connect <domain>` to re-add and revive it")

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

@@ -26,6 +26,8 @@ interface Principal {
  * guessing — a misparsed principal silently grants access to the wrong party.
  */
 export declare function parsePrincipal(raw: string): Principal;
+/** `--with` / `--to` / `--from` help. Groups resolve membership at call time. */
+export declare const PRINCIPAL_HELP = "Email, uid, vault group (grp_\u2026), or `everyone`";
 export declare function registerManageCommands(integrations: Command): void;
 /** Order-insensitive identity of an allowlist, for change detection. */
 export declare function allowlistFingerprint(grants: WriteAllowlistGrant[]): string;

package/dist/commands/integrations-manage.js

@@ -76,6 +76,8 @@ export function parsePrincipal(raw) {
     }
     throw new IntegrationsCliError(`Could not tell what '${raw}' refers to. Use an email address, a uid (prs_… / agt_… / grp_…), \`everyone\`, or an explicit \`person:<id>\` / \`group:<id>\` form.`, { expected: true });
 }
+/** `--with` / `--to` / `--from` help. Groups resolve membership at call time. */
+export const PRINCIPAL_HELP = "Email, uid, vault group (grp_…), or `everyone`";
 /** How a principal reads back in output, without leaking a raw uid as a name. */
 function describePrincipal(entry) {
     if (entry.granteeType === "company-wide")
@@ -379,7 +381,7 @@ export function registerManageCommands(integrations) {
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
         .requiredOption("--tool <name>", "The tool to authorize")
-        .requiredOption("--to <principal>", "Email, uid, or `everyone`")
+        .requiredOption("--to <principal>", PRINCIPAL_HELP)
         .option("--permission <level>", "read, write, or admin", "write")
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
@@ -418,7 +420,7 @@ export function registerManageCommands(integrations) {
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
         .requiredOption("--tool <name>", "The tool to stop authorizing")
-        .requiredOption("--from <principal>", "Email, uid, or `everyone`")
+        .requiredOption("--from <principal>", PRINCIPAL_HELP)
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
         const principal = parsePrincipal(opts.from);
@@ -465,7 +467,7 @@ export function registerManageCommands(integrations) {
         .option("--company <slug>", "Company slug, e.g. indigo")
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
-        .requiredOption("--with <principal>", "Email, uid, or `everyone`")
+        .requiredOption("--with <principal>", PRINCIPAL_HELP)
         .option("--permission <level>", "read, write, or admin", "write")
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
@@ -495,7 +497,7 @@ export function registerManageCommands(integrations) {
         .option("--company <slug>", "Company slug, e.g. indigo")
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
-        .requiredOption("--from <principal>", "Email, uid, or `everyone`")
+        .requiredOption("--from <principal>", PRINCIPAL_HELP)
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
         const principal = parsePrincipal(opts.from);

package/dist/commands/lanes-link.js

@@ -14,6 +14,7 @@ function addLinkOptions(command) {
         .option("--engine <engine>", "Session engine")
         .option("--title <title>", "Session title")
         .option("--host-session <id>", "Host session id")
+        .option("--claims <ids>", "Exact comma-separated recipient receipt IDs")
         .option("--text <message>", "Message text")
         .option("--text-file <path>", "Read message text from a file")
         .option("--state <state>", "Child state")
@@ -35,7 +36,7 @@ function commandError(error) {
 }
 export function registerLanesLinkCommand(lanes) {
     const link = lanes.command("link").description("Link live sessions to a conductor through session inboxes");
-    const commands = ["open", "join", "send", "report", "status", "inbox", "read", "wait", "list", "leave", "close"];
+    const commands = ["open", "join", "send", "ack", "capabilities", "report", "status", "inbox", "read", "wait", "list", "leave", "close"];
     for (const subcommand of commands) {
         addLinkOptions(link.command(subcommand)).action(async (options) => {
             try {
@@ -56,7 +57,8 @@ export function registerLanesLinkCommand(lanes) {
     }
     const deliver = link.command("_deliver", { hidden: true })
         .description("Internal linked-session hook delivery")
-        .requiredOption("--event <event>", "Hook event");
+        .requiredOption("--event <event>", "Hook event")
+        .option("--ack-mode <mode>", "Internal explicit recipient acknowledgement");
     deliver.action(async (options) => {
         // Hook commands must not update/re-exec the CLI inside the provider's time budget.
         process.env.HQ_NO_UPDATE_CHECK = "1";
@@ -70,7 +72,7 @@ export function registerLanesLinkCommand(lanes) {
                 env: process.env,
                 defaultValue: true,
             });
-            const result = await runLaneLinkWithFlag("_deliver", { hqRoot: root, env: process.env, event: options.event, input }, enabled);
+            const result = await runLaneLinkWithFlag("_deliver", { hqRoot: root, env: process.env, event: options.event, ackMode: options.ackMode, input }, enabled);
             if (result.output)
                 writeJson(result.output);
         }

package/dist/commands/lanes-session-start.d.ts

@@ -8,9 +8,21 @@ export interface SessionStartOptions {
     stderr?: Pick<NodeJS.WriteStream, "write">;
     resolveRoot?: (env: NodeJS.ProcessEnv, cwd?: string) => string;
     startSweep?: (root: string, env: NodeJS.ProcessEnv) => void;
+    /** Starts the off-hot-path registry read when an offline flag value is missing or old. */
+    refreshFlags?: (env: NodeJS.ProcessEnv) => void;
 }
+/** Offline flag values older than this trigger one background registry read. */
+export declare const SESSION_START_FLAG_REFRESH_AFTER_MS: number;
 /** Starts the CL-4 read-only orphan report once per host, without holding SessionStart open. */
 export declare function startSessionStartOrphanSweep(root: string, env?: NodeJS.ProcessEnv, spawnDetached?: typeof spawn, rootScoped?: boolean): void;
+/**
+ * Start a detached `hq lanes session-start --refresh-flags` so the registry
+ * read never runs inside the SessionStart hook. A short lease keeps a burst of
+ * session starts to one refresh. An env without a state dir never spawns.
+ */
+export declare function startSessionStartFlagRefresh(env: NodeJS.ProcessEnv, spawnDetached?: typeof spawn, now?: number): boolean;
+/** Read the session-start flags from the registry, refreshing the offline cache. */
+export declare function refreshSessionStartFlags(env?: NodeJS.ProcessEnv): Promise<void>;
 /** SessionStart-compatible, fail-open conduct bootstrap. */
 export declare function runLaneSessionStart(options?: SessionStartOptions): Promise<void>;
 export declare function registerLaneSessionStartCommand(lanes: Command): void;