@indigoai-us/hq-cli 5.345.148 → 5.345.149

package/dist/commands/billing-usage.d.ts

@@ -17,9 +17,18 @@
  *
  * Usage numbers come through `readMonthUsage` (src/lib/billing/usage-cost.ts),
  * the single seam to switch to the US-005 daily rollup once it has a read route.
+ *
+ * Only an account on usage pricing gets costs. The plan comes from the
+ * server: `pricingPlan` / `usageOnly` on the usage-limits body (hq-pro #5042,
+ * computed with `isOnUsagePricing`). Only when that body does not say, the
+ * billing summary the command already reads for the trial. A flat-plan account (for example a Workforce
+ * company that subscribed before the 2026-10-16 cutover) and an account the
+ * server says nothing about get readings only, with no rate, cost or
+ * projected bill.
  */
 import type { Command } from "commander";
-import { type ReadMonthUsageDeps, type StorageSplit, type UsageReport, type UsageScope } from "../lib/billing/usage-cost.js";
+import { type BillingUsageReport, type ReadMonthUsageDeps, type StorageSplit, type UsageScope } from "../lib/billing/usage-cost.js";
+import { type PricingPlan } from "../lib/billing/usage-only.js";
 export interface MembershipRef {
     uid: string;
     slug: string;
@@ -34,6 +43,12 @@ export interface BillingUsageDeps {
     fetchPricing(): Promise<unknown | null>;
     /** Whether the usage trial is running for the scope. Null = unknown. */
     readTrialActive?: (scope: UsageScope) => Promise<boolean | null>;
+    /**
+     * The billing summary body for the scope (company: `/v1/billing/summary`,
+     * person: `/v1/billing/person/summary`). Null when it did not answer. Used
+     * for the plan when usage-limits does not carry it (older server).
+     */
+    fetchBillingSummary?: (scope: UsageScope) => Promise<unknown | null>;
     now(): Date;
 }
 export interface BillingUsageOptions {
@@ -46,7 +61,23 @@ export declare class UsageScopeError extends Error {
 }
 /** Pick the scope. Never reaches outside the caller's own memberships. */
 export declare function resolveUsageScope(memberships: MembershipRef[], opts: BillingUsageOptions): UsageScope;
-export declare function runBillingUsage(opts: BillingUsageOptions, deps: BillingUsageDeps): Promise<UsageReport>;
+/** The plan on a usage-limits body: `pricingPlan`, else the `usageOnly` / `onUsagePricing` boolean. */
+export declare function pricingPlanFromUsageLimits(body: unknown): PricingPlan | null;
+/**
+ * The plan on a billing summary body. A summary that answered without saying
+ * usage-only is a flat plan: the person summary carries `personalUsage` only
+ * for usage pricing, and a company summary from a server older than usage
+ * pricing has no `pricingPlan` at all.
+ */
+export declare function pricingPlanFromSummary(body: unknown): PricingPlan | null;
+/**
+ * True: price the meters. False: flat plan. Null: unknown, show no cost.
+ * When usage-limits answers, only its answer counts: the server computes it
+ * with `isOnUsagePricing`, the source of truth. The summary's plan is used
+ * only when usage-limits does not say.
+ */
+export declare function resolveOnUsagePricing(limitsPlan: PricingPlan | null, summaryPlan: PricingPlan | null): boolean | null;
+export declare function runBillingUsage(opts: BillingUsageOptions, deps: BillingUsageDeps): Promise<BillingUsageReport>;
 /**
  * `hq billing usage --card`: the card from GET /v1/pricing, or the bundled
  * card when the feed has none. Needs no sign-in.

package/dist/commands/billing-usage.js

@@ -17,14 +17,22 @@
  *
  * Usage numbers come through `readMonthUsage` (src/lib/billing/usage-cost.ts),
  * the single seam to switch to the US-005 daily rollup once it has a read route.
+ *
+ * Only an account on usage pricing gets costs. The plan comes from the
+ * server: `pricingPlan` / `usageOnly` on the usage-limits body (hq-pro #5042,
+ * computed with `isOnUsagePricing`). Only when that body does not say, the
+ * billing summary the command already reads for the trial. A flat-plan account (for example a Workforce
+ * company that subscribed before the 2026-10-16 cutover) and an account the
+ * server says nothing about get readings only, with no rate, cost or
+ * projected bill.
  */
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, vaultApiFetchPublic } from "../utils/vault-api.js";
-import { buildReport, formatReport, readMonthUsage, } from "../lib/billing/usage-cost.js";
+import { buildReadingsReport, buildReport, formatReport, readMonthUsage, } from "../lib/billing/usage-cost.js";
 import { ratesFromPricingStatement } from "../lib/billing/usage-rate-card.js";
 import { fetchUsageCard, formatUsageCardLines } from "../lib/billing/usage-card.js";
-import { fetchCompanyBillingSummary, usageTrialActiveFromBody } from "../lib/billing/usage-only.js";
+import { fetchCompanyBillingSummary, pricingPlanFromBody, usageTrialActiveFromBody, } from "../lib/billing/usage-only.js";
 export class UsageScopeError extends Error {
 }
 /** Pick the scope. Never reaches outside the caller's own memberships. */
@@ -51,13 +59,56 @@ export function resolveUsageScope(memberships, opts) {
         memberships.map((m) => `  --company ${m.slug}`).join("\n") +
         "\n  --personal");
 }
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** The plan on a usage-limits body: `pricingPlan`, else the `usageOnly` / `onUsagePricing` boolean. */
+export function pricingPlanFromUsageLimits(body) {
+    const plan = pricingPlanFromBody(body);
+    if (plan)
+        return plan;
+    const rec = asRecord(body);
+    const flag = typeof rec?.onUsagePricing === "boolean" ? rec.onUsagePricing : rec?.usageOnly;
+    if (typeof flag === "boolean")
+        return flag ? "usage-only" : "current";
+    return null;
+}
+/**
+ * The plan on a billing summary body. A summary that answered without saying
+ * usage-only is a flat plan: the person summary carries `personalUsage` only
+ * for usage pricing, and a company summary from a server older than usage
+ * pricing has no `pricingPlan` at all.
+ */
+export function pricingPlanFromSummary(body) {
+    const rec = asRecord(body);
+    if (!rec)
+        return null;
+    // `plan: "usage"` only means "no Workforce subscription", not usage pricing,
+    // so it never turns pricing on. Without pricingPlan, show no cost.
+    return pricingPlanFromBody(rec) ?? "current";
+}
+/**
+ * True: price the meters. False: flat plan. Null: unknown, show no cost.
+ * When usage-limits answers, only its answer counts: the server computes it
+ * with `isOnUsagePricing`, the source of truth. The summary's plan is used
+ * only when usage-limits does not say.
+ */
+export function resolveOnUsagePricing(limitsPlan, summaryPlan) {
+    const plan = limitsPlan ?? summaryPlan;
+    if (plan === null)
+        return null;
+    return plan === "usage-only";
+}
 export async function runBillingUsage(opts, deps) {
     const memberships = await deps.listCompanies();
     const scope = resolveUsageScope(memberships, opts);
     const membership = scope.kind === "company" ? memberships.find((m) => m.uid === scope.companyUid) : undefined;
+    let limitsBody = null;
     const [usage, pricing] = await Promise.all([
         readMonthUsage(scope, {
-            fetchUsageLimits: deps.fetchUsageLimits,
+            fetchUsageLimits: async (s) => (limitsBody = await deps.fetchUsageLimits(s)),
             now: deps.now,
             ...(deps.readTrialActive ? { readTrialActive: deps.readTrialActive } : {}),
             ...(opts.storageScan !== false && deps.readStorageSplit && membership
@@ -66,7 +117,18 @@ export async function runBillingUsage(opts, deps) {
         }),
         deps.fetchPricing().catch(() => null),
     ]);
-    return buildReport(usage, ratesFromPricingStatement(pricing));
+    const limitsPlan = pricingPlanFromUsageLimits(limitsBody);
+    const summary = limitsPlan === null && deps.fetchBillingSummary
+        ? await deps.fetchBillingSummary(scope).catch((err) => {
+            // stderr keeps --json output on stdout parseable.
+            console.error(`Could not read the billing summary: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        })
+        : null;
+    const onUsagePricing = resolveOnUsagePricing(limitsPlan, pricingPlanFromSummary(summary));
+    if (onUsagePricing !== true)
+        return buildReadingsReport(usage, onUsagePricing);
+    return { ...buildReport(usage, ratesFromPricingStatement(pricing)), onUsagePricing: true };
 }
 // ── Production deps ─────────────────────────────────────────────────────────
 function productionDeps() {
@@ -117,6 +179,15 @@ function productionDeps() {
             const body = await fetchCompanyBillingSummary(await token(), scope.companyUid);
             return body === null ? null : usageTrialActiveFromBody(body);
         },
+        async fetchBillingSummary(scope) {
+            // Company: the same cached read as readTrialActive, so no second call.
+            if (scope.kind === "company")
+                return fetchCompanyBillingSummary(await token(), scope.companyUid);
+            const res = await vaultApiFetch({ token: await token(), path: "/v1/billing/person/summary" });
+            if (!res.ok)
+                return null;
+            return res.json().catch(() => null);
+        },
         now: () => new Date(),
     };
 }

package/dist/commands/bot.js

@@ -475,7 +475,7 @@ export function resolveCreateKind(opts, worker) {
         return { kind, companies: [] };
     }
     if (isSetup) {
-        throw Object.assign(new Error("HQ's setup bot is always a personal bot; drop --kind company."), { expected: true });
+        throw Object.assign(new Error("HQ's assistant is always a personal bot; drop --kind company."), { expected: true });
     }
     const companies = requested.length > 0 ? requested : normalizeBotCompanies(worker?.company ? [worker.company] : []);
     if (companies.length === 0) {
@@ -638,7 +638,7 @@ async function runBotCreateLocked(name, opts) {
     const { kind, companies } = resolveCreateKind(opts, worker);
     const isSetupBot = name === RESERVED_SETUP_BOT_NAME && kind === "personal" && worker?.id === SETUP_BOT_WORKER_ID;
     if (name === RESERVED_SETUP_BOT_NAME && kind === "personal" && !isSetupBot) {
-        throw Object.assign(new Error(`The name ${RESERVED_SETUP_BOT_NAME} is reserved for HQ's setup bot; create it with --worker ${RESERVED_SETUP_BOT_NAME}.`), { expected: true });
+        throw Object.assign(new Error(`The name ${RESERVED_SETUP_BOT_NAME} is reserved for HQ's assistant; create it with --worker ${RESERVED_SETUP_BOT_NAME}.`), { expected: true });
     }
     const existing = readBotConfig(dir);
     if (existing) {

package/dist/commands/channels.d.ts

@@ -12,5 +12,32 @@ export declare function describeChannel(c: ChannelSummary): string;
  * fetched list) so the formatting is unit-testable without network/auth.
  */
 export declare function formatChannelsList(channels: ChannelSummary[]): string;
+/** Activity fields the server returns on each channel row. */
+type ChannelWithActivity = ChannelSummary & {
+    lastActivityAt?: string;
+    lastMessageAt?: string;
+    lastHumanMessageAt?: string;
+    unreadCount?: number;
+};
+/**
+ * Latest activity time on a channel row, as epoch ms, or 0 when the channel
+ * has never had activity. lastActivityAt moves on new messages (work-session
+ * status cards do not move it); lastMessageAt and lastHumanMessageAt are read
+ * as fallbacks for rows that carry only those.
+ * Pure → unit-testable.
+ */
+export declare function channelActivityMs(c: ChannelWithActivity): number;
+/**
+ * Parse `--active-since`: an ISO timestamp, or a duration back from now such
+ * as `30m`, `2h`, `1d`, `90s`. Returns epoch ms, or null when unreadable.
+ */
+export declare function parseActiveSince(value: string, now?: number): number | null;
+/**
+ * Channels with activity at or after `sinceMs`, newest first. With no bound,
+ * every channel sorted newest first (never-active channels last, in their
+ * original order). Pure → unit-testable.
+ */
+export declare function channelsByActivity<T extends ChannelWithActivity>(channels: T[], sinceMs?: number): T[];
 export declare function registerChannelsCommand(program: Command): void;
+export {};
 //# sourceMappingURL=channels.d.ts.map

package/dist/commands/channels.js

@@ -67,7 +67,64 @@ function formatChannelMembers(members, json) {
         .map((member) => `${member.displayName ?? ""}\t${member.personUid}`)
         .join("\n");
 }
-async function runChannelsList() {
+/**
+ * Latest activity time on a channel row, as epoch ms, or 0 when the channel
+ * has never had activity. lastActivityAt moves on new messages (work-session
+ * status cards do not move it); lastMessageAt and lastHumanMessageAt are read
+ * as fallbacks for rows that carry only those.
+ * Pure → unit-testable.
+ */
+export function channelActivityMs(c) {
+    let best = 0;
+    for (const v of [c.lastActivityAt, c.lastMessageAt, c.lastHumanMessageAt]) {
+        const ms = typeof v === "string" ? Date.parse(v) : NaN;
+        if (Number.isFinite(ms) && ms > best)
+            best = ms;
+    }
+    return best;
+}
+/**
+ * Parse `--active-since`: an ISO timestamp, or a duration back from now such
+ * as `30m`, `2h`, `1d`, `90s`. Returns epoch ms, or null when unreadable.
+ */
+export function parseActiveSince(value, now = Date.now()) {
+    const v = value.trim();
+    const rel = /^(\d+)\s*([smhd])$/i.exec(v);
+    if (rel) {
+        const unit = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[rel[2].toLowerCase()];
+        return now - Number(rel[1]) * unit;
+    }
+    if (!/^\d{4}-\d{2}-\d{2}/.test(v))
+        return null;
+    const ms = Date.parse(v);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Channels with activity at or after `sinceMs`, newest first. With no bound,
+ * every channel sorted newest first (never-active channels last, in their
+ * original order). Pure → unit-testable.
+ */
+export function channelsByActivity(channels, sinceMs) {
+    return channels
+        .map((c, i) => ({ c, i, at: channelActivityMs(c) }))
+        .filter(({ at }) => sinceMs === undefined || (at > 0 && at >= sinceMs))
+        .sort((a, b) => b.at - a.at || a.i - b.i)
+        .map(({ c }) => c);
+}
+async function runChannelsList(opts = {}) {
+    let sinceMs;
+    if (opts.activeSince !== undefined) {
+        const parsed = parseActiveSince(opts.activeSince);
+        if (parsed === null) {
+            console.error(chalk.red(`--active-since must be an ISO time (2026-10-19T17:00:00Z) or a duration (30m, 2h, 1d); got '${opts.activeSince}'.`));
+            process.exit(2);
+        }
+        sinceMs = parsed;
+    }
+    if (opts.sort !== undefined && opts.sort !== "activity" && opts.sort !== "default") {
+        console.error(chalk.red(`--sort must be 'activity' or 'default'; got '${opts.sort}'.`));
+        process.exit(2);
+    }
     try {
         const token = await ensureCognitoToken();
         const res = await vaultApiFetch({ token, path: "/v1/notify/channels" });
@@ -82,7 +139,44 @@ async function runChannelsList() {
             process.exit(1);
         }
         const data = (await res.json());
-        console.log(formatChannelsList(data.channels ?? []));
+        let list = data.channels ?? [];
+        if (sinceMs !== undefined || opts.sort === "activity") {
+            list = channelsByActivity(list, sinceMs);
+        }
+        console.log(opts.json ? JSON.stringify(list, null, 2) : formatChannelsList(list));
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+/**
+ * `hq channels changes` — one call to the channel directory feed
+ * (GET /v1/notify/channels?cursor). No cursor, or an expired one, returns a
+ * full snapshot in `rows` with `snapshot: true` (or `reset: true`); a valid
+ * cursor returns only the channels that changed since it in `changed`, plus
+ * `removedChannelIds`. Every response carries the successor `cursor`
+ * (single-use, 15-minute TTL). Prints the response as JSON.
+ */
+async function runChannelsChanges(opts) {
+    try {
+        const token = await ensureCognitoToken();
+        const res = await vaultApiFetch({
+            token,
+            path: "/v1/notify/channels",
+            query: { cursor: opts.cursor ?? "" },
+        });
+        if (!res.ok) {
+            if (res.status === 401) {
+                console.error(chalk.red("Not authenticated — run `hq login` and try again."));
+            }
+            else {
+                const err = (await res.json().catch(() => ({})));
+                console.error(chalk.red(`Could not read channel changes: ${err.error ?? err.message ?? res.statusText}`));
+            }
+            process.exit(1);
+        }
+        console.log(JSON.stringify(await res.json(), null, 2));
     }
     catch (err) {
         console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -119,8 +213,18 @@ export function registerChannelsCommand(program) {
     channels
         .command("list", { isDefault: true })
         .description("List your DM channels — named channels and group DMs.")
-        .action(async () => {
-        await runChannelsList();
+        .option("--json", "Output the channel array as JSON, including activity fields.")
+        .option("--active-since <when>", "Only channels with activity at or after an ISO time or a duration back from now (30m, 2h, 1d); newest first.")
+        .option("--sort <order>", "'activity' lists the most recently active channels first.")
+        .action(async (opts) => {
+        await runChannelsList(opts);
+    });
+    channels
+        .command("changes")
+        .description("Print the channels that changed since a feed cursor, as JSON (no cursor → full snapshot).")
+        .option("--cursor <token>", "Cursor from the previous `hq channels changes` response.")
+        .action(async (opts) => {
+        await runChannelsChanges(opts);
     });
     channels
         .command("members <channel>")

package/dist/commands/core-refresh-vault-access-native.d.ts

@@ -7,6 +7,7 @@ export type HqResult = {
     stdout: string;
     stderr: string;
     missing?: boolean;
+    timedOut?: boolean;
 };
 export type RefreshVaultAccessDependencies = {
     cwd: string;
@@ -17,6 +18,21 @@ export type RefreshVaultAccessDependencies = {
     /** How long to wait for another refresh to release the manifest lock. */
     lockWaitMs?: number;
 };
+/**
+ * Per-call ceiling for each child `hq` call. SessionStart runs this helper, so
+ * a stalled vault request must not outlive the session that started it.
+ */
+export declare const DEFAULT_HQ_CALL_TIMEOUT_MS = 30000;
+/**
+ * Run one child `hq` call with a timeout and with browser sign-in disabled.
+ * Without `HQ_NO_BROWSER_LOGIN` (read by cognito-session's
+ * resolveInteractiveLogin) a signed-out child opens a browser login and
+ * waits on it indefinitely. On Windows the call runs under a supervisor so a
+ * timeout ends the cmd.exe shim and every process under it.
+ */
+/** Windows npm shims run hq under cmd.exe, so only there does a plain kill leave the real hq running. */
+export declare function usesTreeKillByDefault(platform?: NodeJS.Platform): boolean;
+export declare function runHqChild(args: string[], cwd: string, env: NodeJS.ProcessEnv, killTree?: boolean): HqResult;
 export declare function createRefreshVaultAccessDependencies(cwd: string, env: NodeJS.ProcessEnv, now: () => Date): RefreshVaultAccessDependencies;
 export declare function runRefreshVaultAccess(args: string[], deps: RefreshVaultAccessDependencies): UtilityOutput;
 /** Test seam: runs after a waiter has judged the lock stale and before it takes the lock over. */

package/dist/commands/core-refresh-vault-access-native.js

@@ -47,18 +47,143 @@ export const REFRESH_VAULT_ACCESS_HELP = `# hq-core: public
 #   bash core/scripts/refresh-vault-access.sh [--company <slug>]... [--root <hqRoot>]
 #
 `.replace(/^# ?/gm, "");
-function defaultHq(args, cwd, env) {
-    const spawnPlan = planHqSpawn(args, env, cwd);
+/**
+ * Per-call ceiling for each child `hq` call. SessionStart runs this helper, so
+ * a stalled vault request must not outlive the session that started it.
+ */
+export const DEFAULT_HQ_CALL_TIMEOUT_MS = 30_000;
+function hqCallTimeoutMs(env) {
+    const parsed = Number(env.HQ_VAULT_ACCESS_TIMEOUT_MS);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_HQ_CALL_TIMEOUT_MS;
+}
+/**
+ * Supervisor for one child call when the whole process tree must die on
+ * timeout. On Windows `hq` is a cmd.exe shim around node, and spawnSync's
+ * timeout ends only cmd.exe: the node child keeps running and keeps the
+ * output pipes open. The supervisor runs the call asynchronously, kills the
+ * tree on timeout (`taskkill /T /F` on Windows, the process group elsewhere),
+ * and writes the result as JSON. It exits without waiting for pipes still
+ * held by a grandchild, so the parent's spawnSync returns.
+ */
+const TREE_KILL_SUPERVISOR = String.raw `
+const { spawn, spawnSync } = require("node:child_process");
+const path = require("node:path");
+const plan = JSON.parse(process.env.HQ_TREE_KILL_PLAN);
+delete process.env.HQ_TREE_KILL_PLAN;
+const win = process.platform === "win32";
+let done = false;
+const finish = (result) => {
+  if (done) return;
+  done = true;
+  process.stdout.write(JSON.stringify(result), () => process.exit(0));
+};
+const out = [];
+const err = [];
+let child;
+try {
+  child = spawn(plan.cmd, plan.args, {
+    cwd: plan.cwd,
+    env: process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: plan.shell,
+    windowsHide: true,
+    windowsVerbatimArguments: plan.verbatim,
+    detached: !win,
+  });
+} catch (error) {
+  finish({ error: String(error && error.message), errorCode: error && error.code });
+}
+if (child) {
+  const killTree = () => {
+    if (child.pid === undefined) return;
+    if (win) {
+      const taskkill = process.env.SystemRoot ? path.join(process.env.SystemRoot, "System32", "taskkill.exe") : "taskkill";
+      spawnSync(taskkill, ["/T", "/F", "/PID", String(child.pid)], { stdio: "ignore", windowsHide: true, timeout: 10000 });
+    } else {
+      try { process.kill(-child.pid, "SIGKILL"); } catch {}
+    }
+  };
+  const timer = setTimeout(() => { killTree(); finish({ timedOut: true }); }, plan.timeoutMs);
+  child.stdout.on("data", (chunk) => out.push(chunk));
+  child.stderr.on("data", (chunk) => err.push(chunk));
+  const result = (code) => ({ code, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") });
+  child.on("error", (error) => { clearTimeout(timer); finish({ error: error.message, errorCode: error.code }); });
+  child.on("close", (code) => { clearTimeout(timer); finish(result(code ?? 128)); });
+  // A grandchild that outlives the call can hold the pipes open. Report once
+  // the direct child has exited and the pipes have had a moment to drain.
+  child.on("exit", (code) => { setTimeout(() => { clearTimeout(timer); finish(result(code ?? 128)); }, 500).unref(); });
+}
+`;
+/** Extra time the parent allows the supervisor beyond the call timeout, for taskkill and startup. */
+const SUPERVISOR_GRACE_MS = 15_000;
+/**
+ * Run one child `hq` call with a timeout and with browser sign-in disabled.
+ * Without `HQ_NO_BROWSER_LOGIN` (read by cognito-session's
+ * resolveInteractiveLogin) a signed-out child opens a browser login and
+ * waits on it indefinitely. On Windows the call runs under a supervisor so a
+ * timeout ends the cmd.exe shim and every process under it.
+ */
+/** Windows npm shims run hq under cmd.exe, so only there does a plain kill leave the real hq running. */
+export function usesTreeKillByDefault(platform = process.platform) {
+    return platform === "win32";
+}
+export function runHqChild(args, cwd, env, killTree = usesTreeKillByDefault()) {
+    const childEnv = { ...env, HQ_NO_BROWSER_LOGIN: "1" };
+    const timeoutMs = hqCallTimeoutMs(env);
+    const timedOut = () => ({ code: 124, stdout: "", stderr: `hq ${args.join(" ")} timed out after ${timeoutMs}ms`, timedOut: true });
+    const failed = (message, code) => ({ code: 127, stdout: "", stderr: message, missing: code === "ENOENT" });
+    const spawnPlan = planHqSpawn(args, childEnv, cwd);
+    if (killTree) {
+        const plan = JSON.stringify({
+            cmd: spawnPlan.cmd,
+            args: spawnPlan.args,
+            cwd,
+            shell: spawnPlan.shell,
+            verbatim: Boolean(spawnPlan.windowsVerbatimArguments),
+            timeoutMs,
+        });
+        const supervised = spawnSync(process.execPath, ["-e", TREE_KILL_SUPERVISOR], {
+            cwd,
+            env: { ...childEnv, HQ_TREE_KILL_PLAN: plan },
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: timeoutMs + SUPERVISOR_GRACE_MS,
+            killSignal: "SIGKILL",
+            maxBuffer: 64 * 1024 * 1024,
+            windowsHide: true,
+        });
+        if (supervised.error) {
+            const code = supervised.error.code;
+            return code === "ETIMEDOUT" ? timedOut() : failed(supervised.error.message, code);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(String(supervised.stdout ?? ""));
+        }
+        catch {
+            return { code: supervised.status ?? 128, stdout: "", stderr: String(supervised.stderr ?? "") };
+        }
+        if (parsed.timedOut)
+            return timedOut();
+        if (parsed.error !== undefined)
+            return failed(parsed.error, parsed.errorCode);
+        return { code: parsed.code ?? 128, stdout: parsed.stdout ?? "", stderr: parsed.stderr ?? "" };
+    }
     const result = spawnSync(spawnPlan.cmd, spawnPlan.args, {
         cwd,
-        env,
+        env: childEnv,
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
         shell: spawnPlan.shell,
+        timeout: timeoutMs,
+        killSignal: "SIGKILL",
+        windowsHide: true,
         ...(spawnPlan.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
     });
-    if (result.error)
-        return { code: 127, stdout: "", stderr: result.error.message, missing: result.error.code === "ENOENT" };
+    if (result.error) {
+        const code = result.error.code;
+        return code === "ETIMEDOUT" ? timedOut() : failed(result.error.message, code);
+    }
     return { code: result.status ?? 128, stdout: String(result.stdout ?? ""), stderr: String(result.stderr ?? "") };
 }
 function executableOnPath(name, value) {
@@ -85,7 +210,7 @@ export function createRefreshVaultAccessDependencies(cwd, env, now) {
         env,
         now,
         hqAvailable: executableOnPath("hq", env.PATH),
-        runHq: (args, directory) => defaultHq(args, directory, env),
+        runHq: (args, directory) => runHqChild(args, directory, env),
     };
 }
 function isHqRoot(root) {
@@ -174,13 +299,18 @@ function roleFromTable(output, email) {
     }
     return "unknown";
 }
+/** `hq whoami` prints this when no person session is cached. */
+const SIGNED_OUT_PATTERN = /^Not logged in\b/m;
 function resolveEmail(deps, runHq) {
     const override = deps.env.HQ_VAULT_ACCESS_EMAIL ?? "";
     if (override)
-        return { email: override, stderr: "" };
+        return { email: override, stderr: "", signedOut: false };
     const result = runHq(["whoami"], deps.cwd);
     const email = getEmail(result.stdout);
-    return { email, stderr: email ? "" : log("could not determine caller email — roles will be 'unknown' (hook will not enforce)") };
+    // An API key reaches the vault without a person session, so only a
+    // key-less caller whose whoami reports no session is treated as signed out.
+    const signedOut = !email && !deps.env.HQ_API_KEY?.trim() && SIGNED_OUT_PATTERN.test(cleanAnsi(result.stdout));
+    return { email, signedOut, stderr: email ? "" : log("could not determine caller email — roles will be 'unknown' (hook will not enforce)") };
 }
 export function runRefreshVaultAccess(args, deps) {
     const parsed = parseOptions(args);
@@ -193,8 +323,11 @@ export function runRefreshVaultAccess(args, deps) {
         return { code: 1, stdout: "", stderr: log("could not resolve the HQ root (pass --root <hqRoot>)") };
     if (!deps.hqAvailable)
         return { code: 0, stdout: "", stderr: log("hq CLI not found — nothing refreshed (the write-access hook stays fail-open without a manifest)") };
-    const runHq = deps.runHq ?? ((hqArgs, cwd) => defaultHq(hqArgs, cwd, deps.env));
+    const runHq = deps.runHq ?? ((hqArgs, cwd) => runHqChild(hqArgs, cwd, deps.env));
     const identity = resolveEmail(deps, runHq);
+    if (identity.signedOut) {
+        return { code: 0, stdout: "", stderr: log("not signed in to HQ — nothing refreshed (run `hq login`; the write-access hook stays fail-open without a manifest)") };
+    }
     let stderr = identity.stderr;
     const explicit = [...new Set(parsed.slugs)];
     const allGrants = new Map();

package/dist/commands/core.js

@@ -443,7 +443,10 @@ export function registerCoreCommands(program) {
     const hookEnginePath = core.command('hook-engine-path')
         .description('Print the offline, version-pinned native hook engine path')
         .option('--repair', 'Repair the pinned copy after closing running hook processes')
-        .action((options) => runHookEnginePath(options.repair ? ['--repair'] : []));
+        .option('--for-registration', 'Print a path only when the offline launcher flag is enabled')
+        .action((options) => runHookEnginePath([
+        ...(options.repair ? ['--repair'] : []), ...(options.forRegistration ? ['--for-registration'] : []),
+    ]));
     describeCoreCommand(hookEnginePath, { execution: 'native', root: 'cwd' });
     registerCoreOntologyCommand(core);
     registerCoreCheckpointGateSettingCommand(core);

package/dist/commands/dm.js

@@ -1465,7 +1465,15 @@ async function resolveChannel(token, target) {
 async function runDmChannel(target, opts) {
     try {
         const token = await ensureCognitoToken();
-        const channel = await resolveChannel(token, target);
+        // A channel id with --json needs no lookup: the id is exact and JSON output
+        // never uses the channel's name. Skipping the list saves fetching every
+        // channel the caller is in (~1000 for an owner), which is what made polled
+        // reads (the super-conductor message wake) take seconds instead of
+        // milliseconds.
+        const rawTarget = target.trim().replace(/^#/, "");
+        const channel = opts.json && /^chn_[A-Za-z0-9]+$/.test(rawTarget)
+            ? { channelId: rawTarget }
+            : await resolveChannel(token, target);
         const channelId = channel.channelId;
         const query = {};
         if (opts.limit)

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

@@ -2,7 +2,6 @@ import { Command } from 'commander';
 import { AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
 import { type RuntimeHookTrustResult } from '../utils/hook-trust.js';
 import { type ShimPathCheck } from '../lib/windows/user-path.js';
-import { type HookTarget } from '../lib/install/claude-targets.js';
 export interface GlobalInstallOptions {
     /** HQ checkout to install from (absolute). */
     hqRoot: string;
@@ -32,13 +31,7 @@ export interface GlobalInstallOptions {
     /** Platform override for link creation (default process.platform). */
     platform?: NodeJS.Platform;
 }
-/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
-export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platform, queryTask?: (task: string) => boolean): boolean;
-/**
- * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
- * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
- */
-export declare function hookTargetFor(hqRoot: string, home: string, daemonInstalled?: boolean, env?: NodeJS.ProcessEnv): HookTarget;
+export { hookTargetFor, isDaemonInstalled } from '../lib/install/hook-target.js';
 export interface ClaudePluginSource {
     sourceDir: string;
     marketplaceName: string;