@indigoai-us/hq-cli 5.345.191 → 5.345.194

package/dist/commands/sources.d.ts

@@ -23,7 +23,9 @@
 import { Command } from "commander";
 import { type RunLedgerAdapterSummary, type RunLedgerEntry, type RunTrigger, type SignalsGeneratedFn } from "../lib/hot-channels/ledger.js";
 import type { HotChannelRegistry } from "../lib/hot-channels/registry.js";
+import { type AdapterFlagReader } from "../lib/signals/adapters-catalog.js";
 import { type SelectionLoader } from "../lib/hot-channels/selection.js";
+import { type FleetCronOps } from "../lib/bot/fleet-cron.js";
 import { type ScheduleReport } from "../lib/hot-channels/schedule.js";
 import { type OnDemandSyncDeps, type OnDemandSyncReport } from "../lib/hot-channels/run.js";
 type ListFormat = "table" | "json";
@@ -74,6 +76,13 @@ export interface CompanyHotChannelSyncInput {
     hqRoot: string;
     company: string;
     adapter?: string;
+    /** Registered adapter ids allowed to run; see OnDemandSyncInput.onlyAdapters. */
+    onlyAdapters?: readonly string[];
+    /**
+     * Company flag reader for the adapter gate. Defaults to the shared hq-flags
+     * evaluator for this company with the signed-in session.
+     */
+    isFlagOn?: AdapterFlagReader;
     registry?: HotChannelRegistry;
     now?: () => Date;
     /** `scheduled` for the bot's hot-signal-sync job; `on-demand` by default. */
@@ -119,6 +128,53 @@ export declare function runCompanyHotChannelSync(input: CompanyHotChannelSyncInp
  * line under `companies/{company}/sources/`, and nothing else.
  */
 export declare function runSync(options: SyncOptions, overrides?: SyncOverrides): Promise<OnDemandSyncReport>;
+export interface SignalsRedoOptions {
+    company?: string;
+    since?: string;
+    key?: string[];
+    channel?: string;
+    maxDocs?: number;
+    dryRun?: boolean;
+    json?: boolean;
+    hqRoot: string;
+}
+export interface SignalsRedoOverrides {
+    now?: () => Date;
+    /** The signed-in person; defaults to the local Cognito session. */
+    author?: {
+        email: string;
+    } | null;
+    /** The signals pass; defaults to the local `claude -p` pass with `maxDocs`. */
+    createPass?: (maxDocs: number) => SignalsGeneratedFn;
+    worklistScript?: string;
+}
+export interface SignalsRedoReport {
+    company: string;
+    dryRun: boolean;
+    /** Keys queued per channel, by how they were queued. */
+    queued: {
+        pending: Record<string, string[]>;
+        worklist: Record<string, string[]>;
+    };
+    signalsWritten: number;
+    /** Keys still waiting in each channel's pending file after the run. */
+    pendingLeft: Record<string, number>;
+    notices: string[];
+    error: string | null;
+    exitCode: number;
+}
+/**
+ * `hq sources signals`: queue landed documents for the signals pass and run
+ * the pass now, under the same per-person lock as `hq sources sync`. The pass
+ * keeps its cap (`--max-docs`, default 20); what the cap leaves stays queued
+ * and the next run (this command or the daily sync) picks it up.
+ */
+export declare function runSignalsRedo(options: SignalsRedoOptions, overrides?: SignalsRedoOverrides): Promise<SignalsRedoReport>;
+/** A usage or setup failure `runSignalsRedo` already printed; the exit code is set. */
+export declare class SignalsRedoExit extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number);
+}
 export interface ScheduleOptions {
     company?: string;
     at?: string;
@@ -131,6 +187,8 @@ export interface ScheduleOverrides {
     botsRoot?: string;
     /** Whose ledger to read; defaults to the signed-in person. */
     email?: string;
+    /** The HQ Fleet Runtime schedule of one bot; defaults to the bot's own runtime. */
+    fleetOps?: (agentUid: string) => FleetCronOps;
 }
 export declare class NoHotSignalSyncJobError extends Error {
     readonly company: string;

package/dist/commands/sources.js

@@ -23,6 +23,7 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { InvalidArgumentError } from "commander";
 import chalk from "chalk";
 import { SOURCE_CHANNELS, assertSourceChannel, resolveEntity, listAvailableEntities, listSources, getSource, VaultClient, } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken, ensureCognitoIdToken, buildVaultConfig, DEFAULT_COGNITO, DEFAULT_HQ_ROOT, } from "../utils/cognito-session.js";
@@ -34,16 +35,20 @@ import { resolveUploadAuthor } from "../utils/upload-author.js";
 import { createSignalsAlertChannelPoster, raiseSignalsFailureAlerts } from "../lib/hot-channels/alert.js";
 import { audienceKey } from "../lib/hot-channels/audience.js";
 import { appendRunLedgerEntry, ledgerDay, readRunLedger, summarizeRunLedger, } from "../lib/hot-channels/ledger.js";
-import { createClaudeSignalsPass } from "../lib/hot-channels/signals-pass.js";
+import { createClaudeSignalsPass, DEFAULT_MAX_SIGNAL_DOCS, readPendingSignals, SignalsPassError, } from "../lib/hot-channels/signals-pass.js";
+import { backlogRunResult, parseSince, queueSignalsRedo, selectSignalsRedo, SignalsRedoUsageError, } from "../lib/hot-channels/signals-redo.js";
 import { assertSafeSegment } from "../lib/hot-channels/landing.js";
 import { acquireSyncLock, SYNC_LOCK_BUSY_REASON } from "../lib/hot-channels/sync-lock.js";
 import { createBuiltinHotChannelRegistry } from "../lib/hot-channels/adapters/index.js";
+import { companyAdapterFlagReader, gateAdapters, readSignalsAdaptersCatalog, } from "../lib/signals/adapters-catalog.js";
 import { createSelectionLoader } from "../lib/hot-channels/selection.js";
 import { createPersonVaultReader } from "../lib/hot-channels/person-vault-reader.js";
 import { S3Client } from "@aws-sdk/client-s3";
 import { resolveCanonicalPersonUid } from "./cloud.js";
 import { botsRoot as defaultBotsRoot } from "../lib/bot/paths.js";
 import { ensureHotSignalSyncJob } from "../lib/bot/jobs/hot-signal-sync.js";
+import { companyOfHotSignalSyncJob, fleetCronOps } from "../lib/bot/fleet-cron.js";
+import { HQ_FLEET_RUNTIME_ENGINE_ID, readBotConfig } from "../lib/bot/config.js";
 import { findHotSignalSyncJobs, lastRunsPerAdapter, parseDailyAt, renderScheduleReport, rescheduleDaily, toJobView, } from "../lib/hot-channels/schedule.js";
 import { listActiveMembers } from "./members.js";
 import { runOnDemandSync, } from "../lib/hot-channels/run.js";
@@ -485,32 +490,78 @@ async function skippedReport(input, vaultRoot, personKey, personUid, now) {
         runId: line.runId,
         signInRequired: false,
         skipped: true,
+        personKey,
         outcomes: [],
         entries: [line],
         notices: [`Another hot-channel sync for ${input.company} is already running, so this one was skipped.`],
         exitCode: 0,
     };
 }
+/**
+ * One `gated` outcome per adapter the local gate turned off (yaml or company
+ * flag). With `--adapter`, only that adapter's. Nothing is fetched for them.
+ */
+function gatedAdapterOutcomes(registry, gating, wanted) {
+    const want = wanted?.toLowerCase();
+    const out = [];
+    for (const adapter of registry.list()) {
+        if (!(adapter.id in gating.skips))
+            continue;
+        const provider = adapter.tokenScope.provider || adapter.id;
+        if (want !== undefined && adapter.id !== want && provider.toLowerCase() !== want)
+            continue;
+        const flag = gating.offFlags[adapter.id];
+        out.push({
+            adapter: adapter.id,
+            provider,
+            connectionId: null,
+            appName: null,
+            status: "gated",
+            landed: 0,
+            duplicates: 0,
+            message: flag
+                ? `${adapter.id} is not enabled for this company (flag ${flag} is off)`
+                : `${adapter.id} is turned off in core/settings/signals-adapters.yaml`,
+        });
+    }
+    return out;
+}
 async function runLockedCompanySync(input, vaultRoot, personKey, author, session, lockHeld) {
     const deps = gatewaySyncDeps(session.token, session.companyUid);
-    // A fresh loader per run: selections are cached for this run only.
-    const selections = input.createSelections ? input.createSelections() : defaultSelections();
-    const report = await runOnDemandSync({
-        ...(selections ? { selections } : {}),
-        deps,
-        registry: input.registry ??
-            createBuiltinHotChannelRegistry({ vaultRoot, identities: await meetingIdentities(input, session, author.email) }),
-        vaultRoot,
-        personUid: author.userSub,
-        personKey,
-        ...(input.adapter !== undefined ? { adapter: input.adapter } : {}),
-        ...(input.now ? { now: input.now } : {}),
-        ...(input.trigger ? { trigger: input.trigger } : {}),
-        ...(input.catchUp === undefined ? {} : { catchUp: input.catchUp }),
-        ...(input.firstRun ? { firstRun: true } : {}),
-        ...(input.signalsGenerated ? { signalsGenerated: input.signalsGenerated } : {}),
-        beforeWrite: lockHeld,
-    });
+    const registry = input.registry ??
+        createBuiltinHotChannelRegistry({ vaultRoot, identities: await meetingIdentities(input, session, author.email) });
+    // The adapter gate for every caller: signals-adapters.yaml plus the company
+    // flags, read through hq-flags.
+    const gating = await gateAdapters(registry.list().map((a) => a.id), readSignalsAdaptersCatalog(input.hqRoot), input.isFlagOn ??
+        companyAdapterFlagReader(session.companyUid, session.token, { hqRoot: input.hqRoot, company: input.company }));
+    const gated = gatedAdapterOutcomes(registry, gating, input.adapter);
+    const onlyAdapters = (input.onlyAdapters ?? gating.enabled).filter((id) => gating.enabled.includes(id));
+    let report;
+    if (input.adapter !== undefined && gated.length > 0) {
+        // `--adapter` named an adapter the gate turned off: there is nothing to run.
+        report = { runId: null, signInRequired: false, personKey, outcomes: [], entries: [], notices: [], exitCode: 0 };
+    }
+    else {
+        // A fresh loader per run: selections are cached for this run only.
+        const selections = input.createSelections ? input.createSelections() : defaultSelections();
+        report = await runOnDemandSync({
+            ...(selections ? { selections } : {}),
+            deps,
+            registry,
+            vaultRoot,
+            personUid: author.userSub,
+            personKey,
+            ...(input.adapter !== undefined ? { adapter: input.adapter } : {}),
+            ...(input.onlyAdapters !== undefined || Object.keys(gating.skips).length > 0 ? { onlyAdapters } : {}),
+            ...(input.now ? { now: input.now } : {}),
+            ...(input.trigger ? { trigger: input.trigger } : {}),
+            ...(input.catchUp === undefined ? {} : { catchUp: input.catchUp }),
+            ...(input.firstRun ? { firstRun: true } : {}),
+            ...(input.signalsGenerated ? { signalsGenerated: input.signalsGenerated } : {}),
+            beforeWrite: lockHeld,
+        });
+    }
+    report.outcomes.push(...gated);
     if (input.signalsAlert) {
         const postCompanyChannel = input.signalsAlert.postCompanyChannel ??
             createSignalsAlertChannelPoster({ hqRoot: input.hqRoot, company: input.company, deps });
@@ -593,6 +644,188 @@ function renderSyncTable(company, report) {
     }
     return lines.join("\n");
 }
+/**
+ * `hq sources signals`: queue landed documents for the signals pass and run
+ * the pass now, under the same per-person lock as `hq sources sync`. The pass
+ * keeps its cap (`--max-docs`, default 20); what the cap leaves stays queued
+ * and the next run (this command or the daily sync) picks it up.
+ */
+export async function runSignalsRedo(options, overrides = {}) {
+    const company = options.company ?? readActiveCompanySlug(options.hqRoot);
+    const fail = (message, exitCode) => {
+        process.stderr.write(chalk.red(`✗ ${message}\n`));
+        process.exitCode = exitCode;
+        throw new SignalsRedoExit(message, exitCode);
+    };
+    if (!company)
+        return fail("No company specified. Pass --company <slug> or set activeCompany in .hq/config.json.", 2);
+    assertSafeSegment(company, "company");
+    if (options.since === undefined && (options.key ?? []).length === 0)
+        return fail("Pass --since <date> or --key <sources/channel/id.md>.", 2);
+    const vaultRoot = path.join(options.hqRoot, "companies", company);
+    if (!fs.existsSync(vaultRoot))
+        return fail(`No company directory: companies/${company}`, 2);
+    const maxDocs = options.maxDocs ?? DEFAULT_MAX_SIGNAL_DOCS;
+    let selection;
+    try {
+        selection = await selectSignalsRedo({
+            vaultRoot,
+            ...(options.key ? { keys: options.key } : {}),
+            ...(options.since !== undefined ? { since: parseSince(options.since) } : {}),
+            ...(options.channel !== undefined ? { channel: options.channel } : {}),
+        });
+    }
+    catch (err) {
+        if (err instanceof SignalsRedoUsageError)
+            return fail(err.message, 2);
+        throw err;
+    }
+    const report = {
+        company,
+        dryRun: options.dryRun === true,
+        queued: { pending: Object.fromEntries(selection.pending), worklist: Object.fromEntries(selection.worklist) },
+        signalsWritten: 0,
+        pendingLeft: {},
+        notices: [...selection.notices],
+        error: null,
+        exitCode: 0,
+    };
+    const channels = [...new Set([...selection.pending.keys(), ...selection.worklist.keys()])];
+    if (!report.dryRun && channels.length > 0) {
+        const author = overrides.author !== undefined ? overrides.author : resolveUploadAuthor();
+        if (!author)
+            return fail(`${SIGN_IN_PROMPT} (the run takes your hot-channel sync lock)`, 1);
+        const lock = await acquireSyncLock(vaultRoot, audienceKey([author.email]), overrides.now ? { now: overrides.now } : {});
+        if (!lock)
+            return fail(`Another hot-channel sync for ${company} is running. Try again when it finishes.`, 1);
+        try {
+            await queueSignalsRedo({
+                hqRoot: options.hqRoot,
+                company,
+                selection,
+                beforeWrite: lock.assertHeld,
+                ...(overrides.worklistScript ? { worklistScript: overrides.worklistScript } : {}),
+            });
+            const pass = overrides.createPass
+                ? overrides.createPass(maxDocs)
+                : createClaudeSignalsPass({ hqRoot: options.hqRoot, company, maxDocs });
+            for (const channel of channels) {
+                report.signalsWritten += await pass(backlogRunResult(channel), { beforeWrite: lock.assertHeld });
+            }
+        }
+        catch (err) {
+            report.error = err instanceof SignalsPassError ? err.code : err instanceof Error ? err.message : String(err);
+            report.exitCode = 1;
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    for (const channel of selection.pending.keys()) {
+        report.pendingLeft[channel] = (await readPendingSignals(vaultRoot, channel)).length;
+    }
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${renderSignalsRedo(report)}\n`);
+    }
+    if (report.exitCode !== 0)
+        process.exitCode = report.exitCode;
+    return report;
+}
+/** A usage or setup failure `runSignalsRedo` already printed; the exit code is set. */
+export class SignalsRedoExit extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.name = "SignalsRedoExit";
+        this.exitCode = exitCode;
+    }
+}
+function renderSignalsRedo(report) {
+    const lines = [`${report.dryRun ? "Would queue" : "Queued"} for signals in ${report.company}:`];
+    const groups = [
+        ...Object.entries(report.queued.pending).map(([channel, keys]) => ({ channel, keys, how: "pending" })),
+        ...Object.entries(report.queued.worklist).map(([channel, keys]) => ({ channel, keys, how: "worklist --redo" })),
+    ];
+    if (groups.length === 0)
+        lines.push("  nothing (no matching landed document without signals)");
+    for (const group of groups) {
+        lines.push(`  sources/${group.channel}: ${group.keys.length} (${group.how})`);
+        for (const key of group.keys)
+            lines.push(`    ${key}`);
+    }
+    lines.push(...report.notices);
+    if (!report.dryRun && groups.length > 0) {
+        lines.push("", `${report.signalsWritten} signal(s) written.`);
+        for (const [channel, left] of Object.entries(report.pendingLeft)) {
+            if (left > 0)
+                lines.push(`${left} document(s) still queued in sources/${channel}; the next run picks them up.`);
+        }
+        if (report.error)
+            lines.push(chalk.red(`The signals pass stopped: ${report.error}. Queued documents stay queued.`));
+    }
+    return lines.join("\n");
+}
+function collectKey(value, previous = []) {
+    return [...previous, value];
+}
+function parseMaxDocs(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new InvalidArgumentError("must be a positive integer");
+    return n;
+}
+function fleetBotsIn(root) {
+    let names;
+    try {
+        names = fs.readdirSync(root).sort();
+    }
+    catch {
+        return [];
+    }
+    const bots = [];
+    for (const botName of names) {
+        const config = readBotConfig(path.join(root, botName));
+        if (config && config.engine?.id === HQ_FLEET_RUNTIME_ENGINE_ID)
+            bots.push({ botName, agentUid: config.agentUid });
+    }
+    return bots;
+}
+function findFleetHotSignalSyncJob(root, company, opsFor) {
+    for (const bot of fleetBotsIn(root)) {
+        let ops;
+        let jobs;
+        try {
+            ops = opsFor(bot.agentUid);
+            jobs = ops.list();
+        }
+        catch {
+            continue;
+        }
+        const job = jobs.find((candidate) => companyOfHotSignalSyncJob(candidate) === company);
+        if (job)
+            return { botName: bot.botName, ops, job };
+    }
+    return null;
+}
+function fleetDailyAt(expr) {
+    const match = /^(\d{1,2}) (\d{1,2}) \* \* \*$/.exec((expr ?? "").trim());
+    return match ? `${match[2].padStart(2, "0")}:${match[1].padStart(2, "0")}` : null;
+}
+function fleetJobView(found) {
+    const expr = found.job.schedule?.expr ?? "";
+    return {
+        botName: found.botName,
+        jobId: found.job.id,
+        cron: expr,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+        dailyAt: fleetDailyAt(expr),
+        nextRunAt: found.job.next_run_at ?? null,
+        lastRunAt: found.job.last_run_at ?? null,
+    };
+}
 export class NoHotSignalSyncJobError extends Error {
     company;
     constructor(company) {
@@ -618,7 +851,22 @@ export async function runSchedule(options, overrides = {}) {
     // Validate before touching any job file.
     if (options.at !== undefined)
         parseDailyAt(options.at);
-    let found = findHotSignalSyncJobs(overrides.botsRoot ?? defaultBotsRoot(), company);
+    const botsRootDir = overrides.botsRoot ?? defaultBotsRoot();
+    const fleetFound = findFleetHotSignalSyncJob(botsRootDir, company, overrides.fleetOps ?? fleetCronOps);
+    if (fleetFound) {
+        if (options.at !== undefined) {
+            const { hour, minute } = parseDailyAt(options.at);
+            const updated = fleetFound.ops.reschedule(fleetFound.job.id, `${minute} ${hour} * * *`);
+            if (!updated)
+                throw new NoHotSignalSyncJobError(company);
+            fleetFound.job = updated;
+        }
+        return finishScheduleReport(options, overrides, company, fleetJobView(fleetFound), [], now);
+    }
+    if (options.at !== undefined && fleetBotsIn(botsRootDir).some((bot) => bot.botName === "setup")) {
+        throw new Error(`The setup bot runs on the HQ Fleet Runtime and has no hot-signal-sync job for ${company} yet. Start it once with \`hq bot start setup\` so it adds the job, then set the time again.`);
+    }
+    let found = findHotSignalSyncJobs(botsRootDir, company);
     if (options.at !== undefined) {
         if (found.length === 0) {
             // Setting a time turns the daily sync on: register it on the personal setup bot.
@@ -638,20 +886,19 @@ export async function runSchedule(options, overrides = {}) {
             throw new NoHotSignalSyncJobError(company);
         found = rescheduleDaily(found, options.at, now);
     }
+    return finishScheduleReport(options, overrides, company, found[0] ? toJobView(found[0], now) : null, found.slice(1).map((f) => f.botName), now);
+}
+async function finishScheduleReport(options, overrides, company, job, extraBots, now) {
     const email = overrides.email ?? resolveUploadAuthor()?.email;
     const lastRuns = email
         ? await lastRunsPerAdapter(path.join(options.hqRoot, "companies", company), audienceKey([email]), now)
         : [];
-    const report = {
-        company,
-        job: found[0] ? toJobView(found[0], now) : null,
-        lastRuns,
-    };
+    const report = { company, job, lastRuns };
     if (options.json) {
         process.stdout.write(JSON.stringify(report, null, 2) + "\n");
     }
     else {
-        process.stdout.write(renderScheduleReport(report, found.slice(1).map((f) => f.botName)) + "\n");
+        process.stdout.write(renderScheduleReport(report, extraBots) + "\n");
         if (!email)
             process.stdout.write("Sign in (hq login) to see recent runs.\n");
     }
@@ -730,6 +977,27 @@ export function registerSourcesCommand(program) {
         .action(withErrorHandling(async (options) => {
         await runSchedule(options);
     }));
+    sources
+        .command("signals")
+        .description("Process landed sources for signals again: queue them for the signals pass and run it now (the pass's document cap still applies)")
+        .option("--company <slug>", "Company slug (defaults to .hq/config.json activeCompany)")
+        .option("--since <date>", "Landed documents from this date on (YYYY-MM-DD is local midnight) that have no signals yet")
+        .option("--key <key>", "A landed document to process again, signals or not (sources/<channel>/<id>.md; repeatable)", collectKey)
+        .option("--channel <channel>", "Limit --since to one channel")
+        .option("--max-docs <n>", `Documents sent to claude in this run (default ${DEFAULT_MAX_SIGNAL_DOCS})`, parseMaxDocs)
+        .option("--dry-run", "Print what would be queued; queue nothing and call no model")
+        .option("--json", "Print the report as JSON")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .action(withErrorHandling(async (options) => {
+        try {
+            await runSignalsRedo(options);
+        }
+        catch (err) {
+            // Usage and setup failures are already printed with their exit code.
+            if (!(err instanceof SignalsRedoExit))
+                throw err;
+        }
+    }));
     sources
         .command("sync")
         .description("Run every hot channel now: each adapter once per connection you can use")

package/dist/commands/staff/reset-test-account.d.ts

@@ -24,6 +24,12 @@ interface PlanCompany {
     slug: string;
     memberCount: number;
 }
+interface PlanCompanyHandoff {
+    companyUid: string;
+    companySlug: string;
+    toPersonUid: string;
+    toEmail: string;
+}
 interface Plan {
     target: {
         input: string;
@@ -32,6 +38,8 @@ interface Plan {
     personUid: string | null;
     cognitoUsers: PlanCognitoUser[];
     ownedCompanies: PlanCompany[];
+    /** Present only when the request opted in to the handoff. */
+    sharedCompanyHandoffs?: PlanCompanyHandoff[];
     personalVault: {
         bucketName: string | null;
         kmsKeyAlias: string | null;
@@ -89,6 +97,8 @@ export interface RunResetTestAccountParams {
     execute: boolean;
     /** Skip the typed-confirmation prompt on --execute (for scripts). */
     yes?: boolean;
+    /** Keep a company with real members and hand it to one, instead of refusing. */
+    handoffSharedCompanies?: boolean;
 }
 export interface RunResetTestAccountDeps {
     prompt?: ConfirmFn;

package/dist/commands/staff/reset-test-account.js

@@ -76,6 +76,13 @@ export function renderPlan(plan) {
         }
     }
     lines.push("");
+    if (plan.sharedCompanyHandoffs && plan.sharedCompanyHandoffs.length > 0) {
+        lines.push(chalk.bold("  Companies kept and handed over"));
+        for (const h of plan.sharedCompanyHandoffs) {
+            lines.push(`    handoff: ${h.companySlug} to ${h.toEmail}`);
+        }
+        lines.push("");
+    }
     lines.push(chalk.bold("  Personal vault"));
     lines.push(`    bucket:               ${plan.personalVault.bucketName ?? chalk.dim("(none)")}`);
     lines.push(`    kms alias:            ${plan.personalVault.kmsKeyAlias ?? chalk.dim("(none)")}`);
@@ -166,13 +173,17 @@ export async function runResetTestAccount(params, deps = {}) {
         throw new Error("reset-test-account requires a super-admin (staff) HQ session. " +
             "Sign in with an @getindigo.ai account and retry.");
     }
+    // Absent unless asked for, so the server's refusal stays the default.
+    const handoff = params.handoffSharedCompanies === true
+        ? { handoffSharedCompanies: true }
+        : {};
     // Dry-run first. The AC calls out "Without --execute, runs dry-run and
     // prints the plan" — so a bare invocation always ends here.
     const dryRunRes = await vaultApiFetch({
         token,
         path: "/v1/admin/test-account/reset",
         method: "POST",
-        body: { email, dryRun: true },
+        body: { email, dryRun: true, ...handoff },
     });
     const dryRunBody = await readBody(dryRunRes);
     if (!dryRunRes.ok) {
@@ -221,7 +232,7 @@ export async function runResetTestAccount(params, deps = {}) {
         token,
         path: "/v1/admin/test-account/reset",
         method: "POST",
-        body: { email, dryRun: false, confirmEmail },
+        body: { email, dryRun: false, confirmEmail, ...handoff },
     });
     const executeBody = await readBody(executeRes);
     // The handler answers 200 (all-ok) and 207 (best-effort partial). Anything
@@ -234,6 +245,9 @@ export async function runResetTestAccount(params, deps = {}) {
         throw new Error("server did not return an execute result");
     }
     console.log(renderExecuteSummary(result));
+    for (const h of plan.sharedCompanyHandoffs ?? []) {
+        console.log(`  handoff: ${h.companySlug} to ${h.toEmail}`);
+    }
     if (!result.ok) {
         // Non-zero exit so a scripted caller can react. The summary line above
         // already shows which step failed.
@@ -253,12 +267,14 @@ export function registerResetTestAccountCommand(staff, deps = {}) {
         .argument("<email>", "Designated test-account email (must be in the registry)")
         .option("--execute", "Actually delete artifacts. Prompts for a typed-email confirmation.")
         .option("-y, --yes", "Skip the typed-email confirmation prompt (still sends confirmEmail).")
+        .option("--handoff-shared-companies", "Keep a company with real members and hand it to one, instead of refusing the reset.")
         .action(async (email, opts) => {
         try {
             await runResetTestAccount({
                 email,
                 execute: opts.execute === true,
                 yes: opts.yes === true,
+                handoffSharedCompanies: opts.handoffSharedCompanies === true,
             }, deps);
         }
         catch (err) {

package/dist/commands/whoami.d.ts

@@ -21,6 +21,13 @@ export interface WhoamiDisplayIdentity {
  * email with the token subject of the delegating machine.
  */
 export declare function resolveWhoamiIdentity(identity: WhoamiTokenIdentity): WhoamiDisplayIdentity;
+/**
+ * Bound on the person-uid lookup, so `--json` callers with short timeouts still
+ * get an answer. Kept at 1s: with every endpoint stalled, a whole `whoami
+ * --json` must still finish inside the foreground network budget plus startup
+ * (foreground-network-budget.test.ts); 3s overran it.
+ */
+export declare const PERSON_UID_LOOKUP_TIMEOUT_MS = 1000;
 export declare function renderWhoamiPlanBlock(status: PlanLimitStatus, opts?: {
     inviteTeammateEnabled?: boolean;
 }): string | null;

package/dist/commands/whoami.js

@@ -8,6 +8,7 @@ import { ensureCognitoToken, loadMachineCachedTokens, resolveCognitoTokenSource,
 import { colorizePlanLimitNotice, fetchPlanLimitStatus, renderPlanLine, renderPlanLimitNotice, } from "../lib/billing/plan-lock.js";
 import { resolveCompanyFlagGate, } from "../lib/flag-registry.js";
 import { queuePlanLimitInviteTeammateExposure } from "../utils/cli-telemetry.js";
+import { resolveCallerPersonUid } from "../utils/vault-api.js";
 export const CLI_LIMIT_INVITE_TEAMMATE_FLAG = "cli.limit-invite-teammate-v1";
 /**
  * Resolves the person represented by an ID token without pairing a delegated
@@ -44,6 +45,36 @@ function peekIdToken(idToken) {
             : undefined,
     };
 }
+/**
+ * Bound on the person-uid lookup, so `--json` callers with short timeouts still
+ * get an answer. Kept at 1s: with every endpoint stalled, a whole `whoami
+ * --json` must still finish inside the foreground network budget plus startup
+ * (foreground-network-budget.test.ts); 3s overran it.
+ */
+export const PERSON_UID_LOOKUP_TIMEOUT_MS = 1_000;
+/**
+ * The signed-in person's canonical `prs_*` uid for `whoami --json`. Person ID
+ * tokens carry no `custom:entityType`/`custom:entityUid` claims, so the token
+ * alone almost never has it; the vault's person-entity lookup does (the same
+ * rule `hq secrets --personal` uses). Best-effort: no session, a timeout or a
+ * network failure resolve to null and the rest of the identity still prints.
+ */
+async function readPersonUid(identity) {
+    if (identity.entityType === 'person' && identity.entityUid)
+        return identity.entityUid;
+    try {
+        const token = await ensureCognitoToken({ interactive: false });
+        if (!token)
+            return null;
+        return await resolveCallerPersonUid(token, undefined, {
+            command: 'hq whoami',
+            signal: AbortSignal.timeout(PERSON_UID_LOOKUP_TIMEOUT_MS),
+        });
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * starter-plan-hard-limits / US-011 — read the workspace plan-limit nag for
  * `--company <slug>` (the bind notice).
@@ -148,9 +179,11 @@ export function registerWhoamiCommand(program) {
                     : boundLegacyAgent;
                 // planLimits is additive: absent-or-null means UNKNOWN.
                 const planLimits = await readPlanLimits(opts.company);
+                const authenticated = machine ? Boolean(machineCreds) : Boolean(cached && !isExpiring(cached, 0));
+                const personUid = !machine && authenticated ? await readPersonUid(identity) : null;
                 console.log(JSON.stringify({
                     schemaVersion: 1,
-                    authenticated: machine ? Boolean(machineCreds) : Boolean(cached && !isExpiring(cached, 0)),
+                    authenticated,
                     tokenSource: machine ? 'machine' : 'person',
                     email: machine ? null : displayedIdentity.email ?? null,
                     // Cognito subject of the person shown in `email` (null for machine
@@ -162,7 +195,7 @@ export function registerWhoamiCommand(program) {
                         ? identity.delegatedEmail : null,
                     delegatedSub: identity.delegatedEmail !== undefined && identity.delegatedSub !== undefined
                         ? identity.delegatedSub : null,
-                    personUid: !machine && identity.entityType === 'person' ? identity.entityUid ?? null : null,
+                    personUid,
                     agentUid,
                     username: machineCreds?.username ?? null,
                     planLimits,