@songsid/agend 2.2.1 → 2.2.5

package/dist/repo-worktree-guard.js

@@ -0,0 +1,143 @@
+/**
+ * Path containment for checkout_repo / release_repo: an instance creates and removes git worktrees only inside its
+ * own `<instanceDir>/repos`, and removes only a worktree it can show is one. Nothing outside passes, whatever the
+ * path text says (`..`, a sibling with the same prefix, an absolute path, a symlink inside `repos/`).
+ */
+import { lstatSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+/** Where this instance's checkouts are recorded: path → the source repo's git common dir. */
+export const CHECKOUTS_FILE = ".agend-checkouts.json";
+/** realpath, or — for a path that does not exist (yet) — its normalized absolute form. */
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/** `candidate` strictly inside `root`: not root itself, not above it, not on another drive. Both must be real paths. */
+function strictlyInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * The `repos` directory of this instance, as a real directory. A `repos` that is a symlink (or not a directory) is
+ * refused: following it would put worktrees, and deletions, somewhere else.
+ */
+export function reposRoot(instanceDir) {
+    const dir = join(instanceDir, "repos");
+    try {
+        const st = lstatSync(dir);
+        if (st.isSymbolicLink() || !st.isDirectory())
+            return { ok: false, reason: "the instance repos directory is not a plain directory" };
+    }
+    catch {
+        return { ok: false, reason: "the instance has no repos directory" };
+    }
+    return { ok: true, path: real(dir) };
+}
+/** Where checkout_repo may create a worktree: one fresh direct child of `repos`, never an existing path. */
+export function checkoutTarget(instanceDir, source, branch) {
+    const root = reposRoot(instanceDir);
+    if (!root.ok)
+        return root;
+    const name = `${basename(source)}-${branch.replace(/\//g, "-")}`;
+    if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\"))
+        return { ok: false, reason: "invalid checkout name" };
+    const target = join(root.path, name);
+    if (!strictlyInside(root.path, target) || relative(root.path, target) !== name)
+        return { ok: false, reason: "checkout path outside the instance repos directory" };
+    try {
+        lstatSync(target);
+        return { ok: false, reason: "a checkout already exists at that path" };
+    }
+    catch { /* free, as required */ }
+    return { ok: true, path: target };
+}
+/** The checkouts this instance recorded (path → git common dir). A missing or broken file is no records. */
+export function readCheckouts(root) {
+    try {
+        const raw = JSON.parse(readFileSync(join(root, CHECKOUTS_FILE), "utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(raw))
+            if (typeof v === "string")
+                out[k] = v;
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+export function writeCheckouts(root, records) {
+    const file = join(root, CHECKOUTS_FILE), tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(records, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, file);
+}
+/**
+ * The real path release_repo may remove, or why not. It must exist, be strictly inside this instance's `repos`
+ * (after resolving symlinks — a link inside `repos/` that points out resolves out, and is refused), and not be a
+ * symlink itself. Whether it is a worktree is checked separately (verifyWorktree), with git.
+ */
+export function releaseCandidate(instanceDir, rawPath) {
+    if (typeof rawPath !== "string" || rawPath.length === 0 || rawPath.includes("\0"))
+        return { ok: false, reason: "missing path" };
+    const root = reposRoot(instanceDir);
+    if (!root.ok)
+        return root;
+    const expanded = rawPath.replace(/^~(?=$|\/)/, process.env.HOME || "~");
+    const absolute = isAbsolute(expanded) ? expanded : join(root.path, expanded);
+    let st;
+    try {
+        st = lstatSync(absolute);
+    }
+    catch {
+        return { ok: false, reason: "no such checkout" };
+    }
+    if (st.isSymbolicLink() || !st.isDirectory())
+        return { ok: false, reason: "not a checkout directory" };
+    const candidate = real(absolute);
+    if (!strictlyInside(root.path, candidate))
+        return { ok: false, reason: "path outside the instance repos directory" };
+    return { ok: true, path: candidate };
+}
+/**
+ * A contained candidate is removable only as a linked git worktree whose top level is exactly that directory, and —
+ * when this instance recorded it — of the repository it was checked out from. `git` is injected for tests.
+ */
+export async function verifyWorktree(root, candidate, git) {
+    let top, gitDir, commonDir;
+    try {
+        top = real((await git(["rev-parse", "--show-toplevel"], candidate)).trim());
+        gitDir = real(resolve(candidate, (await git(["rev-parse", "--git-dir"], candidate)).trim()));
+        commonDir = real(resolve(candidate, (await git(["rev-parse", "--git-common-dir"], candidate)).trim()));
+    }
+    catch {
+        return { ok: false, reason: "not a git worktree" };
+    }
+    if (top !== candidate)
+        return { ok: false, reason: "not the top of a git worktree" };
+    // A linked worktree keeps its git dir under the common dir's worktrees/; the main checkout's git dir IS the common dir.
+    if (gitDir === commonDir || !strictlyInside(join(commonDir, "worktrees"), gitDir))
+        return { ok: false, reason: "not a linked git worktree" };
+    const recorded = readCheckouts(root)[candidate];
+    if (recorded !== undefined && real(recorded) !== commonDir)
+        return { ok: false, reason: "a different repository than the one checked out" };
+    if (recorded === undefined) {
+        // A checkout from before checkouts were recorded: its repository must list it as one of its worktrees.
+        let listed;
+        try {
+            listed = await git(["--git-dir", commonDir, "worktree", "list", "--porcelain"], commonDir);
+        }
+        catch {
+            return { ok: false, reason: "not a git worktree" };
+        }
+        const paths = listed.split("\n").filter(l => l.startsWith("worktree ")).map(l => real(l.slice("worktree ".length)));
+        if (!paths.includes(candidate))
+            return { ok: false, reason: "not a worktree of its repository" };
+    }
+    return { ok: true, commonDir };
+}
+//# sourceMappingURL=repo-worktree-guard.js.map

package/dist/repo-worktree-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-worktree-guard.js","sourceRoot":"","sources":["../src/repo-worktree-guard.ts"],"names":[],"mappings":"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"}

package/dist/restart-progress.d.ts

@@ -37,6 +37,19 @@ export type RestartProgressMode = "restart" | "update" | "reload";
 export declare const RESTART_PROGRESS_TERMINAL_TIMEOUT_MS = 30000;
 /** Minimum ms between non-terminal progress edits (throttle window). */
 export declare const PROGRESS_THROTTLE_MS = 2500;
+/**
+ * #2175: Telegram allows a bot about 20 messages a minute in one group, edits included, and every topic of a forum
+ * group shares it with the fleet's other startup messages. The 1 Hz update ticker drew 429s whose retry_after outlasted
+ * the terminal budget, leaving "Starting... 13/14" as the last word. Progress edits to Telegram are spaced this far
+ * apart (10 a minute); the newest frame is the one sent.
+ */
+export declare const TELEGRAM_PROGRESS_EDIT_SPACING_MS = 6000;
+/**
+ * #2175: how long a terminal state that could not land within RESTART_PROGRESS_TERMINAL_TIMEOUT_MS (a 429 window
+ * longer than that, or the adapter not ready yet) keeps being retried in the background — after startup, never
+ * holding it.
+ */
+export declare const TERMINAL_BACKGROUND_WINDOW_MS: number;
 /** #1716: the shared background-work line for the completion and every fallback path. */
 export declare function formatBackgroundWorkEndedLine(names: readonly string[]): string;
 /** One terminal text shared by the in-place edit and FleetManager fallback. */
@@ -88,6 +101,14 @@ export declare class RestartProgress {
     private throttleTimer;
     /** Resolves the active drainProgressEdits backoff sleep early when finish() is called. */
     private wakeBackoff;
+    /** #2175: the end of the newest 429 window the provider named; no edit is sent before it. */
+    private rateLimitedUntil;
+    /** #2175: when the last progress edit was sent (Telegram pacing). */
+    private lastEditSentAt;
+    /** #2175: the background terminal retry, while one is owed. */
+    private deferredTerminal;
+    /** #2175: the last terminal text the provider acknowledged on the message. */
+    private landedText;
     constructor(total: number, startedAt: number, logger: ProgressLogger, options?: RestartProgressOptions);
     /** May be called before the channel adapter is ready; progress is retained. */
     markReady(): void;
@@ -95,7 +116,10 @@ export declare class RestartProgress {
     start(target: RestartProgressTarget | null): Promise<boolean>;
     /** Adopt the pre-update message after the new fleet process reconnects. */
     resume(target: RestartProgressTarget | null, messageId: string): Promise<boolean>;
-    /** Deliver the terminal state. Returns true only after an edit or fresh fallback succeeds. */
+    /**
+     * Deliver the terminal state. Returns true after an edit or fresh fallback succeeds, or when a passing obstacle (a
+     * 429 window, an adapter not ready yet) handed it to the background retry (#2175) — which owns it from then on.
+     */
     finish(summary?: RestartProgressSummary): Promise<boolean>;
     get readyCount(): number;
     /**
@@ -111,6 +135,8 @@ export declare class RestartProgress {
     /** Tail-only coalescing for non-terminal progress. */
     private scheduleProgressEdit;
     private drainProgressEdits;
+    /** A sleep finish() can cut short (it then delivers the terminal state itself). */
+    private interruptibleSleep;
     /**
      * A terminal state must mean "delivered", not merely "had a message id".
      * Wait through a bounded adapter-recovery window, re-resolving replacement
@@ -119,6 +145,44 @@ export declare class RestartProgress {
      * 429 responses are retried with their retry-after delay up to the deadline.
      */
     private deliverTerminal;
+    /**
+     * #2175: the terminal state could not land within the startup budget for a reason that passes — a 429 window, or
+     * the adapter not ready yet. Startup goes on; this retries after it (edit in place, else a new message) until
+     * TERMINAL_BACKGROUND_WINDOW_MS, each failure at warn and the give-up at error. Returns true: the completion is owed
+     * by this retry, so a caller must not post a second one into the same refusing chat.
+     *
+     * It is the message's only writer from here on: one provider call at a time; a newer text (replaceTerminalText)
+     * is written after the call in flight settles; and a call whose outcome is still unknown at its deadline is never
+     * followed by another write (a duplicate or an overwrite could follow) — it is logged loudly, and only its own
+     * late settlement may write the newer text it missed.
+     */
+    private deferTerminal;
+    private scheduleDeferred;
+    /** One provider call for the deferred terminal; resolves "unknown" when its deadline passes unsettled. */
+    private deferredCall;
+    /** A call that settled after its deadline: the message holds `sent` if it landed; write a newer text it missed. */
+    private settleLate;
+    private attemptDeferred;
+    private deferredDelivered;
+    private loud;
+    /**
+     * #2175: no ready adapter by the deadline. One that is not ready (a gateway still connecting) passes — the
+     * background retry takes it; one that is ready means the budget went to a provider call that never settled, which
+     * stays a loud failure as before.
+     */
+    private adapterNotReady;
+    /**
+     * #2175: hand a newer text for the same message (the completion with a cleanup warning) to the background retry
+     * while it owns the message, so the two never race on it. False when nothing is owed: the caller writes it itself.
+     */
+    replaceTerminalText(text: string): boolean;
+    /**
+     * #2175: whether this exact text is known to have landed on the message (the provider acknowledged it). A text
+     * handed over with replaceTerminalText is not landed until then.
+     */
+    terminalLanded(text: string): boolean;
+    /** #2175: whether the terminal state is still owed by the background retry. */
+    get terminalDeferred(): boolean;
     private waitForReadyAdapter;
     private beforeDeadline;
     private terminalDeliveryFailed;

package/dist/restart-progress.js

@@ -6,6 +6,22 @@ const TERMINAL_DELIVERY_RETRY_MS = 1_000;
 export const RESTART_PROGRESS_TERMINAL_TIMEOUT_MS = 30_000;
 /** Minimum ms between non-terminal progress edits (throttle window). */
 export const PROGRESS_THROTTLE_MS = 2_500;
+/**
+ * #2175: Telegram allows a bot about 20 messages a minute in one group, edits included, and every topic of a forum
+ * group shares it with the fleet's other startup messages. The 1 Hz update ticker drew 429s whose retry_after outlasted
+ * the terminal budget, leaving "Starting... 13/14" as the last word. Progress edits to Telegram are spaced this far
+ * apart (10 a minute); the newest frame is the one sent.
+ */
+export const TELEGRAM_PROGRESS_EDIT_SPACING_MS = 6_000;
+/**
+ * #2175: how long a terminal state that could not land within RESTART_PROGRESS_TERMINAL_TIMEOUT_MS (a 429 window
+ * longer than that, or the adapter not ready yet) keeps being retried in the background — after startup, never
+ * holding it.
+ */
+export const TERMINAL_BACKGROUND_WINDOW_MS = 10 * 60_000;
+const TERMINAL_BACKGROUND_RETRY_MS = 15_000;
+/** #2175: a 429 window must leave this much of the terminal budget for the attempt after it, else it is deferred. */
+const TERMINAL_ATTEMPT_MARGIN_MS = 5_000;
 function formatElapsed(ms) {
     const seconds = Math.max(0, Math.floor(ms / 1000));
     const minutes = Math.floor(seconds / 60);
@@ -90,6 +106,14 @@ export class RestartProgress {
     throttleTimer = null;
     /** Resolves the active drainProgressEdits backoff sleep early when finish() is called. */
     wakeBackoff = null;
+    /** #2175: the end of the newest 429 window the provider named; no edit is sent before it. */
+    rateLimitedUntil = 0;
+    /** #2175: when the last progress edit was sent (Telegram pacing). */
+    lastEditSentAt = Number.NEGATIVE_INFINITY;
+    /** #2175: the background terminal retry, while one is owed. */
+    deferredTerminal = null;
+    /** #2175: the last terminal text the provider acknowledged on the message. */
+    landedText = null;
     constructor(total, startedAt, logger, options = {}) {
         this.total = total;
         this.startedAt = startedAt;
@@ -146,7 +170,10 @@ export class RestartProgress {
         this.updateTimer.unref?.();
         return true;
     }
-    /** Deliver the terminal state. Returns true only after an edit or fresh fallback succeeds. */
+    /**
+     * Deliver the terminal state. Returns true after an edit or fresh fallback succeeds, or when a passing obstacle (a
+     * 429 window, an adapter not ready yet) handed it to the background retry (#2175) — which owns it from then on.
+     */
     async finish(summary) {
         if (!this.enabled)
             return false;
@@ -252,22 +279,31 @@ export class RestartProgress {
             const adapter = this.resolveAdapter(target);
             if (!target || !messageId || !adapter || !this.adapterReady(adapter))
                 continue;
+            // #2175: Telegram's spacing (a 429 window is slept through below); the newest frame is sent when it opens.
+            const openAt = adapter.type === "telegram" ? this.lastEditSentAt + TELEGRAM_PROGRESS_EDIT_SPACING_MS : 0;
+            if (openAt > Date.now()) {
+                this.pendingProgressText ??= text;
+                await this.interruptibleSleep(openAt - Date.now());
+                continue;
+            }
             try {
+                this.lastEditSentAt = Date.now();
                 await adapter.editMessage(target.chatId, messageId, text, target.threadId);
             }
             catch (err) {
                 const backoffMs = retryAfterMs(err);
                 if (backoffMs > 0) {
+                    this.rateLimitedUntil = Math.max(this.rateLimitedUntil, Date.now() + backoffMs);
                     this.logger.warn({ retryAfterMs: backoffMs }, "Fleet restart progress edit throttled (429); backing off");
+                    // A 429 answered after finish() began: the window is the terminal path's now (it waits it out or defers);
+                    // sleeping here would only spend the terminal budget on this worker.
+                    if (this.finished)
+                        return;
                     // Re-queue the current frame (unless a newer one arrived) so the loop
                     // retries this edit after the backoff window.
                     if (this.pendingProgressText == null)
                         this.pendingProgressText = text;
-                    await new Promise(resolve => {
-                        const t = setTimeout(() => { this.wakeBackoff = null; resolve(); }, backoffMs);
-                        t.unref?.();
-                        this.wakeBackoff = () => { clearTimeout(t); this.wakeBackoff = null; resolve(); };
-                    });
+                    await this.interruptibleSleep(backoffMs);
                 }
                 else {
                     this.logger.warn({ err }, "Failed to edit fleet restart progress");
@@ -275,6 +311,14 @@ export class RestartProgress {
             }
         }
     }
+    /** A sleep finish() can cut short (it then delivers the terminal state itself). */
+    interruptibleSleep(ms) {
+        return new Promise(resolve => {
+            const t = setTimeout(() => { this.wakeBackoff = null; resolve(); }, ms);
+            t.unref?.();
+            this.wakeBackoff = () => { clearTimeout(t); this.wakeBackoff = null; resolve(); };
+        });
+    }
     /**
      * A terminal state must mean "delivered", not merely "had a message id".
      * Wait through a bounded adapter-recovery window, re-resolving replacement
@@ -299,16 +343,28 @@ export class RestartProgress {
         }
         let adapter = await this.waitForReadyAdapter(deadline);
         if (!adapter)
-            return this.terminalDeliveryFailed();
+            return this.adapterNotReady(text);
         // Retry terminal edit with 429-aware backoff until the deadline.
         while (true) {
+            // #2175: a 429 window still open from the progress edits (finish() cut that sleep short) is waited out here;
+            // one that outlasts the budget goes to the background retry instead of an edit the provider would refuse.
+            if (this.rateLimitedUntil > Date.now()) {
+                if (this.rateLimitedUntil + TERMINAL_ATTEMPT_MARGIN_MS > deadline)
+                    return this.deferTerminal(text, this.rateLimitedUntil, "rate limited (429)");
+                await new Promise(resolve => { const t = setTimeout(resolve, this.rateLimitedUntil - Date.now()); t.unref?.(); });
+                adapter = await this.waitForReadyAdapter(deadline);
+                if (!adapter)
+                    return this.adapterNotReady(text);
+            }
             const remaining = deadline - Date.now();
             if (remaining <= 0)
                 break;
             const editAdapter = adapter;
             const edit = await this.beforeDeadline(() => editAdapter.editMessage(target.chatId, this.messageId, text, target.threadId), deadline);
-            if (edit.status === "fulfilled")
+            if (edit.status === "fulfilled") {
+                this.landedText = text;
                 return true;
+            }
             if (edit.status === "timeout") {
                 this.logger.warn({}, "Timed out editing fleet restart progress terminal state");
                 break; // no point retrying after timeout
@@ -316,6 +372,9 @@ export class RestartProgress {
             // rejected
             const backoff = retryAfterMs(edit.reason);
             if (backoff > 0) {
+                this.rateLimitedUntil = Math.max(this.rateLimitedUntil, Date.now() + backoff);
+                if (this.rateLimitedUntil + TERMINAL_ATTEMPT_MARGIN_MS > deadline)
+                    return this.deferTerminal(text, this.rateLimitedUntil, "rate limited (429)");
                 const wait = Math.min(backoff, deadline - Date.now());
                 if (wait > 0) {
                     this.logger.warn({ retryAfterMs: backoff }, "Fleet restart terminal edit throttled (429); will retry");
@@ -326,7 +385,7 @@ export class RestartProgress {
                     // Re-resolve adapter after backoff (it may have rotated)
                     adapter = await this.waitForReadyAdapter(deadline);
                     if (!adapter)
-                        return this.terminalDeliveryFailed();
+                        return this.adapterNotReady(text);
                     continue;
                 }
             }
@@ -338,14 +397,20 @@ export class RestartProgress {
         // replacement generation before the one and only fresh-send attempt.
         adapter = await this.waitForReadyAdapter(deadline);
         if (!adapter)
-            return this.terminalDeliveryFailed();
+            return this.adapterNotReady(text);
         const sendAdapter = adapter;
         const sent = await this.beforeDeadline(() => sendAdapter.sendText(target.chatId, text, { threadId: target.threadId }), deadline);
         if (sent.status === "fulfilled") {
+            this.landedText = text;
             this.logger.warn({}, "Posted fresh fleet completion after terminal progress edit was unavailable");
             return true;
         }
         if (sent.status === "rejected") {
+            const sendBackoff = retryAfterMs(sent.reason);
+            if (sendBackoff > 0) {
+                this.rateLimitedUntil = Math.max(this.rateLimitedUntil, Date.now() + sendBackoff);
+                return this.deferTerminal(text, this.rateLimitedUntil, "rate limited (429)");
+            }
             this.logger.warn({ err: sent.reason }, "Failed to post fresh fleet completion after edit failure");
         }
         else {
@@ -353,6 +418,167 @@ export class RestartProgress {
         }
         return this.terminalDeliveryFailed();
     }
+    /**
+     * #2175: the terminal state could not land within the startup budget for a reason that passes — a 429 window, or
+     * the adapter not ready yet. Startup goes on; this retries after it (edit in place, else a new message) until
+     * TERMINAL_BACKGROUND_WINDOW_MS, each failure at warn and the give-up at error. Returns true: the completion is owed
+     * by this retry, so a caller must not post a second one into the same refusing chat.
+     *
+     * It is the message's only writer from here on: one provider call at a time; a newer text (replaceTerminalText)
+     * is written after the call in flight settles; and a call whose outcome is still unknown at its deadline is never
+     * followed by another write (a duplicate or an overwrite could follow) — it is logged loudly, and only its own
+     * late settlement may write the newer text it missed.
+     */
+    deferTerminal(text, at, reason) {
+        const state = {
+            text, timer: null, giveUpAt: Date.now() + TERMINAL_BACKGROUND_WINDOW_MS,
+        };
+        this.deferredTerminal = state;
+        this.logger.warn({ reason, retryInMs: Math.max(0, at - Date.now()) }, "Fleet completion could not land yet — retrying in the background");
+        this.scheduleDeferred(state, at);
+        return true;
+    }
+    scheduleDeferred(state, when) {
+        if (this.deferredTerminal !== state)
+            return;
+        if (when > state.giveUpAt) {
+            this.deferredTerminal = null;
+            this.loud({ window_ms: TERMINAL_BACKGROUND_WINDOW_MS }, "Fleet completion could not be delivered in the background window");
+            return;
+        }
+        state.timer = setTimeout(() => { state.timer = null; void this.attemptDeferred(state); }, Math.max(0, when - Date.now()));
+        state.timer.unref?.();
+    }
+    /** One provider call for the deferred terminal; resolves "unknown" when its deadline passes unsettled. */
+    async deferredCall(call, onLate) {
+        const op = Promise.resolve().then(call);
+        let late = false;
+        op.then(v => { if (late)
+            onLate(true, v); }, reason => { if (late)
+            onLate(false, undefined, reason); });
+        const result = await this.beforeDeadline(() => op, Date.now() + RESTART_PROGRESS_TERMINAL_TIMEOUT_MS);
+        if (result.status === "timeout") {
+            late = true;
+            return { status: "unknown" };
+        }
+        return result.status === "fulfilled" ? { status: "fulfilled", value: result.value } : { status: "rejected", reason: result.reason };
+    }
+    /** A call that settled after its deadline: the message holds `sent` if it landed; write a newer text it missed. */
+    settleLate(state, sent, ok, reason) {
+        if (this.deferredTerminal !== state)
+            return;
+        if (!ok) {
+            // Settled as refused: nothing landed, so another write is safe again — after the window a 429 names.
+            const backoff = retryAfterMs(reason);
+            if (backoff > 0)
+                this.rateLimitedUntil = Math.max(this.rateLimitedUntil, Date.now() + backoff);
+            this.logger.warn({ err: reason }, "A fleet completion call that had timed out was refused; retrying in the background");
+            this.scheduleDeferred(state, Math.max(Date.now() + TERMINAL_BACKGROUND_RETRY_MS, this.rateLimitedUntil));
+            return;
+        }
+        this.landedText = sent;
+        if (state.text !== sent) {
+            this.logger.warn({}, "A late fleet completion call landed; writing the newer text it missed");
+            this.scheduleDeferred(state, Math.max(Date.now(), this.rateLimitedUntil));
+            return;
+        }
+        this.deferredTerminal = null;
+        this.logger.warn({}, "Fleet completion delivered late (a call that had timed out settled)");
+    }
+    async attemptDeferred(state) {
+        if (this.deferredTerminal !== state)
+            return;
+        const target = this.target;
+        if (!target || !this.messageId) {
+            this.deferredTerminal = null;
+            return;
+        }
+        const adapter = this.resolveAdapter();
+        if (!adapter || !this.adapterReady(adapter))
+            return this.scheduleDeferred(state, Date.now() + TERMINAL_BACKGROUND_RETRY_MS);
+        const sent = state.text;
+        const messageId = this.messageId;
+        const edit = await this.deferredCall(() => adapter.editMessage(target.chatId, messageId, sent, target.threadId), (ok, _value, reason) => this.settleLate(state, sent, ok, reason));
+        if (this.deferredTerminal !== state)
+            return;
+        if (edit.status === "unknown") {
+            return this.loud({ timeout_ms: RESTART_PROGRESS_TERMINAL_TIMEOUT_MS }, "Background fleet completion edit did not settle — not retried, its outcome is unknown");
+        }
+        if (edit.status === "fulfilled")
+            return this.deferredDelivered(state, sent, "Fleet completion delivered late (background retry)");
+        const editBackoff = retryAfterMs(edit.reason);
+        if (editBackoff > 0) {
+            this.rateLimitedUntil = Math.max(this.rateLimitedUntil, Date.now() + editBackoff);
+            this.logger.warn({ retryAfterMs: editBackoff }, "Fleet completion still throttled (429); retrying in the background");
+            return this.scheduleDeferred(state, this.rateLimitedUntil);
+        }
+        this.logger.warn({ err: edit.reason }, "Background fleet completion edit failed; posting it as a new message");
+        const fresh = state.text;
+        const posted = await this.deferredCall(() => adapter.sendText(target.chatId, fresh, { threadId: target.threadId }), (ok, value, reason) => {
+            if (ok && value)
+                this.messageId = value.messageId;
+            this.settleLate(state, fresh, ok, reason);
+        });
+        if (this.deferredTerminal !== state)
+            return;
+        if (posted.status === "unknown") {
+            return this.loud({ timeout_ms: RESTART_PROGRESS_TERMINAL_TIMEOUT_MS }, "Background fleet completion message did not settle — not retried, its outcome is unknown");
+        }
+        if (posted.status === "fulfilled") {
+            // Later writers (a newer text) edit the message that now carries the completion.
+            this.messageId = posted.value.messageId;
+            return this.deferredDelivered(state, fresh, "Fleet completion posted late as a new message (background retry)");
+        }
+        const sendBackoff = retryAfterMs(posted.reason);
+        if (sendBackoff > 0)
+            this.rateLimitedUntil = Math.max(this.rateLimitedUntil, Date.now() + sendBackoff);
+        this.logger.warn({ err: posted.reason }, "Background fleet completion message failed; retrying");
+        this.scheduleDeferred(state, Math.max(this.rateLimitedUntil, Date.now() + TERMINAL_BACKGROUND_RETRY_MS));
+    }
+    deferredDelivered(state, sent, message) {
+        this.logger.warn({}, message);
+        this.landedText = sent;
+        if (state.text !== sent)
+            return this.scheduleDeferred(state, Math.max(Date.now(), this.rateLimitedUntil));
+        if (state.timer)
+            clearTimeout(state.timer);
+        this.deferredTerminal = null;
+    }
+    loud(data, message) {
+        if (this.logger.error)
+            this.logger.error(data, message);
+        else
+            this.logger.warn(data, message);
+    }
+    /**
+     * #2175: no ready adapter by the deadline. One that is not ready (a gateway still connecting) passes — the
+     * background retry takes it; one that is ready means the budget went to a provider call that never settled, which
+     * stays a loud failure as before.
+     */
+    adapterNotReady(text) {
+        const adapter = this.resolveAdapter();
+        if (adapter && this.adapterReady(adapter))
+            return this.terminalDeliveryFailed();
+        return this.deferTerminal(text, Date.now() + TERMINAL_BACKGROUND_RETRY_MS, "adapter not ready");
+    }
+    /**
+     * #2175: hand a newer text for the same message (the completion with a cleanup warning) to the background retry
+     * while it owns the message, so the two never race on it. False when nothing is owed: the caller writes it itself.
+     */
+    replaceTerminalText(text) {
+        const state = this.deferredTerminal;
+        if (!state)
+            return false;
+        state.text = text;
+        return true;
+    }
+    /**
+     * #2175: whether this exact text is known to have landed on the message (the provider acknowledged it). A text
+     * handed over with replaceTerminalText is not landed until then.
+     */
+    terminalLanded(text) { return this.landedText === text; }
+    /** #2175: whether the terminal state is still owed by the background retry. */
+    get terminalDeferred() { return this.deferredTerminal !== null; }
     async waitForReadyAdapter(deadline) {
         while (true) {
             const remaining = deadline - Date.now();