@indigoai-us/hq-cli 5.345.103 → 5.345.105

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

@@ -106,13 +106,14 @@ export interface BuildDoctorJsonInput {
     clientHealthCheckStatusEnabledCheckIds?: ReadonlySet<string>;
     /**
      * JSON consumed by the SessionStart health hook (`--client-health-report`).
-     * Ordinary hq-core upgrade WARNs are omitted from every JSON document
-     * (`--json` and `--client-health-report`), including `summary` tallies:
-     * `--fix` cannot apply a release, and both current hooks and older ones
-     * that only call `hq doctor --json` treated the leftover WARN as an
-     * unrepaired failure. Human `hq doctor` still prints the upgrade. 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.
+     * 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. 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`. */
@@ -129,6 +130,17 @@ export declare function isOrdinaryCoreUpdateWarn(result: {
     checkId: string;
     status: DoctorStatus;
 }): boolean;
+/**
+ * True when doctor still WARNs on the leftover `personal` journal shard.
+ * That file is not the live personal-files target; `--fix` refreshes the vault
+ * journal instead. JSON omits the WARN so older `--json` health hooks do not
+ * file it as a failed repair. FAIL stays visible. NA leftover rows stay in
+ * JSON so operators can still see the unused shard.
+ */
+export declare function isLeftoverPersonalJournalWarn(result: {
+    checkId: string;
+    status: DoctorStatus;
+}): boolean;
 /** Assemble the machine-readable document from a completed run. */
 export declare function buildDoctorJson(input: BuildDoctorJsonInput): DoctorJsonDocument;
 /** Serialise the document as pretty-printed JSON with a trailing newline. */

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

@@ -40,6 +40,19 @@ export const DOCTOR_JSON_SCHEMA_VERSION = 2;
 export function isOrdinaryCoreUpdateWarn(result) {
     return result.checkId === "sync.update.core" && result.status === "WARN";
 }
+/**
+ * True when doctor still WARNs on the leftover `personal` journal shard.
+ * That file is not the live personal-files target; `--fix` refreshes the vault
+ * journal instead. JSON omits the WARN so older `--json` health hooks do not
+ * file it as a failed repair. FAIL stays visible. NA leftover rows stay in
+ * JSON so operators can still see the unused shard.
+ */
+export function isLeftoverPersonalJournalWarn(result) {
+    return result.checkId === "sync.journal.personal" && result.status === "WARN";
+}
+function omitFromDoctorJson(result) {
+    return isOrdinaryCoreUpdateWarn(result) || isLeftoverPersonalJournalWarn(result);
+}
 /** Tally the results that actually ship in the JSON document. */
 function summarizeJsonResults(results) {
     const counts = emptyStatusCounts();
@@ -49,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 (isOrdinaryCoreUpdateWarn(result)) {
+            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

package/dist/lib/packages/setup-block.js

@@ -0,0 +1,236 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+export const SETUP_BOT_NAME_RE = /^[a-z0-9-]{2,32}$/;
+export const SETUP_QUESTION_ID_RE = /^[a-z_]+$/;
+/** A validation failure; `field` is the dotted path of the offending field. */
+export class PackSetupError extends Error {
+    field;
+    constructor(field, detail) {
+        super(`${field} ${detail}`);
+        this.field = field;
+        this.name = "PackSetupError";
+    }
+}
+function isMapping(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new PackSetupError(field, "must be a non-empty string");
+    }
+    return value;
+}
+function optionalBoolean(value, field, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "boolean")
+        throw new PackSetupError(field, "must be true or false");
+    return value;
+}
+/** A relative pack path that stays inside the pack root; null when it escapes. */
+function insidePack(packDir, rel) {
+    if (path.isAbsolute(rel))
+        return null;
+    const root = path.resolve(packDir);
+    const abs = path.resolve(root, rel);
+    if (abs !== root && !abs.startsWith(`${root}${path.sep}`))
+        return null;
+    return abs;
+}
+function requirePackFile(ctx, rel, field) {
+    const exists = ctx.existsSync ?? fs.existsSync;
+    const abs = insidePack(ctx.packDir, rel);
+    if (!abs)
+        throw new PackSetupError(field, `"${rel}" must be a relative path inside the pack`);
+    if (!exists(abs))
+        throw new PackSetupError(field, `"${rel}" does not exist in the pack`);
+}
+function parseQuestion(raw, index) {
+    const field = `setup.questions[${index}]`;
+    if (!isMapping(raw))
+        throw new PackSetupError(field, "must be a mapping with id and text");
+    const id = requireString(raw.id, `${field}.id`);
+    if (!SETUP_QUESTION_ID_RE.test(id)) {
+        throw new PackSetupError(`${field}.id`, `"${id}" must match ${SETUP_QUESTION_ID_RE.source}`);
+    }
+    const text = requireString(raw.text, `${field}.text`);
+    let options = [];
+    if (raw.options !== undefined) {
+        if (!Array.isArray(raw.options) || !raw.options.every((o) => typeof o === "string")) {
+            throw new PackSetupError(`${field}.options`, "must be a list of strings (it may be empty)");
+        }
+        options = raw.options;
+    }
+    const skippable = optionalBoolean(raw.skippable, `${field}.skippable`, false);
+    let defaultFrom;
+    if (raw.default_from !== undefined)
+        defaultFrom = requireString(raw.default_from, `${field}.default_from`);
+    let goal;
+    if (raw.goal !== undefined)
+        goal = requireString(raw.goal, `${field}.goal`);
+    return { id, text, options, skippable, ...(defaultFrom ? { default_from: defaultFrom } : {}), ...(goal ? { goal } : {}) };
+}
+/**
+ * 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 function parseSetupBlock(raw, ctx) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isMapping(raw))
+        throw new PackSetupError("setup", "must be a mapping (bot, questions, run, done)");
+    // bot
+    if (!isMapping(raw.bot))
+        throw new PackSetupError("setup.bot", "must be a mapping with name, display_name, intro");
+    const botName = requireString(raw.bot.name, "setup.bot.name");
+    if (!SETUP_BOT_NAME_RE.test(botName)) {
+        throw new PackSetupError("setup.bot.name", `"${botName}" must match ${SETUP_BOT_NAME_RE.source}`);
+    }
+    if (!ctx.workers.includes(botName)) {
+        throw new PackSetupError("setup.bot.name", `"${botName}" is not listed under contributes.workers` +
+            (ctx.workers.length ? ` (declared: ${ctx.workers.join(", ")})` : " (none declared)"));
+    }
+    const displayName = requireString(raw.bot.display_name, "setup.bot.display_name");
+    const intro = requireString(raw.bot.intro, "setup.bot.intro");
+    const takeoverSetup = optionalBoolean(raw.takeover_setup, "setup.takeover_setup", false);
+    // questions
+    if (!Array.isArray(raw.questions) || raw.questions.length === 0) {
+        throw new PackSetupError("setup.questions", "must be a non-empty list");
+    }
+    const questions = raw.questions.map(parseQuestion);
+    const ids = new Set();
+    questions.forEach((q, i) => {
+        if (ids.has(q.id))
+            throw new PackSetupError(`setup.questions[${i}].id`, `"${q.id}" is used more than once`);
+        ids.add(q.id);
+    });
+    // run
+    if (!isMapping(raw.run))
+        throw new PackSetupError("setup.run", "must be a mapping with script (and optional args, then)");
+    const script = requireString(raw.run.script, "setup.run.script");
+    requirePackFile(ctx, script, "setup.run.script");
+    const args = {};
+    if (raw.run.args !== undefined) {
+        if (!isMapping(raw.run.args))
+            throw new PackSetupError("setup.run.args", "must be a mapping of question id to flag");
+        for (const [key, flag] of Object.entries(raw.run.args)) {
+            if (!ids.has(key)) {
+                throw new PackSetupError(`setup.run.args.${key}`, `is not a question id (questions: ${[...ids].join(", ")})`);
+            }
+            args[key] = requireString(flag, `setup.run.args.${key}`);
+        }
+    }
+    const then = [];
+    if (raw.run.then !== undefined) {
+        if (!Array.isArray(raw.run.then))
+            throw new PackSetupError("setup.run.then", "must be a list of commands");
+        raw.run.then.forEach((entry, i) => {
+            const field = `setup.run.then[${i}]`;
+            const command = requireString(entry, field);
+            const first = command.trim().split(/\s+/)[0];
+            requirePackFile(ctx, first, field);
+            then.push(command.trim());
+        });
+    }
+    // done
+    if (!isMapping(raw.done))
+        throw new PackSetupError("setup.done", "must be a mapping with message (and optional suggestion)");
+    const message = requireString(raw.done.message, "setup.done.message");
+    let suggestion;
+    if (raw.done.suggestion !== undefined)
+        suggestion = requireString(raw.done.suggestion, "setup.done.suggestion");
+    // documents
+    let documents;
+    if (raw.documents !== undefined) {
+        if (!Array.isArray(raw.documents) || raw.documents.length === 0 || !raw.documents.every((d) => typeof d === "string" && d.trim())) {
+            throw new PackSetupError("setup.documents", "must be a non-empty list of document descriptions");
+        }
+        documents = raw.documents.map((d) => d.trim());
+    }
+    // sources
+    let sources;
+    if (raw.sources !== undefined) {
+        if (!Array.isArray(raw.sources) || raw.sources.length === 0) {
+            throw new PackSetupError("setup.sources", "must be a non-empty list of { kind, read, informs, options }");
+        }
+        sources = raw.sources.map((entry, i) => {
+            const field = `setup.sources[${i}]`;
+            if (!isMapping(entry))
+                throw new PackSetupError(field, "must be a mapping with kind, read, informs and options");
+            const kind = requireString(entry.kind, `${field}.kind`);
+            const read = requireString(entry.read, `${field}.read`);
+            if (!Array.isArray(entry.informs) || entry.informs.length === 0 || !entry.informs.every((x) => typeof x === "string")) {
+                throw new PackSetupError(`${field}.informs`, "must be a non-empty list of question ids");
+            }
+            for (const id of entry.informs) {
+                if (!ids.has(id))
+                    throw new PackSetupError(`${field}.informs`, `"${id}" is not a question id (questions: ${[...ids].join(", ")})`);
+            }
+            if (!Array.isArray(entry.options) || entry.options.length === 0) {
+                throw new PackSetupError(`${field}.options`, "must be a non-empty list of { name, domain }");
+            }
+            const options = entry.options.map((o, j) => {
+                const of = `${field}.options[${j}]`;
+                if (!isMapping(o))
+                    throw new PackSetupError(of, "must be a mapping with name and a domain or a tool");
+                const name = requireString(o.name, `${of}.name`);
+                const available = optionalBoolean(o.available, `${of}.available`, true);
+                const opt = { name, ...(available ? {} : { available: false }) };
+                for (const key of ["domain", "tool", "connect", "status", "usage", "note"]) {
+                    if (o[key] !== undefined)
+                        opt[key] = requireString(o[key], `${of}.${key}`);
+                }
+                if (opt.tool)
+                    requirePackFile(ctx, opt.tool, `${of}.tool`);
+                if (available && !opt.domain && !opt.tool)
+                    throw new PackSetupError(of, "needs a domain (HQ integrations) or a tool (pack script), or available: false");
+                return opt;
+            });
+            return { kind, read, informs: [...entry.informs], options };
+        });
+    }
+    return {
+        bot: { name: botName, display_name: displayName, intro },
+        takeover_setup: takeoverSetup,
+        questions,
+        run: { script, args, then },
+        done: { message, ...(suggestion ? { suggestion } : {}) },
+        ...(documents ? { documents } : {}),
+        ...(sources ? { sources } : {}),
+    };
+}
+/**
+ * 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 function readInstalledPackSetup(manifest, packDir, existsSync) {
+    if (!manifest || manifest.setup === undefined)
+        return undefined;
+    try {
+        return parseSetupBlock(manifest.setup, {
+            packDir,
+            workers: manifest.contributes?.workers ?? [],
+            ...(existsSync ? { existsSync } : {}),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=setup-block.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * The auto-generated "Pack setup" section of a pack bot's system prompt
+ * (build contract section 3). Rendered from the pack's validated `setup:`
+ * block: the questions in order with their options, the one-at-a-time rule
+ * with the `hq-block` suggestions envelope (contract section 2), the exact
+ * command to run with the collected answers, and the done message.
+ */
+import type { PackSetup, PackSetupQuestion } from "../../types.js";
+export declare const SKIP_SUGGESTION = "Skip";
+export declare const HQ_BLOCK_FENCE = "hq-block";
+export interface PackSetupPromptInput {
+    /** Manifest name, e.g. hq-pack-sample. */
+    packName: string;
+    /** Absolute installed pack root (core/packages/<pack>). */
+    packRoot: string;
+    setup: PackSetup;
+}
+/** The fenced JSON envelope the app draws as buttons (contract section 2). */
+export declare function suggestionsEnvelope(items: readonly string[]): string;
+/** The buttons for one question: its options, plus Skip when it is skippable. */
+export declare function questionSuggestions(q: PackSetupQuestion): string[];
+/** `bash <packRoot>/<script> --firm <company slug> --flag '<answer>' ...` */
+export declare function renderRunCommand(input: PackSetupPromptInput): string;
+/** The `then` commands, each run from the pack root with the same --firm. */
+export declare function renderThenCommands(input: PackSetupPromptInput): string[];
+/**
+ * "Their tools": what the bot needs to know to learn from the person's tools
+ * before asking. Facts (how each tool connects and is read) and principles;
+ * the bot decides how to run the conversation.
+ */
+export declare function renderLearnFirst(setup: PackSetup, packRoot: string): string;
+/** The whole "## Pack setup" section: a brief, not a script. */
+export declare function renderPackSetupSection(input: PackSetupPromptInput): string;
+//# sourceMappingURL=setup-prompt.d.ts.map