@fastagent-sh/fastagent 0.20.0 → 0.21.1

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,

package/dist/channels/slack/manifest.js

@@ -63,7 +63,11 @@ export function buildSlackManifest(input) {
                 : {}),
             org_deploy_enabled: false,
             socket_mode_enabled: false,
-            token_rotation_enabled: true,
+            // Off, and Slack makes the alternative permanent: an app with rotation on can never turn it off
+            // (`cannot_disable_once_enabled`, verified against the API). Rotation would ship the refresh token
+            // and the client secret to every host beside the access token — the same blast radius as one
+            // long-lived bot token, plus a 12-hour refresh lineage to keep single and durable.
+            token_rotation_enabled: false,
         },
     };
 }

package/dist/channels/slack/onboard.d.ts

@@ -10,13 +10,10 @@ export interface SlackOnboardIO {
         state?: string;
         error?: string;
     }>;
-    /** Stage runtime-only credentials into the gitignored .env. */
+    /** Stage the runtime secrets into the gitignored .env — the bot token and the signing secret, nothing
+     *  else: the client credentials are setup-only (the OAuth code exchange) and stay in onboarding state. */
     writeRuntimeSecrets(values: {
         botToken?: string;
-        botRefreshToken?: string;
-        botTokenExpiresAt?: number;
-        clientId?: string;
-        clientSecret?: string;
         signingSecret?: string;
     }): Promise<void>;
 }
@@ -31,6 +28,9 @@ export declare function onboardSlackApp(input: SlackOnboardInput, io: SlackOnboa
     createApp?: typeof createSlackApp;
     updateManifest?: typeof updateSlackAppManifest;
     exchangeCode?: typeof exchangeSlackOAuthCode;
+    /** Attempts absorbing the setup tunnel's warm-up before Slack can verify its URL. */
+    attempts?: number;
+    retryMs?: number;
 }): Promise<SlackOnboardingState>;
 export declare function newSlackOnboardingState(input: {
     appName: string;

package/dist/channels/slack/onboard.js

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
-import { createSlackApp, exchangeSlackOAuthCode, SlackConfigApiError, updateSlackAppManifest } from "./config-api.js";
+import { retryWhile } from "../registration.js";
+import { createSlackApp, exchangeSlackOAuthCode, isSlackRequestUrlUnverified, isSlackRotationLocked, SLACK_ROTATING_APP_UPGRADE, SlackConfigApiError, updateSlackAppManifest, } from "./config-api.js";
 import { buildSlackManifest, slackBotScopes } from "./manifest.js";
 import { currentSlackConfigToken, writeSlackOnboardingState } from "./onboarding-state.js";
 /** Create/resume one internal Slack app and complete its workspace OAuth installation. */
@@ -7,6 +8,16 @@ export async function onboardSlackApp(input, io, deps = {}) {
     let state = input.state;
     const current = await currentSlackConfigToken(input.stateRoot, state);
     state = current.state;
+    /** Slack challenges request_url from ITS network during a manifest call and validates the whole
+     *  manifest before acting, so an unverifiable URL created nothing and the call is safe to repeat. */
+    const whileUnverified = (call, onRetry) => retryWhile(call, isSlackRequestUrlUnverified, {
+        attempts: deps.attempts,
+        retryMs: deps.retryMs,
+        onRetry: ({ attempt, attempts }) => {
+            onRetry?.();
+            io.note(`Slack cannot reach the temporary setup URL yet (attempt ${attempt}/${attempts}); retrying…`);
+        },
+    });
     const manifest = buildSlackManifest({
         name: state.appName,
         groupBehavior: state.groupBehavior,
@@ -19,21 +30,26 @@ export async function onboardSlackApp(input, io, deps = {}) {
                 "Inspect https://api.slack.com/apps before retrying; if an app exists, delete that incomplete app first, then remove the local Slack onboarding state and re-run");
         }
         io.note("Creating the internal Slack app from its FastAgent manifest…");
-        // Record BEFORE the non-idempotent API call. A transport/internal failure may have created the app;
-        // refusing a blind retry is safer than silently producing duplicates.
-        state = { ...state, createAttemptedAt: new Date().toISOString() };
-        writeSlackOnboardingState(input.stateRoot, state);
+        const setMarker = (value) => {
+            state = { ...state, createAttemptedAt: value };
+            writeSlackOnboardingState(input.stateRoot, state);
+        };
         let created;
         try {
-            created = await (deps.createApp ?? createSlackApp)(current.token, manifest);
+            created = await whileUnverified(() => {
+                // Record BEFORE the non-idempotent API call. A transport/internal failure may have created the
+                // app; refusing a blind retry is safer than silently producing duplicates. The marker spans
+                // exactly one in-flight call: an unverifiable URL created nothing, so it comes off again before
+                // the wait — a Ctrl-C during that wait must not wedge the next run on an app that never existed.
+                setMarker(new Date().toISOString());
+                return (deps.createApp ?? createSlackApp)(current.token, manifest);
+            }, () => setMarker(undefined));
         }
         catch (error) {
             const ambiguous = !(error instanceof SlackConfigApiError) ||
                 ["fatal_error", "internal_error", "request_timeout", "service_unavailable", "failed_creating_app"].includes(error.code);
-            if (!ambiguous) {
-                state = { ...state, createAttemptedAt: undefined };
-                writeSlackOnboardingState(input.stateRoot, state);
-            }
+            if (!ambiguous)
+                setMarker(undefined);
             throw error;
         }
         state = {
@@ -53,8 +69,17 @@ export async function onboardSlackApp(input, io, deps = {}) {
             throw new Error(`Slack app ${state.appId} exists but OAuth client credentials are no longer available — ` +
                 "the app appears already installed; set SLACK_BOT_TOKEN/SLACK_SIGNING_SECRET in .env or remove the app and onboarding state to start over");
         }
-        io.note(`Resuming Slack app ${state.appId}; refreshing its temporary setup URLs…`);
-        await (deps.updateManifest ?? updateSlackAppManifest)(current.token, state.appId, manifest);
+        const appId = state.appId;
+        io.note(`Resuming Slack app ${appId}; refreshing its temporary setup URLs…`);
+        try {
+            await whileUnverified(() => (deps.updateManifest ?? updateSlackAppManifest)(current.token, appId, manifest));
+        }
+        catch (error) {
+            // A resume of an app created with rotation on: the manifest is refused for good, so say what fixes it.
+            if (isSlackRotationLocked(error))
+                throw new Error(SLACK_ROTATING_APP_UPGRADE, { cause: error });
+            throw error;
+        }
     }
     if (state.signingSecret) {
         await io.writeRuntimeSecrets({ signingSecret: state.signingSecret });
@@ -70,7 +95,9 @@ export async function onboardSlackApp(input, io, deps = {}) {
     authorize.searchParams.set("scope", slackBotScopes(state.groupBehavior).join(","));
     authorize.searchParams.set("redirect_uri", input.redirectUrl);
     authorize.searchParams.set("state", oauthState);
-    io.note(`Approve the internal app installation in Slack: ${authorize}`);
+    // The redirect lands on the tunnel hostname, which THIS machine may not resolve yet (#421) — a broken
+    // page beside a terminal that looks hung, unless the reload is named before it happens.
+    io.note(`Click Allow in Slack to install the app: ${authorize}\nIf the page it returns to does not load, reload it.`);
     io.openUrl(authorize.toString());
     const callback = await io.waitForOAuth();
     if (callback.error)
@@ -90,13 +117,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
     if (slackBotScopes(state.groupBehavior).some((scope) => !oauth.scopes.includes(scope))) {
         throw new Error("Slack OAuth completed without all required bot scopes; re-run fastagent add slack to reinstall");
     }
-    await io.writeRuntimeSecrets({
-        botToken: oauth.botToken,
-        botRefreshToken: oauth.botRefreshToken,
-        botTokenExpiresAt: oauth.botTokenExpiresAt,
-        clientId: state.clientId,
-        clientSecret: state.clientSecret,
-    });
+    await io.writeRuntimeSecrets({ botToken: oauth.botToken });
     state = {
         ...state,
         clientSecret: undefined,

package/dist/channels/slack/register-webhook.d.ts

@@ -1,8 +1,9 @@
-import type { RegistrationOutcome } from "../registration.ts";
+import { type RegistrationOutcome } from "../registration.ts";
 export interface RegisterSlackWebhookOptions {
     stateRoot: string;
     log?: (message: string) => void;
-    healthTimeoutMs?: number;
+    attempts?: number;
+    retryMs?: number;
     apiBaseUrl?: string;
     fetch?: typeof fetch;
 }

package/dist/channels/slack/register-webhook.js

@@ -1,5 +1,5 @@
-import { waitForHealth } from "../wait-health.js";
-import { updateSlackAppManifest } from "./config-api.js";
+import { retryWhile } from "../registration.js";
+import { SLACK_ROTATING_APP_UPGRADE, isSlackRequestUrlUnverified, isSlackRotationLocked, updateSlackAppManifest, } from "./config-api.js";
 import { buildSlackManifest } from "./manifest.js";
 import { currentSlackConfigToken, readSlackOnboardingState } from "./onboarding-state.js";
 /** Update one onboarded internal Slack app without sending its configuration credential to the host. */
@@ -20,30 +20,50 @@ export async function registerSlackWebhook(baseUrl, options) {
             `(repair its expired/revoked tokens with \`fastagent add slack --replace-config\`)`);
         return "manual";
     }
-    const healthy = await waitForHealth(`${publicBaseUrl}/health`, options.healthTimeoutMs ?? 45_000, 500);
-    if (!healthy) {
-        note(`[fastagent] slack: ${publicBaseUrl}/health did not become reachable; Request URL was not changed`);
-        return "failed";
-    }
+    const consoleFallback = `set ${publicBaseUrl}/slack as the Event Subscriptions Request URL in the Slack console`;
+    let current;
     try {
-        const current = await currentSlackConfigToken(options.stateRoot, state, {
+        // Rotation is not retried with the manifest below: each rotate invalidates the previous pair, so a
+        // repeat would spend tokens on a failure that is about the URL, not about the credential.
+        current = await currentSlackConfigToken(options.stateRoot, state, {
             apiBaseUrl: options.apiBaseUrl,
             fetch: options.fetch,
         });
-        await updateSlackAppManifest(current.token, current.state.appId, buildSlackManifest({
+    }
+    catch (error) {
+        note(`[fastagent] slack: could not refresh the App Configuration token: ${String(error)} — ` +
+            `re-run \`fastagent add slack --replace-config\` to repair it, or ${consoleFallback}`);
+        return "failed";
+    }
+    // Slack verifies the new request_url with a challenge DURING apps.manifest.update, from Slack's own
+    // network — that verdict IS the readiness signal, so it is retried while a fresh tunnel/container
+    // warms up. No local `/health` poll precedes it: this machine's reach is the wrong question (#421).
+    try {
+        await retryWhile(() => updateSlackAppManifest(current.token, current.state.appId, buildSlackManifest({
             name: current.state.appName,
             groupBehavior: current.state.groupBehavior,
             requestUrl: `${publicBaseUrl}/slack`,
-            // Token-rotation manifests require at least one OAuth redirect URL even after installation.
-            // Actual reinstall flows replace this placeholder with their one-shot local setup callback.
+            // A manifest update replaces the whole manifest and redirect_urls may not be empty, so a
+            // placeholder is declared; a reinstall replaces it with its one-shot local setup callback.
             redirectUrl: `${publicBaseUrl}/slack/oauth/callback`,
-        }), { apiBaseUrl: options.apiBaseUrl, fetch: options.fetch });
+        }), { apiBaseUrl: options.apiBaseUrl, fetch: options.fetch }), isSlackRequestUrlUnverified, {
+            attempts: options.attempts,
+            retryMs: options.retryMs,
+            onRetry: ({ attempt, attempts }) => note(`[fastagent] slack: Slack cannot verify ${publicBaseUrl}/slack yet (attempt ${attempt}/${attempts}); retrying…`),
+        });
         note(`[fastagent] slack: Event Subscriptions Request URL registered → ${publicBaseUrl}/slack`);
         return "registered";
     }
     catch (error) {
-        note(`[fastagent] slack: automatic Request URL registration failed: ${String(error)} — ` +
-            `re-run \`fastagent add slack --replace-config\` to repair the configuration tokens, or set ${publicBaseUrl}/slack in the Slack console`);
+        if (isSlackRotationLocked(error)) {
+            note(`[fastagent] slack: ${SLACK_ROTATING_APP_UPGRADE}, or ${consoleFallback}`);
+            return "failed";
+        }
+        note(isSlackRequestUrlUnverified(error)
+            ? `[fastagent] slack: Slack could not verify ${publicBaseUrl}/slack after retries (last error: ${String(error)}) — ` +
+                `once the app is up, ${consoleFallback}`
+            : `[fastagent] slack: automatic Request URL registration failed: ${String(error)} — ` +
+                `re-run \`fastagent add slack --replace-config\` to repair the configuration tokens, or ${consoleFallback}`);
         return "failed";
     }
 }

package/dist/channels/slack/scaffold/channel.ts

@@ -8,18 +8,11 @@ import { slackChannel } from "@fastagent-sh/fastagent/slack";
 //   3. Event Subscriptions: app_home_opened, app_context_changed, app_mention, message.im,
 //      message.channels, message.groups, and message.mpim. Mention-only may omit the last three.
 //      Set Request URL to https://<host>/slack.
-//   4. Enable token rotation and install/reinstall the app after changing scopes. Rotating credentials
-//      are written by `fastagent add slack`; manual long-lived tokens may omit the four rotation fields.
+//   4. Install the app (reinstall after changing scopes) and leave token rotation OFF: it cannot be
+//      turned off again, and this channel takes one long-lived Bot User OAuth Token.
 export default slackChannel({
-  botToken: process.env.SLACK_BOT_TOKEN ?? "", // Bot User OAuth Token (xoxb-… or rotating xoxe.xoxb-…)
+  botToken: process.env.SLACK_BOT_TOKEN ?? "", // OAuth & Permissions → Bot User OAuth Token (xoxb-…)
   signingSecret: process.env.SLACK_SIGNING_SECRET ?? "", // Basic Information → App Credentials
-  botRefreshToken: process.env.SLACK_BOT_REFRESH_TOKEN || undefined,
-  clientId: process.env.SLACK_CLIENT_ID || undefined,
-  clientSecret: process.env.SLACK_CLIENT_SECRET || undefined,
-  botTokenExpiresAt: process.env.SLACK_BOT_TOKEN_EXPIRES_AT
-    ? Number(process.env.SLACK_BOT_TOKEN_EXPIRES_AT)
-    : undefined,
-  groupBehavior: "context", // default; use "mentions" only for an explicit least-privilege setup
   // Slack Agent stream; its inline tool traces show each call's first argument and stay in the
   // delivered message. "classic" settles into the answer alone (and gives up native streaming).
   rendering: "native",