@indigoai-us/hq-cli 5.134.0 → 5.136.0

package/dist/commands/lanes.js

@@ -1,8 +1,9 @@
 /**
  * `hq lanes` — worker lane management and decision queue (spec §5–§7, §10–§11).
  *
- * Every command prints JSON on stdout and takes no interactive input, except
+ * Existing commands print JSON on stdout and take no interactive input, except
  * `accounts login`, which hands the terminal to the vendor's own sign-in.
+ * `watch` and the monitor reminder are the line-oriented text surfaces.
  */
 import { spawn, spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
@@ -17,7 +18,7 @@ import { vaultApiFetch } from "../utils/vault-api.js";
 import { openMeshTransport } from "../lib/mesh/client.js";
 import { createLaneMesh, emitLaneDecisionEvents, } from "../lib/lanes/mesh-events.js";
 import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
-import { AccountResolutionError, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, LANE_STATES, PROVIDER_HOME_ENV, QUESTION_STATUSES, SENIOR_KINDS, accountMaxRunning, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installDrainHook, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, listAccountStatuses, listLaneIds, listQuestionIds, listSessionLiveness, loadLanesConfig, MAX_LANE_DEPTH, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneState, parseLivenessState, parseQuestionStatus, parseSeniorKind, readDaemonPresenceConnected, readLane, retryUpdateLane, readQuestion, resolveAccount, resolveLaneWorker, isLoggedOut, runReconcilePass, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, writeLanesConfig, appendDropboxMessage, answerDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsDropboxDelivery, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasRecordedSessionId, providerSupportsSessionResume, laneIdForAnswerDelivery, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, writeQuestionBody, } from "../lib/lanes/index.js";
+import { AccountResolutionError, coveredLaneIds, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, LANE_STATES, PROVIDER_HOME_ENV, QUESTION_STATUSES, SENIOR_KINDS, accountMaxRunning, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installDrainHook, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, listAccountStatuses, listLaneIds, listQuestionIds, listSessionLiveness, loadLanesConfig, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, MONITOR_ENGINES, MONITOR_MAX_TIMEOUT_MS, MONITOR_UNCOVERED_EXIT_CODE, MAX_WATCHED_LANES, monitorReminderText, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneState, parseLivenessState, parseQuestionStatus, parseSeniorKind, readDaemonPresenceConnected, readLane, retryUpdateLane, readQuestion, resolveAccount, resolveLaneWorker, isLoggedOut, runReconcilePass, runLaneWatch, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, writeLanesConfig, appendDropboxMessage, answerDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsDropboxDelivery, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasRecordedSessionId, providerSupportsSessionResume, laneIdForAnswerDelivery, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, writeQuestionBody, } from "../lib/lanes/index.js";
 import { questionBodyAbsPath } from "../lib/lanes/questions.js";
 import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
 import { providerCompactAfterMs } from "../lib/lanes/config.js";
@@ -62,6 +63,24 @@ function wrap(action) {
         }
     };
 }
+function failText(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`hq lanes: ${message}\n`);
+    process.exit(MONITOR_ERROR_EXIT_CODE);
+}
+function wrapText(action) {
+    return async (...args) => {
+        let code;
+        try {
+            code = await action(...args);
+        }
+        catch (err) {
+            failText(err);
+        }
+        if (code !== 0)
+            process.exit(code);
+    };
+}
 function collectRepeatable(value, previous = []) {
     return previous.concat(value);
 }
@@ -206,6 +225,12 @@ function resolveDeps(deps = {}) {
         probeProvider: deps.probeProvider ?? defaultProbe,
         runCompaction: deps.runCompaction,
         locateTranscript: deps.locateTranscript,
+        monitorEvidence: deps.monitorEvidence ??
+            ((sessionId) => readLiveMonitorEvidence(sessionId, {
+                homedir: () => deps.homedir?.() ?? os.homedir(),
+                env,
+                now: deps.now ?? (() => new Date()),
+            })),
         stageOutpostPayload: deps.stageOutpostPayload ?? defaultStageOutpostPayload,
         dispatchOutpostExec: deps.dispatchOutpostExec ?? defaultDispatchOutpostExec,
         fetchText: deps.fetchText ?? defaultFetchText,
@@ -387,6 +412,115 @@ function loadAllLanes(hqRoot) {
 function loadAllQuestions(hqRoot) {
     return listQuestionIds(hqRoot).map((id) => readQuestion(hqRoot, id));
 }
+const MONITOR_ACTIVE_LANE_STATES = new Set([
+    "running",
+    "queued",
+    "awaiting_input",
+    "blocked",
+]);
+function resolveMonitorEngine(requested, env) {
+    const value = requested?.trim().toLowerCase() ||
+        env.HQ_CONDUCT_ENGINE?.trim().toLowerCase() ||
+        "claude";
+    if (!MONITOR_ENGINES.includes(value)) {
+        throw new LanesError("monitor_invalid_engine", `Unknown monitor-check engine ${JSON.stringify(value)}. Accepted: ${MONITOR_ENGINES.join(", ")}`, { accepted: [...MONITOR_ENGINES], value });
+    }
+    return value;
+}
+async function runWatch(ctx, laneIds, opts) {
+    const rawInterval = opts.intervalMs === undefined ? undefined : Number(opts.intervalMs);
+    await runLaneWatch(ctx.hqRoot(), laneIds, {
+        intervalMs: rawInterval,
+        sleep: ctx.sleep,
+        writeLine: (line) => console.log(opts.json ? JSON.stringify({ event: line }) : line),
+        writeError: (line) => process.stderr.write(`${line}\n`),
+    });
+    return 0;
+}
+function monitorCallsForLaneIds(laneIds) {
+    const calls = [];
+    for (let offset = 0; offset < laneIds.length; offset += MAX_WATCHED_LANES) {
+        const chunk = laneIds.slice(offset, offset + MAX_WATCHED_LANES);
+        calls.push({
+            command: `hq lanes watch ${chunk.join(" ")}`,
+            timeout_ms: MONITOR_MAX_TIMEOUT_MS,
+            persistent: true,
+        });
+    }
+    return calls;
+}
+async function runMonitorCheck(ctx, opts) {
+    if (opts.reminder) {
+        console.log(monitorReminderText());
+        return 0;
+    }
+    const sessionId = opts.session?.trim();
+    if (!sessionId) {
+        throw new LanesError("monitor_session_required", "hq lanes monitor-check requires --session <id> unless --reminder is used");
+    }
+    const engine = resolveMonitorEngine(opts.engine, ctx.env);
+    const activeLanes = loadAllLanes(ctx.hqRoot()).filter((lane) => lane.senior.kind === "session" &&
+        lane.senior.id === sessionId &&
+        MONITOR_ACTIVE_LANE_STATES.has(lane.state));
+    if (engine !== "claude") {
+        if (opts.json) {
+            printJson({
+                ok: true,
+                action: "monitor-check",
+                session_id: sessionId,
+                engine,
+                active_lane_ids: activeLanes.map((lane) => lane.lane_id),
+                covered_lane_ids: [],
+                uncovered_lane_ids: [],
+                skipped: "engine_has_no_claude_monitor",
+            });
+        }
+        return 0;
+    }
+    if (activeLanes.length === 0) {
+        if (opts.json) {
+            printJson({
+                ok: true,
+                action: "monitor-check",
+                session_id: sessionId,
+                engine,
+                active_lane_ids: [],
+                covered_lane_ids: [],
+                uncovered_lane_ids: [],
+            });
+        }
+        return 0;
+    }
+    const evidence = await ctx.monitorEvidence(sessionId);
+    if (evidence.sessionId !== sessionId) {
+        throw new LanesError("monitor_evidence_session_mismatch", `Monitor evidence was for ${JSON.stringify(evidence.sessionId)}, expected ${JSON.stringify(sessionId)}`);
+    }
+    const covered = coveredLaneIds(evidence, ctx.now());
+    const activeIds = activeLanes.map((lane) => lane.lane_id);
+    const uncovered = activeIds.filter((laneId) => !covered.has(laneId));
+    const monitorCalls = monitorCallsForLaneIds(uncovered);
+    if (opts.json) {
+        printJson({
+            ok: uncovered.length === 0,
+            action: "monitor-check",
+            session_id: sessionId,
+            engine,
+            active_lane_ids: activeIds,
+            covered_lane_ids: activeIds.filter((laneId) => covered.has(laneId)),
+            uncovered_lane_ids: uncovered,
+            monitor_call: monitorCalls.length === 1 ? monitorCalls[0] : null,
+            monitor_calls: monitorCalls,
+        });
+    }
+    else if (uncovered.length > 0) {
+        for (const laneId of uncovered)
+            console.log(`uncovered lane: ${laneId}`);
+        for (const monitorCall of monitorCalls) {
+            console.log(`Monitor(command=${JSON.stringify(monitorCall.command)}, timeout_ms=${monitorCall.timeout_ms}, persistent=true)`);
+        }
+    }
+    return uncovered.length > 0 ? MONITOR_UNCOVERED_EXIT_CODE : 0;
+}
 function sessionMetaPath(hqRoot, sessionId) {
     return path.join(hqRoot, "workspace", "sessions", sessionId, "meta.yaml");
 }
@@ -3193,6 +3327,20 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (opts) => {
         await runList(ctx, opts);
     }));
+    lanes
+        .command("watch")
+        .description("Watch lane state and question changes until all lanes are terminal")
+        .argument("<lane-id...>", "Lane ids to watch")
+        .option("--interval-ms <ms>", "Polling interval, bounded to 100ms–30s", "5000")
+        .action(wrapText(async (laneIds, opts) => runWatch(ctx, laneIds, opts)));
+    lanes
+        .command("monitor-check")
+        .description("Check that active Claude senior lanes have live Monitor watch tasks")
+        .option("--session <id>", "Senior session id")
+        .option("--engine <engine>", "claude | codex | grok; defaults to HQ_CONDUCT_ENGINE or claude")
+        .option("--reminder", "Print the senior Monitor reminder text")
+        .option("--json", "JSON on stdout")
+        .action(wrapText(async (opts) => runMonitorCheck(ctx, opts)));
     lanes
         .command("show")
         .description("Show one lane")

package/dist/lib/bot/api.d.ts

@@ -29,6 +29,59 @@ export interface InboxItem {
     mentionedMe?: boolean;
     memberCount?: number;
     senderTrust?: "member";
+    /**
+     * Scheduled-job run items only (channel === "job"). The cloud fires the job
+     * on its own schedule and writes this durable item; the run carries its own
+     * prompt instead of `text` (server: hq-pro-agents jobs/run-record.ts
+     * `JobRunInboxItem`).
+     */
+    jobId?: string;
+    prompt?: string;
+    context?: Record<string, unknown> | string;
+    script?: string;
+    firedAt?: string;
+    staleAfter?: string;
+    requestId?: string;
+}
+/** The terminal outcome a box reports for one fired run. */
+export type JobRunStatus = "succeeded" | "failed" | "skipped-precondition";
+export interface JobRunCompletion {
+    status: JobRunStatus;
+    output?: string;
+    disposition?: string;
+}
+/** A job record as the cloud returns it (hq-pro-agents jobs/schema.ts `JobRecord`). */
+export interface BotJobRecord {
+    jobId: string;
+    prompt: string;
+    status?: string;
+    schedule?: {
+        kind?: string;
+        cron?: string;
+        at?: string;
+        timezone?: string;
+    };
+    context?: Record<string, unknown>;
+    script?: string;
+    createdAt?: string;
+    nextRunAt?: string;
+    lastRunAt?: string;
+    lastStatus?: string;
+    runCount?: number;
+}
+export interface CreateJobInput {
+    prompt: string;
+    context?: Record<string, unknown>;
+    script?: string;
+    schedule: {
+        kind: "once";
+        at: string;
+        timezone: string;
+    } | {
+        kind: "recurring";
+        cron: string;
+        timezone: string;
+    };
 }
 /** @deprecated use InboxItem */
 export type DmInboxItem = InboxItem;
@@ -132,6 +185,19 @@ export declare class BotApi {
     pullInbox(agentUid: string): Promise<InboxItem[]>;
     /** POST /v1/agents/{uid}/inbox/{messageId}/ack */
     ackInbox(agentUid: string, messageId: string): Promise<void>;
+    /**
+     * POST /v1/agents/{uid}/jobs/{jobId}/runs/{messageId}/complete — report one
+     * fired run as finished. MANDATORY: nothing else clears the job's
+     * in-progress flag, so a run that is never reported makes every later fire
+     * of that job `skipped-overlap` for up to an hour.
+     */
+    completeJobRun(agentUid: string, jobId: string, messageId: string, completion: JobRunCompletion): Promise<void>;
+    /** GET /v1/agents/{uid}/jobs — the bot's own scheduled jobs (self-only). */
+    listJobs(agentUid: string): Promise<BotJobRecord[]>;
+    /** POST /v1/agents/{uid}/jobs — schedule a new job for the bot itself. */
+    createJob(agentUid: string, input: CreateJobInput): Promise<BotJobRecord>;
+    /** POST /v1/agents/{uid}/jobs/{jobId}/cancel — cancel and delete its schedule. */
+    cancelJob(agentUid: string, jobId: string): Promise<void>;
     /** POST /v1/notify/dm — send as the bot (agent identity). */
     sendDm(input: {
         toPersonUid: string;

package/dist/lib/bot/api.js

@@ -101,6 +101,44 @@ export class BotApi {
     async ackInbox(agentUid, messageId) {
         await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/inbox/${encodeURIComponent(messageId)}/ack`, { method: "POST", body: {} });
     }
+    /**
+     * POST /v1/agents/{uid}/jobs/{jobId}/runs/{messageId}/complete — report one
+     * fired run as finished. MANDATORY: nothing else clears the job's
+     * in-progress flag, so a run that is never reported makes every later fire
+     * of that job `skipped-overlap` for up to an hour.
+     */
+    async completeJobRun(agentUid, jobId, messageId, completion) {
+        await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/runs/${encodeURIComponent(messageId)}/complete`, {
+            method: "POST",
+            body: {
+                status: completion.status,
+                ...(completion.output !== undefined ? { output: completion.output } : {}),
+                ...(completion.disposition !== undefined ? { disposition: completion.disposition } : {}),
+            },
+        }, [200, 201, 202, 204]);
+    }
+    /** GET /v1/agents/{uid}/jobs — the bot's own scheduled jobs (self-only). */
+    async listJobs(agentUid) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/jobs`);
+        return body.jobs ?? [];
+    }
+    /** POST /v1/agents/{uid}/jobs — schedule a new job for the bot itself. */
+    async createJob(agentUid, input) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/jobs`, {
+            method: "POST",
+            body: {
+                prompt: input.prompt,
+                ...(input.context ? { context: input.context } : {}),
+                ...(input.script ? { script: input.script } : {}),
+                schedule: input.schedule,
+            },
+        });
+        return body.job;
+    }
+    /** POST /v1/agents/{uid}/jobs/{jobId}/cancel — cancel and delete its schedule. */
+    async cancelJob(agentUid, jobId) {
+        await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/cancel`, { method: "POST", body: {} }, [200, 201, 202, 204]);
+    }
     /** POST /v1/notify/dm — send as the bot (agent identity). */
     async sendDm(input) {
         const payload = { toPersonUid: input.toPersonUid, body: input.body };

package/dist/lib/bot/index.d.ts

@@ -17,4 +17,7 @@ export * from "./local-config.js";
 export * from "./self-heal.js";
 export * from "./runnable.js";
 export * from "./local-name.js";
+export * from "./job-run.js";
+export * from "./job-completions.js";
+export * from "./inflight.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/bot/index.js

@@ -17,4 +17,7 @@ export * from "./local-config.js";
 export * from "./self-heal.js";
 export * from "./runnable.js";
 export * from "./local-name.js";
+export * from "./job-run.js";
+export * from "./job-completions.js";
+export * from "./inflight.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/bot/inflight.d.ts

@@ -26,6 +26,48 @@ export interface InflightTurn {
         kind: "room";
         channelId: string;
     };
+    /**
+     * Scheduled-job runs: the job this message is a run of, so a turn cut off by
+     * a restart is still reported to the cloud (which is the only thing that
+     * clears the job's in-progress flag).
+     */
+    jobId?: string;
+    /**
+     * Set as soon as this run's outcome has been REPORTED to the cloud (accepted,
+     * or durably queued for retry). A recovery pass must not report it again: the
+     * server's complete is last-write-wins, so a second "failed" would overwrite
+     * a recorded "succeeded" after a crash between reporting and acking.
+     */
+    jobCompleted?: "succeeded" | "failed" | "skipped-precondition";
+    /**
+     * The "scheduled job" header this run's FIRST message carries, so a report
+     * posted by the recovery path still reads as a scheduled run rather than an
+     * unsolicited DM.
+     */
+    jobHeader?: string;
+    /**
+     * The bot a scheduled run's marker belongs to. `hq bot adopt` can place a
+     * DIFFERENT bot into a folder that survived (bot.json gone, the rest left);
+     * recovery drops a job marker stamped with another agent instead of posting
+     * its report into this bot's DM and completing it under this identity.
+     * Absent on markers written before it was recorded: those behave as before.
+     */
+    agentUid?: string;
+    /**
+     * The run's own report, as it is recorded with the cloud, kept apart from the
+     * body saved for resending (which may carry the header or earlier progress).
+     */
+    jobOutput?: string;
+    /**
+     * Why a started scheduled run did not finish (the runtime's error, or the
+     * owner stopping it), saved BEFORE the "did not finish" post is attempted. If
+     * that post fails, recovery reports and tells the owner THIS reason rather
+     * than claiming the bot was restarted.
+     */
+    jobFailure?: {
+        reason: string;
+        excerpt?: string;
+    };
     rootEventId?: string;
     /** DM message carrying the thinking reaction, so a restart can clear it. */
     reactionEventId?: string;

package/dist/lib/bot/job-completions.d.ts

@@ -0,0 +1,91 @@
+/**
+ * job-completions.json — run completions the cloud has not accepted yet.
+ *
+ * Reporting a finished run is MANDATORY: nothing else clears the job's
+ * in-progress flag, and until it is cleared every later fire of that job is
+ * skipped as an overlap for up to an hour. So when the completion call fails
+ * (the network was down, the token was stale), the bot logs it loudly, still
+ * acks the inbox item — the work is done and must never run twice — and keeps
+ * the completion here to retry.
+ *
+ * A retry only re-sends a small report; it never re-runs the work.
+ *
+ * Retries are spaced by EXPONENTIAL BACKOFF and given up on by WALL-CLOCK AGE,
+ * not by a count of attempts. The inbox polls every 2 seconds, so a fixed
+ * ten-attempt budget was spent in about twenty seconds — an ordinary sixty-
+ * second network drop permanently lost the completion and wedged that job for
+ * the rest of the server's in-progress hour. Giving up is pegged to that same
+ * hour, after which the cloud releases the slot by itself anyway.
+ *
+ * ── After a reinstall: restore, adopt, repair (decision, 2026-09-16) ─────────
+ *
+ * This file lives in the bot's own folder (~/.hq/bots/<name>/), which is never
+ * synced. What `hq bot restore` / `hq bot adopt` do to it decides what happens
+ * to a completion owed by a run on the OLD machine:
+ *
+ * - REPAIR (the folder is still here; only the credentials are re-issued): the
+ *   file survives and its completions are still reported, with the new
+ *   credentials. That is correct — it is the same agent, and the complete route
+ *   authorizes by agent identity, not by machine.
+ * - ADOPT onto a fresh machine: there is no file, so nothing is reported from
+ *   here. That is not a lost report: the old machine ACKED the run before it
+ *   queued the completion (the work must never run twice), so the cloud will
+ *   not redeliver it, and the job's in-progress slot is released by the cloud
+ *   itself within the hour. Not duplicated, and not jammed for longer than the
+ *   outage already cost.
+ * - ADOPT into a folder that SURVIVED (bot.json gone, the rest left behind):
+ *   completions stamped with THIS bot's agentUid are reported as normal. A
+ *   completion stamped with a DIFFERENT agentUid — a same-named bot that was
+ *   deleted and re-created — is dropped, never sent: it belongs to another
+ *   identity, and reporting it against this one would be a cross-identity
+ *   write that can only fail or, worse, land on the wrong run.
+ *
+ * Per-job model SESSIONS (session-job-<jobId>.json) need no such care: a job
+ * that finds no session simply starts a fresh one, and a scheduled run carries
+ * everything it needs in its own prompt.
+ */
+import type { JobRunStatus } from "./api.js";
+export declare const BOT_JOB_COMPLETIONS_NAME = "job-completions.json";
+/** First retry gap; each failure doubles it. */
+export declare const COMPLETION_RETRY_BASE_MS = 2000;
+/** Never wait longer than this between retries. */
+export declare const COMPLETION_RETRY_MAX_MS: number;
+/**
+ * Stop retrying a completion older than this. Matches the server's
+ * DEFAULT_JOBS_MAX_IN_PROGRESS_SECONDS: past it the cloud reclaims the job's
+ * in-progress slot on its own, so a later report changes nothing.
+ */
+export declare const MAX_COMPLETION_AGE_MS: number;
+export interface PendingJobCompletion {
+    v: 1;
+    /**
+     * The agent that owes this report. Checked before every retry so a folder
+     * that outlived its bot never reports under a different identity. Absent on
+     * entries written before it was recorded; those are treated as this bot's.
+     */
+    agentUid?: string;
+    jobId: string;
+    /** The inbox item id — the run id in the completion route. */
+    messageId: string;
+    status: JobRunStatus;
+    output?: string;
+    disposition?: string;
+    firstFailedAt: string;
+    attempts: number;
+    /** Epoch ms before which this must not be retried (exponential backoff). */
+    nextAttemptAt: number;
+}
+export declare function botJobCompletionsPath(dir: string): string;
+export declare function readPendingJobCompletions(dir: string): PendingJobCompletion[];
+/** The gap before attempt N (1-based), doubling and capped. */
+export declare function completionRetryDelayMs(attempts: number): number;
+/** True when this entry is due for another attempt. */
+export declare function isCompletionDue(entry: PendingJobCompletion, nowMs: number): boolean;
+/** True when this entry was owed by a different bot identity than `agentUid`. */
+export declare function isCompletionForOtherAgent(entry: PendingJobCompletion, agentUid: string): boolean;
+/** True when the cloud has already reclaimed the slot; retrying changes nothing. */
+export declare function isCompletionExpired(entry: PendingJobCompletion, nowMs: number): boolean;
+/** Record (or back off) a completion the cloud has not taken. */
+export declare function recordPendingJobCompletion(dir: string, entry: Omit<PendingJobCompletion, "v" | "firstFailedAt" | "attempts" | "nextAttemptAt">, now: Date): PendingJobCompletion;
+export declare function clearPendingJobCompletion(dir: string, messageId: string): void;
+//# sourceMappingURL=job-completions.d.ts.map

package/dist/lib/bot/job-completions.js

@@ -0,0 +1,132 @@
+/**
+ * job-completions.json — run completions the cloud has not accepted yet.
+ *
+ * Reporting a finished run is MANDATORY: nothing else clears the job's
+ * in-progress flag, and until it is cleared every later fire of that job is
+ * skipped as an overlap for up to an hour. So when the completion call fails
+ * (the network was down, the token was stale), the bot logs it loudly, still
+ * acks the inbox item — the work is done and must never run twice — and keeps
+ * the completion here to retry.
+ *
+ * A retry only re-sends a small report; it never re-runs the work.
+ *
+ * Retries are spaced by EXPONENTIAL BACKOFF and given up on by WALL-CLOCK AGE,
+ * not by a count of attempts. The inbox polls every 2 seconds, so a fixed
+ * ten-attempt budget was spent in about twenty seconds — an ordinary sixty-
+ * second network drop permanently lost the completion and wedged that job for
+ * the rest of the server's in-progress hour. Giving up is pegged to that same
+ * hour, after which the cloud releases the slot by itself anyway.
+ *
+ * ── After a reinstall: restore, adopt, repair (decision, 2026-09-16) ─────────
+ *
+ * This file lives in the bot's own folder (~/.hq/bots/<name>/), which is never
+ * synced. What `hq bot restore` / `hq bot adopt` do to it decides what happens
+ * to a completion owed by a run on the OLD machine:
+ *
+ * - REPAIR (the folder is still here; only the credentials are re-issued): the
+ *   file survives and its completions are still reported, with the new
+ *   credentials. That is correct — it is the same agent, and the complete route
+ *   authorizes by agent identity, not by machine.
+ * - ADOPT onto a fresh machine: there is no file, so nothing is reported from
+ *   here. That is not a lost report: the old machine ACKED the run before it
+ *   queued the completion (the work must never run twice), so the cloud will
+ *   not redeliver it, and the job's in-progress slot is released by the cloud
+ *   itself within the hour. Not duplicated, and not jammed for longer than the
+ *   outage already cost.
+ * - ADOPT into a folder that SURVIVED (bot.json gone, the rest left behind):
+ *   completions stamped with THIS bot's agentUid are reported as normal. A
+ *   completion stamped with a DIFFERENT agentUid — a same-named bot that was
+ *   deleted and re-created — is dropped, never sent: it belongs to another
+ *   identity, and reporting it against this one would be a cross-identity
+ *   write that can only fail or, worse, land on the wrong run.
+ *
+ * Per-job model SESSIONS (session-job-<jobId>.json) need no such care: a job
+ * that finds no session simply starts a fresh one, and a scheduled run carries
+ * everything it needs in its own prompt.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const BOT_JOB_COMPLETIONS_NAME = "job-completions.json";
+/** First retry gap; each failure doubles it. */
+export const COMPLETION_RETRY_BASE_MS = 2_000;
+/** Never wait longer than this between retries. */
+export const COMPLETION_RETRY_MAX_MS = 5 * 60_000;
+/**
+ * Stop retrying a completion older than this. Matches the server's
+ * DEFAULT_JOBS_MAX_IN_PROGRESS_SECONDS: past it the cloud reclaims the job's
+ * in-progress slot on its own, so a later report changes nothing.
+ */
+export const MAX_COMPLETION_AGE_MS = 60 * 60_000;
+export function botJobCompletionsPath(dir) {
+    return path.join(dir, BOT_JOB_COMPLETIONS_NAME);
+}
+function isPending(raw) {
+    const c = raw;
+    return c?.v === 1 && typeof c.jobId === "string" && typeof c.messageId === "string" && typeof c.status === "string";
+}
+export function readPendingJobCompletions(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(botJobCompletionsPath(dir), "utf8"));
+        if (raw?.v !== 1 || !Array.isArray(raw.completions))
+            return [];
+        return raw.completions.filter(isPending);
+    }
+    catch {
+        return [];
+    }
+}
+/** The gap before attempt N (1-based), doubling and capped. */
+export function completionRetryDelayMs(attempts) {
+    const exponent = Math.max(0, attempts - 1);
+    // Bound the shift so a long-lived entry cannot overflow into Infinity.
+    const raw = COMPLETION_RETRY_BASE_MS * 2 ** Math.min(exponent, 20);
+    return Math.min(COMPLETION_RETRY_MAX_MS, raw);
+}
+/** True when this entry is due for another attempt. */
+export function isCompletionDue(entry, nowMs) {
+    return nowMs >= (entry.nextAttemptAt ?? 0);
+}
+/** True when this entry was owed by a different bot identity than `agentUid`. */
+export function isCompletionForOtherAgent(entry, agentUid) {
+    return typeof entry.agentUid === "string" && entry.agentUid !== "" && entry.agentUid !== agentUid;
+}
+/** True when the cloud has already reclaimed the slot; retrying changes nothing. */
+export function isCompletionExpired(entry, nowMs) {
+    const first = new Date(entry.firstFailedAt).getTime();
+    if (Number.isNaN(first))
+        return false;
+    return nowMs - first >= MAX_COMPLETION_AGE_MS;
+}
+function write(dir, completions) {
+    if (completions.length === 0) {
+        fs.rmSync(botJobCompletionsPath(dir), { force: true });
+        return;
+    }
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `.job-completions.tmp.${process.pid}.${Date.now()}`);
+    const file = { v: 1, completions };
+    fs.writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, botJobCompletionsPath(dir));
+}
+/** Record (or back off) a completion the cloud has not taken. */
+export function recordPendingJobCompletion(dir, entry, now) {
+    const rest = readPendingJobCompletions(dir);
+    const existing = rest.find((c) => c.messageId === entry.messageId);
+    const attempts = (existing?.attempts ?? 0) + 1;
+    const next = {
+        v: 1,
+        ...entry,
+        firstFailedAt: existing?.firstFailedAt ?? now.toISOString(),
+        attempts,
+        nextAttemptAt: now.getTime() + completionRetryDelayMs(attempts),
+    };
+    write(dir, [...rest.filter((c) => c.messageId !== entry.messageId), next]);
+    return next;
+}
+export function clearPendingJobCompletion(dir, messageId) {
+    const rest = readPendingJobCompletions(dir);
+    const kept = rest.filter((c) => c.messageId !== messageId);
+    if (kept.length !== rest.length)
+        write(dir, kept);
+}
+//# sourceMappingURL=job-completions.js.map