@indigoai-us/hq-cli 5.345.170 → 5.345.171

package/dist/commands/cloud.d.ts

@@ -14,6 +14,7 @@
  */
 import { Command } from "commander";
 import { type ConflictStrategy, type EntityContext, type MembershipSyncConfig, type SyncMode, type PullScope, type ExplicitGrant, type ShareOptions, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
+import { withSyncWatchdog, type SyncWatchdogLimits } from "../utils/sync-watchdog.js";
 import { type BannerLevel } from "../lib/narrow-hint-banner.js";
 import { type PlanLimitRefusalSummary } from "../lib/billing/plan-limit-refusals.js";
 /**
@@ -45,7 +46,54 @@ export declare class SyncExitError extends Error {
  * deliberately duck-typed so hq-cli remains compatible while hq-cloud and the
  * CLI are released independently.
  */
-export declare function formatSyncFailure(err: unknown): string;
+export declare function formatSyncFailure(err: unknown, ctx?: {
+    hqRoot?: string;
+    cwd?: string;
+    companySlug?: string;
+}): string;
+/**
+ * The `.hqinclude` line that admits a named path: its HQ-relative spelling,
+ * with a trailing slash for a folder. Resolved the way the push resolver
+ * reads a named path (absolute, HQ root, the company folder, then the current
+ * directory); a path that resolves nowhere inside the HQ tree is suggested as
+ * typed.
+ */
+export declare function hqincludeEntryFor(namedPath: string, ctx?: {
+    hqRoot?: string;
+    cwd?: string;
+    companySlug?: string;
+}): string;
+/**
+ * Re-render hq-cloud's UnreachablePushPathsError with the real blocker per
+ * path (feedback_6afa6ce4). The upstream message always ends with advice
+ * about symlinks, so a path left out of `.hqinclude` read as a symlink
+ * problem. This names the `.hqinclude` line to add, and keeps the symlink
+ * advice only for reasons that are about links or paths outside the company
+ * folder. Returns null for any other error.
+ */
+export declare function formatUnreachablePushPaths(err: unknown, ctx?: {
+    hqRoot?: string;
+    cwd?: string;
+    companySlug?: string;
+}): string | null;
+/**
+ * Lines naming the blocker when a push with user-named paths uploaded nothing
+ * and every not-uploaded file fell outside write scope (feedback_5baccb9e).
+ * The summary before this gave a count and the granted prefixes; this names
+ * each requested path as the thing no write grant covers and points at
+ * `hq access`, which reports the ACL row that blocks it.
+ */
+export declare function explicitPushBlockedLines(input: {
+    userNamedPaths: boolean;
+    namedPaths: readonly string[];
+    filesUploaded: number;
+    filesExcludedByScope: number;
+    otherNotUploaded: number;
+    prefixSet: readonly string[] | undefined;
+    hqRoot: string;
+    cwd?: string;
+    companySlug?: string;
+}): string[];
 /**
  * US-003: run one sync fanout under a client-health attempt/outcome report.
  * The report is best-effort, bounded, and swallowed — it can only append a
@@ -128,6 +176,15 @@ export declare function scopeExcludedPrefixDetail(prefixSet: readonly string[] |
  * folder foo/ — and grant advice would point the reader the wrong way.
  */
 export declare function scopeExcludedLines(count: number, prefixSet: readonly string[] | undefined): string[];
+/**
+ * feedback_b7c00a62: run a `sync now` runner under the watchdog (see
+ * `utils/sync-watchdog.ts` for the limits). A timeout prints a clear message
+ * and unwinds as a failed {@link SyncExitError}, so {@link withSyncHealthReport}
+ * records the failure and exits 124. The failure report gets at most
+ * {@link SYNC_WATCHDOG_REPORT_GRACE_MS}; after that the process exits 124
+ * regardless, and the worker backstop stays armed behind both.
+ */
+export declare function runUnderSyncWatchdog<T>(limits: SyncWatchdogLimits, label: string, run: () => Promise<T>, watchdog?: typeof withSyncWatchdog, exit?: (code: number) => void): Promise<T>;
 /**
  * Bound foreground waits for a watcher/manual sync that currently owns the
  * per-root operation lock. The cloud engine reads this environment value on

package/dist/commands/cloud.js

@@ -18,8 +18,9 @@ import { SERVER_OWNED_FOLDERS, findServerOwnedLocalOnly, } from "../lib/sync/ser
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
-import { share, getStateDir, listJournals, createIgnoreFilter, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, syncDoctor, } from "@indigoai-us/hq-cloud";
+import { share, getStateDir, listJournals, createIgnoreFilter, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, readSyncProgress, syncDoctor, } from "@indigoai-us/hq-cloud";
 import { syncLeg } from "../utils/sync-operation-lock.js";
+import { SYNC_WATCHDOG_EXIT_CODE, SYNC_WATCHDOG_REPORT_GRACE_MS, SyncWatchdogTimeoutError, createSnapshotProgressProbe, resolveSyncWatchdogLimits, withSyncWatchdog, } from "../utils/sync-watchdog.js";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, loadCachedTokens, } from "../utils/cognito-session.js";
 import { resolveUploadAuthor } from "../utils/upload-author.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
@@ -69,7 +70,10 @@ async function ensureSyncCognitoToken() {
  * deliberately duck-typed so hq-cli remains compatible while hq-cloud and the
  * CLI are released independently.
  */
-export function formatSyncFailure(err) {
+export function formatSyncFailure(err, ctx = {}) {
+    const unreachable = formatUnreachablePushPaths(err, ctx);
+    if (unreachable)
+        return unreachable;
     // A plan-limit refusal the runner threw (a 402 on the whole request) renders
     // with the same reason, fix options and upgrade link as every other refusal.
     const planGate = planGateErrorFromVaultError(err);
@@ -105,6 +109,150 @@ export function formatSyncFailure(err) {
     }
     return err instanceof Error ? err.message : String(err);
 }
+function asUnreachablePushPaths(err) {
+    if (!(err instanceof Error) || err.name !== "UnreachablePushPathsError")
+        return null;
+    const candidate = err;
+    if (!Array.isArray(candidate.paths))
+        return null;
+    if (typeof candidate.reasons !== "object" || candidate.reasons === null)
+        return null;
+    const paths = candidate.paths.filter((p) => typeof p === "string");
+    return {
+        message: err.message,
+        paths,
+        reasons: candidate.reasons,
+    };
+}
+/**
+ * The `.hqinclude` line that admits a named path: its HQ-relative spelling,
+ * with a trailing slash for a folder. Resolved the way the push resolver
+ * reads a named path (absolute, HQ root, the company folder, then the current
+ * directory); a path that resolves nowhere inside the HQ tree is suggested as
+ * typed.
+ */
+export function hqincludeEntryFor(namedPath, ctx = {}) {
+    const toEntry = (rel, isDir) => {
+        const posix = rel.split(path.sep).join("/").replace(/\/+$/, "");
+        return isDir ? posix + "/" : posix;
+    };
+    const hqRoot = ctx.hqRoot ? path.resolve(ctx.hqRoot) : undefined;
+    if (hqRoot) {
+        const candidates = path.isAbsolute(namedPath)
+            ? [namedPath]
+            : [
+                path.join(hqRoot, namedPath),
+                ...(ctx.companySlug
+                    ? [path.join(hqRoot, "companies", ctx.companySlug, namedPath)]
+                    : []),
+                path.resolve(ctx.cwd ?? process.cwd(), namedPath),
+            ];
+        for (const candidate of candidates) {
+            const rel = path.relative(hqRoot, candidate);
+            if (rel === "" ||
+                rel === ".." ||
+                rel.startsWith(".." + path.sep) ||
+                path.isAbsolute(rel)) {
+                continue;
+            }
+            let stat;
+            try {
+                stat = fs.statSync(candidate);
+            }
+            catch {
+                stat = undefined;
+            }
+            if (stat)
+                return toEntry(rel, stat.isDirectory());
+        }
+    }
+    return toEntry(namedPath.replace(/^\.\//, ""), namedPath.endsWith("/"));
+}
+/**
+ * Re-render hq-cloud's UnreachablePushPathsError with the real blocker per
+ * path (feedback_6afa6ce4). The upstream message always ends with advice
+ * about symlinks, so a path left out of `.hqinclude` read as a symlink
+ * problem. This names the `.hqinclude` line to add, and keeps the symlink
+ * advice only for reasons that are about links or paths outside the company
+ * folder. Returns null for any other error.
+ */
+export function formatUnreachablePushPaths(err, ctx = {}) {
+    const parsed = asUnreachablePushPaths(err);
+    if (!parsed || parsed.paths.length === 0)
+        return null;
+    const upstreamLines = parsed.message.split("\n");
+    const upstreamLine = (p) => upstreamLines.find((l) => l.startsWith("  · " + p + " — "));
+    const ruleFor = (p) => {
+        const line = upstreamLine(p);
+        if (!line)
+            return undefined;
+        return line.slice(("  · " + p + " — ").length).replace(/; it was not uploaded$/, "");
+    };
+    const includeEntries = [];
+    let linkAdvice = false;
+    const lines = parsed.paths.map((p) => {
+        const reason = parsed.reasons[p];
+        if (reason === "ignored") {
+            const rule = ruleFor(p) ?? "excluded by a sync ignore rule";
+            if (rule === "not listed in .hqinclude") {
+                const entry = hqincludeEntryFor(p, ctx);
+                includeEntries.push(entry);
+                return "  · " + p + " — not listed in .hqinclude, so sync skips it. Add this line to .hqinclude: " + entry;
+            }
+            return "  · " + p + " — " + rule + "; it was not uploaded";
+        }
+        if (reason === "outside-company" || reason === "unreadable-link") {
+            linkAdvice = true;
+        }
+        return upstreamLine(p) ?? "  · " + p + " — could not be pushed (" + String(reason) + ")";
+    });
+    const count = parsed.paths.length;
+    const out = [
+        count + " named path" + (count === 1 ? "" : "s") + " could not be pushed; nothing was uploaded.",
+        ...lines,
+    ];
+    if (includeEntries.length > 0) {
+        out.push("Your HQ root has a .hqinclude allowlist, so only listed paths sync. Add the line" +
+            (includeEntries.length === 1 ? "" : "s") +
+            " above to .hqinclude at the HQ root, then push again.");
+    }
+    if (linkAdvice) {
+        out.push("A path reached through a symlink is only pushable when it stays inside the HQ tree " +
+            "(e.g. companies/<slug>/knowledge → repos/private/knowledge-<slug>); one that points " +
+            "outside HQ has to sync through whatever owns it, not the vault.");
+    }
+    return out.join("\n");
+}
+/**
+ * Lines naming the blocker when a push with user-named paths uploaded nothing
+ * and every not-uploaded file fell outside write scope (feedback_5baccb9e).
+ * The summary before this gave a count and the granted prefixes; this names
+ * each requested path as the thing no write grant covers and points at
+ * `hq access`, which reports the ACL row that blocks it.
+ */
+export function explicitPushBlockedLines(input) {
+    if (!input.userNamedPaths || input.namedPaths.length === 0)
+        return [];
+    if (input.filesUploaded > 0 || input.filesExcludedByScope <= 0)
+        return [];
+    if (input.otherNotUploaded > 0)
+        return [];
+    const keys = input.namedPaths.map((p) => hqincludeEntryFor(p, {
+        hqRoot: input.hqRoot,
+        cwd: input.cwd,
+        companySlug: input.companySlug,
+    }).replace(/\/$/, ""));
+    const lines = [
+        "✗ None of the paths you named were uploaded: every file in them is outside your write access.",
+    ];
+    for (const key of keys) {
+        lines.push(input.prefixSet === undefined
+            ? "  · " + key + " — the server refused writes here (an ACL on this path or a parent blocks you)"
+            : "  · " + key + " — no write prefix you hold covers this path");
+    }
+    lines.push("  Run `hq access " + keys[0] + "` to see which ACL row blocks the write, then ask its creator or a company admin for write access.");
+    return lines;
+}
 /**
  * US-003: run one sync fanout under a client-health attempt/outcome report.
  * The report is best-effort, bounded, and swallowed — it can only append a
@@ -298,6 +446,34 @@ function resolveDeletePolicy() {
     return "currency-gated";
 }
 const DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS = 300;
+/**
+ * feedback_b7c00a62: run a `sync now` runner under the watchdog (see
+ * `utils/sync-watchdog.ts` for the limits). A timeout prints a clear message
+ * and unwinds as a failed {@link SyncExitError}, so {@link withSyncHealthReport}
+ * records the failure and exits 124. The failure report gets at most
+ * {@link SYNC_WATCHDOG_REPORT_GRACE_MS}; after that the process exits 124
+ * regardless, and the worker backstop stays armed behind both.
+ */
+export async function runUnderSyncWatchdog(limits, label, run, watchdog = withSyncWatchdog, exit = (code) => process.exit(code)) {
+    try {
+        return await watchdog(run, {
+            idleMs: limits.idleSeconds * 1000,
+            maxRuntimeMs: limits.maxRuntimeSeconds * 1000,
+            label,
+            probeProgress: createSnapshotProgressProbe(readSyncProgress),
+        });
+    }
+    catch (err) {
+        if (err instanceof SyncWatchdogTimeoutError) {
+            console.error(chalk.red("\n\u2717 " + err.message));
+            process.exitCode = SYNC_WATCHDOG_EXIT_CODE;
+            const forceExit = setTimeout(() => exit(SYNC_WATCHDOG_EXIT_CODE), SYNC_WATCHDOG_REPORT_GRACE_MS);
+            forceExit.unref();
+            throw new SyncExitError(SYNC_WATCHDOG_EXIT_CODE);
+        }
+        throw err;
+    }
+}
 /**
  * Bound foreground waits for a watcher/manual sync that currently owns the
  * per-root operation lock. The cloud engine reads this environment value on
@@ -947,6 +1123,9 @@ export function registerCloudCommands(program) {
         // failures never count as a sync attempt (US-003).
         let syncHealth;
         let explicitPersonalPaths;
+        // Company folder the push resolves relative paths against; names the
+        // .hqinclude line and the blocked path in failure output.
+        let pushCompanySlug;
         try {
             if (options.personal && options.credsFromStdin) {
                 throw new Error("`--personal` cannot be combined with --creds-from-stdin: " +
@@ -1063,6 +1242,14 @@ export function registerCloudCommands(program) {
                 companyRef: targetCompany ?? readActiveCompany(options.hqRoot),
             });
             const planLimitTracker = createPlanLimitRefusalTracker(companySlugForBilling(progressCompany));
+            // A cmp_ uid target has no slug in progressCompany; fall back to
+            // the entity slug, then the company folder the paths sit in.
+            pushCompanySlug =
+                companySlugForBilling(progressCompany).companySlug ??
+                    (entityContext && !entityContext.uid.startsWith("prs_")
+                        ? entityContext.slug
+                        : undefined) ??
+                    (personalMode ? undefined : companySlugFromSyncPaths(options.hqRoot, targetPaths));
             const identityHeld = createIdentityHeldTracker();
             syncHealth = beginSyncHealthReport();
             if (!personalMode) {
@@ -1191,6 +1378,18 @@ export function registerCloudCommands(program) {
                 for (const line of scopeExcludedLines(result.filesExcludedByScope, pushPrefixSet)) {
                     log(chalk.yellow(line));
                 }
+                for (const line of explicitPushBlockedLines({
+                    userNamedPaths,
+                    namedPaths: targetPaths,
+                    filesUploaded: result.filesUploaded,
+                    filesExcludedByScope: result.filesExcludedByScope,
+                    otherNotUploaded: staleRefusalCount + uploadFailed.count + identityHeldCount,
+                    prefixSet: pushPrefixSet,
+                    hqRoot: options.hqRoot,
+                    companySlug: pushCompanySlug,
+                })) {
+                    log(chalk.red(line));
+                }
                 for (const line of staleUploadRefusalLines(staleRefusalCount, result.filesRefusedStalePaths)) {
                     log(chalk.yellow(line));
                 }
@@ -1220,7 +1419,10 @@ export function registerCloudCommands(program) {
             }
             if (syncHealth)
                 await syncHealth.failed();
-            const message = formatSyncFailure(err);
+            const message = formatSyncFailure(err, {
+                hqRoot: options.hqRoot,
+                companySlug: pushCompanySlug,
+            });
             if (jsonMode) {
                 // In JSON mode, the parent process is parsing stderr for ndjson —
                 // human-formatted error lines would corrupt the stream. Emit a
@@ -1509,6 +1711,14 @@ export function registerCloudCommands(program) {
         .option("--force-scope-shrink", "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/.")
+        .option("--max-idle <seconds>", "For scheduled or unattended runs: stop with exit code " + SYNC_WATCHDOG_EXIT_CODE +
+        " 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)")
+        .option("--max-runtime <seconds>", "For scheduled or unattended runs: stop with exit code " + SYNC_WATCHDOG_EXIT_CODE +
+        " 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)")
         .action(async (options) => {
         const skips = refuseSyncForOffVaults("now", {
             all: options.all,
@@ -1519,15 +1729,19 @@ export function registerCloudCommands(program) {
         try {
             configureSyncLockTimeout(options.lockTimeout);
             assertSingleSelector(options, "now");
+            const watchdogLimits = resolveSyncWatchdogLimits({
+                maxIdle: options.maxIdle,
+                maxRuntime: options.maxRuntime,
+            });
             if (options.all) {
                 // `options.personal === false` is Commander's auto-negation
                 // of `--personal`; in `--all` mode that means "drop the
                 // personal leg from both legs of the bidirectional fanout"
                 // (see `--no-personal` option above).
-                await withSyncHealthReport(() => runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true, skips.skipPersonal, options.forceScopeShrink === true, skips.skipCompanies));
+                await withSyncHealthReport(() => runUnderSyncWatchdog(watchdogLimits, "hq sync now --all", () => runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true, skips.skipPersonal, options.forceScopeShrink === true, skips.skipCompanies)));
                 return;
             }
-            await withSyncHealthReport(() => runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true, options.forceScopeShrink === true));
+            await withSyncHealthReport(() => runUnderSyncWatchdog(watchdogLimits, "hq sync now", () => runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true, options.forceScopeShrink === true)));
         }
         catch (err) {
             console.error(chalk.red("\n✗ Sync now failed:"), err instanceof Error ? err.message : String(err));

package/dist/commands/core-company-index-scope-flag.d.ts

@@ -1,3 +1,10 @@
-export declare const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
+import { CORE_COMPANY_INDEX_SCOPE_FLAG } from "../lib/cli-flag-keys.js";
+export { CORE_COMPANY_INDEX_SCOPE_FLAG };
+/**
+ * Kill switch for company-scoped index rebuilds, default ON
+ * (indigo-feature-flags-default-on-as-fail-safes). An absent, archived or
+ * unreadable flag row keeps scoping on; only an explicit false turns it off,
+ * and then `companies` rebuilds every company as it did before scoping.
+ */
 export declare function coreCompanyIndexScopeEnabled(): boolean;
 //# sourceMappingURL=core-company-index-scope-flag.d.ts.map

package/dist/commands/core-company-index-scope-flag.js

@@ -1,6 +1,13 @@
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
-export const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
+import { CORE_COMPANY_INDEX_SCOPE_FLAG } from "../lib/cli-flag-keys.js";
+export { CORE_COMPANY_INDEX_SCOPE_FLAG };
+/**
+ * Kill switch for company-scoped index rebuilds, default ON
+ * (indigo-feature-flags-default-on-as-fail-safes). An absent, archived or
+ * unreadable flag row keeps scoping on; only an explicit false turns it off,
+ * and then `companies` rebuilds every company as it did before scoping.
+ */
 export function coreCompanyIndexScopeEnabled() {
-    return resolveProcessFlagGate(CORE_COMPANY_INDEX_SCOPE_FLAG, { fallback: false }, () => false);
+    return resolveProcessFlagGate(CORE_COMPANY_INDEX_SCOPE_FLAG, { fallback: true }, () => true, undefined, { acceptStaleSnapshot: true, killSwitchWithoutCompany: true });
 }
 //# sourceMappingURL=core-company-index-scope-flag.js.map

package/dist/commands/core-delegate-w1b.js

@@ -3,6 +3,7 @@ import { createHash, randomInt } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { callerIsMachinePrincipal } from "../lib/caller-principal.js";
 import { serializeJqJson } from "../lib/core-utils/jq-json-serializer.js";
 import { shellDisplayPath } from "../lib/core-utils/shell-display-path.js";
 import { matchingSecretPatterns } from "../lib/core-utils/secret-patterns.js";
@@ -1079,8 +1080,10 @@ function runSend(args, context) {
         catch {
             return fail("send", "could not persist sending state; no DM attempted");
         }
-        // The pickup DM is read by the person and acted on by their agent.
-        const dm = runHq(["dm", principal, headline, "--audience", "both", "--prompt-file", prompt, "--details-file", brief], context);
+        // The pickup DM is read by the person and acted on by their agent. Only an
+        // agent or bot may tag it `both`; a person login sends `human`.
+        const audience = callerIsMachinePrincipal() ? "both" : "human";
+        const dm = runHq(["dm", principal, headline, "--audience", audience, "--prompt-file", prompt, "--details-file", brief], context);
         if (dm.code !== 0)
             return fail("send", "hq dm delivery outcome is uncertain; status is sending, inspect DM history before retrying");
         const event = /eventId[: ]+([A-Za-z0-9_-]+)/.exec(dm.stdout ?? "")?.[1] ?? "";

package/dist/commands/core-dm-bind-native.js

@@ -2,6 +2,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { tokenIsMachinePrincipal } from "../lib/caller-principal.js";
 import { spawnSync } from "node:child_process";
 import { resolveWindowsExecutable } from "../lib/bot/runtime/windows.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
@@ -329,9 +330,12 @@ function latestCliEventId(d, ch) {
     });
     return String(jqAlternative(rows.at(-1)?.eventId, jqAlternative(rows.at(-1)?.messageId, "")));
 }
-async function sendHuman(d, ch, payload) {
+/** The ID token every human-API request in this file sends as its bearer. */
+function humanApiToken(d) {
+    return JSON.parse(d.fs.readFileSync(path.join(d.home, ".hq/cognito-tokens.json"), "utf8")).idToken;
+}
+async function sendHuman(d, ch, payload, token = humanApiToken(d)) {
     const config = JSON.parse(d.fs.readFileSync(path.join(d.home, ".hq/config.json"), "utf8"));
-    const token = JSON.parse(d.fs.readFileSync(path.join(d.home, ".hq/cognito-tokens.json"), "utf8")).idToken;
     const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
     const channelsResponse = await d.fetch(`${config.vaultApiUrl}/v1/notify/channels`, { headers, signal: AbortSignal.timeout(DM_BIND_API_TIMEOUT_MS) });
     const channels = await channelsResponse.json();
@@ -596,11 +600,22 @@ async function post(d, args) {
         const mentions = mentionsJson(d, sid, names);
         if (!mentions.length)
             return fail("no mention resolved to a channel member id — not posting an update that notifies nobody");
-        const payload = { body: postedMessage, mentions, audience: "agent" };
+        // People never send agent-tagged messages: a person login posts `human`.
+        // The audience is read from the token this request sends as its bearer, so
+        // a box with machine creds plus a person cache cannot tag a person-token
+        // post `agent` (the server rejects that with 403).
+        let token;
+        try {
+            token = humanApiToken(d);
+        }
+        catch (error) {
+            return utilityError(`hq-dm-bind: ${error.message}\n`, 1);
+        }
+        const payload = { body: postedMessage, mentions, audience: tokenIsMachinePrincipal(token) ? "agent" : "human" };
         if (root)
             payload.rootEventId = root;
         try {
-            eventId = await sendHuman(d, ch, payload);
+            eventId = await sendHuman(d, ch, payload, token);
         }
         catch (error) {
             return utilityError(`hq-dm-bind: ${error.message}\n`, 1);

package/dist/commands/core-rebuild-index-fast.js

@@ -1,5 +1,7 @@
 /** Isolated fast-entry adapter for rebuild-index native renderers. */
 import { CompanyIndexUserError, renderIndexTarget } from "../lib/index-render/index.js";
+import { planScopedRebuild } from "../lib/index-render/session-scope.js";
+import { CORE_COMPANY_INDEX_SCOPE_FLAG } from "../lib/cli-flag-keys.js";
 const targets = new Set([
     "all", "companies", "company-knowledge", "orchestrator", "projects",
     "public-knowledge", "reports", "social-drafts", "threads", "workers",
@@ -10,7 +12,10 @@ const targets = new Set([
  */
 export async function runRebuildIndexFast(args, _stdin, _cwd, hqRoot) {
     const [target, ...rest] = args;
-    if (!target || !targets.has(target) || rest.length > 0 || !hqRoot)
+    // The only argument the fast route takes is --all-companies; anything else
+    // needs the full graph's argument handling.
+    const allCompanies = rest.length === 1 && rest[0] === "--all-companies";
+    if (!target || !targets.has(target) || (rest.length > 0 && !allCompanies) || !hqRoot)
         return undefined;
     const logs = [];
     const flushLogs = () => {
@@ -19,11 +24,24 @@ export async function runRebuildIndexFast(args, _stdin, _cwd, hqRoot) {
     };
     try {
         const refused = [];
-        renderIndexTarget(target, {
-            root: hqRoot,
-            log: (message) => logs.push(message),
-            refused,
-        });
+        // Same session company scope as the full command, resolved before any
+        // write. A refusal falls back to the full graph, which reports it.
+        // The full flag registry is off-limits on the fast route; read the
+        // default-on kill switch from the lightweight snapshot reader, and only for
+        // the targets that need it.
+        const companyIndexScopeEnabled = target === "companies" || target === "all"
+            ? await (await import("../native-fast-route.js")).fastFlagEnabledDefaultOn(CORE_COMPANY_INDEX_SCOPE_FLAG)
+            : true;
+        const plan = planScopedRebuild(target, rest, hqRoot, process.env, { companyIndexScopeEnabled });
+        if (plan.warning)
+            logs.push(plan.warning);
+        for (const run of plan.runs) {
+            renderIndexTarget(run.target, {
+                root: hqRoot,
+                log: (message) => logs.push(message),
+                refused,
+            }, run.args);
+        }
         if (refused.length > 0)
             return undefined;
         flushLogs();

package/dist/commands/core.js

@@ -57,6 +57,7 @@ import { registerCoreWorkflowRunCommand } from "./core-workflow-run-command.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { interpreterFor, runBundledScript } from "../utils/run-bundled-script.js";
 import { CompanyIndexUserError, renderIndexTarget } from "../lib/index-render/index.js";
+import { planScopedRebuild, SESSION_SCOPE_HELP } from "../lib/index-render/session-scope.js";
 import { generateWorkersRegistry } from "../lib/workers-registry/index.js";
 import { scanPackages } from "../lib/scan-packages/index.js";
 import { detectStaleCorePolicyMirror } from "../lib/core-utils/detect-stale-core-policy-mirror.js";
@@ -671,6 +672,7 @@ export function registerCoreCommands(program) {
         const wantsHelp = rendererArgs.some((arg) => arg === "--help" || arg === "-h");
         if (wantsHelp && ["companies", "company-knowledge", "projects"].includes(entry.renderer)) {
             renderIndexTarget(entry.renderer, { root: "", output: (message) => process.stdout.write(message) }, rendererArgs);
+            process.stdout.write(SESSION_SCOPE_HELP);
             return;
         }
         if (wantsHelp) {
@@ -686,12 +688,22 @@ export function registerCoreCommands(program) {
         const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
         const refused = [];
         try {
-            renderIndexTarget(entry.renderer, {
-                root: hqRoot,
-                log: (message) => process.stderr.write(`${message}\n`),
-                force,
-                refused,
-            }, rendererArgs);
+            // Resolve the session's company scope before any write: a bound
+            // session rebuilds only its bound companies, and an unbound one must
+            // name a company or pass --all-companies.
+            const plan = planScopedRebuild(entry.renderer, rendererArgs, hqRoot, process.env, {
+                companyIndexScopeEnabled: coreCompanyIndexScopeEnabled(),
+            });
+            if (plan.warning)
+                process.stderr.write(`${plan.warning}\n`);
+            for (const run of plan.runs) {
+                renderIndexTarget(run.target, {
+                    root: hqRoot,
+                    log: (message) => process.stderr.write(`${message}\n`),
+                    force,
+                    refused,
+                }, run.args);
+            }
         }
         catch (error) {
             if (error instanceof CompanyIndexUserError)

package/dist/commands/dm.d.ts

@@ -77,6 +77,14 @@ export interface DmContact {
  * eba06f59). Returns null when nothing or more than one contact matches. Pure.
  */
 export declare function matchContactByName(contacts: DmContact[], name: string): DmContact | null;
+/**
+ * Every distinct contact (person or bot) whose display name matches `name`,
+ * using the same rule as matchContactByName. A leading '@' is the explicit
+ * person/bot selector and is ignored for matching. Pure.
+ */
+export declare function matchContactsByName(contacts: DmContact[], name: string): DmContact[];
+/** One line per ambiguous contact match, for a refusal message. Pure. */
+export declare function formatContactMatches(matches: DmContact[]): string;
 /**
  * The confirmation line for a channel send. When the typed target is not the
  * channel's own display name (for example `hq dm setup` matching a channel
@@ -236,15 +244,21 @@ export declare function fetchChannels(token: string): Promise<ChannelSummary[]>;
  * post itself passes. Used to resolve `@name` mentions into participant uids.
  */
 export declare function fetchChannelMembers(token: string, channelId: string): Promise<ChannelMember[]>;
+/** An explicit agent/both audience from a person login. */
+export declare class PersonAudienceError extends Error {
+    constructor();
+}
 /**
  * Resolve the audience for a send. The default comes from the recipient kind
- * (`defaultAudienceFor`); `--for-human` maps to `human`; an explicit
- * `--audience` wins over `--for-human` (with a warning) and is validated.
+ * and the caller (`defaultAudienceFor`: always `human` for a person login);
+ * `--for-human` maps to `human`; an explicit `--audience` wins over
+ * `--for-human` (with a warning) and is validated. A person login passing
+ * `--audience agent|both` throws PersonAudienceError.
  */
 export declare function resolveSendAudience(opts: {
     audience?: string;
     forHuman?: boolean;
-}, recipientKind: DmRecipientKind, warn?: (msg: string) => void): string;
+}, recipientKind: DmRecipientKind, warn?: (msg: string) => void, machineCaller?: boolean): string;
 /** One incoming DM as returned by GET /v1/notify/inbox. */
 export interface DmInboxEvent {
     eventId: string;