@indigoai-us/hq-cli 5.345.104 → 5.345.106

package/dist/lib/daemon/remote-control-pools.js

@@ -0,0 +1,245 @@
+/** Host-local desired state for opt-in Claude Remote Control account pools. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { isIPv4 } from "node:net";
+import { readSessionCompanyLock } from "../session-company-lock.js";
+import { ensurePrivateDir } from "./paths.js";
+const ACCOUNT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,127}$/;
+const CAPACITY_MIN = 1;
+const CAPACITY_MAX = 100;
+const PORT_MIN = 1024;
+const PORT_MAX = 65535;
+function object(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function absoluteRealPath(value, field) {
+    if (typeof value !== "string" || !path.isAbsolute(value) || value.includes("\0")) {
+        throw new Error(`${field} must be an absolute path`);
+    }
+    return path.normalize(value);
+}
+function port(value, field) {
+    if (!Number.isInteger(value) || value < PORT_MIN || value > PORT_MAX) {
+        throw new Error(`${field} must be an integer from ${PORT_MIN} to ${PORT_MAX}`);
+    }
+    return value;
+}
+function frontendAddress(value, field) {
+    if (typeof value !== "string" || !isIPv4(value) || !value.startsWith("127.")) {
+        throw new Error(`${field} must be a distinct 127.0.0.0/8 IPv4 loopback address`);
+    }
+    return value;
+}
+/** Parse and validate the complete desired state; unknown keys fail closed. */
+export function parseRemoteControlPoolsConfig(value, knownAccountIds, home = os.homedir()) {
+    if (!object(value))
+        throw new Error("remote-control pools config must be a JSON object");
+    if (Object.keys(value).some((key) => !["version", "pools", "frontendCaPath", "serviceSessionId"].includes(key))) {
+        throw new Error("remote-control pools config contains an unknown field");
+    }
+    if (value.version !== 1)
+        throw new Error("remote-control pools config version must be 1");
+    if (!Array.isArray(value.pools))
+        throw new Error("remote-control pools config pools must be an array");
+    let frontendCaPath;
+    if (value.frontendCaPath !== undefined)
+        frontendCaPath = absoluteRealPath(value.frontendCaPath, "frontendCaPath");
+    if (value.pools.length > 0 && !frontendCaPath)
+        throw new Error("frontendCaPath is required when remote-control pools are configured");
+    let serviceSessionId;
+    if (value.serviceSessionId !== undefined) {
+        if (typeof value.serviceSessionId !== "string" || !/^[A-Za-z0-9._-]+$/.test(value.serviceSessionId) || value.serviceSessionId === "." || value.serviceSessionId === "..") {
+            throw new Error("serviceSessionId must be a valid HQ session ID");
+        }
+        serviceSessionId = value.serviceSessionId;
+    }
+    if (value.pools.length > 0 && !serviceSessionId) {
+        throw new Error("serviceSessionId is required when remote-control pools are configured");
+    }
+    const seenAccounts = new Set();
+    const known = knownAccountIds === undefined ? null : new Set(knownAccountIds);
+    const seenEndpoints = new Set();
+    const seenPaths = new Set();
+    const pools = value.pools.map((raw, index) => {
+        const prefix = `pools[${index}]`;
+        if (!object(raw))
+            throw new Error(`${prefix} must be a JSON object`);
+        const allowed = ["accountId", "capacity", "frontendAddress", "frontendPort", "forwarderPort", "mountPath", "secretName"];
+        if (Object.keys(raw).some((key) => !allowed.includes(key)))
+            throw new Error(`${prefix} contains an unknown field`);
+        if (typeof raw.accountId !== "string" || !ACCOUNT_ID.test(raw.accountId)) {
+            throw new Error(`${prefix}.accountId is invalid`);
+        }
+        if (known && !known.has(raw.accountId))
+            throw new Error(`${prefix}.accountId "${raw.accountId}" is not configured in hq lanes accounts`);
+        if (seenAccounts.has(raw.accountId))
+            throw new Error(`duplicate accountId "${raw.accountId}"`);
+        seenAccounts.add(raw.accountId);
+        if (!Number.isInteger(raw.capacity) || raw.capacity < CAPACITY_MIN || raw.capacity > CAPACITY_MAX) {
+            throw new Error(`${prefix}.capacity must be an integer from ${CAPACITY_MIN} to ${CAPACITY_MAX}`);
+        }
+        const address = frontendAddress(raw.frontendAddress, `${prefix}.frontendAddress`);
+        if (raw.frontendPort !== 443)
+            throw new Error(`${prefix}.frontendPort must be 443`);
+        const frontendPort = 443;
+        const forwarderPort = port(raw.forwarderPort, `${prefix}.forwarderPort`);
+        const forwarderEndpoint = `127.0.0.1:${forwarderPort}`;
+        if (seenEndpoints.has(forwarderEndpoint))
+            throw new Error(`duplicate pool endpoint ${forwarderEndpoint}`);
+        seenEndpoints.add(forwarderEndpoint);
+        const endpoint = `${address}:${frontendPort}`;
+        if (seenEndpoints.has(endpoint))
+            throw new Error(`duplicate pool frontend endpoint ${endpoint}`);
+        seenEndpoints.add(endpoint);
+        const mountPath = absoluteRealPath(raw.mountPath, `${prefix}.mountPath`);
+        if (mountPath !== path.join(home, ".local", "state", "hq-remote-control", raw.accountId)) {
+            throw new Error(`${prefix}.mountPath must be ${path.join(home, ".local", "state", "hq-remote-control", raw.accountId)}`);
+        }
+        if (seenPaths.has(mountPath))
+            throw new Error(`duplicate mountPath "${mountPath}"`);
+        seenPaths.add(mountPath);
+        if (typeof raw.secretName !== "string" || !SECRET_NAME.test(raw.secretName)) {
+            throw new Error(`${prefix}.secretName is invalid`);
+        }
+        return {
+            accountId: raw.accountId,
+            capacity: raw.capacity,
+            frontendAddress: address,
+            frontendPort,
+            forwarderPort,
+            mountPath,
+            secretName: raw.secretName,
+        };
+    });
+    return { version: 1, ...(frontendCaPath ? { frontendCaPath } : {}), ...(serviceSessionId ? { serviceSessionId } : {}), pools };
+}
+/** Override ambient session selection only for a Secrets child process. */
+export function remoteControlPoolSecretsEnv(env, serviceSessionId) {
+    return { ...env, HQ_SESSION_ID: serviceSessionId };
+}
+/** Require an explicit, existing capability; never inherit the mutable .current session. */
+export function assertPersonalServiceSessionCapability(root, serviceSessionId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(serviceSessionId) || serviceSessionId === "." || serviceSessionId === "..") {
+        throw new Error("configured serviceSessionId is not a valid HQ session ID");
+    }
+    const capabilityPath = path.join(root, "workspace", "sessions", serviceSessionId, "scope-capability.json");
+    let stat;
+    try {
+        stat = fs.lstatSync(capabilityPath);
+    }
+    catch {
+        throw new Error("configured serviceSessionId has no readable scope capability");
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error("configured serviceSessionId has no readable scope capability");
+    }
+    const lock = readSessionCompanyLock({ ...process.env, HQ_ROOT: root, HQ_SESSION_ID: serviceSessionId });
+    if (!lock || lock.sessionId !== serviceSessionId || lock.companies.length !== 1 || lock.companies[0] !== "personal") {
+        throw new Error("configured serviceSessionId must have a personal-only scope capability");
+    }
+}
+/** Hosts file overlay consumed inside this pool's private mount namespace. */
+export function remoteControlPoolHostsOverlay(pool) {
+    return `${pool.frontendAddress} api.anthropic.com\n`;
+}
+export function poolHostsFile(baseHosts, pool) {
+    const retained = baseHosts
+        .split(/\r?\n/)
+        .filter((line) => !/(^|\s)api\.anthropic\.com(?:\s|$)/.test(line))
+        .filter((line) => line.trim() !== "");
+    return `${retained.join("\n")}\n${remoteControlPoolHostsOverlay(pool)}`;
+}
+export function readRemoteControlPoolsConfig(file, knownAccountIds, home = os.homedir()) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { version: 1, pools: [] };
+        throw new Error(`could not read remote-control pools config: ${error.message}`);
+    }
+    return parseRemoteControlPoolsConfig(parsed, knownAccountIds, home);
+}
+export function writeRemoteControlPoolsConfig(file, config, home = os.homedir()) {
+    const validated = parseRemoteControlPoolsConfig(config, undefined, home);
+    ensurePrivateDir(path.dirname(file));
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(validated, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temp, file);
+    fs.chmodSync(file, 0o600);
+}
+export function remoteControlPoolArgs(pool) {
+    return [
+        "remote-control",
+        "--no-create-session-in-dir",
+        "--capacity",
+        String(pool.capacity),
+        "--name",
+        `hq-${pool.accountId}`,
+        "--spawn=same-dir",
+        "--permission-mode",
+        "bypassPermissions",
+    ];
+}
+/** Reject an existing symlink anywhere in the requested path. */
+export function assertNoSymlinkPathComponents(target) {
+    const parsed = path.parse(target);
+    let cursor = parsed.root;
+    for (const part of target.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        cursor = path.join(cursor, part);
+        try {
+            if (fs.lstatSync(cursor).isSymbolicLink())
+                throw new Error("pool mountPath cannot contain symlinks");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+/** Compare paths after resolving their real filesystem identities. */
+export function assertDistinctRealMountPath(mountPath, hqRoot) {
+    const realRoot = fs.realpathSync(hqRoot);
+    assertNoSymlinkPathComponents(mountPath);
+    let resolvedMount;
+    try {
+        resolvedMount = fs.realpathSync(mountPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        const parent = path.dirname(mountPath);
+        resolvedMount = path.join(fs.realpathSync(parent), path.basename(mountPath));
+    }
+    if (resolvedMount === realRoot || resolvedMount.startsWith(`${realRoot}${path.sep}`) || realRoot.startsWith(`${resolvedMount}${path.sep}`)) {
+        throw new Error("pool mountPath must be distinct from the HQ root after realpath resolution");
+    }
+}
+/** Validate the private readiness marker against the live forwarder process identity. */
+export function isOwnedPoolForwarder(readyFile, accountId, isAlive, commandLine) {
+    try {
+        const marker = JSON.parse(fs.readFileSync(readyFile, "utf8"));
+        if (marker.accountId !== accountId || !Number.isSafeInteger(marker.pid) || marker.pid <= 0)
+            return false;
+        const pid = marker.pid;
+        const line = isAlive(pid) ? commandLine(pid) : null;
+        const args = line?.split(/\s+/) ?? [];
+        const accountFlag = args.indexOf("--account-id");
+        return args.includes("remote-control-pool-forwarder") && accountFlag >= 0 && args[accountFlag + 1] === accountId;
+    }
+    catch {
+        return false;
+    }
+}
+/** Fail the pool host when its separately supervised inference process disappears. */
+export async function monitorOwnedPoolForwarder(isOwned, signal, sleep = () => new Promise((resolve) => setTimeout(resolve, 500))) {
+    while (!signal.aborted) {
+        if (!isOwned())
+            throw new Error("the owned pool inference forwarder exited or lost its listener");
+        await sleep();
+    }
+}
+//# sourceMappingURL=remote-control-pools.js.map

package/dist/lib/daemon/remote-control.d.ts

@@ -53,6 +53,10 @@ export declare const IDLE_BEFORE_RESTART_MS: number;
 export declare const MAX_RESTART_WAIT_MS: number;
 export interface RemoteControlHostDeps {
     tmux: string;
+    /** Optional private tmux server per managed pool; A keeps the legacy socket. */
+    tmuxSocket?: string;
+    /** Environment applied only to this private tmux server before its session starts. */
+    sessionEnv?: Record<string, string | null>;
     /** tmux session name on the daemon's private socket. */
     session: string;
     /** Folder the command starts in (the HQ folder). */

package/dist/lib/daemon/remote-control.js

@@ -204,7 +204,7 @@ function safePaneTail(output) {
         .join("\n");
 }
 export async function runRemoteControlHost(deps) {
-    const tmux = (...args) => deps.run(deps.tmux, ["-L", TMUX_SOCKET, ...args]);
+    const tmux = (...args) => deps.run(deps.tmux, ["-L", deps.tmuxSocket ?? TMUX_SOCKET, ...args]);
     const invokerPid = process.pid;
     const killSession = () => {
         if (tmux("has-session", "-t", deps.session).status !== 0)
@@ -279,11 +279,26 @@ export async function runRemoteControlHost(deps) {
         await deps.sleep(deps.pollMs);
     }
     // Start the replacement only after no live foreign Claude owner remains.
-    const created = tmux("new-session", "-d", "-s", deps.session, "-x", "200", "-y", "50", "-c", deps.cwd);
+    // A private pool socket has no server until its first session is created.
+    // Keep that first pane inert, then set only this session's environment before
+    // replacing it with the actual command. The ordinary A service keeps its
+    // existing shell startup path when no session environment is configured.
+    const bootstrap = deps.sessionEnv ? ["/usr/bin/sleep", "2147483647"] : [];
+    const created = tmux("new-session", "-d", "-s", deps.session, "-x", "200", "-y", "50", "-c", deps.cwd, ...bootstrap);
     if (created.status !== 0) {
         deps.log(`could not create the tmux session: ${created.stderr.trim() || `tmux exited ${created.status}`}`);
         return 1;
     }
+    for (const [name, value] of Object.entries(deps.sessionEnv ?? {})) {
+        const result = value === null
+            ? tmux("set-environment", "-u", "-t", deps.session, name)
+            : tmux("set-environment", "-t", deps.session, name, value);
+        if (result.status !== 0) {
+            deps.log(`could not configure the private tmux environment for ${name}`);
+            tmux("kill-session", "-t", deps.session);
+            return 1;
+        }
+    }
     const creatorRecord = JSON.stringify({ pid: invokerPid, cwd: deps.cwd });
     const recorded = tmux("set-option", "-t", deps.session, TMUX_CREATOR_OPTION, creatorRecord);
     if (recorded.status !== 0) {

package/dist/lib/daemon/run.js

@@ -22,6 +22,8 @@ import { readBotConfig } from "../bot/config.js";
 import { botsRoot } from "../bot/paths.js";
 import { CLAUDE_RUNNER_SCRIPT, CODEX_RUNNER_SCRIPT, enabledServices, planUnits } from "./catalog.js";
 import { effectiveSyncOwner, readDaemonConfig } from "./config.js";
+import { assertPersonalServiceSessionCapability, readRemoteControlPoolsConfig, remoteControlPoolSecretsEnv, } from "./remote-control-pools.js";
+import { loadLanesConfig } from "../lanes/config.js";
 import { SUPERVISOR_HANDOFF_FLAG, readDaemonFlag } from "./flag.js";
 import { findLegacyUnits, legacyMeshUnitsToRetire, legacyOwnerLookup } from "./legacy.js";
 import { readLegacySyncEnv } from "./legacy-sync-env.js";
@@ -636,6 +638,45 @@ export async function runDaemon(opts) {
     };
     let warnedMissingPin = null;
     let warnedMissingSyncRunner = false;
+    const poolProbeCache = new Map();
+    const poolProbeProcess = (file, args, options) => new Promise((resolve) => {
+        const child = spawn(file, args, { cwd: options.cwd, env: options.env, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+        let stdout = "";
+        let error = false;
+        child.stdout?.on("data", (chunk) => { stdout += chunk.toString().slice(0, 256); });
+        child.on("error", () => { error = true; });
+        const timer = setTimeout(() => child.kill("SIGKILL"), options.timeout);
+        child.once("close", (status) => { clearTimeout(timer); resolve({ status, stdout, error }); });
+    });
+    const poolProbe = (key, probe) => {
+        const cached = poolProbeCache.get(key);
+        if (cached && (cached.pending || Date.now() - cached.at < 30_000))
+            return cached.value;
+        let result;
+        try {
+            result = probe();
+        }
+        catch (error) {
+            log("error", `remote-control pool probe ${key} failed: ${error.message}`);
+            poolProbeCache.set(key, { at: Date.now(), value: "unavailable" });
+            return "unavailable";
+        }
+        if (typeof result === "string") {
+            poolProbeCache.set(key, { at: Date.now(), value: result });
+            return result;
+        }
+        const pending = { at: Date.now(), value: cached?.value ?? "unavailable", pending: true };
+        poolProbeCache.set(key, pending);
+        result.then((value) => {
+            if (poolProbeCache.get(key) === pending)
+                poolProbeCache.set(key, { at: Date.now(), value });
+        }, (error) => {
+            log("error", `remote-control pool probe ${key} failed: ${error.message}`);
+            if (poolProbeCache.get(key) === pending)
+                poolProbeCache.set(key, { at: Date.now(), value: "unavailable" });
+        });
+        return pending.value;
+    };
     const daemonSyncRunnerPids = new Set();
     let supervisor = null;
     const plan = () => {
@@ -643,6 +684,83 @@ export async function runDaemon(opts) {
         const legacy = legacyUnits();
         const configured = config.hqRoot ?? (env.HQ_ROOT?.trim() || undefined);
         const hqRoot = configured && fs.existsSync(configured) ? configured : undefined;
+        let remoteControlPools = { version: 1, pools: [] };
+        let remoteControlPoolsError;
+        try {
+            if (fs.existsSync(paths.remoteControlPoolsPath)) {
+                const knownAccounts = hqRoot ? Object.keys(loadLanesConfig(hqRoot).providers.claude.accounts) : undefined;
+                remoteControlPools = readRemoteControlPoolsConfig(paths.remoteControlPoolsPath, knownAccounts, home);
+            }
+        }
+        catch (error) {
+            remoteControlPoolsError = error.message;
+            log("error", `remote-control pool config is invalid: ${remoteControlPoolsError}`);
+        }
+        const availablePoolSecrets = new Set();
+        const unverifiablePoolSecrets = new Set();
+        const invalidPoolServiceSessions = new Set();
+        const availablePoolFrontends = new Set();
+        const unverifiablePoolFrontends = new Set();
+        for (const pool of remoteControlPools.pools) {
+            const serviceSession = poolProbe(`service-session:${remoteControlPools.serviceSessionId ?? ""}`, () => {
+                try {
+                    if (!remoteControlPools.serviceSessionId)
+                        return "unavailable";
+                    assertPersonalServiceSessionCapability(hqRoot ?? home, remoteControlPools.serviceSessionId);
+                    return "available";
+                }
+                catch {
+                    return "unavailable";
+                }
+            });
+            if (serviceSession === "unavailable")
+                invalidPoolServiceSessions.add(pool.accountId);
+            const secret = serviceSession === "available" ? poolProbe(`secret:${pool.secretName}`, async () => {
+                const result = await poolProbeProcess(opts.hqBinary, ["secrets", "--personal", "exists", pool.secretName, "--quiet"], {
+                    cwd: hqRoot ?? home,
+                    env: remoteControlPoolSecretsEnv({
+                        ...env,
+                        ...(hqRoot ? { HQ_ROOT: hqRoot } : {}),
+                        HQ_NO_UPDATE_CHECK: "1",
+                    }, remoteControlPools.serviceSessionId),
+                    timeout: 15_000,
+                });
+                if (result.status === 0)
+                    return "available";
+                return result.status === 1 ? "missing" : "unavailable";
+            }) : "unavailable";
+            if (secret === "available")
+                availablePoolSecrets.add(pool.secretName);
+            if (secret === "unavailable" && serviceSession === "available")
+                unverifiablePoolSecrets.add(pool.secretName);
+            let caValid = false;
+            try {
+                const caStat = fs.statSync(remoteControlPools.frontendCaPath);
+                caValid = caStat.isFile() && fs.accessSync(remoteControlPools.frontendCaPath, fs.constants.R_OK) === undefined;
+            }
+            catch {
+                caValid = false;
+            }
+            const frontend = poolProbe(`frontend:${pool.accountId}:${pool.frontendAddress}`, async () => {
+                if (!caValid)
+                    return "unavailable";
+                const result = await poolProbeProcess("curl", [
+                    "--silent", "--show-error", "--output", "/dev/null", "--write-out", "%{http_code}",
+                    "--connect-timeout", "1", "--max-time", "2", "--head",
+                    "--cacert", remoteControlPools.frontendCaPath,
+                    "--resolve", `api.anthropic.com:443:${pool.frontendAddress}`,
+                    "https://api.anthropic.com/v1/messages",
+                ], { timeout: 3_000 });
+                const code = Number.parseInt(result.stdout.trim(), 10);
+                if (result.status === 0 && code >= 100 && code <= 599)
+                    return "available";
+                return result.error ? "unavailable" : "missing";
+            });
+            if (frontend === "available")
+                availablePoolFrontends.add(pool.accountId);
+            if (frontend === "unavailable")
+                unverifiablePoolFrontends.add(pool.accountId);
+        }
         getStagedHqChildBootstrap();
         const staged = getStagedSyncBundle();
         // Before release, preserve today's selection. Later plans can only use the
@@ -746,6 +864,14 @@ export async function runDaemon(opts) {
             remoteControlName: runnerSessionName(readIfExists(CLAUDE_RUNNER_SCRIPT) ?? ""),
             tmuxPath: findOnPath("tmux", env),
             hostName,
+            claudeConfigDir: env.CLAUDE_CONFIG_DIR?.trim() || path.join(home, ".claude"),
+            remoteControlPools,
+            remoteControlPoolsError,
+            availablePoolSecrets,
+            unverifiablePoolSecrets,
+            invalidPoolServiceSessions,
+            availablePoolFrontends,
+            unverifiablePoolFrontends,
         });
         if (startupPlanOpen) {
             const replaceablePackageRoots = cliPackageRoot ? [cliPackageRoot] : [];

package/dist/lib/doctor/fix/refresh-sync-progress.d.ts

@@ -3,9 +3,10 @@
  *
  * `lastAttemptedSlug` is written before each pull so a killed repair resumes
  * after that company instead of starving later journals. `lastRunAttemptedCheckIds`
- * is written only when a repair pass finishes, so `--client-health-report`
- * can omit company journals this pass did not try — the SessionStart hook
- * otherwise files those leftover rows as unrepaired.
+ * is written only when a repair pass finishes, so doctor JSON
+ * (`--json` and `--client-health-report`) can omit company journals this
+ * pass did not try — SessionStart hooks, including older ones that only
+ * call `hq doctor --json`, otherwise file those leftover rows as unrepaired.
  */
 import type { CheckResult } from "../types.js";
 export declare const REFRESH_SYNC_PROGRESS_RELATIVE_PATH: string;
@@ -27,6 +28,6 @@ export declare function writeRefreshSyncLastRun(hqRoot: string, input: {
     lastRunAtMs: number;
 }): void;
 export declare function freshAttemptedCompanyJournalCheckIds(hqRoot: string, nowMs: number): ReadonlySet<string> | null;
-/** True when a client-health report should hide this leftover company journal. */
+/** True when doctor JSON should hide this leftover company journal. */
 export declare function isUnreachedCompanyJournalForClientHealth(result: CheckResult, attemptedCheckIds: ReadonlySet<string> | null): boolean;
 //# sourceMappingURL=refresh-sync-progress.d.ts.map

package/dist/lib/doctor/fix/refresh-sync-progress.js

@@ -3,9 +3,10 @@
  *
  * `lastAttemptedSlug` is written before each pull so a killed repair resumes
  * after that company instead of starving later journals. `lastRunAttemptedCheckIds`
- * is written only when a repair pass finishes, so `--client-health-report`
- * can omit company journals this pass did not try — the SessionStart hook
- * otherwise files those leftover rows as unrepaired.
+ * is written only when a repair pass finishes, so doctor JSON
+ * (`--json` and `--client-health-report`) can omit company journals this
+ * pass did not try — SessionStart hooks, including older ones that only
+ * call `hq doctor --json`, otherwise file those leftover rows as unrepaired.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -93,7 +94,7 @@ export function freshAttemptedCompanyJournalCheckIds(hqRoot, nowMs) {
     }
     return new Set(progress.lastRunAttemptedCheckIds);
 }
-/** True when a client-health report should hide this leftover company journal. */
+/** True when doctor JSON should hide this leftover company journal. */
 export function isUnreachedCompanyJournalForClientHealth(result, attemptedCheckIds) {
     if (!attemptedCheckIds)
         return false;

package/dist/lib/doctor/json-output.d.ts

@@ -109,11 +109,11 @@ export interface BuildDoctorJsonInput {
      * Ordinary hq-core upgrade WARNs and leftover `sync.journal.personal` WARNs
      * are omitted from every JSON document (`--json` and `--client-health-report`),
      * including `summary` tallies: `--fix` cannot apply a release, and the leftover
-     * personal shard is not a live sync target. Both current hooks and older ones
-     * that only call `hq doctor --json` treated those leftover WARNs as unrepaired
-     * failures. Human `hq doctor` still prints them. Company journals this `--fix`
-     * pass did not try to refresh are omitted only from `--client-health-report`:
-     * the repair cap leaves them for a later session.
+     * personal shard is not a live sync target. Company journals this `--fix`
+     * pass did not try to refresh are omitted the same way: the repair cap leaves
+     * them for a later session, and older hooks that only call `hq doctor --json`
+     * treated those leftover WARNs as unrepaired failures. Human `hq doctor`
+     * still prints them.
      */
     clientHealthReport?: boolean;
     /** Clock for the leftover-journal freshness window. Default: `Date.now`. */

package/dist/lib/doctor/json-output.js

@@ -62,17 +62,14 @@ function summarizeJsonResults(results) {
 }
 /** Assemble the machine-readable document from a completed run. */
 export function buildDoctorJson(input) {
-    const attemptedRefreshSyncCheckIds = input.clientHealthReport === true
-        ? freshAttemptedCompanyJournalCheckIds(input.hqRoot, (input.now ?? (() => new Date()))().getTime())
-        : null;
+    const attemptedRefreshSyncCheckIds = freshAttemptedCompanyJournalCheckIds(input.hqRoot, (input.now ?? (() => new Date()))().getTime());
     const results = [];
     for (const run of input.families) {
         for (const result of run.results) {
             if (omitFromDoctorJson(result)) {
                 continue;
             }
-            if (input.clientHealthReport === true &&
-                isUnreachedCompanyJournalForClientHealth(result, attemptedRefreshSyncCheckIds)) {
+            if (isUnreachedCompanyJournalForClientHealth(result, attemptedRefreshSyncCheckIds)) {
                 continue;
             }
             results.push(toJsonResult(run.family.id, result, input.clientHealthReasonCodesEnabledCheckIds, input.clientHealthCheckStatusEnabledCheckIds));

package/dist/lib/packages/setup-block.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The `setup:` block of a content pack's package.yaml (sample-pack-in-app-setup
+ * US-001, build contract section 1).
+ *
+ * A pack that declares one can be set up from the HQ app chat: the pack's own
+ * bot (`setup.bot.name`, also a worker under `contributes.workers`) asks the
+ * questions in order with tap-to-answer suggestions, then runs `setup.run`
+ * with the answers. `hq packages install` validates the block and fails naming
+ * the field; a pack without the block is untouched.
+ *
+ * Validation (contract):
+ * - `setup.bot.name` matches ^[a-z0-9-]{2,32}$ and appears in contributes.workers
+ * - question ids unique, ^[a-z_]+$; options is a list of strings (may be empty)
+ * - `run.script` exists in the pack; every `run.args` key is a question id;
+ *   every `then` entry's first token exists in the pack
+ */
+import type { PackManifest, PackSetup } from "../../types.js";
+export declare const SETUP_BOT_NAME_RE: RegExp;
+export declare const SETUP_QUESTION_ID_RE: RegExp;
+/** A validation failure; `field` is the dotted path of the offending field. */
+export declare class PackSetupError extends Error {
+    readonly field: string;
+    constructor(field: string, detail: string);
+}
+export interface SetupBlockContext {
+    /** Pack root on disk (the payload at install, `core/packages/<name>` later). */
+    packDir: string;
+    /** `contributes.workers` of the same manifest. */
+    workers: readonly string[];
+    /** Filesystem seam for tests; defaults to node:fs. */
+    existsSync?: (p: string) => boolean;
+}
+/**
+ * Validate a raw `setup:` value. Returns the typed block, or undefined when the
+ * manifest has no block (a legacy pack). Throws PackSetupError naming the field.
+ */
+export declare function parseSetupBlock(raw: unknown, ctx: SetupBlockContext): PackSetup | undefined;
+/**
+ * The validated setup block of an installed pack, or undefined when the pack
+ * has none or the block is invalid (`hq packages list` prints `setup: no`).
+ */
+export declare function readInstalledPackSetup(manifest: Pick<PackManifest, "setup" | "contributes"> | null | undefined, packDir: string, existsSync?: (p: string) => boolean): PackSetup | undefined;
+//# sourceMappingURL=setup-block.d.ts.map