@indigoai-us/hq-cli 5.161.0 → 5.163.0

package/dist/lib/daemon/updater.js

@@ -0,0 +1,103 @@
+/**
+ * One run of the `updater` service (`hq daemon service self-update`), which
+ * replaces the boxes' `hq-cli-update.timer` and `*-codex-update.timer`:
+ *
+ * 1. Update the hq CLI through the shared self-update path (same install
+ *    routing, lock and convergence check as every other CLI update).
+ * 2. Update Codex when it is installed as a global npm package and behind.
+ * 3. After a CLI update, ask the daemon to restart itself so the supervisor and
+ *    every service run the new version.
+ */
+import { spawnSync } from "node:child_process";
+import semver from "semver";
+export const CODEX_PACKAGE = "@openai/codex";
+export async function runDaemonUpdater(deps) {
+    let ok = true;
+    const cli = await deps.updateCli();
+    // The restart stops this process too, so it is requested only once all the
+    // updater's work (including a global npm install of Codex) is done.
+    let restart = false;
+    switch (cli.action) {
+        case "updated":
+            deps.log(`hq CLI updated to ${cli.latest ?? "the latest version"}; the daemon restarts onto it once Codex is checked`);
+            restart = true;
+            break;
+        case "update-failed":
+        case "update-ineffective":
+            deps.log(`hq CLI update to ${cli.latest ?? "latest"} did not take effect (${cli.action})`);
+            ok = false;
+            break;
+        default:
+            deps.log(`hq CLI: ${cli.action === "current" ? "up to date" : cli.action}`);
+    }
+    if (!updateCodex(deps))
+        ok = false;
+    if (restart)
+        deps.requestDaemonRestart();
+    return { ok };
+}
+/** Update Codex when it is a global npm install and behind; false when that update failed. */
+function updateCodex(deps) {
+    const installed = deps.codex.installedVersion();
+    if (installed === null)
+        return true;
+    const latest = deps.codex.latestVersion();
+    if (latest === null || !semver.valid(installed) || !semver.valid(latest) || !semver.gt(latest, installed)) {
+        deps.log(`Codex ${installed}: nothing to update`);
+        return true;
+    }
+    const result = deps.codex.install();
+    if (result.ok) {
+        deps.log(`Codex updated ${installed} -> ${latest}`);
+        return true;
+    }
+    deps.log(`Codex update ${installed} -> ${latest} failed: ${result.detail ?? "unknown error"}`);
+    return false;
+}
+/**
+ * The variables for the updater's own CLI update. Every supervised service
+ * gets HQ_NO_UPDATE_CHECK=1 so it never updates itself; the updater is the one
+ * process that must, so it drops that opt-out.
+ */
+export function updaterEnv(vars) {
+    const copy = { ...vars };
+    delete copy.HQ_NO_UPDATE_CHECK;
+    return copy;
+}
+function npm(args) {
+    const r = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", args, {
+        encoding: "utf8",
+        timeout: 10 * 60_000,
+        windowsHide: true,
+        shell: process.platform === "win32",
+    });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+/** Codex through the global npm install, the way the boxes install it. */
+export function npmCodexUpdater() {
+    return {
+        installedVersion: () => {
+            const r = npm(["ls", "-g", CODEX_PACKAGE, "--depth=0", "--json"]);
+            try {
+                const parsed = JSON.parse(r.stdout);
+                return parsed.dependencies?.[CODEX_PACKAGE]?.version ?? null;
+            }
+            catch {
+                return null;
+            }
+        },
+        latestVersion: () => {
+            const r = npm(["view", CODEX_PACKAGE, "version"]);
+            const v = r.status === 0 ? r.stdout.trim() : "";
+            return v || null;
+        },
+        install: () => {
+            const r = npm(["install", "-g", `${CODEX_PACKAGE}@latest`]);
+            if (r.status === 0)
+                return { ok: true };
+            const tail = r.stderr.trim().split("\n").slice(-3).join(" ").slice(0, 400);
+            return { ok: false, detail: tail || `npm exited ${r.status ?? "by signal"}` };
+        },
+    };
+}
+//# sourceMappingURL=updater.js.map

package/dist/lib/flag-registry.d.ts

@@ -6,7 +6,7 @@
  * keep a short-lived, offline CLI alive until the client's network deadline.
  */
 import { type WorkerOptions } from "node:worker_threads";
-import { type FlagClient, type FlagLookupOptions } from "@indigoai-us/hq-flags-client";
+import { type FlagClient, type FlagLookupOptions, type FlagSnapshot } from "@indigoai-us/hq-flags-client";
 /** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
 export declare const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
 /** The synchronous capability that command gate call sites need. */
@@ -38,6 +38,12 @@ export declare function kickFlagRegistryReadiness(dependencies?: FlagRegistryDep
 export declare function resolveFlagGate(reader: FlagReader | null | undefined, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
 /** Resolve a process gate against the shared snapshot reader, when configured. */
 export declare function resolveProcessFlagGate(flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
+/**
+ * The registry snapshot held by this process, or null when none has arrived
+ * (no endpoint configured, offline, or still fetching). Callers that must
+ * distinguish "unreachable" from "off" read this instead of a gate.
+ */
+export declare function currentFlagSnapshot(): FlagSnapshot | null;
 /** Test-only reset for process-global readiness state. */
 export declare function _resetFlagRegistryForTests(): void;
 export {};

package/dist/lib/flag-registry.js

@@ -83,6 +83,14 @@ export function resolveFlagGate(reader, flagKey, lookup, legacyFallback) {
 export function resolveProcessFlagGate(flagKey, lookup, legacyFallback) {
     return resolveFlagGate(processReader, flagKey, lookup, legacyFallback);
 }
+/**
+ * The registry snapshot held by this process, or null when none has arrived
+ * (no endpoint configured, offline, or still fetching). Callers that must
+ * distinguish "unreachable" from "off" read this instead of a gate.
+ */
+export function currentFlagSnapshot() {
+    return heldSnapshot;
+}
 /** Test-only reset for process-global readiness state. */
 export function _resetFlagRegistryForTests() {
     heldSnapshot = null;

package/dist/lib/lanes/delivery.d.ts

@@ -57,7 +57,9 @@ export type ResumeCommandState = (typeof RESUME_COMMAND_STATES)[number];
 export declare function isResumeCommandState(state: LaneState): state is ResumeCommandState;
 export declare const LANE_DELIVERY_MECHANISMS: readonly ["dropbox", "resume", "none"];
 export type LaneDeliveryMechanism = (typeof LANE_DELIVERY_MECHANISMS)[number];
-export type DeliveryLane = Pick<LaneRecord, "state" | "provider" | "provider_session_id">;
+export type DeliveryLane = Pick<LaneRecord, "state" | "provider" | "provider_session_id" | "terminal_reason" | "envelope_repair">;
+/** Only the terminal result of a failed automatic envelope repair is recoverable. */
+export declare function isFailedEnvelopeRepairLane(lane: DeliveryLane): boolean;
 /**
  * `dropbox`: a process is (or is about to be) alive to drain the inbox.
  * `resume`: the process has exited, the provider can resume, the state allows
@@ -120,7 +122,7 @@ export type LaunchTrigger = {
     /** `hq lanes resume`: the operator's explicit opt-in to continue an exited lane. */
     kind: "resume";
     /** Lane state at the moment of the command; recorded as `last_resume.resumed_from`. */
-    from: ResumeCommandState;
+    from: ResumeCommandState | "failed";
     text?: string;
     message_id?: string;
 };
@@ -147,5 +149,5 @@ export declare function resumeCommandRefusal(lane: DeliveryLane): {
  */
 export declare function planLaneLaunch(lane: DeliveryLane, trigger: LaunchTrigger): LaunchPlan;
 /** Lane states a launch may claim `running` from, per trigger. */
-export declare function claimableStatesFor(trigger: LaunchTrigger): readonly LaneState[];
+export declare function claimableStatesFor(trigger: LaunchTrigger, lane?: DeliveryLane): readonly LaneState[];
 //# sourceMappingURL=delivery.d.ts.map

package/dist/lib/lanes/delivery.js

@@ -20,7 +20,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { LanesError } from "./errors.js";
-import { parseLaneProvider, } from "./types.js";
+import { parseLaneProvider, ENVELOPE_INVALID_REASON, } from "./types.js";
 /** Which providers can continue an exited worker from a recorded session id. */
 export const PROVIDER_SESSION_RESUME = {
     claude: true,
@@ -67,6 +67,13 @@ export function isResumeCommandState(state) {
     return RESUME_COMMAND_STATES.includes(state);
 }
 export const LANE_DELIVERY_MECHANISMS = ["dropbox", "resume", "none"];
+/** Only the terminal result of a failed automatic envelope repair is recoverable. */
+export function isFailedEnvelopeRepairLane(lane) {
+    return (lane.state === "failed" &&
+        lane.terminal_reason === ENVELOPE_INVALID_REASON &&
+        lane.envelope_repair?.attempted === true &&
+        lane.envelope_repair.succeeded === false);
+}
 /**
  * `dropbox`: a process is (or is about to be) alive to drain the inbox.
  * `resume`: the process has exited, the provider can resume, the state allows
@@ -77,7 +84,7 @@ export function laneDeliveryMechanism(lane) {
     if (lane.state === "queued" || lane.state === "running")
         return "dropbox";
     if (providerSupportsSessionResume(lane.provider) &&
-        isResumableLaneState(lane.state) &&
+        (isResumableLaneState(lane.state) || isFailedEnvelopeRepairLane(lane)) &&
         hasRecordedSessionId(lane)) {
         return "resume";
     }
@@ -275,7 +282,7 @@ export const LAUNCH_TRIGGERS = ["admit", "answered_questions", "message", "resum
  * without a resume path, no recorded session. Null when the resume can go.
  */
 export function resumeCommandRefusal(lane) {
-    if (!isResumeCommandState(lane.state)) {
+    if (!isResumeCommandState(lane.state) && !isFailedEnvelopeRepairLane(lane)) {
         return {
             error: "lane_not_resumable",
             message: `Lane is ${lane.state}. hq lanes resume continues a lane in ${RESUME_COMMAND_STATES.join(", ")}; ${lane.state === "awaiting_input"
@@ -337,16 +344,17 @@ export function planLaneLaunch(lane, trigger) {
     }
 }
 /** Lane states a launch may claim `running` from, per trigger. */
-export function claimableStatesFor(trigger) {
+export function claimableStatesFor(trigger, lane) {
+    const envelopeRepairFailed = lane !== undefined && isFailedEnvelopeRepairLane(lane) && hasRecordedSessionId(lane);
     switch (trigger.kind) {
         case "admit":
             return ["queued"];
         case "answered_questions":
             return ["awaiting_input"];
         case "message":
-            return RESUMABLE_LANE_STATES;
+            return envelopeRepairFailed ? [...RESUMABLE_LANE_STATES, "failed"] : RESUMABLE_LANE_STATES;
         case "resume":
-            return RESUME_COMMAND_STATES;
+            return envelopeRepairFailed ? [...RESUME_COMMAND_STATES, "failed"] : RESUME_COMMAND_STATES;
         default: {
             const _exhaustive = trigger;
             return _exhaustive;

package/dist/lib/lanes/spawn.d.ts

@@ -192,6 +192,11 @@ export declare function resumePrompt(input: {
     answers?: AnsweredQuestionLine[];
     /** `hq lanes resume`: the state the operator resumed the lane from. */
     resumedFrom?: string;
+    /** Exact validator errors recorded after the prior envelope repair failed. */
+    envelopeRepairErrors?: {
+        first_error: string;
+        second_error?: string;
+    };
 }): string;
 /** Spec §4: the one repair turn. Schema, parser error, raw text, JSON only. */
 export declare function envelopeRepairPrompt(input: {

package/dist/lib/lanes/spawn.js

@@ -26,7 +26,7 @@ import { copySessionFiles, planSessionCopy } from "./move-account.js";
 import { ensureSessionHome } from "./session-relink.js";
 import { hasEarlierEligibleQueuedLane, laneAdmissionCapReason, withLaneAdmissionLock, } from "./admission.js";
 import { resolveAdmissionHost } from "./admission-host.js";
-import { LANE_ENVELOPE_JSON_SCHEMA, parseLaneProvider, } from "./types.js";
+import { LANE_ENVELOPE_JSON_SCHEMA, ENVELOPE_INVALID_REASON, parseLaneProvider, } from "./types.js";
 export const LANES_RUNS_REL = path.join("workspace", "lanes-runs");
 /** Written by reconcile before a resume spawn; the worker prompt names this path. */
 export const ANSWERED_QUESTIONS_FILE = "answered-questions.json";
@@ -996,6 +996,16 @@ export function resumePrompt(input) {
             ...(lines.length > 0 ? ["Answers:", ...lines] : []),
         ].join("\n"));
     }
+    if (input.envelopeRepairErrors !== undefined) {
+        const errors = [input.envelopeRepairErrors.first_error, input.envelopeRepairErrors.second_error]
+            .filter((error) => typeof error === "string" && error.length > 0);
+        parts.push([
+            `The previous envelope repair failed validation. The next envelope slot is ${input.envelopePath}; write a new valid envelope there.`,
+            "Exact validation errors recorded in envelope_repair:",
+            ...errors.map((error, index) => `- envelope_repair.${index === 0 ? "first_error" : "second_error"}: ${JSON.stringify(error)}`),
+            "For an ask question, include non-empty id, question, and context fields.",
+        ].join("\n"));
+    }
     // Every resume turn carries the authorization, including a textless
     // `hq lanes resume`: a pre-upgrade session's brief never had the paragraph.
     if (input.operatorMessage !== undefined ||
@@ -1028,6 +1038,7 @@ export function envelopeRepairPrompt(input) {
         `The file you wrote at ${input.envelopePath} is not a valid hq-lane-envelope.v1. ` +
             `This is the single repair turn: rewrite that file so it validates, and do nothing else.`,
         `Parser error: ${input.error}`,
+        "For an ask question, include non-empty id, question, and context fields.",
         "Schema:",
         JSON.stringify(LANE_ENVELOPE_JSON_SCHEMA, null, 2),
         "Your previous output was:",
@@ -1723,6 +1734,16 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 answers: (trigger.kind === "answered_questions" || pendingResume?.trigger === "answered_questions") && existsSync(answersPath)
                     ? readAnsweredQuestionLines(answersPath)
                     : undefined,
+                envelopeRepairErrors: lane.terminal_reason === ENVELOPE_INVALID_REASON &&
+                    lane.envelope_repair?.attempted === true &&
+                    lane.envelope_repair.succeeded === false
+                    ? {
+                        first_error: lane.envelope_repair.first_error,
+                        ...(lane.envelope_repair.second_error !== undefined
+                            ? { second_error: lane.envelope_repair.second_error }
+                            : {}),
+                    }
+                    : undefined,
             }),
         }
         : undefined;
@@ -1805,7 +1826,6 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     }
     // Claim running before spawning. Two callers that both observe queued must
     // not both start processes; the CAS loser returns without spawn.
-    const claimable = claimableStatesFor(trigger);
     const nowIso = (deps.now ?? (() => new Date()))().toISOString();
     let claimed = false;
     const claimedRecord = retryUpdateLane(hqRoot, lane.lane_id, "spawn", (current) => {
@@ -1816,7 +1836,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             }
             return current;
         }
-        if (!claimable.includes(current.state)) {
+        if (!claimableStatesFor(trigger, current).includes(current.state)) {
             throw new LanesError("spawn_state_mismatch", `Cannot mark ${current.lane_id} running from ${current.state}`, { lane_id: current.lane_id, state: current.state, trigger: trigger.kind });
         }
         claimed = true;
@@ -1826,6 +1846,8 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             queued_reason: undefined,
             queued_at: undefined,
             admission_reserved_at: undefined,
+            terminal_reason: undefined,
+            terminal_details: undefined,
             // An account move's reservation ends with the claim.
             pending_resume: undefined,
             account: resolved.id,

package/dist/lib/lanes/types.d.ts

@@ -7,6 +7,8 @@ export declare const LANE_SCHEMA_VERSION: "hq-lane.v1";
 export declare const QUESTION_SCHEMA_VERSION: "hq-lane-question.v1";
 export declare const ENVELOPE_SCHEMA_VERSION: "hq-lane-envelope.v1";
 export declare const CONFIG_SCHEMA_VERSION: "hq-lanes-config.v1";
+/** Lane terminal reason for an envelope still invalid after its one repair turn. */
+export declare const ENVELOPE_INVALID_REASON: "envelope_invalid";
 /**
  * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
  * check; this is the text handed to a worker on the repair turn (spec §4) so
@@ -36,6 +38,11 @@ export declare const LANE_ENVELOPE_JSON_SCHEMA: {
                 readonly additionalProperties: false;
                 readonly required: readonly ["question", "context", "options"];
                 readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly pattern: "\\S";
+                    };
                     readonly question: {
                         readonly type: "string";
                     };
@@ -444,7 +451,7 @@ export interface AccountHistoryEntry {
 export interface PendingResume {
     session_id: string;
     trigger: "answered_questions" | "message" | "resume";
-    resumed_from?: "interrupted" | "done" | "blocked";
+    resumed_from?: "interrupted" | "done" | "blocked" | "failed";
     text?: string;
     message_id?: string;
     /** False when the command passed --no-compact; the deferred spawn honours it. */
@@ -471,7 +478,7 @@ export interface LaneResumeRecord {
      * `hq lanes resume` only: the state the lane was in when the operator
      * resumed it (`interrupted`, `done` or `blocked`) and the text they sent.
      */
-    resumed_from?: "interrupted" | "done" | "blocked";
+    resumed_from?: "interrupted" | "done" | "blocked" | "failed";
     text?: string;
     /** False when the continued turn explicitly skipped compaction. */
     compact?: boolean;
@@ -555,6 +562,8 @@ export interface QuestionRecord {
     answer_history?: QuestionAnswer[];
 }
 export interface EnvelopeQuestion {
+    /** Optional for compatibility with existing v1 envelopes; repair prompts request it. */
+    id?: string;
     question: string;
     context: string;
     options: string[];

package/dist/lib/lanes/types.js

@@ -8,6 +8,8 @@ export const LANE_SCHEMA_VERSION = "hq-lane.v1";
 export const QUESTION_SCHEMA_VERSION = "hq-lane-question.v1";
 export const ENVELOPE_SCHEMA_VERSION = "hq-lane-envelope.v1";
 export const CONFIG_SCHEMA_VERSION = "hq-lanes-config.v1";
+/** Lane terminal reason for an envelope still invalid after its one repair turn. */
+export const ENVELOPE_INVALID_REASON = "envelope_invalid";
 /**
  * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
  * check; this is the text handed to a worker on the repair turn (spec §4) so
@@ -30,6 +32,7 @@ export const LANE_ENVELOPE_JSON_SCHEMA = {
                 additionalProperties: false,
                 required: ["question", "context", "options"],
                 properties: {
+                    id: { type: "string", minLength: 1, pattern: "\\S" },
                     question: { type: "string" },
                     context: { type: "string" },
                     options: { type: "array", items: { type: "string" } },
@@ -357,6 +360,14 @@ export function parseLaneEnvelope(raw) {
                 context: requireString(item.context, `questions[${index}].context`),
                 options,
             };
+            if (item.id !== undefined) {
+                if (typeof item.id !== "string" || item.id.trim().length === 0) {
+                    throw new LaneSchemaError(`Expected non-empty string for questions[${index}].id`, {
+                        field: `questions[${index}].id`,
+                    });
+                }
+                parsed.id = item.id;
+            }
             if (item.recommended !== undefined) {
                 parsed.recommended = requireString(item.recommended, `questions[${index}].recommended`);
             }

package/dist/lib/lanes/watcher.d.ts

@@ -31,7 +31,7 @@
  * Queue admission of the next lane when a slot frees is owned by the
  * periodic reconcile pass and is out of scope here.
  */
-import { type LaneEnvelope, type LaneRecord, type LaneState } from "./types.js";
+import { ENVELOPE_INVALID_REASON, type LaneEnvelope, type LaneRecord, type LaneState } from "./types.js";
 import { type QuotaSignal } from "./quota.js";
 import { type ProviderRejection } from "./provider-rejection.js";
 import type { AdmissionHost } from "./admission.js";
@@ -50,7 +50,7 @@ export declare const WATCHER_HEARTBEAT_MS: number;
 export declare const WATCHER_OUT_MAX_BYTES: number;
 export declare const WATCHER_DECISION_EVENTS: readonly ["liveness_transition", "silence_deadline", "envelope_observed", "envelope_invalid", "envelope_repair", "classification", "terminal_write", "mesh_event", "mesh_event_failed"];
 /** Terminal reason when the envelope failed to parse after the repair turn (spec §4). */
-export declare const ENVELOPE_INVALID_REASON: "envelope_invalid";
+export { ENVELOPE_INVALID_REASON };
 export type WatcherDecisionEvent = (typeof WATCHER_DECISION_EVENTS)[number];
 export declare const WATCHER_SIGNAL_KINDS: readonly ["progress", "terminal", "silence"];
 export type WatcherSignalKind = (typeof WATCHER_SIGNAL_KINDS)[number];

package/dist/lib/lanes/watcher.js

@@ -35,7 +35,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { LanesError } from "./errors.js";
 import { raiseEnvelopeQuestions } from "./questions.js";
-import { isTerminalLaneState, parseLaneEnvelope, } from "./types.js";
+import { isTerminalLaneState, ENVELOPE_INVALID_REASON, parseLaneEnvelope, } from "./types.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
 import { readLane, retryUpdateLane } from "./store.js";
 import { readWorkerRunResult } from "./delivery.js";
@@ -70,7 +70,7 @@ export const WATCHER_DECISION_EVENTS = [
     "mesh_event_failed",
 ];
 /** Terminal reason when the envelope failed to parse after the repair turn (spec §4). */
-export const ENVELOPE_INVALID_REASON = "envelope_invalid";
+export { ENVELOPE_INVALID_REASON };
 export const WATCHER_SIGNAL_KINDS = ["progress", "terminal", "silence"];
 export function parseWatcherSignalKind(value) {
     if (typeof value === "string" &&

package/dist/lib/mesh/live/backoff.d.ts

@@ -6,11 +6,11 @@ export declare const BACKOFF_BASE_MS = 1000;
 export declare const BACKOFF_CAP_MS = 60000;
 export declare const FLUSH_MAX_ATTEMPTS = 5;
 export type RandomFn = () => number;
-export type SleepFn = (ms: number) => Promise<void>;
+export type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
 export declare function fullJitterDelayMs(attempt: number, opts?: {
     baseMs?: number;
     capMs?: number;
     random?: RandomFn;
 }): number;
-export declare function defaultSleep(ms: number): Promise<void>;
+export declare function defaultSleep(ms: number, signal?: AbortSignal): Promise<void>;
 //# sourceMappingURL=backoff.d.ts.map

package/dist/lib/mesh/live/backoff.js

@@ -12,9 +12,22 @@ export function fullJitterDelayMs(attempt, opts = {}) {
     const exp = Math.min(cap, base * 2 ** attempt);
     return Math.floor(random() * exp);
 }
-export async function defaultSleep(ms) {
-    if (ms <= 0)
+export async function defaultSleep(ms, signal) {
+    if (ms <= 0 || signal?.aborted)
         return;
-    await new Promise((resolve) => setTimeout(resolve, ms));
+    await new Promise((resolve) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            finish();
+        };
+        const finish = () => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+    });
 }
 //# sourceMappingURL=backoff.js.map

package/dist/lib/mesh/live/daemon/run.d.ts

@@ -45,8 +45,8 @@ export interface DaemonRunDeps {
     timers?: TimerHost;
     fetchCredentials?: CredentialsFetcher;
     mqttConnect?: MqttConnectFn;
-    /** Injected flush (tests). */
-    flush?: () => Promise<FlushSummary>;
+    /** Injected flush (tests). Receives the daemon shutdown signal. */
+    flush?: (signal?: AbortSignal) => Promise<FlushSummary>;
     /** Injected outbox replay (tests). */
     replayOutbox?: () => Promise<{
         delivered: number;

package/dist/lib/mesh/live/daemon/run.js

@@ -330,8 +330,9 @@ export async function runMeshDaemon(deps = {}) {
     };
     /** In-memory held re-attempt throttle (survives watch-triggered flushes). */
     let lastHeldRetryAtMs = 0;
+    const shutdownController = new AbortController();
     const flushFn = deps.flush ??
-        (async () => {
+        (async (signal) => {
             const t = await getToken();
             const poster = deps.poster ?? createSessionEventsPoster({
                 token: t,
@@ -341,6 +342,7 @@ export async function runMeshDaemon(deps = {}) {
                 workMeshRoot: meshRoot,
                 workContextRoot: ctxRoot,
                 poster,
+                signal,
                 heldRetryIntervalMs: HELD_RETRY_INTERVAL_MS,
                 lastHeldRetryAtMs,
                 onHeldClaimed: (atMs) => {
@@ -628,7 +630,7 @@ export async function runMeshDaemon(deps = {}) {
                 const at = now().getTime();
                 noteHookSessionsFromSpoolFile(workMeshSpoolPath(meshRoot), lastHookEventAt, at);
                 noteHookSessionsFromSpoolFile(workMeshHeldPath(meshRoot), lastHookEventAt, at);
-                const summary = await flushFn();
+                const summary = await flushFn(shutdownController.signal);
                 try {
                     const replay = await replayFn();
                     const delivered = replay.delivered ?? 0;
@@ -794,6 +796,7 @@ export async function runMeshDaemon(deps = {}) {
         if (stopped)
             return;
         stopped = true;
+        shutdownController.abort();
         log(dir, "daemon stopping");
         if (debounceHandle !== null)
             timers.clearTimeout(debounceHandle);

package/dist/lib/mesh/live/flush.d.ts

@@ -2,8 +2,8 @@
  * Flush spool + held session events (US-008).
  *
  * Claim-by-rename → group by sessionId → read work-context state →
- * drop untracked / hold unverified / strip local-only → POST batches of ≤100
- * with bounded full-jitter retries. Never touches sessions-bind.json.
+ * drop untracked / hold unverified / strip local-only → POST at most 25 events
+ * per session per flush. Throttles honor Retry-After and preserve the backlog.
  *
  * Orphan `*.claimed` files from a prior crash are recovered first.
  * 2xx responses are accounted per eventId (accepted / duplicates / rejected).
@@ -32,6 +32,7 @@ export interface FlushDeps {
     workMeshRoot: string;
     workContextRoot: string;
     poster: SessionEventsPoster;
+    signal?: AbortSignal;
     now?: () => Date;
     sleep?: SleepFn;
     random?: RandomFn;

package/dist/lib/mesh/live/flush.js

@@ -2,8 +2,8 @@
  * Flush spool + held session events (US-008).
  *
  * Claim-by-rename → group by sessionId → read work-context state →
- * drop untracked / hold unverified / strip local-only → POST batches of ≤100
- * with bounded full-jitter retries. Never touches sessions-bind.json.
+ * drop untracked / hold unverified / strip local-only → POST at most 25 events
+ * per session per flush. Throttles honor Retry-After and preserve the backlog.
  *
  * Orphan `*.claimed` files from a prior crash are recovered first.
  * 2xx responses are accounted per eventId (accepted / duplicates / rejected).
@@ -21,6 +21,10 @@ import { LOCAL_ONLY_FIELDS, stripLocalOnlyFields } from "./format-spool-line.js"
 import { SESSION_EVENTS_BATCH_MAX, WRITABLE_CONTEXT_STATUSES, parseSessionEventsBatchAck, } from "./session-events-client.js";
 import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendSpoolLine, claimHeld, claimSpool, countJsonlLines, ensureSpoolFile, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
 import { workMeshHeldPath, workMeshRoot } from "./paths.js";
+/** Bound a replayed session backlog so one flush cannot burst hundreds of events. */
+const SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH = 25;
+/** Never keep a flush blocked on a Retry-After value for more than five minutes. */
+const MAX_RETRY_AFTER_MS = 5 * 60 * 1000;
 export const HELD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 /** Re-attempt held events at most this often (spool still flushes every cycle). */
 export const HELD_RETRY_INTERVAL_MS = 5 * 60 * 1000;
@@ -126,18 +130,32 @@ async function postBatchWithRetries(poster, body, deps) {
     let lastStatus = 0;
     let lastBody = {};
     for (let attempt = 0; attempt < deps.maxAttempts; attempt += 1) {
+        if (deps.signal?.aborted) {
+            return { ok: false, retryable: true, status: lastStatus, body: lastBody };
+        }
         const res = await poster(body);
         lastStatus = res.status;
         lastBody = res.body;
         if (res.ok)
             return { ok: true, body: res.body };
+        if (res.status === 429 || res.status === 503) {
+            const retryAfterMs = typeof res.retryAfterMs === "number" &&
+                Number.isFinite(res.retryAfterMs) &&
+                res.retryAfterMs >= 0
+                ? Math.min(res.retryAfterMs, MAX_RETRY_AFTER_MS)
+                : 0;
+            const jitterMs = fullJitterDelayMs(attempt, { random: deps.random });
+            await deps.sleep(Math.min(MAX_RETRY_AFTER_MS, Math.max(retryAfterMs, jitterMs)), deps.signal);
+            // A throttled batch stays queued for a later flush; do not hot-loop it.
+            return { ok: false, retryable: true, status: res.status, body: res.body };
+        }
         if (!res.retryable) {
             return { ok: false, retryable: false, status: res.status, body: res.body };
         }
         if (attempt + 1 >= deps.maxAttempts)
             break;
         const delay = fullJitterDelayMs(attempt, { random: deps.random });
-        await deps.sleep(delay);
+        await deps.sleep(delay, deps.signal);
     }
     return { ok: false, retryable: true, status: lastStatus, body: lastBody };
 }
@@ -230,7 +248,9 @@ export async function flushSessionEvents(deps) {
             pendingRestore.delete(event);
         };
         const loggedProject404 = new Set();
-        for (const [sessionId, items] of bySession) {
+        sessionLoop: for (const [sessionId, items] of bySession) {
+            if (deps.signal?.aborted)
+                break sessionLoop;
             let state = readSessionState(sessionId, deps.workContextRoot);
             if (state?.companyConfidence === "device_default" &&
                 deps.authorizeDeviceDefaultTenant) {
@@ -273,11 +293,13 @@ export async function flushSessionEvents(deps) {
                 }
                 continue;
             }
-            // Post path: strip local-only, batch ≤100, retry.
-            const stripped = items.map((item) => stripLocalOnlyFields(item.event));
+            // Post a bounded portion of this session's backlog. Untouched events
+            // remain in pendingRestore and are put back on the spool below.
+            const flushItems = items.slice(0, SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH);
+            const stripped = flushItems.map((item) => stripLocalOnlyFields(item.event));
             for (let i = 0; i < stripped.length; i += SESSION_EVENTS_BATCH_MAX) {
                 const chunk = stripped.slice(i, i + SESSION_EVENTS_BATCH_MAX);
-                const originalChunk = items.slice(i, i + SESSION_EVENTS_BATCH_MAX);
+                const originalChunk = flushItems.slice(i, i + SESSION_EVENTS_BATCH_MAX);
                 const body = {
                     contractVersion: 1,
                     companyUid: decision.companyUid,
@@ -296,6 +318,7 @@ export async function flushSessionEvents(deps) {
                     maxAttempts,
                     sleep,
                     random,
+                    signal: deps.signal,
                 });
                 if (result.ok) {
                     accountBatchSuccess(result.body, originalChunk, deps.workMeshRoot, now, summary, markDisposed);
@@ -347,6 +370,10 @@ export async function flushSessionEvents(deps) {
                     summary.restored += 1;
                     markDisposed(item.event);
                 }
+                if (result.status === 429 || result.status === 503)
+                    break;
+                if (deps.signal?.aborted)
+                    break sessionLoop;
             }
         }
     }