@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/queued-message.d.ts

@@ -0,0 +1,35 @@
+/** A queued message awaiting auto-send. */
+export interface QueuedMessage {
+    text: string;
+    createdAtMs: number;
+}
+export declare class QueuedMessageStore {
+    private readonly stateFile;
+    /** In-memory map of key -> QueuedMessage (loaded once, written through on change). */
+    private state;
+    /** Serialises concurrent writes so the file never interleaves. */
+    private writing;
+    constructor(dataDir: string);
+    /** Load the persisted map (lazily; tolerant of a missing/corrupt file). */
+    private ensureLoaded;
+    /**
+     * Retrieve a queued message for a chat, or `null` if none / unavailable.
+     * Non-throwing: any load error reads as null.
+     */
+    get(agent: string, sessionId: string): Promise<QueuedMessage | null>;
+    /**
+     * Atomically read AND remove a chat's queued message (#245). Returns the entry
+     * (or null if none). The read+delete happen without an intervening `await`, so
+     * two concurrent drains — e.g. a turn-completion drain and an idle `set_queue`
+     * drain — can never both observe the same message and double-send it: whichever
+     * `take()` runs first gets it, the other gets null. Non-throwing.
+     */
+    take(agent: string, sessionId: string): Promise<QueuedMessage | null>;
+    /**
+     * Store (or clear, when `message` is null) a queued message for a chat.
+     * Setting `null` deletes the key, keeping the file compact.
+     */
+    set(agent: string, sessionId: string, message: QueuedMessage | null): Promise<void>;
+    /** Write-through, serialised so overlapping writes can't corrupt the file. */
+    private persist;
+}

package/packages/server/dist/queued-message.js

@@ -0,0 +1,116 @@
+/**
+ * QueuedMessageStore — a Paddock-side sidecar for per-chat queued messages (#197).
+ *
+ * The message queue (#91) lets users stack a follow-up to auto-send when the
+ * current turn finishes. In PR #204, the queued text lived only in component-local
+ * React state, so closing the browser before the turn completed silently dropped it.
+ *
+ * This store persists queued messages server-side so they survive browser close,
+ * page reload, and server restart — enabling true server-driven auto-send.
+ *
+ * Clones the ReadStateStore pattern: a lightweight, write-through, serialised,
+ * corruption-tolerant JSON sidecar in the data dir, storing a `key -> queued text`
+ * map (persisted as a plain JSON object). Keyed by `agent \0 sessionId` (NUL-separated).
+ *
+ * When a turn completes, the server checks for a queued message, auto-sends it as
+ * the next message, and deletes the stored entry. The web client receives a
+ * `chat:queued_flushed` frame to clear its localStorage.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "queued-message.json";
+/** Separator in a storage key; a NUL can't occur in an agent name or a UUID. */
+const KEY_SEP = "\u0000";
+/** Compose the storage key for an (agent, session) pair. */
+function keyOf(agent, sessionId) {
+    return `${agent}${KEY_SEP}${sessionId}`;
+}
+export class QueuedMessageStore {
+    stateFile;
+    /** In-memory map of key -> QueuedMessage (loaded once, written through on change). */
+    state = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    /** Load the persisted map (lazily; tolerant of a missing/corrupt file). */
+    async ensureLoaded() {
+        if (this.state)
+            return this.state;
+        const map = new Map();
+        try {
+            const raw = await fs.readFile(this.stateFile, "utf8");
+            const parsed = JSON.parse(raw);
+            // A plain JSON object `{ [key]: QueuedMessage }` — NOT an array.
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                for (const [k, v] of Object.entries(parsed)) {
+                    if (v &&
+                        typeof v === "object" &&
+                        typeof v.text === "string" &&
+                        typeof v.createdAtMs === "number") {
+                        map.set(k, v);
+                    }
+                }
+            }
+        }
+        catch {
+            /* missing or unreadable — start empty */
+        }
+        this.state = map;
+        return this.state;
+    }
+    /**
+     * Retrieve a queued message for a chat, or `null` if none / unavailable.
+     * Non-throwing: any load error reads as null.
+     */
+    async get(agent, sessionId) {
+        const map = await this.ensureLoaded().catch(() => new Map());
+        return map.get(keyOf(agent, sessionId)) ?? null;
+    }
+    /**
+     * Atomically read AND remove a chat's queued message (#245). Returns the entry
+     * (or null if none). The read+delete happen without an intervening `await`, so
+     * two concurrent drains — e.g. a turn-completion drain and an idle `set_queue`
+     * drain — can never both observe the same message and double-send it: whichever
+     * `take()` runs first gets it, the other gets null. Non-throwing.
+     */
+    async take(agent, sessionId) {
+        const map = await this.ensureLoaded().catch(() => null);
+        if (!map)
+            return null;
+        const key = keyOf(agent, sessionId);
+        const v = map.get(key);
+        if (!v)
+            return null;
+        map.delete(key);
+        await this.persist(map);
+        return v;
+    }
+    /**
+     * Store (or clear, when `message` is null) a queued message for a chat.
+     * Setting `null` deletes the key, keeping the file compact.
+     */
+    async set(agent, sessionId, message) {
+        const map = await this.ensureLoaded();
+        const key = keyOf(agent, sessionId);
+        if (message === null) {
+            map.delete(key);
+        }
+        else {
+            map.set(key, message);
+        }
+        await this.persist(map);
+    }
+    /** Write-through, serialised so overlapping writes can't corrupt the file. */
+    persist(map) {
+        this.writing = this.writing.then(async () => {
+            const obj = {};
+            for (const [k, v] of map)
+                obj[k] = v;
+            const json = JSON.stringify(obj, null, 2);
+            await fs.writeFile(this.stateFile, json, "utf8").catch(() => undefined);
+        });
+        return this.writing;
+    }
+}

package/packages/server/dist/read-state.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Compose the storage key for a (user, agent, session) triple. A null/empty
+ * username selects the SHARED bucket (no user segment) — so `none`-mode
+ * deployments get cross-device continuity for free without a per-user segment,
+ * and can never collide with a real user's entry.
+ */
+export declare function keyOf(username: string | null, agent: string, sessionId: string): string;
+export declare class ReadStateStore {
+    private readonly stateFile;
+    /** In-memory map of key -> lastSeenMs (loaded once, written through on change). */
+    private state;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read.
+     * Caching only the resolved `state` would let several marks that begin before
+     * the first `fs.readFile` resolves each build their own map and race on the
+     * assignment — a lost update (last writer's map wins, dropping the others'
+     * keys).
+     */
+    private loadPromise;
+    /** Serialises concurrent writes so the file never interleaves. */
+    private writing;
+    constructor(dataDir: string);
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    private ensureLoaded;
+    /**
+     * The epoch-ms moment this user last viewed this chat, or 0 if never seen /
+     * unavailable. Non-throwing: any load error reads as 0. Pass `null` for
+     * `username` to read the shared bucket.
+     */
+    getLastSeen(username: string | null, agent: string, sessionId: string): Promise<number>;
+    /**
+     * Advance this chat's last-seen time to `whenMs` (monotonic: an older or equal
+     * timestamp is a no-op, avoiding a needless write and never moving read-state
+     * backwards). Pass `null` for `username` to write the shared bucket.
+     */
+    setLastSeen(username: string | null, agent: string, sessionId: string, whenMs: number): Promise<void>;
+    /**
+     * Advance MANY chats' last-seen times to `whenMs` in ONE write (#508) — the
+     * subtree "mark read" action. Per-key monotonic exactly like
+     * {@link setLastSeen}, so a chat already seen later than `whenMs` is skipped
+     * rather than moved backwards. Returns the ids that actually advanced.
+     */
+    setManyLastSeen(username: string | null, agent: string, sessionIds: readonly string[], whenMs: number): Promise<string[]>;
+    /** Write-through, serialised so overlapping marks can't corrupt the file. */
+    private persist;
+}

package/packages/server/dist/read-state.js

@@ -0,0 +1,139 @@
+/**
+ * ReadStateStore — a Paddock-side sidecar for per-chat "last seen" (read-state),
+ * moving the unread affordance (#160/#161) off the browser's localStorage and
+ * onto the server so it follows a user ACROSS DEVICES (#189).
+ *
+ * This clones the ArchiveStore pattern exactly — a lightweight, write-through,
+ * serialised, corruption-tolerant JSON sidecar in the data dir — but stores a
+ * `key -> lastSeenMs` MAP (persisted as a plain JSON object) rather than a set,
+ * since read-state is a timestamp per chat, not a boolean flag.
+ *
+ * Keying — by user WHEN PRESENT, else a single shared bucket:
+ *   - Real identity (trusted-header / jwt): `username \0 agent \0 sessionId`
+ *   - No user (`none` mode / anonymous):     `agent \0 sessionId` (shared)
+ * NUL-separated, same rationale as ArchiveStore: a NUL can occur in neither a
+ * username, an agent name (`keeper-<slug>`), nor a UUID, so keys
+ * can't collide — and a user-keyed entry can never alias the shared bucket.
+ *
+ * `setLastSeen` is MONOTONIC (only ever advances a chat's last-seen time): the
+ * marker means "the most recent moment the user viewed this chat", so an older
+ * timestamp is a no-op and never moves read-state backwards.
+ *
+ * The file is written `0o600` (like github-auth.json) — read-state is
+ * low-sensitivity (which chats you viewed + when), but there's no reason for it
+ * to be world-readable.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "read-state.json";
+/** Separator in a storage key; a NUL can't occur in a username, agent, or UUID. */
+const KEY_SEP = "\u0000";
+/**
+ * Compose the storage key for a (user, agent, session) triple. A null/empty
+ * username selects the SHARED bucket (no user segment) — so `none`-mode
+ * deployments get cross-device continuity for free without a per-user segment,
+ * and can never collide with a real user's entry.
+ */
+export function keyOf(username, agent, sessionId) {
+    return username
+        ? `${username}${KEY_SEP}${agent}${KEY_SEP}${sessionId}`
+        : `${agent}${KEY_SEP}${sessionId}`;
+}
+export class ReadStateStore {
+    stateFile;
+    /** In-memory map of key -> lastSeenMs (loaded once, written through on change). */
+    state = null;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read.
+     * Caching only the resolved `state` would let several marks that begin before
+     * the first `fs.readFile` resolves each build their own map and race on the
+     * assignment — a lost update (last writer's map wins, dropping the others'
+     * keys).
+     */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.state)
+            return Promise.resolve(this.state);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                const map = new Map();
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    // A plain JSON object `{ [key]: number }` — NOT an array (unlike Archive).
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        for (const [k, v] of Object.entries(parsed)) {
+                            if (typeof v === "number" && Number.isFinite(v))
+                                map.set(k, v);
+                        }
+                    }
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.state = map;
+                return map;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /**
+     * The epoch-ms moment this user last viewed this chat, or 0 if never seen /
+     * unavailable. Non-throwing: any load error reads as 0. Pass `null` for
+     * `username` to read the shared bucket.
+     */
+    async getLastSeen(username, agent, sessionId) {
+        const map = await this.ensureLoaded().catch(() => new Map());
+        return map.get(keyOf(username, agent, sessionId)) ?? 0;
+    }
+    /**
+     * Advance this chat's last-seen time to `whenMs` (monotonic: an older or equal
+     * timestamp is a no-op, avoiding a needless write and never moving read-state
+     * backwards). Pass `null` for `username` to write the shared bucket.
+     */
+    async setLastSeen(username, agent, sessionId, whenMs) {
+        const map = await this.ensureLoaded();
+        const key = keyOf(username, agent, sessionId);
+        if (whenMs <= (map.get(key) ?? 0))
+            return; // monotonic — no-op
+        map.set(key, whenMs);
+        await this.persist(map);
+    }
+    /**
+     * Advance MANY chats' last-seen times to `whenMs` in ONE write (#508) — the
+     * subtree "mark read" action. Per-key monotonic exactly like
+     * {@link setLastSeen}, so a chat already seen later than `whenMs` is skipped
+     * rather than moved backwards. Returns the ids that actually advanced.
+     */
+    async setManyLastSeen(username, agent, sessionIds, whenMs) {
+        const map = await this.ensureLoaded();
+        const advanced = [];
+        for (const sessionId of sessionIds) {
+            const key = keyOf(username, agent, sessionId);
+            if (whenMs <= (map.get(key) ?? 0))
+                continue; // monotonic — no-op
+            map.set(key, whenMs);
+            advanced.push(sessionId);
+        }
+        if (advanced.length)
+            await this.persist(map);
+        return advanced;
+    }
+    /** Write-through, serialised so overlapping marks can't corrupt the file. */
+    persist(map) {
+        this.writing = this.writing.then(async () => {
+            const obj = {};
+            for (const [k, v] of map)
+                obj[k] = v;
+            const json = JSON.stringify(obj, null, 2);
+            await fs.writeFile(this.stateFile, json, { encoding: "utf8", mode: 0o600 }).catch(() => undefined);
+        });
+        return this.writing;
+    }
+}

package/packages/server/dist/recovery-config.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Keeper-chat recovery config — the shared foundation for issue #301 (Phase 0).
+ *
+ * ── The problem (see edspencer/herdctl#374) ──────────────────────────────────
+ * When a keeper launches a BACKGROUND task (background `Bash`, or a background
+ * `Task`/`Agent`) and ends its turn while that task is still running, herdctl
+ * correctly keeps the session ALIVE at the turn boundary (it sees the running
+ * task in the Stop snapshot and does not reap). But the SDK/native binary kills
+ * the still-running background child ~2–8s later anyway. A COMPLETED task emits a
+ * re-invocation turn and the keeper continues; a KILLED task emits no wake at all
+ * — the `killed`/`stopped` `<task-notification>` is written to the transcript but
+ * nothing consumes it. The keeper is left alive-but-idle-forever, recovering only
+ * when a human sends the next message. Because the session stays injectable, the
+ * whole class of workarounds is "automate (or one-click) the nudge a human sends."
+ *
+ * ── The two configurable layers ──────────────────────────────────────────────
+ * This ticket adds an app-side recovery mechanism in two independently-toggleable
+ * layers, each resolved here:
+ *
+ *   Layer 2 ({@link RecoveryConfig.surfaceKilledTask}, default ON) — pure
+ *     visibility + a manual one-click "Continue". Low-risk, so on by default.
+ *   Layer 3 ({@link RecoveryConfig.autoReDrive}, default OFF) — automatic
+ *     detection + re-drive of a hung keeper. Costs a turn/tokens and acts on its
+ *     own, so opt-in. The DETECTION/INJECT ENGINE is a FOLLOW-UP chat; this
+ *     module only defines + resolves the flag so the config surface exists.
+ *
+ * ── Config discipline (the `driveMode`/`maxSpawnDepth` pattern) ───────────────
+ * Every field is an instance default (`PADDOCK_RECOVERY_*` env, YAML instance
+ * file beneath it) with an optional PER-PROJECT override (`project.yaml` →
+ * {@link import("./projects.js").ProjectYaml.recovery}). An absent/invalid
+ * override inherits the instance default, resolved at dispatch by
+ * {@link resolveRecoveryConfig} — never baked into the DTO (mirrors how
+ * `driveMode` resolves against `cfg.driveMode` and `maxSpawnDepth` via
+ * `resolveMaxSpawnDepth`). A malformed override is ignored rather than fatal so a
+ * hand-edited `project.yaml` can't wedge dispatch.
+ */
+/**
+ * Resolved recovery config — all fields concrete. Held on {@link
+ * import("./config.js").PaddockConfig.recovery} (instance defaults) and produced
+ * per-dispatch by {@link resolveRecoveryConfig} (project override else instance).
+ */
+export interface RecoveryConfig {
+    /**
+     * Layer 2 — render the killed/stopped `<task-notification>` as a distinct
+     * "keeper is idle" affordance with a one-click Continue button, instead of
+     * silently hiding it. Default ON (pure visibility + a manual button is
+     * low-risk). Env `PADDOCK_RECOVERY_SURFACE`.
+     */
+    surfaceKilledTask: boolean;
+    /**
+     * Layer 3 — automatically re-drive a keeper whose background task was killed at
+     * the turn boundary (detect + inject a nudge so it wakes on its own). Default
+     * OFF (auto-acts and costs a turn/tokens → opt-in). Env
+     * `PADDOCK_RECOVERY_AUTODRIVE`. NOTE: this chat only plumbs the flag; the
+     * detection/inject engine lands in a follow-up.
+     */
+    autoReDrive: boolean;
+    /**
+     * Layer 3 guard — minimum ms of quiet after a killed-task notification before
+     * the auto re-drive fires, so a genuinely-finishing keeper isn't poked. Default
+     * 5000. Env `PADDOCK_RECOVERY_DEBOUNCE_MS`.
+     */
+    debounceMs: number;
+    /**
+     * Layer 3 guard — how many times a single hung session may be auto re-driven
+     * before giving up, so a wedged keeper isn't poked in a loop. Default 1. Env
+     * `PADDOCK_RECOVERY_MAX_RETRIES`.
+     */
+    maxRetries: number;
+    /**
+     * Layer 2 backstop — if a kept-alive keeper session shows no activity for this
+     * many ms after a killed-task notification, surface it as stuck. `0` disables
+     * the backstop (the default). Env `PADDOCK_RECOVERY_LIMBO_MS`.
+     */
+    limboTimeoutMs: number;
+}
+/**
+ * A per-project recovery override as stored in `project.yaml` — every field
+ * optional (an absent field inherits the instance default at dispatch).
+ */
+export type RecoveryOverride = Partial<RecoveryConfig>;
+/**
+ * The built-in recovery defaults (beneath env + YAML + per-project override).
+ * Layer 2 ON, Layer 3 OFF, guards at their documented values.
+ */
+export declare const DEFAULT_RECOVERY: RecoveryConfig;
+/**
+ * True when a `<task-notification>` `<status>` value denotes a task that was
+ * TERMINATED (killed/stopped) — the turn-boundary-kill case #301 recovers from —
+ * rather than a clean `completed` (or a still-`running`/`timed out` Monitor).
+ * Case-insensitive; a missing/blank/other status is not terminated.
+ */
+export declare function isTerminatedTaskStatus(status: string | null | undefined): boolean;
+/**
+ * Validate + normalise an untrusted value (from `project.yaml` or a PATCH body)
+ * into a {@link RecoveryOverride}, dropping any field that is missing or invalid,
+ * and returning `undefined` when nothing valid remains (so an empty override is
+ * never persisted). Booleans must be real booleans; the numeric knobs must be
+ * non-negative integers. Defensive by design — a malformed hand-edit degrades to
+ * "inherit the instance default", never a startup/dispatch crash.
+ */
+export declare function sanitizeRecoveryOverride(value: unknown): RecoveryOverride | undefined;
+/**
+ * Resolve the effective recovery config for a dispatch: a valid per-project
+ * override wins field-by-field; every absent field inherits the instance default.
+ * Mirrors how `driveMode`/`maxSpawnDepth` resolve — the override is carried on
+ * disk only for the fields explicitly set, so an absent value transparently
+ * inherits the instance (env/YAML) default. The override is re-sanitised so a
+ * corrupt on-disk value can't leak through.
+ */
+export declare function resolveRecoveryConfig(override: RecoveryOverride | undefined, instanceDefault: RecoveryConfig): RecoveryConfig;

package/packages/server/dist/recovery-config.js

@@ -0,0 +1,105 @@
+/**
+ * Keeper-chat recovery config — the shared foundation for issue #301 (Phase 0).
+ *
+ * ── The problem (see edspencer/herdctl#374) ──────────────────────────────────
+ * When a keeper launches a BACKGROUND task (background `Bash`, or a background
+ * `Task`/`Agent`) and ends its turn while that task is still running, herdctl
+ * correctly keeps the session ALIVE at the turn boundary (it sees the running
+ * task in the Stop snapshot and does not reap). But the SDK/native binary kills
+ * the still-running background child ~2–8s later anyway. A COMPLETED task emits a
+ * re-invocation turn and the keeper continues; a KILLED task emits no wake at all
+ * — the `killed`/`stopped` `<task-notification>` is written to the transcript but
+ * nothing consumes it. The keeper is left alive-but-idle-forever, recovering only
+ * when a human sends the next message. Because the session stays injectable, the
+ * whole class of workarounds is "automate (or one-click) the nudge a human sends."
+ *
+ * ── The two configurable layers ──────────────────────────────────────────────
+ * This ticket adds an app-side recovery mechanism in two independently-toggleable
+ * layers, each resolved here:
+ *
+ *   Layer 2 ({@link RecoveryConfig.surfaceKilledTask}, default ON) — pure
+ *     visibility + a manual one-click "Continue". Low-risk, so on by default.
+ *   Layer 3 ({@link RecoveryConfig.autoReDrive}, default OFF) — automatic
+ *     detection + re-drive of a hung keeper. Costs a turn/tokens and acts on its
+ *     own, so opt-in. The DETECTION/INJECT ENGINE is a FOLLOW-UP chat; this
+ *     module only defines + resolves the flag so the config surface exists.
+ *
+ * ── Config discipline (the `driveMode`/`maxSpawnDepth` pattern) ───────────────
+ * Every field is an instance default (`PADDOCK_RECOVERY_*` env, YAML instance
+ * file beneath it) with an optional PER-PROJECT override (`project.yaml` →
+ * {@link import("./projects.js").ProjectYaml.recovery}). An absent/invalid
+ * override inherits the instance default, resolved at dispatch by
+ * {@link resolveRecoveryConfig} — never baked into the DTO (mirrors how
+ * `driveMode` resolves against `cfg.driveMode` and `maxSpawnDepth` via
+ * `resolveMaxSpawnDepth`). A malformed override is ignored rather than fatal so a
+ * hand-edited `project.yaml` can't wedge dispatch.
+ */
+/**
+ * The built-in recovery defaults (beneath env + YAML + per-project override).
+ * Layer 2 ON, Layer 3 OFF, guards at their documented values.
+ */
+export const DEFAULT_RECOVERY = Object.freeze({
+    surfaceKilledTask: true,
+    autoReDrive: false,
+    debounceMs: 5000,
+    maxRetries: 1,
+    limboTimeoutMs: 0,
+});
+/** The `<status>` values a killed-at-turn-boundary task notification carries. */
+const TERMINATED_STATUSES = new Set(["killed", "stopped"]);
+/**
+ * True when a `<task-notification>` `<status>` value denotes a task that was
+ * TERMINATED (killed/stopped) — the turn-boundary-kill case #301 recovers from —
+ * rather than a clean `completed` (or a still-`running`/`timed out` Monitor).
+ * Case-insensitive; a missing/blank/other status is not terminated.
+ */
+export function isTerminatedTaskStatus(status) {
+    return typeof status === "string" && TERMINATED_STATUSES.has(status.trim().toLowerCase());
+}
+/** True when `n` is a valid non-negative-integer ms/count knob. */
+function isNonNegativeInt(n) {
+    return typeof n === "number" && Number.isInteger(n) && n >= 0 && Number.isFinite(n);
+}
+/**
+ * Validate + normalise an untrusted value (from `project.yaml` or a PATCH body)
+ * into a {@link RecoveryOverride}, dropping any field that is missing or invalid,
+ * and returning `undefined` when nothing valid remains (so an empty override is
+ * never persisted). Booleans must be real booleans; the numeric knobs must be
+ * non-negative integers. Defensive by design — a malformed hand-edit degrades to
+ * "inherit the instance default", never a startup/dispatch crash.
+ */
+export function sanitizeRecoveryOverride(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const o = value;
+    const out = {};
+    if (typeof o.surfaceKilledTask === "boolean")
+        out.surfaceKilledTask = o.surfaceKilledTask;
+    if (typeof o.autoReDrive === "boolean")
+        out.autoReDrive = o.autoReDrive;
+    if (isNonNegativeInt(o.debounceMs))
+        out.debounceMs = o.debounceMs;
+    if (isNonNegativeInt(o.maxRetries))
+        out.maxRetries = o.maxRetries;
+    if (isNonNegativeInt(o.limboTimeoutMs))
+        out.limboTimeoutMs = o.limboTimeoutMs;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Resolve the effective recovery config for a dispatch: a valid per-project
+ * override wins field-by-field; every absent field inherits the instance default.
+ * Mirrors how `driveMode`/`maxSpawnDepth` resolve — the override is carried on
+ * disk only for the fields explicitly set, so an absent value transparently
+ * inherits the instance (env/YAML) default. The override is re-sanitised so a
+ * corrupt on-disk value can't leak through.
+ */
+export function resolveRecoveryConfig(override, instanceDefault) {
+    const clean = sanitizeRecoveryOverride(override) ?? {};
+    return {
+        surfaceKilledTask: clean.surfaceKilledTask ?? instanceDefault.surfaceKilledTask,
+        autoReDrive: clean.autoReDrive ?? instanceDefault.autoReDrive,
+        debounceMs: clean.debounceMs ?? instanceDefault.debounceMs,
+        maxRetries: clean.maxRetries ?? instanceDefault.maxRetries,
+        limboTimeoutMs: clean.limboTimeoutMs ?? instanceDefault.limboTimeoutMs,
+    };
+}