@indigoai-us/hq-cli 5.345.200 → 5.345.201

package/dist/lib/bot/jobs/source-report.js

@@ -0,0 +1,276 @@
+/** Owner-only source reports with durable at-least-once delivery receipts. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { readBotConfig } from "../config.js";
+import { botsRoot } from "../paths.js";
+import { emitBotEvent } from "../events.js";
+import { isExecutiveBot } from "./meeting-rider.js";
+import { signalLaneCompanies } from "./signal-to-lane.js";
+import { readBuiltinJobsMarker, writeBuiltinJobsMarker } from "./hot-signal-sync.js";
+import { readLocalJobsStrict, writeLocalJobs, withJobsLock } from "../local-jobs.js";
+import { listLanesBySource, readAllLanes, retryUpdateLane } from "../../lanes/store.js";
+import { buildSourceReport, renderSourceReportText } from "../../lanes/source-report.js";
+import { lockFileContents, reclaimStaleLock } from "../../lanes/stale-lock.js";
+import { isTerminalLaneState } from "../../lanes/types.js";
+export const SOURCE_REPORT_JOB_KIND = "source-report";
+export const REPORT_COOLDOWN_MS = 10 * 60 * 1000;
+const events = ["meeting.ended", "lane.finished"];
+const safeCompany = (value) => /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(value) && value !== "personal";
+export const sourceLaneTerminal = (lane) => isTerminalLaneState(lane.state);
+export function ensureSourceReportJobs(dir, config, companies = signalLaneCompanies(config), home) {
+    if (!isExecutiveBot(config, home))
+        return [];
+    return withJobsLock(dir, () => {
+        const jobs = readLocalJobsStrict(dir);
+        const marker = readBuiltinJobsMarker(dir);
+        for (const company of new Set(companies.filter(safeCompany)))
+            for (const event of events) {
+                const key = `${SOURCE_REPORT_JOB_KIND}:${company}:${event}`;
+                if (marker.registered[key])
+                    continue;
+                if (!jobs.some(job => job.context?.jobKind === SOURCE_REPORT_JOB_KIND && job.context.company === company && job.trigger?.event === event)) {
+                    jobs.push({ jobId: `job_${randomUUID().replaceAll("-", "").slice(0, 20)}`,
+                        prompt: "Deliver the source report to the owner in-process.", timezone: "UTC",
+                        trigger: { kind: "event", event, filter: { company } },
+                        context: { jobKind: SOURCE_REPORT_JOB_KIND, company }, createdAt: new Date().toISOString() });
+                }
+                marker.registered[key] = new Date().toISOString();
+            }
+        writeLocalJobs(dir, jobs);
+        writeBuiltinJobsMarker(dir, marker);
+        return jobs.filter(job => job.context?.jobKind === SOURCE_REPORT_JOB_KIND);
+    });
+}
+/** Local append only; duplicate watcher observations are harmless. */
+export function emitExecutiveLaneFinished(hqRoot, lane, root = botsRoot(), home) {
+    if (!lane.signal || !lane.company || !sourceLaneTerminal(lane) || !fs.existsSync(root))
+        return false;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(root, entry.name);
+        const config = readBotConfig(dir);
+        if (!config || typeof config.hqRoot !== "string" || path.resolve(config.hqRoot) !== path.resolve(hqRoot) ||
+            !isExecutiveBot(config, home) || !signalLaneCompanies(config).includes(lane.company.slug))
+            continue;
+        const payload = { lane_id: lane.lane_id, signal_id: lane.signal.signal_id,
+            source_ref: lane.signal.source_ref, company: lane.company.slug, state: lane.state };
+        emitBotEvent(dir, "lane.finished", payload, new Date(), prior => prior.event === "lane.finished" && Object.entries(payload).every(([key, value]) => prior.payload[key] === value));
+        return true;
+    }
+    return false;
+}
+/** Replay terminal commits whose watcher never durably published its event. */
+export function flushExecutiveLaneFinished(hqRoot, root = botsRoot(), home) {
+    const failures = [];
+    for (const lane of readAllLanes(hqRoot)) {
+        if (!lane.source_report_pending || !sourceLaneTerminal(lane))
+            continue;
+        try {
+            if (!emitExecutiveLaneFinished(hqRoot, lane, root, home))
+                continue;
+            // Clearing follows the journal append. A crash here only re-appends via
+            // the journal's dedupe; it cannot lose the terminal notification.
+            retryUpdateLane(hqRoot, lane.lane_id, "watcher", current => current.state === lane.state && current.company?.slug === lane.company?.slug &&
+                current.signal?.source_ref === lane.signal?.source_ref
+                ? { ...current, source_report_pending: undefined } : current);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length)
+        throw new AggregateError(failures, "Terminal report events remain pending");
+}
+export function sourceReportReceiptPath(hqRoot, company, sourceRef) {
+    if (!safeCompany(company))
+        throw new Error("Invalid report company");
+    return path.join(hqRoot, "workspace/executive/reports", company, `${createHash("sha256").update(sourceRef).digest("hex")}.json`);
+}
+function atomic(file, value) {
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function validIntent(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const intent = value;
+    return typeof intent.body === "string" && typeof intent.allTerminal === "boolean" &&
+        (intent.phase === "meeting" || intent.phase === "final") && typeof intent.at === "string" &&
+        Number.isFinite(Date.parse(intent.at)) && (intent.rootEventId === undefined || typeof intent.rootEventId === "string");
+}
+function read(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!value || value.v !== 1 || !Array.isArray(value.sent) || typeof value.sourceRef !== "string" ||
+            typeof value.company !== "string" || typeof value.title !== "string" ||
+            typeof value.ownerUid !== "string" || typeof value.agentUid !== "string" || value.sent.length > 2 ||
+            (value.intent !== undefined && !validIntent(value.intent)) ||
+            (value.finalDueAt !== undefined && !Number.isFinite(Date.parse(value.finalDueAt))) ||
+            value.sent.some(sent => !validIntent(sent) || typeof sent.eventId !== "string" || !Number.isFinite(Date.parse(sent.sentAt)))) {
+            throw new Error("Invalid source report receipt");
+        }
+        return value;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/** Reclaim only a dead process's lock; never expire a live network send's lock. */
+async function locked(file, work) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const lock = `${file}.lock`;
+    const acquire = () => fs.writeFileSync(lock, lockFileContents(), { flag: "wx", mode: 0o600 });
+    try {
+        acquire();
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        if (!reclaimStaleLock(lock, { staleMs: 60_000, liveOwnerMaxMs: Number.MAX_SAFE_INTEGER,
+            label: "source report" }))
+            throw new Error("Source report delivery is busy");
+        acquire();
+    }
+    const held = fs.statSync(lock);
+    try {
+        return await work();
+    }
+    finally {
+        try {
+            const current = fs.statSync(lock);
+            if (held.ino === current.ino && held.dev === current.dev)
+                fs.unlinkSync(lock);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                process.stderr.write(`source report lock cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
+}
+export function createSourceReporter(deps) {
+    const { config } = deps;
+    const now = deps.now ?? (() => new Date());
+    const companies = deps.companies ?? (() => signalLaneCompanies(config));
+    const lanes = deps.lanes ?? ((company, ref) => listLanesBySource(company, ref, config.hqRoot));
+    let queue = Promise.resolve();
+    const serial = (work) => {
+        const result = queue.then(work);
+        queue = result.catch(() => undefined);
+        return result;
+    };
+    const allowed = (company) => isExecutiveBot(config, deps.home) && safeCompany(company) &&
+        companies().includes(company) && config.ownerUid.startsWith("prs_");
+    async function deliver(file, receipt) {
+        if (!receipt.intent)
+            return;
+        const intent = receipt.intent;
+        // At-least-once: a crash after sendDm accepts the DM but before this sent
+        // receipt is durable can resend on restart. A sent receipt always skips it.
+        const result = await deps.api.sendDm({ toPersonUid: config.ownerUid, body: intent.body,
+            audience: "human", ...(intent.rootEventId ? { rootEventId: intent.rootEventId } : {}) });
+        deps.afterSend?.();
+        if (!result.eventId)
+            throw new Error("Source report delivery returned no event receipt");
+        receipt.sent.push({ ...intent, eventId: result.eventId, sentAt: now().toISOString() });
+        delete receipt.intent;
+        atomic(file, receipt);
+    }
+    async function processSource(company, ref, event, title) {
+        if (!allowed(company))
+            return;
+        const file = sourceReportReceiptPath(config.hqRoot, company, ref);
+        await locked(file, async () => {
+            const receipt = read(file) ?? { v: 1, company, sourceRef: ref, ownerUid: config.ownerUid,
+                agentUid: config.agentUid, title: title ?? ref, sent: [] };
+            if (receipt.ownerUid !== config.ownerUid || receipt.agentUid !== config.agentUid || receipt.company !== company || receipt.sourceRef !== ref) {
+                throw new Error("Source report receipt identity mismatch");
+            }
+            await deliver(file, receipt);
+            if (receipt.sent.some(sent => sent.allTerminal) || receipt.sent.length >= 2)
+                return;
+            const current = lanes(company, ref).filter(lane => lane.company?.slug === company && lane.signal?.source_ref === ref);
+            const allTerminal = current.length > 0 && current.every(sourceLaneTerminal);
+            const meeting = event === "meeting.ended" && receipt.sent.length === 0;
+            if (!meeting && !allTerminal)
+                return;
+            if (!meeting && !event && !receipt.finalDueAt)
+                return;
+            const lastSent = receipt.sent.at(-1);
+            if (!meeting && lastSent && now().getTime() - Date.parse(lastSent.sentAt) < REPORT_COOLDOWN_MS) {
+                receipt.finalDueAt = new Date(Date.parse(lastSent.sentAt) + REPORT_COOLDOWN_MS).toISOString();
+                atomic(file, receipt);
+                return;
+            }
+            if (!meeting && receipt.finalDueAt && now().getTime() < Date.parse(receipt.finalDueAt))
+                return;
+            let template;
+            try {
+                template = fs.readFileSync(path.join(config.hqRoot, "personal/settings/executive/report.md"), "utf8");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            const body = renderSourceReportText(buildSourceReport(company, ref, current), template);
+            receipt.intent = { body: `Report for ${receipt.title}\n${body}`, allTerminal,
+                phase: meeting ? "meeting" : "final", at: now().toISOString(),
+                ...(lastSent ? { rootEventId: lastSent.eventId } : {}) };
+            delete receipt.finalDueAt;
+            atomic(file, receipt);
+            deps.afterIntent?.();
+            await deliver(file, receipt);
+        });
+    }
+    return {
+        handle(event, payload, company) {
+            return serial(async () => {
+                const p = payload;
+                if (typeof event !== "string" || !events.includes(event) ||
+                    !p || typeof company !== "string" || p.company !== company || !allowed(company) ||
+                    typeof p.source_ref !== "string" || !p.source_ref.trim()) {
+                    return { status: "skipped-precondition", output: "Source outside the Executive report scope" };
+                }
+                await processSource(company, p.source_ref, event, typeof p.title === "string" ? p.title.replace(/[\r\n]+/g, " ") : undefined);
+                return { status: "succeeded", output: "Source report processed" };
+            });
+        },
+        /** Poll from the resident bot loop, so a last lane inside cooldown is not lost. */
+        recover() {
+            return serial(async () => {
+                if (!isExecutiveBot(config, deps.home))
+                    return;
+                const failures = [];
+                try {
+                    flushExecutiveLaneFinished(config.hqRoot, deps.botsDir, deps.home);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                for (const company of companies().filter(allowed)) {
+                    const dir = path.dirname(sourceReportReceiptPath(config.hqRoot, company, ""));
+                    if (!fs.existsSync(dir))
+                        continue;
+                    for (const name of fs.readdirSync(dir).filter(name => /^[a-f0-9]{64}\.json$/.test(name))) {
+                        try {
+                            const receipt = read(path.join(dir, name));
+                            if (receipt && (receipt.intent || receipt.finalDueAt))
+                                await processSource(company, receipt.sourceRef);
+                        }
+                        catch (error) {
+                            failures.push(error);
+                        }
+                    }
+                }
+                // One damaged receipt must not starve unrelated pending reports.
+                if (failures.length)
+                    throw new AggregateError(failures, "Source report recovery deferred");
+            });
+        },
+    };
+}
+//# sourceMappingURL=source-report.js.map

package/dist/lib/bot/legacy-convert.d.ts

@@ -1,15 +1,118 @@
-import { type BotConfig } from "./config.js";
+import { type BotConfig, type BotRuntimeId } from "./config.js";
 export declare const KEEP_LEGACY_RUNTIME_ENV = "HQ_BOT_KEEP_LEGACY_RUNTIME";
+/** The runtimes whose Fleet sign-in can be imported from a login already on this computer. */
+export type LegacyProviderRuntime = "codex" | "grok";
+/**
+ * Whether the provider sign-in a legacy bot needs is readable on this
+ * computer, the way the HQ Fleet Runtime imports it: the Codex CLI login
+ * file, or another Fleet bot's Grok login. `env` is the extra environment the
+ * import runs with (a bot's own Codex home).
+ */
+export interface LegacyProviderLogin {
+    readable: boolean;
+    /** Where the check looked, for the log, `hq bot status` and the owner's DM. */
+    detail: string;
+    env?: Record<string, string>;
+}
+export type LegacyProviderLoginProbe = (runtime: LegacyProviderRuntime) => LegacyProviderLogin;
+export type LegacyConversionReason = "already-fleet" | "kept-by-env" | "needs-sign-in" | "own-claude-account";
 export type LegacyConversionDecision = {
     convert: true;
+    signIn?: {
+        runtime: LegacyProviderRuntime;
+        env?: Record<string, string>;
+    };
 } | {
     convert: false;
-    reason: "already-fleet" | "kept-by-env" | "needs-sign-in" | "own-claude-account";
+    reason: LegacyConversionReason;
+    detail: string;
 };
-export declare function legacyConversionDecision(config: Pick<BotConfig, "engine" | "runtime" | "runtimeAuth">, env?: NodeJS.ProcessEnv): LegacyConversionDecision;
+/**
+ * Whether a legacy bot moves to the HQ Fleet Runtime at this start.
+ *
+ * A Claude bot on the owner's login moves as is: the runtime reads the same
+ * Claude Code login. A Codex or Grok bot moves when its provider sign-in can
+ * be imported here without a browser (`probe`); otherwise it waits for
+ * `hq bot auth`. A Claude bot with its own Claude account stays: HQ Fleet
+ * Local answers with the owner's Claude Code login only, so that account
+ * cannot come along.
+ */
+export declare function legacyConversionDecision(config: Pick<BotConfig, "engine" | "runtime" | "runtimeAuth">, env: NodeJS.ProcessEnv, probe: LegacyProviderLoginProbe): LegacyConversionDecision;
+/** The `--provider` value `hq bot auth` takes for a runtime. */
+export declare function fleetAuthProviderFlag(runtime: BotRuntimeId): string;
+export interface LegacyHoldNotice {
+    /** Why the bot still runs on its legacy runner, in plain words. */
+    cause: string;
+    /** What the owner does about it. */
+    fix: string;
+}
+/** The one-time owner notice (and the status line) for a bot that stays on its legacy runner. */
+export declare function legacyHoldNotice(name: string, runtime: BotRuntimeId, decision: Extract<LegacyConversionDecision, {
+    convert: false;
+}>): LegacyHoldNotice;
+/** Reasons the owner is told about once; the others are the owner's own choice or no hold at all. */
+export declare function legacyHoldNotifiesOwner(reason: LegacyConversionReason): boolean;
 /** How long a legacy runner's own start skips the move after one failed. */
 export declare const FLEET_MOVE_RETRY_MS: number;
+export interface FleetMoveFailure {
+    at: string;
+    /** The step that failed: install, sign in, start. */
+    step?: string;
+    error?: string;
+}
 export declare function fleetMoveFailurePath(dir: string): string;
-export declare function writeFleetMoveFailure(dir: string, now?: Date): void;
+export declare function writeFleetMoveFailure(dir: string, now?: Date, failure?: Omit<FleetMoveFailure, "at">): void;
+export declare function readFleetMoveFailure(dir: string): FleetMoveFailure | null;
 export declare function fleetMoveRecentlyFailed(dir: string, now?: number): boolean;
+/**
+ * Why the bot stayed on its legacy runner at its last start, and whether the
+ * owner has been told. One DM per reason: a bot that is still waiting for the
+ * same sign-in at every start does not DM the owner again.
+ */
+export interface FleetMoveHold {
+    reason: LegacyConversionReason;
+    detail: string;
+    at: string;
+    notifiedAt?: string;
+    notifiedReason?: LegacyConversionReason;
+    /** The HQ failure report filed for this hold, once per reason. */
+    reportId?: string;
+    reportedReason?: LegacyConversionReason;
+}
+export declare function fleetMoveHoldPath(dir: string): string;
+export declare function readFleetMoveHold(dir: string): FleetMoveHold | null;
+export declare function writeFleetMoveHold(dir: string, hold: FleetMoveHold): void;
+export declare function clearFleetMoveRecords(dir: string): void;
+/** True when the owner has not yet been told about this reason. */
+export declare function ownerHoldNoticeDue(hold: FleetMoveHold | null, reason: LegacyConversionReason): boolean;
+/** True when no HQ failure report has been filed for this reason yet. */
+export declare function holdReportDue(hold: FleetMoveHold | null, reason: LegacyConversionReason): boolean;
+/**
+ * The failure report a held legacy bot files with HQ, in the shape the HQ
+ * Fleet Runtime's HQ DM adapter uploads for a failed turn (`build_upload`),
+ * so stuck legacy bots show up next to failing Fleet bots. No credential
+ * value is ever part of it.
+ */
+export declare function legacyHoldFailureReport(input: {
+    reportId: string;
+    createdAt: string;
+    name: string;
+    config: Pick<BotConfig, "agentUid" | "ownerUid" | "runtime" | "model">;
+    decision: Extract<LegacyConversionDecision, {
+        convert: false;
+    }>;
+    notice: LegacyHoldNotice;
+    machine: string;
+    hqCliVersion: string;
+    os: string;
+    logPath: string;
+}): Record<string, unknown>;
+/** What `hq bot status` and `hq doctor` say about a legacy bot's move. */
+export interface LegacyMoveState {
+    decision: LegacyConversionDecision;
+    notice: LegacyHoldNotice | null;
+    lastFailure: FleetMoveFailure | null;
+    hold: FleetMoveHold | null;
+}
+export declare function legacyMoveState(dir: string, config: Pick<BotConfig, "name" | "engine" | "runtime" | "runtimeAuth">, probe: LegacyProviderLoginProbe, env?: NodeJS.ProcessEnv): LegacyMoveState;
 //# sourceMappingURL=legacy-convert.d.ts.map

package/dist/lib/bot/legacy-convert.js

@@ -1,38 +1,184 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { HQ_FLEET_RUNTIME_ENGINE_ID } from "./config.js";
+import { runtimeDisplayName } from "./runtime-sign-in.js";
 export const KEEP_LEGACY_RUNTIME_ENV = "HQ_BOT_KEEP_LEGACY_RUNTIME";
-export function legacyConversionDecision(config, env = process.env) {
+/**
+ * Whether a legacy bot moves to the HQ Fleet Runtime at this start.
+ *
+ * A Claude bot on the owner's login moves as is: the runtime reads the same
+ * Claude Code login. A Codex or Grok bot moves when its provider sign-in can
+ * be imported here without a browser (`probe`); otherwise it waits for
+ * `hq bot auth`. A Claude bot with its own Claude account stays: HQ Fleet
+ * Local answers with the owner's Claude Code login only, so that account
+ * cannot come along.
+ */
+export function legacyConversionDecision(config, env, probe) {
     if (config.engine?.id === HQ_FLEET_RUNTIME_ENGINE_ID)
-        return { convert: false, reason: "already-fleet" };
+        return { convert: false, reason: "already-fleet", detail: "it already runs on the HQ Fleet Runtime" };
     if (env[KEEP_LEGACY_RUNTIME_ENV] === "1")
-        return { convert: false, reason: "kept-by-env" };
-    if (config.runtime !== "claude")
-        return { convert: false, reason: "needs-sign-in" };
-    if (config.runtimeAuth?.claude)
-        return { convert: false, reason: "own-claude-account" };
-    return { convert: true };
+        return { convert: false, reason: "kept-by-env", detail: `${KEEP_LEGACY_RUNTIME_ENV}=1 keeps it on its legacy runner` };
+    if (config.runtime === "claude") {
+        if (config.runtimeAuth?.claude !== undefined) {
+            return { convert: false, reason: "own-claude-account", detail: "it uses its own Claude account, which HQ Fleet Local cannot carry over" };
+        }
+        return { convert: true };
+    }
+    const runtime = config.runtime === "grok" ? "grok" : "codex";
+    const login = probe(runtime);
+    if (!login.readable)
+        return { convert: false, reason: "needs-sign-in", detail: login.detail };
+    return { convert: true, signIn: { runtime, ...(login.env ? { env: login.env } : {}) } };
+}
+/** The `--provider` value `hq bot auth` takes for a runtime. */
+export function fleetAuthProviderFlag(runtime) {
+    return runtime === "grok" ? "grok" : runtime === "codex" ? "chatgpt" : "claude";
+}
+/** The one-time owner notice (and the status line) for a bot that stays on its legacy runner. */
+export function legacyHoldNotice(name, runtime, decision) {
+    const tool = runtimeDisplayName(runtime);
+    const auth = `hq bot auth ${name} --provider ${fleetAuthProviderFlag(runtime)}`;
+    switch (decision.reason) {
+        case "needs-sign-in":
+            return {
+                cause: `${name} still runs on its older ${tool} runner, so it cannot report problems to HQ or get runtime fixes: its ${tool} sign-in is not readable on this computer (${decision.detail}).`,
+                fix: `Sign in to ${tool} with: ${auth}. ${name} then moves to the HQ Fleet Runtime.`,
+            };
+        case "own-claude-account":
+            return {
+                cause: `${name} still runs on its older Claude Code runner with its own Claude account, which HQ Fleet Local cannot carry over (it answers with your Claude Code login).`,
+                fix: `To move ${name} onto your Claude Code login, run: ${auth}.`,
+            };
+        case "kept-by-env":
+            return {
+                cause: `${name} stays on its older ${tool} runner because ${KEEP_LEGACY_RUNTIME_ENV}=1 is set.`,
+                fix: `Unset ${KEEP_LEGACY_RUNTIME_ENV} and start it again: hq bot start ${name}.`,
+            };
+        case "already-fleet":
+            return { cause: `${name} already runs on the HQ Fleet Runtime.`, fix: "" };
+    }
+}
+/** Reasons the owner is told about once; the others are the owner's own choice or no hold at all. */
+export function legacyHoldNotifiesOwner(reason) {
+    return reason === "needs-sign-in" || reason === "own-claude-account";
 }
 /** How long a legacy runner's own start skips the move after one failed. */
 export const FLEET_MOVE_RETRY_MS = 60 * 60 * 1000;
 export function fleetMoveFailurePath(dir) {
     return path.join(dir, "fleet-move-failed.json");
 }
-export function writeFleetMoveFailure(dir, now = new Date()) {
+export function writeFleetMoveFailure(dir, now = new Date(), failure = {}) {
     try {
-        fs.writeFileSync(fleetMoveFailurePath(dir), JSON.stringify({ at: now.toISOString() }) + "\n", { mode: 0o600 });
+        fs.writeFileSync(fleetMoveFailurePath(dir), JSON.stringify({ at: now.toISOString(), ...failure }) + "\n", { mode: 0o600 });
     }
     catch {
         /* the next start just tries again */
     }
 }
-export function fleetMoveRecentlyFailed(dir, now = Date.now()) {
+export function readFleetMoveFailure(dir) {
     try {
-        const at = Date.parse(JSON.parse(fs.readFileSync(fleetMoveFailurePath(dir), "utf8")).at ?? "");
-        return Number.isFinite(at) && now - at < FLEET_MOVE_RETRY_MS;
+        const raw = JSON.parse(fs.readFileSync(fleetMoveFailurePath(dir), "utf8"));
+        if (typeof raw.at !== "string" || !Number.isFinite(Date.parse(raw.at)))
+            return null;
+        return {
+            at: raw.at,
+            ...(typeof raw.step === "string" ? { step: raw.step } : {}),
+            ...(typeof raw.error === "string" ? { error: raw.error } : {}),
+        };
     }
     catch {
+        return null;
+    }
+}
+export function fleetMoveRecentlyFailed(dir, now = Date.now()) {
+    const failure = readFleetMoveFailure(dir);
+    if (!failure)
         return false;
+    const at = Date.parse(failure.at);
+    return Number.isFinite(at) && now - at < FLEET_MOVE_RETRY_MS;
+}
+export function fleetMoveHoldPath(dir) {
+    return path.join(dir, "fleet-move-hold.json");
+}
+export function readFleetMoveHold(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(fleetMoveHoldPath(dir), "utf8"));
+        if (typeof raw.reason !== "string" || typeof raw.at !== "string")
+            return null;
+        return {
+            reason: raw.reason,
+            detail: typeof raw.detail === "string" ? raw.detail : "",
+            at: raw.at,
+            ...(typeof raw.notifiedAt === "string" ? { notifiedAt: raw.notifiedAt } : {}),
+            ...(typeof raw.notifiedReason === "string" ? { notifiedReason: raw.notifiedReason } : {}),
+            ...(typeof raw.reportId === "string" ? { reportId: raw.reportId } : {}),
+            ...(typeof raw.reportedReason === "string" ? { reportedReason: raw.reportedReason } : {}),
+        };
     }
+    catch {
+        return null;
+    }
+}
+export function writeFleetMoveHold(dir, hold) {
+    try {
+        fs.writeFileSync(fleetMoveHoldPath(dir), JSON.stringify(hold) + "\n", { mode: 0o600 });
+    }
+    catch {
+        /* status then shows the live decision without the record */
+    }
+}
+export function clearFleetMoveRecords(dir) {
+    fs.rmSync(fleetMoveFailurePath(dir), { force: true });
+    fs.rmSync(fleetMoveHoldPath(dir), { force: true });
+}
+/** True when the owner has not yet been told about this reason. */
+export function ownerHoldNoticeDue(hold, reason) {
+    return hold?.notifiedReason !== reason;
+}
+/** True when no HQ failure report has been filed for this reason yet. */
+export function holdReportDue(hold, reason) {
+    return hold?.reportedReason !== reason;
+}
+/**
+ * The failure report a held legacy bot files with HQ, in the shape the HQ
+ * Fleet Runtime's HQ DM adapter uploads for a failed turn (`build_upload`),
+ * so stuck legacy bots show up next to failing Fleet bots. No credential
+ * value is ever part of it.
+ */
+export function legacyHoldFailureReport(input) {
+    return {
+        reportId: input.reportId,
+        createdAt: input.createdAt,
+        agentUid: input.config.agentUid,
+        ownerUid: input.config.ownerUid,
+        botName: input.name,
+        machine: input.machine,
+        failureClass: "auth",
+        site: "legacy-fleet-move",
+        provider: input.config.runtime,
+        model: input.config.model ?? null,
+        platform: "hq-cli-legacy-runner",
+        conversationKey: null,
+        detail: `${input.decision.reason}: ${input.decision.detail}`,
+        leakLabels: [],
+        credentialSources: [],
+        runtimeVersion: "",
+        distributionVersion: "",
+        hqCliVersion: input.hqCliVersion,
+        os: input.os,
+        pythonVersion: "",
+        errorsLogPath: input.logPath,
+        errorsLogTail: "",
+        ownerNotice: { cause: input.notice.cause, fix: input.notice.fix },
+    };
+}
+export function legacyMoveState(dir, config, probe, env = process.env) {
+    const decision = legacyConversionDecision(config, env, probe);
+    return {
+        decision,
+        notice: decision.convert ? null : legacyHoldNotice(config.name, config.runtime, decision),
+        lastFailure: readFleetMoveFailure(dir),
+        hold: readFleetMoveHold(dir),
+    };
 }
 //# sourceMappingURL=legacy-convert.js.map

package/dist/lib/bot/legacy-provider-login.d.ts

@@ -0,0 +1,34 @@
+import type { BotConfig } from "./config.js";
+import { type FleetLocalProviderAuthStatus } from "./fleet-local.js";
+import type { LegacyProviderLogin, LegacyProviderLoginProbe } from "./legacy-convert.js";
+export declare function codexCliAuthPath(home: string): string;
+/** The `exp` claim of a JWT, in seconds, or null when the token has none that reads. */
+export declare function jwtExpiry(token: string): number | null;
+/** Mirrors the runtime's `_import_codex_cli_tokens`: a refreshable, unexpired login in `<home>/auth.json`. */
+export declare function codexCliLoginReadable(home: string, now?: number): LegacyProviderLogin;
+/**
+ * Where a legacy bot's Codex login lives: its own folder, a capacity account,
+ * or the owner's (CODEX_HOME, else ~/.codex). `env` is set when the import
+ * must look somewhere other than the owner's default.
+ */
+export declare function legacyCodexHome(dir: string, config: Pick<BotConfig, "name" | "runtime" | "runtimeAuth" | "hqRoot">, env?: NodeJS.ProcessEnv, homedir?: string): {
+    home: string;
+    env?: Record<string, string>;
+} | {
+    error: string;
+};
+export interface GrokLoginProbeDeps {
+    profiles?: () => Array<{
+        agentUid: string;
+        profileDir: string;
+    }>;
+    status?: (agentUid: string) => FleetLocalProviderAuthStatus | null;
+}
+/** The helper asks the keychain per profile, so one list of bots shares a scan this long. */
+export declare const GROK_HOLDER_SCAN_TTL_MS = 30000;
+export declare function resetGrokHolderScan(): void;
+/** Mirrors the helper's `_existing_machine_oauth`: another Fleet bot here holds a Grok OAuth login. */
+export declare function grokLoginReadableHere(exclude: string, deps?: GrokLoginProbeDeps, now?: number): LegacyProviderLogin;
+/** The live probe for a bot: Codex from its login home, Grok from the other Fleet bots here. */
+export declare function legacyProviderLoginProbe(dir: string, config: Pick<BotConfig, "name" | "agentUid" | "runtime" | "runtimeAuth" | "hqRoot">): LegacyProviderLoginProbe;
+//# sourceMappingURL=legacy-provider-login.d.ts.map