@indigoai-us/hq-cli 5.345.179 → 5.345.180

package/dist/commands/bot.js

@@ -56,6 +56,7 @@ import { isAncestorProcess } from "../lib/bot/self-process.js";
 import { runtimeDisplayName, signInCommand } from "../lib/bot/runtime-sign-in.js";
 import { classifyRuntimeFailure, runtimeFailureReason } from "../lib/bot/runtime-failure.js";
 import { PROBE_DEFAULT_TIMEOUT_MS, probeBotRuntime } from "../lib/bot/probe.js";
+import { BOT_LOGIN_RUNTIMES, botAuthEnv, botRuntimeAuth, capacityAccountHome, describeBotAuth, formatBotAuth, isBotLoginRuntime, restoreBotSessions, setAsideBotSessions, signInBotRuntime, signOutBotRuntime, withRuntimeAuth, } from "../lib/bot/runtime-auth.js";
 import { BotApi, BotApiError, BOT_RESTORE_DEFAULTS, buildBotLocalConfig, describeBotLocalConfig, orphanBotRunMessage, parseBotLocalConfig, removeOrphanBotDaemon, botDaemonStatus, botDir, botCredsPath, botLogPath, botsRoot, botTokenStateDir, botWorkerRelDir, buildBotDaemonPaths, createBotLogger, deleteBotCreds, installBotDaemon, repairBotDaemonIfStale, healBotDaemonNodeFromJob, introDmText, isBotMemoryMode, botLocalMemoryDir, botMemoryMode, resolveBotMemoryDir, validateBotIntro, validateBotDisplayName, validateBotKickoff, validateBotEffort, validateBotModel, effectiveBotEffort, BOT_EFFORT_LEVELS, DEFAULT_BOT_EFFORT, BOT_MEMORY_MODES, BOT_KINDS, isBotKind, effectiveBotKind, effectiveBotCompanies, normalizeBotCompanies, SETUP_BOT_WORKER_ID, isBotRuntimeId, localNameForRemoteBot, remoteBotRunnability, isPidAlive, listBotWorkerOptions, patchBotConfig, readBotConfig, readBotCredsIdentity, readBotStatus, runtimeCrashSinceStart, resolveBotWorker, runBot, runtimeFor, scaffoldBotMemory, scaffoldBotWorker, startBotDaemon, stopBotDaemon, uninstallBotDaemon, validateBotName, writeBotConfig, writeBotCreds, BOT_RUNTIMES, BOT_INTRO_MAX_CHARS, BOT_DISPLAY_NAME_MAX_CHARS, BOT_KICKOFF_MAX_CHARS, detectBotPlatform, withBotLock, localBotRole, remoteBotRole, remoteBotDisplayName, personFacingName, writeCloudDisplayName, setupSlugFor, ASSISTANT_ROLE, HQ_FLEET_RUNTIME_ENGINE_ID, authenticateFleetLocalBot, bootstrapFleetLocalBot, buildSystemPrompt, controlFleetLocalBot, ensureFleetPython, fleetLocalGatewayPid, fleetProviderForRuntime, importFleetLocalMachineCredential, fleetProviderNeedsSignIn, fleetDefaultCompanies, fleetOwnerCompanies, fleetRuntimeIsDefault, refreshFleetLocalInstructions, fleetLocalPromotionRuntime, installPinnedFleetLocalDistribution, readPromptSources, removeFleetLocalBot, } from "../lib/bot/index.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
@@ -800,6 +801,11 @@ async function runBotCreateLocked(name, opts) {
     // cost an identity).
     const worker = opts.worker?.trim() ? resolveBotWorker(hqRoot, opts.worker) : null;
     const { kind, companies } = resolveCreateKind(opts, worker);
+    if (requestedFleetRuntime && kind === "company" && companies.length !== 1) {
+        throw Object.assign(new Error("An HQ Fleet company bot must belong to exactly one company."), {
+            expected: true,
+        });
+    }
     // Companies with the fleet-default flag get their personal bots on
     // the HQ Fleet Runtime; --legacy-runtime keeps the model-CLI runner.
     const fleetCandidate = requestedFleetRuntime ||
@@ -808,12 +814,11 @@ async function runBotCreateLocked(name, opts) {
     // and only where the company turned the flag on.
     const flaggedCompanies = fleetCandidate && kind === "personal" ? await fleetDefaultCompanies(hqRoot) : [];
     const useFleetRuntime = requestedFleetRuntime || (fleetCandidate && fleetRuntimeIsDefault(flaggedCompanies));
-    const ownerCompanies = useFleetRuntime && kind === "personal" ? await fleetOwnerCompanies() : [];
-    if (useFleetRuntime && kind !== "personal") {
-        throw Object.assign(new Error("--hq-fleet-runtime creates a personal bot. Drop --kind company and --company."), {
-            expected: true,
-        });
-    }
+    const ownerCompanies = useFleetRuntime
+        ? kind === "personal"
+            ? await fleetOwnerCompanies()
+            : companies
+        : [];
     const isSetupBot = name === RESERVED_SETUP_BOT_NAME && kind === "personal" && worker?.id === SETUP_BOT_WORKER_ID;
     if (name === RESERVED_SETUP_BOT_NAME && kind === "personal" && !isSetupBot) {
         throw Object.assign(new Error(`The name ${RESERVED_SETUP_BOT_NAME} is reserved for HQ's assistant; create it with --worker ${RESERVED_SETUP_BOT_NAME}.`), { expected: true });
@@ -1387,14 +1392,16 @@ async function runBotStatus(nameArg, opts) {
     const status = readBotStatus(dir);
     const creds = readBotCredsIdentity(dir);
     if (opts.json) {
-        console.log(JSON.stringify({ ...row, ...(fleet ? { engine: config.engine } : {}), credsPresent: fleet || !!creds, status }, null, 2));
+        console.log(JSON.stringify({ ...row, ...(fleet ? { engine: config.engine } : {}), credsPresent: fleet || !!creds, login: describeBotAuth(dir, config), status }, null, 2));
         return;
     }
     console.log(`${chalk.bold(name)}  ${row.agentUid}`);
     if (fleet)
         console.log(`  engine:     HQ Fleet Runtime ${config.engine?.version ?? ""}  ${chalk.dim(`logs ~/.hq-fleet/profiles/${config.agentUid}/logs`)}`);
     console.log(`  kind:       ${describeKind(row.kind, row.companies)}`);
+    const login = describeBotAuth(dir, config);
     console.log(`  runtime:    ${row.runtime}  model ${row.model ?? "default"}  thinking ${row.effort}${row.effortIsDefault ? " (default)" : ""}`);
+    console.log(`  login:      ${login.login === "own" && !login.present ? chalk.red(formatBotAuth(login, name)) : formatBotAuth(login, name)}`);
     if (row.workerId)
         console.log(`  worker:     ${row.workerId}${row.companySlug ? ` (company ${row.companySlug})` : ""}  ${chalk.dim(row.workerDir)}`);
     console.log(`  memory:     ${row.memory}  ${chalk.dim(row.memoryDir)}`);
@@ -1421,7 +1428,13 @@ async function runBotStatus(nameArg, opts) {
         if (status.runtimeSignIn) {
             const tool = runtimeDisplayName(status.runtimeSignIn.runtime);
             const what = status.runtimeSignIn.state === "signed-out" ? `${tool} is not signed in for ${name}` : `${tool} needs to sign in again`;
-            console.log(`  ${chalk.yellow(what)} — sign in from HQ, or run \`${signInCommand(status.runtimeSignIn.runtime)}\`; ${name} checks again on its own`);
+            const which = login.login === "default" ? "" : ` (${formatBotAuth(login, name)})`;
+            const fix = login.login === "own"
+                ? `run \`hq bot login ${name} --runtime ${status.runtimeSignIn.runtime}\`, then \`hq bot restart ${name}\``
+                : login.login === "account"
+                    ? `run \`hq capacity login ${status.runtimeSignIn.runtime} --account ${login.account}\`, then \`hq bot restart ${name}\``
+                    : `sign in from HQ, or run \`${signInCommand(status.runtimeSignIn.runtime)}\`; ${name} checks again on its own`;
+            console.log(`  ${chalk.yellow(`${what}${which}`)} — ${fix}`);
         }
         else if (status.runtimeSignInCheck) {
             const c = status.runtimeSignInCheck;
@@ -1701,9 +1714,9 @@ async function runBotRmLocked(validated, opts) {
         console.log(chalk.dim(`  HQ did not finish: ${incomplete.steps.join(", ")}`));
     throw Object.assign(new Error(message), { expected: true });
 }
-export async function runBotSet(nameArg, opts) {
+export async function runBotSet(nameArg, opts, deps = {}) {
     const name = validateBotName(nameArg);
-    await withBotLock(name, () => runBotSetLocked(name, opts), { command: "hq bot set" });
+    await withBotLock(name, () => runBotSetLocked(name, opts, deps), { command: "hq bot set" });
 }
 /** A sentence for a refused name write: the status only, never the server's text. */
 function nameWriteRefused(name, err) {
@@ -1730,12 +1743,48 @@ function nameWriteRefused(name, err) {
         expected: true,
     });
 }
-async function runBotSetLocked(nameArg, opts) {
+const defaultSetLifecycle = {
+    isRunning: (dir) => {
+        const s = readBotStatus(dir);
+        return !!s && isPidAlive(s.pid) && s.state === "running";
+    },
+    stop: async (name, dir, config) => {
+        await stopBot(name, dir, config, "silent");
+        return waitFor(() => {
+            const s = readBotStatus(dir);
+            return !s || !isPidAlive(s.pid);
+        }, 15_000);
+    },
+    start: async (name, dir, config) => (await startBot(name, dir, config, "silent")).running,
+};
+async function runBotSetLocked(nameArg, opts, deps = {}) {
     const { name, dir, config } = requireBot(nameArg);
     if (hasPromotionHold(dir))
         throw new Error("This bot is held for cloud promotion. Continue its promotion before changing local settings or lifecycle.");
-    if (opts.model === undefined && opts.effort === undefined && opts.displayName === undefined) {
-        throw Object.assign(new Error("Nothing to change: pass --model <id|default>, --effort <level|default> and/or --display-name <name>."), { expected: true });
+    if (opts.runtime === undefined && opts.account === undefined && opts.model === undefined && opts.effort === undefined && opts.displayName === undefined) {
+        throw Object.assign(new Error("Nothing to change: pass --runtime <runtime>, --account <id|default>, --model <id|default>, --effort <level|default> and/or --display-name <name>."), { expected: true });
+    }
+    if (opts.runtime !== undefined && !isBotRuntimeId(opts.runtime)) {
+        throw Object.assign(new Error(`--runtime must be one of ${BOT_RUNTIMES.join(", ")}`), { expected: true });
+    }
+    const targetRuntime = opts.runtime ?? config.runtime;
+    const switching = targetRuntime !== config.runtime;
+    if ((switching || opts.account !== undefined) && opts.displayName !== undefined) {
+        throw Object.assign(new Error("Change --display-name on its own, not together with --runtime or --account."), { expected: true });
+    }
+    let runtimeAuth = config.runtimeAuth;
+    if (opts.account !== undefined) {
+        const id = opts.account.trim();
+        let auth = null;
+        if (id && id.toLowerCase() !== "default") {
+            // Checked now so a typo never reaches a turn.
+            capacityAccountHome(config.hqRoot, targetRuntime, id);
+            auth = { mode: "account", account: id };
+        }
+        runtimeAuth = withRuntimeAuth(runtimeAuth, targetRuntime, auth);
+    }
+    if (switching || opts.account !== undefined) {
+        return switchRuntimeOrAccount({ name, dir, config, targetRuntime, switching, runtimeAuth, opts, deps });
     }
     // Only the keys this command changes are written, onto a fresh read of
     // bot.json: the running bot writes it too (introSentAt, kickoff state), and
@@ -1812,6 +1861,174 @@ async function runBotSetLocked(nameArg, opts) {
         console.log(chalk.green(`${name} is now called ${displayName}`) + chalk.dim(`${where}${how}`));
     }
 }
+/**
+ * `hq bot set --runtime/--account`: probe the new setup first (nothing changes
+ * when it cannot answer), stop a running bot, back up bot.json and set the
+ * old runtime's session files aside, save, and start it again. A bot that does
+ * not come back is rolled back to its old settings and sessions.
+ */
+async function switchRuntimeOrAccount(input) {
+    const { name, dir, config, targetRuntime, switching, runtimeAuth, opts, deps } = input;
+    const life = deps.lifecycle ?? defaultSetLifecycle;
+    const patch = { runtime: targetRuntime, runtimeAuth };
+    // Model ids and thinking levels belong to one runtime: a switch resets what does not carry over.
+    patch.model = opts.model !== undefined ? validateBotModel(opts.model) || undefined : switching ? undefined : config.model;
+    patch.effort =
+        opts.effort !== undefined
+            ? validateBotEffort(targetRuntime, opts.effort) || undefined
+            : config.effort && BOT_EFFORT_LEVELS[targetRuntime].includes(config.effort)
+                ? config.effort
+                : undefined;
+    const candidate = { ...config, ...patch };
+    const probeEnv = botAuthEnv(dir, candidate, process.env);
+    const probe = await (deps.probe ?? probeBotRuntime)({
+        runtime: targetRuntime,
+        ...(candidate.model ? { model: candidate.model } : {}),
+        ...(candidate.effort ? { effort: candidate.effort } : {}),
+        env: probeEnv,
+    });
+    if (!probe.ok) {
+        throw Object.assign(new Error(`${name} stays on ${config.runtime}: ${probe.detail} Nothing was changed.`), { expected: true });
+    }
+    const status = readBotStatus(dir);
+    if (status && isPidAlive(status.pid) && selfStopProbe(status.pid)) {
+        throw Object.assign(new Error(`${name} cannot change its runtime or login from inside one of its own turns. Run this from outside the bot. Nothing was changed.`), { expected: true });
+    }
+    const wasRunning = life.isRunning(dir);
+    if (wasRunning && !(await life.stop(name, dir, config))) {
+        throw Object.assign(new Error(`${name} did not stop, so nothing was changed. Try again, or run hq bot stop ${name} first.`), { expected: true });
+    }
+    let aside = null;
+    // Only the settings this command changed go back, onto a fresh bot.json.
+    const rollBack = () => {
+        if (aside)
+            restoreBotSessions(dir, aside);
+        return patchBotConfig(dir, { runtime: config.runtime, runtimeAuth: config.runtimeAuth, model: config.model, effort: config.effort });
+    };
+    let next;
+    let running = false;
+    let rolledBack = false;
+    try {
+        if (switching)
+            aside = setAsideBotSessions(dir, config.runtime);
+        next = patchBotConfig(dir, patch);
+        if (wasRunning)
+            running = await life.start(name, dir, next);
+    }
+    catch (err) {
+        // Any failure part-way puts the old settings and sessions back, and the bot back up.
+        try {
+            await life.stop(name, dir, config);
+        }
+        catch { /* best effort */ }
+        const old = rollBack();
+        if (wasRunning)
+            await life.start(name, dir, old);
+        throw err;
+    }
+    const login = describeBotAuth(dir, next);
+    createBotLogger(dir)("info", `settings: runtime=${next.runtime} login=${login.login}${login.account ? ` account=${login.account}` : ""} model=${next.model ?? "default"} effort=${effectiveBotEffort(next)}${aside ? ` (sessions set aside in ${aside.archiveDir})` : ""}`);
+    if (wasRunning && !running) {
+        await life.stop(name, dir, next);
+        const old = rollBack();
+        rolledBack = true;
+        running = await life.start(name, dir, old);
+        createBotLogger(dir)("warn", `settings rolled back: ${name} did not start on ${next.runtime}`);
+    }
+    const result = {
+        ok: !rolledBack,
+        name,
+        runtime: rolledBack ? config.runtime : next.runtime,
+        previousRuntime: config.runtime,
+        login: rolledBack ? describeBotAuth(dir, config) : login,
+        model: rolledBack ? config.model ?? null : next.model ?? null,
+        effort: effectiveBotEffort(rolledBack ? config : next),
+        sessionsSetAside: aside && !rolledBack ? { dir: aside.archiveDir, files: aside.moved.length } : null,
+        backup: aside ? path.join(aside.archiveDir, "bot.json") : null,
+        running,
+        restarted: wasRunning,
+        rolledBack,
+    };
+    if (rolledBack)
+        process.exitCode = 1;
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (rolledBack) {
+        console.log(chalk.red(`${name} did not start on ${next.runtime}, so it is back on ${config.runtime} with its old sessions. Check: hq bot logs ${name}`));
+        return;
+    }
+    if (switching) {
+        console.log(chalk.green(`${name} now runs on ${next.runtime} (${formatBotAuth(login, name)}), model ${next.model ?? "default"}, thinking ${result.effort}.`));
+        console.log(chalk.dim(`  ${aside.moved.length} ${config.runtime} session file(s) set aside in ${aside.archiveDir}; DM history and memory are unchanged.`));
+    }
+    else {
+        console.log(chalk.green(`${name} now uses ${formatBotAuth(login, name)} for ${next.runtime}.`));
+    }
+    if (wasRunning)
+        console.log(chalk.dim(running ? "  restarted" : `  did not report running; check: hq bot logs ${name}`));
+}
+/** `hq bot login <name>`: sign the bot in with a login of its own. */
+export async function runBotLogin(nameArg, opts, deps = {}) {
+    const name = validateBotName(nameArg);
+    await withBotLock(name, async () => {
+        const { dir, config } = requireBot(name);
+        const runtime = opts.runtime ?? config.runtime;
+        if (!isBotLoginRuntime(runtime)) {
+            throw Object.assign(new Error(`hq bot login supports ${BOT_LOGIN_RUNTIMES.join(", ")}${opts.runtime ? "" : `; ${name} runs on ${runtime}, pass --runtime`}.`), { expected: true });
+        }
+        if (!(deps.interactive ?? process.stdin.isTTY === true)) {
+            throw Object.assign(new Error("hq bot login needs an interactive terminal: the sign-in opens in your browser."), { expected: true });
+        }
+        signInBotRuntime(dir, runtime, deps.spawn ? { spawn: deps.spawn } : {});
+        const next = patchBotConfig(dir, { runtimeAuth: withRuntimeAuth(config.runtimeAuth, runtime, { mode: "own" }) });
+        createBotLogger(dir)("info", `login: own ${runtime} login set`);
+        const login = describeBotAuth(dir, { ...next, runtime });
+        if (opts.json)
+            console.log(JSON.stringify({ ok: true, name, runtime, login }, null, 2));
+        else
+            console.log(chalk.green(`${name} now uses its own ${runtime} login${runtime === config.runtime ? " from its next message" : ` when it runs on ${runtime}`}.`));
+    }, { command: "hq bot login" });
+}
+/** `hq bot logout <name>`: sign the bot's own login out and delete it. */
+export async function runBotLogout(nameArg, opts, deps = {}) {
+    const name = validateBotName(nameArg);
+    await withBotLock(name, async () => {
+        const { dir, config } = requireBot(name);
+        if (opts.runtime !== undefined && !isBotLoginRuntime(opts.runtime)) {
+            throw Object.assign(new Error(`--runtime must be one of ${BOT_LOGIN_RUNTIMES.join(", ")}`), { expected: true });
+        }
+        const runtimes = opts.runtime ? [opts.runtime] : [...BOT_LOGIN_RUNTIMES];
+        let runtimeAuth = config.runtimeAuth;
+        const results = [];
+        for (const rt of runtimes) {
+            const r = signOutBotRuntime(dir, rt, deps.spawn ? { spawn: deps.spawn } : {});
+            results.push({ runtime: rt, ...r });
+            // A failed vendor logout keeps the folder and the setting, so the bot never drops to your login.
+            if (r.removed && botRuntimeAuth({ runtime: rt, runtimeAuth }, rt)?.mode === "own")
+                runtimeAuth = withRuntimeAuth(runtimeAuth, rt, null);
+        }
+        patchBotConfig(dir, { runtimeAuth });
+        createBotLogger(dir)("info", `logout: ${results.map((r) => `${r.runtime}=${r.removed ? "removed" : "none"}`).join(" ")}`);
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, name, results }, null, 2));
+            return;
+        }
+        const failed = results.filter((r) => r.vendorLogout === "failed");
+        for (const r of results) {
+            if (r.removed)
+                console.log(chalk.green(`${name}'s own ${r.runtime} login is signed out and removed.`));
+            else if (r.vendorLogout === "failed")
+                console.log(chalk.yellow(`${r.runtime} logout did not finish, so ${name}'s own ${r.runtime} login was kept. Make sure ${r.runtime} is installed, then run hq bot logout ${name} --runtime ${r.runtime} again.`));
+        }
+        if (failed.length)
+            process.exitCode = 1;
+        if (!results.some((r) => r.removed || r.vendorLogout === "failed"))
+            console.log(`${name} has no login of its own${opts.runtime ? ` for ${opts.runtime}` : ""}.`);
+        console.log(chalk.dim(`  ${name} now uses your default sign-in for ${runtimes.join(" and ")} unless an account is set (hq bot set ${name} --account <id>).`));
+    }, { command: "hq bot logout" });
+}
 /** `hq bot probe`: exit code 0 when the runtime answered, 1 when it did not. */
 export async function runBotProbe(opts, deps = {}) {
     const saved = opts.bot ? requireBot(opts.bot).config : undefined;
@@ -1829,6 +2046,7 @@ export async function runBotProbe(opts, deps = {}) {
         ...(model ? { model } : {}),
         ...(effort ? { effort } : {}),
         timeoutMs,
+        ...(opts.bot && saved ? { env: botAuthEnv(botDir(validateBotName(opts.bot)), { ...saved, runtime }, process.env) } : {}),
     });
     if (!result.ok)
         process.exitCode = 1;
@@ -2622,11 +2840,25 @@ export function registerBotCommand(program) {
     bot
         .command("set <name>")
         .description("Change the model and thinking level a bot uses (applies from its next message), or the name people see for it (saved in HQ; a running bot restarts to use it)")
+        .option("--runtime <runtime>", `Switch the model CLI: ${BOT_RUNTIMES.join("|")}. Checked with one test turn first; the old runtime's sessions are set aside (backed up), DM history and memory stay`)
+        .option("--account <id>", "Use this hq capacity account's login for the bot's runtime, or default for your own sign-in")
         .option("--model <model>", "Model id for the runtime CLI, or default for the CLI's own default")
         .option("--display-name <name>", `The name people see for the bot in HQ (up to ${BOT_DISPLAY_NAME_MAX_CHARS} chars). The handle stays <name>`)
         .option("--effort <level>", `Thinking level (claude ${BOT_EFFORT_LEVELS.claude.join("|")}; codex ${BOT_EFFORT_LEVELS.codex.join("|")}; grok ${BOT_EFFORT_LEVELS.grok.join("|")}), or default (${DEFAULT_BOT_EFFORT})`)
         .option("--json", "Print machine-readable JSON")
         .action((name, opts) => wrap(() => runBotSet(name, opts))());
+    bot
+        .command("login <name>")
+        .description("Give the bot a model login of its own, so it does not use yours: runs the runtime's own sign-in into ~/.hq/bots/<name>/auth/<runtime>")
+        .option("--runtime <runtime>", `${BOT_LOGIN_RUNTIMES.join("|")} (default: the bot's runtime)`)
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(() => runBotLogin(name, opts))());
+    bot
+        .command("logout <name>")
+        .description("Sign the bot's own model login out and delete it; the bot goes back to your default sign-in")
+        .option("--runtime <runtime>", `${BOT_LOGIN_RUNTIMES.join("|")} (default: both)`)
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(() => runBotLogout(name, opts))());
     bot
         .command("set-model <name> <model>")
         .description("Set the model this bot asks its runtime for (stored in the bot's own settings; the runtime's own config is never changed), or default to clear it")

package/dist/commands/channels.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { type ChannelSummary } from "./dm.js";
+import { type ChannelSummary, type DmContact } from "./dm.js";
 /**
  * Human label for a channel row. Named channels (personal/company) show their
  * name + a `hq dm <slug>` hint; unnamed group DMs are identified by their
@@ -38,6 +38,23 @@ export declare function parseActiveSince(value: string, now?: number): number |
  * original order). Pure → unit-testable.
  */
 export declare function channelsByActivity<T extends ChannelWithActivity>(channels: T[], sinceMs?: number): T[];
+/**
+ * Resolve the `<member>` argument of `hq channels add|remove` to a person or
+ * agent uid. Accepts a uid (`prs_…`, `agt_…`), an email, or a display name /
+ * @handle matched against the caller's DM contacts (which include the bots the
+ * caller owns). Pure → unit-testable. Returns an error sentence on no or
+ * ambiguous match so the caller never guesses. Feedback e165b286.
+ */
+export declare function resolveMemberTarget(contacts: DmContact[], raw: string): {
+    ok: true;
+    personUid: string;
+    displayName: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** The server's refusal, as one plain sentence. */
+export declare function channelMembershipError(res: Response, verb: "add" | "remove", fallback: string): Promise<string>;
 export declare function registerChannelsCommand(program: Command): void;
 export {};
 //# sourceMappingURL=channels.d.ts.map

package/dist/commands/channels.js

@@ -2,7 +2,7 @@ import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { suggestChannels, withChannelSuggestions } from "./channel-suggest.js";
-import { callerFromToken, channelSlug, fetchChannelMembers, fetchChannels, matchChannelsByName, } from "./dm.js";
+import { callerFromToken, channelSlug, fetchChannelMembers, fetchChannels, matchChannelsByName, matchContactByName, } from "./dm.js";
 /**
  * Human label for a channel row. Named channels (personal/company) show their
  * name + a `hq dm <slug>` hint; unnamed group DMs are identified by their
@@ -294,6 +294,176 @@ async function runChannelsDelete(channelName, opts) {
         process.exit(1);
     }
 }
+// ─── Channel membership: add / remove ────────────────────────────────────────
+/**
+ * Resolve the `<member>` argument of `hq channels add|remove` to a person or
+ * agent uid. Accepts a uid (`prs_…`, `agt_…`), an email, or a display name /
+ * @handle matched against the caller's DM contacts (which include the bots the
+ * caller owns). Pure → unit-testable. Returns an error sentence on no or
+ * ambiguous match so the caller never guesses. Feedback e165b286.
+ */
+export function resolveMemberTarget(contacts, raw) {
+    const target = raw.trim().replace(/^@/, "");
+    if (!target)
+        return { ok: false, error: "Name a member: a @handle, an email, or a prs_/agt_ uid." };
+    if (/^(prs|agt)_[A-Za-z0-9_-]+$/.test(target)) {
+        const known = contacts.find((c) => c.personUid === target);
+        return { ok: true, personUid: target, displayName: known?.displayName?.trim() || target };
+    }
+    if (target.includes("@")) {
+        const email = target.toLowerCase();
+        const hits = contacts.filter((c) => c.personUid && c.email?.trim().toLowerCase() === email);
+        const unique = [...new Map(hits.map((c) => [c.personUid, c])).values()];
+        if (unique.length === 1) {
+            return { ok: true, personUid: unique[0].personUid, displayName: unique[0].displayName?.trim() || email };
+        }
+        return {
+            ok: false,
+            error: unique.length === 0
+                ? `No contact with the email '${target}'. They must share a company with you; pass their prs_/agt_ uid to add them anyway.`
+                : `'${target}' matches ${unique.length} contacts. Pass the prs_/agt_ uid instead.`,
+        };
+    }
+    const match = matchContactByName(contacts, target);
+    if (match?.personUid) {
+        return { ok: true, personUid: match.personUid, displayName: match.displayName?.trim() || target };
+    }
+    const names = contacts
+        .map((c) => c.displayName?.trim())
+        .filter((n) => Boolean(n))
+        .sort((a, b) => a.localeCompare(b));
+    return {
+        ok: false,
+        error: `No contact matches '${raw.trim()}'. Contacts: ${names.slice(0, 12).join(", ") || "(none)"}` +
+            `${names.length > 12 ? ", …" : ""}. Use the exact name, an email, or a prs_/agt_ uid.`,
+    };
+}
+async function fetchDmContacts(token) {
+    const res = await vaultApiFetch({ token, path: "/v1/notify/contacts" });
+    if (!res.ok)
+        return [];
+    const data = (await res.json().catch(() => ({})));
+    return Array.isArray(data.contacts) ? data.contacts : [];
+}
+async function resolveOneChannel(token, channelName) {
+    const channels = await fetchChannels(token);
+    const matches = matchChannelsByName(channels, channelName);
+    if (matches.length === 0) {
+        const message = `No channel named '${channelName}'. Run \`hq channels\` to see your channels.`;
+        throw new Error(withChannelSuggestions(message, suggestChannels(channels, channelName)));
+    }
+    if (matches.length > 1) {
+        const scopes = matches.map((match) => match.scope ?? "?").join(", ");
+        throw new Error(`'${channelName}' matches ${matches.length} channels (${scopes}). Name one of them.`);
+    }
+    return matches[0];
+}
+/** The server's refusal, as one plain sentence. */
+export async function channelMembershipError(res, verb, fallback) {
+    const err = (await res.json().catch(() => ({})));
+    switch (err.code) {
+        case "CHANNEL_NOT_MEMBER":
+            return "Join the channel before adding members (so far you only browse it). Post once with `hq dm <channel> \"…\"`, or add yourself first with your own uid.";
+        case "INVITEE_NOT_FOUND":
+            return "That person or bot is not reachable from this company.";
+        case "CHANNEL_NOT_OWNER":
+            return verb === "add"
+                ? "Only the channel owner or a company admin can add members."
+                : "Only the channel owner or a company admin can remove other members, and the channel owner cannot be removed.";
+        default: {
+            const detail = err.error ?? err.message;
+            return detail ? `${fallback} (HTTP ${res.status}): ${detail}` : `${fallback} (HTTP ${res.status})`;
+        }
+    }
+}
+/**
+ * `hq channels add <channel> <member…>`: POST /v1/notify/channels/{id}/members
+ * once per member. Agents (`agt_…`) are allowed; this is how an owner adds a
+ * personal bot to a channel so everyone there can @mention it. The server
+ * reports `alreadyMember` on a repeat, which is printed, not treated as an error.
+ */
+async function runChannelsAdd(channelName, members, opts) {
+    let failed;
+    try {
+        const token = await ensureCognitoToken();
+        const channel = await resolveOneChannel(token, channelName);
+        const contacts = await fetchDmContacts(token);
+        const results = [];
+        for (const raw of members) {
+            const target = resolveMemberTarget(contacts, raw);
+            if (!target.ok) {
+                results.push({ member: raw, ok: false, error: target.error });
+                continue;
+            }
+            const res = await vaultApiFetch({
+                token,
+                path: `/v1/notify/channels/${encodeURIComponent(channel.channelId)}/members`,
+                method: "POST",
+                body: { toPersonUid: target.personUid },
+            });
+            if (!res.ok) {
+                results.push({ member: raw, personUid: target.personUid, ok: false, error: await channelMembershipError(res, "add", "Could not add the member") });
+                continue;
+            }
+            const data = (await res.json().catch(() => ({})));
+            results.push({ member: target.displayName, personUid: target.personUid, ok: true, alreadyMember: data.alreadyMember === true });
+        }
+        const label = channel.name ?? channelName;
+        if (opts.json) {
+            console.log(JSON.stringify({ channelId: channel.channelId, name: label, results }, null, 2));
+        }
+        else {
+            for (const r of results) {
+                if (r.ok) {
+                    console.log(r.alreadyMember ? chalk.dim(`${r.member} is already in #${label}.`) : chalk.green(`Added ${r.member} to #${label}.`));
+                }
+                else {
+                    console.error(chalk.red(`${r.member}: ${r.error}`));
+                }
+            }
+        }
+        failed = results.some((r) => !r.ok);
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        failed = true;
+    }
+    if (failed)
+        process.exit(1);
+}
+/** `hq channels remove <channel> <member>`: DELETE /v1/notify/channels/{id}/members/{uid}. */
+async function runChannelsRemove(channelName, member, opts) {
+    try {
+        const token = await ensureCognitoToken();
+        const channel = await resolveOneChannel(token, channelName);
+        // The member is in the channel, so resolve against the roster first, then contacts.
+        const roster = await fetchChannelMembers(token, channel.channelId);
+        const rosterContacts = roster.map((m) => ({ personUid: m.personUid, email: m.email, displayName: m.displayName }));
+        let target = resolveMemberTarget(rosterContacts, member);
+        if (!target.ok)
+            target = resolveMemberTarget(await fetchDmContacts(token), member);
+        if (!target.ok)
+            throw new Error(target.error);
+        const res = await vaultApiFetch({
+            token,
+            path: `/v1/notify/channels/${encodeURIComponent(channel.channelId)}/members/${encodeURIComponent(target.personUid)}`,
+            method: "DELETE",
+        });
+        if (!res.ok)
+            throw new Error(await channelMembershipError(res, "remove", "Could not remove the member"));
+        const label = channel.name ?? channelName;
+        if (opts.json) {
+            console.log(JSON.stringify({ channelId: channel.channelId, personUid: target.personUid, removed: true }, null, 2));
+        }
+        else {
+            console.log(chalk.green(`Removed ${target.displayName} from #${label}.`));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
 export function registerChannelsCommand(program) {
     const channels = program
         .command("channels")
@@ -329,5 +499,19 @@ export function registerChannelsCommand(program) {
         .action(async (channelName, opts) => {
         await runChannelsDelete(channelName, opts);
     });
+    channels
+        .command("add <channel> <member...>")
+        .description("Add people or your own bots to a channel, by @handle, email, or prs_/agt_ uid.")
+        .option("--json", "Output the per-member results as JSON.")
+        .action(async (channelName, members, opts) => {
+        await runChannelsAdd(channelName, members, opts);
+    });
+    channels
+        .command("remove <channel> <member>")
+        .description("Remove a member or bot from a channel (owner or company admin), or leave it yourself.")
+        .option("--json", "Output the result as JSON.")
+        .action(async (channelName, member, opts) => {
+        await runChannelsRemove(channelName, member, opts);
+    });
 }
 //# sourceMappingURL=channels.js.map

package/dist/commands/lanes.d.ts

@@ -147,7 +147,7 @@ export declare function checkpointInstruction(worker: Pick<ResolvedLaneWorker, "
 export declare function composeWorkerBrief(worker: ResolvedLaneWorker, taskBrief: string, hqRoot: string): string;
 /**
  * A lane with no worker still carries the standing authorization paragraph,
- * the foreground-only rule and the temp-home rule.
+ * the foreground-only rule, the temp-home rule and the self-review rule.
  */
 export declare function composeGeneralBrief(taskBrief: string, hqRoot: string): string;
 export declare const DISPATCH_TERMINAL_REASON: "outpost_dispatch_failed";

package/dist/commands/lanes.js

@@ -108,7 +108,7 @@ import { resolveKrFreshnessForShow } from "../lib/lanes/kr-freshness.js";
 import { ensureSessionHome } from "../lib/lanes/session-relink.js";
 import { defaultProbe, validateProfileLaneModel, validateLaneModel, } from "../lib/lanes/models.js";
 import { readLaneClaudeCredential } from "../lib/lanes/claude-credential.js";
-import { parseCliModel, refuseOutpostSelfTarget, resolveLaneModel, FOREGROUND_ONLY_RULE, STANDING_AUTHORIZATION, tempHomeRule, spawnLaneWorker, spawnEnvelopeRepairRequest, laneRunDir, readSpawnManifest, stopLaneProcesses, } from "../lib/lanes/spawn.js";
+import { parseCliModel, refuseOutpostSelfTarget, resolveLaneModel, FOREGROUND_ONLY_RULE, STANDING_AUTHORIZATION, selfReviewRule, tempHomeRule, spawnLaneWorker, spawnEnvelopeRepairRequest, laneRunDir, readSpawnManifest, stopLaneProcesses, } from "../lib/lanes/spawn.js";
 import { handOffInstallHere } from "../lib/daemon/handoff.js";
 export { spawnLaneWorker };
 export function openPullRequestsForProject(hqRoot, metadata) {
@@ -3041,11 +3041,13 @@ export function composeWorkerBrief(worker, taskBrief, hqRoot) {
         "",
         tempHomeRule(hqRoot),
         "",
+        selfReviewRule(hqRoot),
+        "",
     ].join("\n");
 }
 /**
  * A lane with no worker still carries the standing authorization paragraph,
- * the foreground-only rule and the temp-home rule.
+ * the foreground-only rule, the temp-home rule and the self-review rule.
  */
 export function composeGeneralBrief(taskBrief, hqRoot) {
     return [
@@ -3058,6 +3060,8 @@ export function composeGeneralBrief(taskBrief, hqRoot) {
         "",
         tempHomeRule(hqRoot),
         "",
+        selfReviewRule(hqRoot),
+        "",
     ].join("\n");
 }
 function parseMaxRuntimeSeconds(raw, workerId) {

package/dist/commands/mesh.js

@@ -3071,6 +3071,25 @@ export function registerMeshCommand(program, deps = {}) {
         .description("Report daemon running/MQTT/spool/held/dead-letter/outbox/flush health")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runDaemonDoctorCmd(opts))());
+    mesh
+        .command("push-status")
+        .description("Report whether the owner DM push signal is live or stale, with the last event time")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => wrap(() => runMeshPushStatus(opts))());
+}
+async function runMeshPushStatus(opts) {
+    const { ownerPushStatusForAccount, readOwnerInboxPushState, formatOwnerPushStatus } = await import("../lib/mesh/live/daemon/owner-inbox-push.js");
+    const { describeCognitoTokenSource } = await import("../utils/cognito-session.js");
+    const { actorKind } = describeCognitoTokenSource({ home: os.homedir(), env: process.env });
+    const status = ownerPushStatusForAccount(readOwnerInboxPushState(workMeshRoot(undefined, process.env)), Date.now(), actorKind);
+    if (opts.json) {
+        console.log(JSON.stringify(status, null, 2));
+    }
+    else {
+        console.log(formatOwnerPushStatus(status));
+    }
+    if (status.status === "stale")
+        process.exitCode = 1;
 }
 async function runDaemonRun(opts = {}) {
     const { runMeshDaemon } = await import("../lib/mesh/live/daemon/run.js");