@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/channels/kit/tasks.js

@@ -2,10 +2,16 @@
  * SHARED fire-and-forget side-task tracking. Channels launch work off the request path (stop
  * feedback, DM welcomes) that must not block the transport ACK but MUST be drained on shutdown
  * (`turnsIdle`) — otherwise a reply in flight when the process exits is silently dropped. Error
- * handling stays with the caller: track() only guarantees the drain sees the task settle.
+ * handling stays with the caller: track() only guarantees the drain sees the task SETTLE, and settle
+ * includes reject. A caller that handles its error on a separate branch (`p.catch(log); track(p)`)
+ * still hands us a promise that rejects, and a drain that propagated it would fail the channel's whole
+ * `turnsIdle` over one side task. A rejection that reaches us is logged — we
+ * cannot tell a missing `.catch` from one on a separate branch, so the line is a visibility floor
+ * rather than a diagnosis, and without it a dropped side task leaves no trace anywhere.
  */
 import { beginWork } from "../busy.js";
-export function createTaskTracker() {
+import { log } from "../../log.js";
+export function createTaskTracker(label) {
     const tasks = new Set();
     return {
         track(task) {
@@ -18,8 +24,8 @@ export function createTaskTracker() {
                 workDone();
                 tasks.delete(task);
             })
-                .catch(() => { }); // the caller's chain owns the error
+                .catch((error) => log.warn(`${label} side task rejected: ${String(error)}`));
         },
-        drain: () => Promise.all(tasks).then(() => undefined),
+        drain: () => Promise.allSettled(tasks).then(() => undefined),
     };
 }

package/dist/channels/kit/turn-runner.d.ts

@@ -0,0 +1,59 @@
+import type { ContextBuffer } from "./context-buffer.ts";
+import { type TurnRecordBase, type TurnStore } from "./turn-store.ts";
+/** A pending turn is the persisted intent minus its attempt count, plus live-only fields the
+ *  channel adds (a notice's message id) — never persisted, reconstructed fresh on replay. */
+export type PendingBase<S extends TurnRecordBase> = Omit<S, "attempts">;
+export interface TurnRunnerOptions<R extends PendingBase<S>, S extends TurnRecordBase, E> {
+    label: string;
+    store: TurnStore<S>;
+    buffer: ContextBuffer<E>;
+    /** Delivery dedup by platform id, recorded post-persist (Slack, Feishu). */
+    seen?: {
+        add(id: string): void;
+    };
+    /** The persisted intent for a pending turn — drops the live-only fields. */
+    toStored(rec: R): S;
+    /** A recovered intent as a pending turn — live-only fields start absent. */
+    fromStored(stored: S): R;
+    /** The context-buffer bucket this turn folds. */
+    bufferKey(rec: R): string;
+    /** The place, for the lifecycle log line (`chat=… thread=…`). */
+    where(rec: R): string;
+    /** Queue feedback when a turn is scheduled BEHIND an active one. Returns what the runner awaits at
+     *  dequeue (so the turn reliably takes the notice over instead of racing it) and, optionally, how
+     *  to cancel a notice that has not fired yet. `done` may reject — posting the notice is a platform
+     *  call — and the runner logs that and runs the turn anyway. */
+    onQueuedBehind?(rec: R): {
+        done: Promise<void>;
+        cancel?: () => void;
+    };
+    /** Runs before the attempt is counted. Answer false to leave the intent untouched for a later run
+     *  (Slack: its transport is known to be down, so an Agent turn now would have nowhere to answer). */
+    beforeRun?(rec: R): Promise<boolean>;
+    /** The attempt could not be recorded (disk failure): a restart replays the turn, so say so on any
+     *  notice it holds rather than leaving it pinned at "Queued". */
+    onDeferred(rec: R): void;
+    /** The turn started the ceiling's worth of times without finishing: tell the asker. */
+    notifyDropped(rec: R): void;
+    /** Run the turn. `onCompleted` is the durable-commit point (the turn's `completed` event): it drops
+     *  the intent and commits the folded discussion, in that order. A throw is logged as the turn's
+     *  failure; the intent is dropped either way. */
+    execute(rec: R, discussion: {
+        text: string;
+        consumed: E[];
+    }, onCompleted: () => void): Promise<void>;
+}
+export interface TurnRunner<R, S> {
+    /** Accept a turn: persist its intent (pre-ACK — a failed write throws so the platform redelivers),
+     *  record the delivery id, enqueue. Recovery re-enqueues without re-persisting. */
+    submit(rec: R, persist: boolean): void;
+    /** Re-enqueue the turns a prior crash left mid-flight; returns them so a channel can continue its
+     *  arrival counter. */
+    recover(): S[];
+    /** Resolve once no turn is in flight — the test/observability seam. */
+    idle(): Promise<void>;
+}
+export declare function createTurnRunner<R extends PendingBase<S> & {
+    id: string;
+    session: string;
+}, S extends TurnRecordBase, E>(options: TurnRunnerOptions<R, S, E>): TurnRunner<R, S>;

package/dist/channels/kit/turn-runner.js

@@ -0,0 +1,84 @@
+/**
+ * The durable-turn LIFECYCLE the stateful chat channels share, over the kit's parts: accept
+ * (persist pre-ACK, dedup, enqueue) → dequeue (settle the queue notice, count the attempt against
+ * the poison ceiling, fold the buffered discussion) → execute → end (log, drop the intent). Telegram,
+ * Slack and Feishu each wrote this out; the copies had already drifted in small ways that were not
+ * decisions (which one deletes its notice on defer, which one logs the duration on failure).
+ *
+ * What stays with the platform is everything that names a platform object: how a queue notice is
+ * mounted and taken over, what the prompt looks like, how attachments resolve, what a dropped turn
+ * says and where. Those arrive as hooks; the ORDER they run in is this module's.
+ */
+import { log } from "../../log.js";
+import { createTurnQueue } from "./turn-queue.js";
+import { commitAnsweredTurn } from "./turn-store.js";
+export function createTurnRunner(options) {
+    const { label, store, buffer, seen, onQueuedBehind } = options;
+    const notices = new Map();
+    const queue = createTurnQueue({
+        label,
+        onQueuedBehind: onQueuedBehind && ((rec) => notices.set(rec.id, onQueuedBehind(rec))),
+        run: async (rec) => {
+            // Runs at DEQUEUE time (serialized). The queue wait is over: cancel a notice that has not
+            // fired, then settle so the turn's preview handle is final — in the common path this await is
+            // instant. BEFORE the ceiling check so a dropped or deferred turn can take the notice over too.
+            const notice = notices.get(rec.id);
+            notice?.cancel?.();
+            // The notice is the PLATFORM's feedback, not the turn: a failed post must not throw out of the
+            // run, which would leak the persisted intent (removed only below) into a replay that burns an
+            // attempt against the ceiling. Logged, then the turn proceeds without its handle.
+            await notice?.done.catch((error) => log.warn(`${label} queue notice failed: turn=${rec.id} session=${rec.session}: ${String(error)}`));
+            notices.delete(rec.id);
+            if (options.beforeRun && !(await options.beforeRun(rec)))
+                return;
+            const decision = store.startAttempt(rec.id);
+            if (decision === "exceeded") {
+                options.notifyDropped(rec);
+                return;
+            }
+            if (decision === "defer") {
+                options.onDeferred(rec);
+                return;
+            }
+            const startedAt = Date.now();
+            log.info(`${label} turn start: turn=${rec.id} session=${rec.session} ${options.where(rec)}`);
+            // Snapshot the discussion at dequeue; commit only this snapshot on `completed`, so a message
+            // arriving while the turn runs stays buffered for the next answered turn.
+            const bufferKey = options.bufferKey(rec);
+            const discussion = buffer.peek(bufferKey);
+            try {
+                await options.execute(rec, discussion, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey, consumed: discussion.consumed }));
+                log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
+            }
+            catch (error) {
+                log.error(`${label} turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error)}`);
+            }
+            finally {
+                // Fallback removal for the caught-error paths (a `failed` event or a transport throw): those
+                // never reach the completed hook. Idempotent. Only an INTERRUPTED run (this finally never
+                // runs — a crash or SIGTERM deploy) leaves the record for replay; a transport throw is
+                // dropped, not retried (safe retry needs an L2 delivery key).
+                store.remove(rec.id);
+            }
+        },
+    });
+    const submit = (rec, persist) => {
+        if (persist) {
+            store.add(options.toStored(rec)); // pre-ACK: a failed write throws → 500 → redelivery
+            seen?.add(rec.id); // post-persist — recording first could turn a failed write into silent loss
+        }
+        queue.accept(rec);
+    };
+    return {
+        submit,
+        recover() {
+            const recovered = store.recover();
+            if (recovered.length > 0)
+                log.info(`${label} recovering ${recovered.length} unfinished turn(s) from a prior run`);
+            for (const stored of recovered)
+                submit(options.fromStored(stored), false);
+            return recovered;
+        },
+        idle: () => queue.idle(),
+    };
+}

package/dist/channels/kit/turn-store.d.ts

@@ -1,3 +1,4 @@
+import type { ContextBuffer } from "./context-buffer.ts";
 /** What every persisted turn record carries regardless of channel: identity, the session whose FIFO
  *  chain it runs on, and how many times it has STARTED executing without finishing (0 until its first
  *  run; bumped at each `startAttempt`). The channel's record type extends this with everything its
@@ -20,14 +21,14 @@ export interface TurnStore<T extends TurnRecordBase> {
     recover(): T[];
     /** Called when a turn is about to RUN (dequeued). Returns:
      *   - "run": bumped its persisted execution count; go ahead.
-     *   - "exceeded": over `maxAttempts` starts without finishing (killed mid-run every time, whatever the
-     *     cause); the record is dropped and the runner notifies the asker.
+     *   - "exceeded": over {@link MAX_TURN_ATTEMPTS} starts without finishing (killed mid-run every time,
+     *     whatever the cause); the record is dropped and the runner notifies the asker.
      *   - "defer": the bump could not be persisted — skip this cycle (fail closed: an unpersisted count
      *     would let a poison turn re-run forever); the record stays on disk and replays on the next start
      *     (a restart is required — disk recovery alone does not re-run it). The runner does NOT notify.
      *  An id with no record returns "run" (untracked): a completed turn's `remove` cleared it, so the
      *  redelivery-double-run tail (see the header's pre-ACK window) lands here. */
-    startAttempt(id: string, maxAttempts: number): "run" | "exceeded" | "defer";
+    startAttempt(id: string): "run" | "exceeded" | "defer";
 }
 export interface TurnStoreOptions<T extends TurnRecordBase> {
     /** Log prefix naming the consumer (e.g. "[telegram]") — the store itself is channel-neutral. */
@@ -39,4 +40,19 @@ export interface TurnStoreOptions<T extends TurnRecordBase> {
      *  (telegram: numeric update_id; lark: an explicit per-record seq). */
     order: (a: T, b: T) => number;
 }
+/**
+ * End an ANSWERED turn: drop its durable intent, then commit the discussion it folded in.
+ *
+ * The ORDER is the safety property, which is why this is a function and not two lines at each call
+ * site. A crash between the two writes may re-fold already-answered context into the next summon —
+ * additive and harmless. The reverse order leaves intent on disk with its context already consumed,
+ * so the replay runs the same turn with its context stripped.
+ *
+ * Called from the turn's `completed` event, when the fold provably lives in the durable session.
+ */
+export declare function commitAnsweredTurn<T extends TurnRecordBase, E>(store: TurnStore<T>, buffer: ContextBuffer<E>, turn: {
+    id: string;
+    bufferKey: string;
+    consumed: E[];
+}): void;
 export declare function createTurnStore<T extends TurnRecordBase>(path: string, opts: TurnStoreOptions<T>): TurnStore<T>;

package/dist/channels/kit/turn-store.js

@@ -51,6 +51,33 @@
  */
 import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
+/**
+ * How many times a turn may START without finishing before it is dropped rather than run again — the
+ * poison-turn ceiling described at length above. One value for every channel: it prices replay against
+ * DEPLOY frequency, which is a property of how fastagent is operated, not of which chat platform is in
+ * front of it.
+ *
+ * Known limitation: the count cannot tell a self-inflicted crash from an external SIGTERM (there is no
+ * graceful drain), so a legitimately long turn interrupted by this many successive deploys is dropped
+ * as if it were poison. Three is a bet that such a turn is an outlier, not a defence against one:
+ * catching SIGTERM to spare it would reintroduce the drain the design refuses — raise this constant
+ * instead if such turns are expected.
+ */
+const MAX_TURN_ATTEMPTS = 3;
+/**
+ * End an ANSWERED turn: drop its durable intent, then commit the discussion it folded in.
+ *
+ * The ORDER is the safety property, which is why this is a function and not two lines at each call
+ * site. A crash between the two writes may re-fold already-answered context into the next summon —
+ * additive and harmless. The reverse order leaves intent on disk with its context already consumed,
+ * so the replay runs the same turn with its context stripped.
+ *
+ * Called from the turn's `completed` event, when the fold provably lives in the durable session.
+ */
+export function commitAnsweredTurn(store, buffer, turn) {
+    store.remove(turn.id);
+    buffer.commit(turn.bufferKey, turn.consumed);
+}
 export function createTurnStore(path, opts) {
     const { label, isRecord, order } = opts;
     const load = () => {
@@ -102,12 +129,12 @@ export function createTurnStore(path, opts) {
             // happening to survive the load's JSON round-trip.
             return [...turns.values()].sort(order);
         },
-        startAttempt(id, maxAttempts) {
+        startAttempt(id) {
             const rec = turns.get(id);
             if (!rec)
                 return "run"; // no record — run untracked (a redelivery double-run whose first run removed it)
             const attempts = rec.attempts + 1;
-            if (attempts > maxAttempts) {
+            if (attempts > MAX_TURN_ATTEMPTS) {
                 // State the fact, not a cause the counter can't prove: a turn killed mid-run every time bumps
                 // this whether IT poisoned the process or a deploy/OOM took it down each time.
                 log.error(`${label} dropping turn ${id} after starting ${rec.attempts} time(s) without finishing ` +

package/dist/channels/lark/scaffold/lark-send.ts

@@ -1,58 +1,8 @@
 import { defineTool, z } from "@fastagent-sh/fastagent";
+import { larkTransport } from "@fastagent-sh/fastagent/lark";
 
-// Send a message to a Lark chat. In a CHAT turn the channel delivers the reply itself — this
-// tool is for turns NO channel is carrying: a scheduled turn (schedules/<name>.ts) or a self-scheduled
-// wake-up, whose plain reply is not delivered anywhere. The chatId comes from the [lark: chat …]
-// context line in a chat turn; a scheduled turn has no such line, so the schedule's prompt must name
-// the target chat id. tools/ is auto-discovered.
-
-// Embedded copy of the channel transport's discipline: a timeout so a wedged connection can't hang
-// the tool call (and the turn), named errors, and success gated on the body's own code===0.
-// Deliberately NO rate-limit retry — a tool error goes back to the agent, which can decide to retry;
-// fail-fast beats a silently sleeping tool.
-const BASE = "https://open.larksuite.com";
-
-async function callApi(path: string, body: unknown, token?: string): Promise<Record<string, unknown>> {
-  let res: Response;
-  let raw: string;
-  try {
-    res = await fetch(`${BASE}${path}`, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json; charset=utf-8",
-        ...(token ? { authorization: `Bearer ${token}` } : {}),
-      },
-      body: JSON.stringify(body),
-      signal: AbortSignal.timeout(30_000),
-    });
-    raw = await res.text();
-  } catch (e) {
-    throw new Error(`lark ${path}: ${String(e)}`, { cause: e });
-  }
-  let data: { code?: number; msg?: string; [k: string]: unknown };
-  try {
-    data = JSON.parse(raw) as typeof data;
-  } catch {
-    data = {};
-  }
-  if (!res.ok || data.code !== 0) {
-    throw new Error(`lark ${path} failed: ${res.status} ${data.msg ?? "response was not the expected JSON"}`);
-  }
-  return data;
-}
-
-async function tenantToken(): Promise<string> {
-  const appId = process.env.LARK_APP_ID;
-  const appSecret = process.env.LARK_APP_SECRET;
-  if (!appId || !appSecret) throw new Error("LARK_APP_ID / LARK_APP_SECRET are not set");
-  const data = await callApi("/open-apis/auth/v3/tenant_access_token/internal", {
-    app_id: appId,
-    app_secret: appSecret,
-  });
-  const token = data.tenant_access_token;
-  if (typeof token !== "string") throw new Error("lark tenant_access_token: response carried no token");
-  return token;
-}
+// Proactive delivery uses the mounted channel's credentials, gateway and token cache. With no
+// channel mounted (fire/invoke/tool), it reads LARK_APP_ID / LARK_APP_SECRET from the environment.
 
 export default defineTool({
   description:
@@ -70,23 +20,18 @@ export default defineTool({
     text: z.string().optional().describe("plain text message to send"),
     markdown: z.string().optional().describe("markdown to send as a card"),
   }),
-  async execute({ chatId, text, markdown }) {
+  async execute({ chatId, text, markdown }, ctx) {
     if ((text === undefined) === (markdown === undefined)) {
       throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
     }
-    const token = await tenantToken();
-    const msg =
-      text !== undefined
-        ? { msg_type: "text", content: JSON.stringify({ text }) }
-        : {
-            msg_type: "interactive",
-            // An inline static card: one markdown element, no entity/streaming machinery needed here.
-            content: JSON.stringify({
-              schema: "2.0",
-              body: { elements: [{ tag: "markdown", content: markdown }] },
-            }),
-          };
-    await callApi(`/open-apis/im/v1/messages?receive_id_type=chat_id`, { receive_id: chatId, ...msg }, token);
+    const api = larkTransport(ctx.cwd);
+    if (text !== undefined) await api.sendText({ chatId }, text);
+    else {
+      await api.sendMessage(chatId, "interactive", JSON.stringify({
+        schema: "2.0",
+        body: { elements: [{ tag: "markdown", content: markdown }] },
+      }));
+    }
     return `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}`;
   },
 });

package/dist/channels/registration.d.ts

@@ -10,6 +10,41 @@
  *   unreachable) and a cloud without the config API (the Lark cloud-lag 404 — no re-run can ever
  *   register it; the console is the only path).
  * - "failed": this run ends with the webhook NOT registered, and acting + re-running can fix it
- *   (health timeout, a permanent config error, exhausted retries).
+ *   (a permanent config error, or the platform still unable to reach the URL when the retries ran out).
  */
 export type RegistrationOutcome = "registered" | "manual" | "failed";
+export declare const REGISTRATION_RETRY_MS = 10000;
+/**
+ * What `deploy --run` spends instead: 180s, because a host CLI returns before the deployment serves —
+ * the same gap a tunnel has, on a scale no local signal reports (`docker compose --tunnel` is the one
+ * host whose ingress does report it, and its driver waits on it the way the tunnel does).
+ *
+ * `railway up --ci` returns when the BUILD ends — container start, healthcheck and a freshly minted
+ * domain's DNS all happen after that, and railway-deploy.live.test.ts allows 180s for exactly this.
+ * Registration failure GATES the deploy (registration-gate.ts), so a budget shorter than the host's
+ * own start-up turns a working deployment into a re-run instruction.
+ *
+ * N attempts buy (N - 1) waits — {@link retryWhile} only waits BETWEEN calls — so 180s of patience is
+ * 19, not 18. At 18 the last call went out at t=170s and a host that started answering in the final
+ * ten seconds was still reported as a deploy to re-run.
+ */
+export declare const DEPLOY_REGISTRATION_ATTEMPTS = 19;
+/**
+ * Call, and while `retryable` says the failure is the platform not reaching the URL YET, call again —
+ * the one retry loop every registrar spends {@link REGISTRATION_ATTEMPTS} through. Retryability and
+ * what a final failure MEANS stay with each platform (their vocabularies differ, and one registrar's
+ * terminal state is another's `"manual"`); the counting, the announcement and the wait do not.
+ *
+ * `onRetry` runs BEFORE the wait — registrars announce there (a silent minute reads as a hang), and
+ * `add slack` also drops its duplicate-guard marker so it never spans a sleep. The last error is
+ * thrown, so a caller can tell "still unreachable" from "a config error" in one place.
+ */
+export declare function retryWhile<T>(call: () => Promise<T>, retryable: (error: unknown) => boolean, options?: {
+    attempts?: number;
+    retryMs?: number;
+    onRetry?: (info: {
+        attempt: number;
+        attempts: number;
+        error: unknown;
+    }) => void;
+}): Promise<T>;

package/dist/channels/registration.js

@@ -1 +1,57 @@
-export {};
+/**
+ * SHARED: how long a registrar waits for the PLATFORM to be able to reach a freshly minted public URL.
+ * One judgement (a new tunnel's warm-up), so one pair of numbers — telegram, feishu, slack registration
+ * and `add slack` all spend it.
+ *
+ * Sized for a tunnel, which is live before its URL is HANDED OVER — not before it is printed, which is
+ * what this budget once had to absorb: a quick tunnel's hostname is published when the tunnel registers
+ * an edge connection, seconds after cloudflared prints it, and no budget covers a platform that already
+ * answered "cannot resolve" (#435). `startCloudflareTunnel` waits for that connection, so what is left
+ * here is the platform's own warm-up. Applied by {@link retryWhile} as its default; a DEPLOY is slower
+ * and its callers pass {@link DEPLOY_REGISTRATION_ATTEMPTS} instead.
+ */
+const REGISTRATION_ATTEMPTS = 8;
+export const REGISTRATION_RETRY_MS = 10_000;
+/**
+ * What `deploy --run` spends instead: 180s, because a host CLI returns before the deployment serves —
+ * the same gap a tunnel has, on a scale no local signal reports (`docker compose --tunnel` is the one
+ * host whose ingress does report it, and its driver waits on it the way the tunnel does).
+ *
+ * `railway up --ci` returns when the BUILD ends — container start, healthcheck and a freshly minted
+ * domain's DNS all happen after that, and railway-deploy.live.test.ts allows 180s for exactly this.
+ * Registration failure GATES the deploy (registration-gate.ts), so a budget shorter than the host's
+ * own start-up turns a working deployment into a re-run instruction.
+ *
+ * N attempts buy (N - 1) waits — {@link retryWhile} only waits BETWEEN calls — so 180s of patience is
+ * 19, not 18. At 18 the last call went out at t=170s and a host that started answering in the final
+ * ten seconds was still reported as a deploy to re-run.
+ */
+export const DEPLOY_REGISTRATION_ATTEMPTS = 19;
+/** Sleep on the GLOBAL timer (not `node:timers/promises`) so tests can drive it with fake timers — the
+ *  same reason feishu-api.ts does. What must happen BEFORE this wait is the point of `onRetry`. */
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Call, and while `retryable` says the failure is the platform not reaching the URL YET, call again —
+ * the one retry loop every registrar spends {@link REGISTRATION_ATTEMPTS} through. Retryability and
+ * what a final failure MEANS stay with each platform (their vocabularies differ, and one registrar's
+ * terminal state is another's `"manual"`); the counting, the announcement and the wait do not.
+ *
+ * `onRetry` runs BEFORE the wait — registrars announce there (a silent minute reads as a hang), and
+ * `add slack` also drops its duplicate-guard marker so it never spans a sleep. The last error is
+ * thrown, so a caller can tell "still unreachable" from "a config error" in one place.
+ */
+export async function retryWhile(call, retryable, options = {}) {
+    const attempts = options.attempts ?? REGISTRATION_ATTEMPTS;
+    const retryMs = options.retryMs ?? REGISTRATION_RETRY_MS;
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (attempt >= attempts || !retryable(error))
+                throw error;
+            options.onRetry?.({ attempt, attempts, error });
+            await wait(retryMs);
+        }
+    }
+}

package/dist/channels/secret.d.ts

@@ -0,0 +1 @@
+export declare function secretEquals(given: unknown, expected: string | undefined): boolean;

package/dist/channels/secret.js

@@ -0,0 +1,16 @@
+/**
+ * The ONE constant-time comparison every shared-secret gate uses: a webhook secret token, a
+ * signature, a bearer token, an envelope secret. Timing-safe on equal lengths; a length mismatch
+ * answers false without leaking a prefix. Non-string input reads as no secret — and an EMPTY
+ * expected value never matches, so a gate whose secret was never configured cannot be passed by
+ * sending none.
+ */
+import { Buffer } from "node:buffer";
+import { timingSafeEqual } from "node:crypto";
+export function secretEquals(given, expected) {
+    if (typeof given !== "string" || !expected)
+        return false;
+    const a = Buffer.from(given);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}

package/dist/channels/slack/config-api.d.ts

@@ -10,8 +10,40 @@ interface SlackErrorShape {
 export declare class SlackConfigApiError extends Error {
     readonly code: string;
     readonly status: number;
+    /** Kept, not just formatted into the message: which FIELD Slack rejected is how a caller tells a
+     *  not-yet-reachable URL from a malformed one, and a message match cannot see the difference. */
+    readonly errors: {
+        message?: string;
+        pointer?: string;
+    }[];
     constructor(method: string, status: number, data: SlackErrorShape, fallback: string);
 }
+/**
+ * Whether a manifest call failed because Slack could not verify the `request_url` it carries — the
+ * platform's own readiness verdict on a freshly minted public URL, and the reason no local `/health`
+ * poll precedes these calls (#421). Slack validates the manifest BEFORE acting on it, so a call that
+ * ends here changed nothing and is safe to repeat.
+ *
+ * Read from the rejected FIELD (`invalid_manifest` + {@link rejectsRequestUrl}), not from `request_url`
+ * appearing anywhere in the formatted string: that also matched errors which merely mention the field.
+ *
+ * KNOWN IMPRECISION: this cannot separate "not reachable yet" from "this URL is unacceptable" — both
+ * arrive the same way, and the wording that would tell them apart has not been observed against the
+ * real API, so guessing at it would risk never retrying at all. A permanently bad URL therefore costs
+ * the full budget before it is reported. Every URL here is a tunnel's or a host's, so it is well-formed
+ * https by construction; narrow this the day a real rejection is captured.
+ */
+export declare function isSlackRequestUrlUnverified(error: unknown): boolean;
+/**
+ * Whether a manifest write was refused because the app has token rotation on, which Slack never lets
+ * off again — the refusal every app created by a release up to 0.20 meets, since this release sends
+ * `token_rotation_enabled: false`. Slack documents field rejections as `invalid_manifest` plus an
+ * `errors[]` of message + pointer; the bare code was what a real refusal once showed. Both shapes are
+ * read: a miss here sends the operator to repair configuration tokens that are not the problem.
+ */
+export declare function isSlackRotationLocked(error: unknown): boolean;
+/** The upgrade every rotating-app refusal points at. */
+export declare const SLACK_ROTATING_APP_UPGRADE = "this app has token rotation on, which this release no longer uses and Slack cannot turn off \u2014 create a new app (docs/slack.md \u2192 \"Upgrading from a rotating-token app\")";
 export interface SlackAppCredentials {
     appId: string;
     clientId: string;
@@ -19,7 +51,9 @@ export interface SlackAppCredentials {
     signingSecret: string;
     oauthAuthorizeUrl?: string;
 }
-/** Create is intentionally single-attempt: an ambiguous response may already have created the app. */
+/** Single-attempt BY DESIGN: an ambiguous response may already have created the app, so this never
+ *  retries itself. The one repeatable failure — a `request_url` Slack could not verify, which it
+ *  rejects before creating anything — is retried by the caller ({@link isSlackRequestUrlUnverified}). */
 export declare function createSlackApp(configToken: string, manifest: SlackAppManifest, options?: {
     apiBaseUrl?: string;
     fetch?: typeof fetch;
@@ -40,8 +74,6 @@ export declare function rotateSlackConfigToken(refreshToken: string, options?: {
 }): Promise<RotatedSlackConfigToken>;
 export interface SlackOAuthResult {
     botToken: string;
-    botRefreshToken: string;
-    botTokenExpiresAt: number;
     appId: string;
     teamId: string;
     teamName?: string;

package/dist/channels/slack/config-api.js

@@ -1,8 +1,20 @@
 const SLACK_API = "https://slack.com/api";
 const REQUEST_TIMEOUT_MS = 30_000;
+/** One `errors[]` entry that means "Slack could not verify this URL", by either signal it may carry.
+ *  The pointer is the precise one but an INFERENCE — the only reply captured from the real API is the
+ *  PERMANENT shape error, which reports on the parent pointer (`/settings/event_subscriptions`). If the
+ *  unverifiable case reports there too, a pointer-only check would retry zero times and gate the deploy
+ *  immediately, which is the failure this whole path exists to prevent. So a message about VERIFICATION
+ *  (challenge wording included) counts as well, while one that merely names the field does not — the
+ *  captured permanent error says "Event Subscription requires a Request URL". */
+const rejectsRequestUrl = (e) => e.pointer?.endsWith("/request_url") === true ||
+    (/request.?url/i.test(e.message ?? "") && /verif|challenge/i.test(e.message ?? ""));
 export class SlackConfigApiError extends Error {
     code;
     status;
+    /** Kept, not just formatted into the message: which FIELD Slack rejected is how a caller tells a
+     *  not-yet-reachable URL from a malformed one, and a message match cannot see the difference. */
+    errors;
     constructor(method, status, data, fallback) {
         const code = data.error ?? fallback;
         const fields = data.errors
@@ -12,8 +24,42 @@ export class SlackConfigApiError extends Error {
         this.name = "SlackConfigApiError";
         this.code = code;
         this.status = status;
+        this.errors = data.errors ?? [];
     }
 }
+/**
+ * Whether a manifest call failed because Slack could not verify the `request_url` it carries — the
+ * platform's own readiness verdict on a freshly minted public URL, and the reason no local `/health`
+ * poll precedes these calls (#421). Slack validates the manifest BEFORE acting on it, so a call that
+ * ends here changed nothing and is safe to repeat.
+ *
+ * Read from the rejected FIELD (`invalid_manifest` + {@link rejectsRequestUrl}), not from `request_url`
+ * appearing anywhere in the formatted string: that also matched errors which merely mention the field.
+ *
+ * KNOWN IMPRECISION: this cannot separate "not reachable yet" from "this URL is unacceptable" — both
+ * arrive the same way, and the wording that would tell them apart has not been observed against the
+ * real API, so guessing at it would risk never retrying at all. A permanently bad URL therefore costs
+ * the full budget before it is reported. Every URL here is a tunnel's or a host's, so it is well-formed
+ * https by construction; narrow this the day a real rejection is captured.
+ */
+export function isSlackRequestUrlUnverified(error) {
+    return (error instanceof SlackConfigApiError && error.code === "invalid_manifest" && error.errors.some(rejectsRequestUrl));
+}
+/**
+ * Whether a manifest write was refused because the app has token rotation on, which Slack never lets
+ * off again — the refusal every app created by a release up to 0.20 meets, since this release sends
+ * `token_rotation_enabled: false`. Slack documents field rejections as `invalid_manifest` plus an
+ * `errors[]` of message + pointer; the bare code was what a real refusal once showed. Both shapes are
+ * read: a miss here sends the operator to repair configuration tokens that are not the problem.
+ */
+export function isSlackRotationLocked(error) {
+    if (!(error instanceof SlackConfigApiError))
+        return false;
+    return (error.code === "cannot_disable_once_enabled" ||
+        error.errors.some((e) => e.message?.includes("cannot_disable_once_enabled") || e.pointer?.endsWith("token_rotation_enabled")));
+}
+/** The upgrade every rotating-app refusal points at. */
+export const SLACK_ROTATING_APP_UPGRADE = 'this app has token rotation on, which this release no longer uses and Slack cannot turn off — create a new app (docs/slack.md → "Upgrading from a rotating-token app")';
 async function slackJson(method, body, options = {}) {
     const fetchFn = options.fetch ?? globalThis.fetch;
     let response;
@@ -45,7 +91,9 @@ async function slackJson(method, body, options = {}) {
     }
     return data;
 }
-/** Create is intentionally single-attempt: an ambiguous response may already have created the app. */
+/** Single-attempt BY DESIGN: an ambiguous response may already have created the app, so this never
+ *  retries itself. The one repeatable failure — a `request_url` Slack could not verify, which it
+ *  rejects before creating anything — is retried by the caller ({@link isSlackRequestUrlUnverified}). */
 export async function createSlackApp(configToken, manifest, options = {}) {
     const data = await slackJson("apps.manifest.create", { manifest: JSON.stringify(manifest) }, { ...options, token: configToken });
     const credentials = data.credentials;
@@ -126,17 +174,11 @@ export async function exchangeSlackOAuthCode(input, options = {}) {
     }
     if (!response.ok || data.ok !== true)
         throw slackOAuthFailure(response.status, data.error);
-    if (!data.access_token ||
-        !data.refresh_token ||
-        typeof data.expires_in !== "number" ||
-        !data.app_id ||
-        !data.team?.id) {
-        throw new Error("Slack oauth.v2.access succeeded but returned incomplete rotating bot credentials/app identity");
+    if (!data.access_token || !data.app_id || !data.team?.id) {
+        throw new Error("Slack oauth.v2.access succeeded but returned incomplete bot credentials/app identity");
     }
     return {
         botToken: data.access_token,
-        botRefreshToken: data.refresh_token,
-        botTokenExpiresAt: Date.now() + data.expires_in * 1_000,
         appId: data.app_id,
         teamId: data.team.id,
         teamName: data.team.name,