@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/channels/wait-health.js

@@ -1,19 +1,13 @@
 /**
- * Readiness probe for a server THIS process can reach directly — the local port `deploy docker --run`
- * just published, and the live probes' own origins.
- *
- * NOT a probe for a public URL a platform must reach: a freshly minted hostname (a quick tunnel, a
- * fresh deploy) is routinely unreachable from here for a minute or more while the platform reaches it
- * fine, and polling it hard from t+0 makes that worse (#421). The webhook registrars therefore let the
- * platform's own URL verification be the probe, retried, instead of gating on this.
+ * Readiness probe for a server THIS process can reach over HTTP — the local port `deploy docker --run` just
+ * published, the live probes' own origins, and the public URL a host deploy must clear before it registers a webhook
+ * (`publicHealthGate` in deploy/channel-ingress.ts).
  */
 import { setTimeout as sleep } from "node:timers/promises";
-/**
- * Poll `healthUrl` until it responds 200, or the timeout elapses. Any error (not routable yet, DNS not
- * settled, connection refused) is a "keep waiting", not a failure — that IS the readiness signal. Each
- * probe has its own short timeout so one slow attempt can't eat the whole budget.
- */
-export async function waitForHealth(healthUrl, timeoutMs, intervalMs) {
+/** Poll `healthUrl` until it responds 200, or the timeout elapses. */
+export async function waitForHealth(healthUrl, timeoutMs, intervalMs, 
+/** Optional liveness answer from whoever runs the server. */
+stillStarting) {
     const deadline = Date.now() + timeoutMs;
     for (;;) {
         try {
@@ -21,10 +15,12 @@ export async function waitForHealth(healthUrl, timeoutMs, intervalMs) {
                 return true;
         }
         catch {
-            /* not routable yet — keep polling until the deadline */
+            // not routable yet — keep polling until the deadline
         }
         if (Date.now() >= deadline)
             return false;
+        if (stillStarting && !(await stillStarting()))
+            return false;
         await sleep(intervalMs);
     }
 }

package/dist/cli/add-feishu.d.ts

@@ -11,20 +11,10 @@ export declare function configureGroupBehavior(input: {
     apiBase: string;
     api: Pick<FeishuApi, "listAppScopes" | "addAppScopes">;
     behavior: FeishuGroupBehavior;
-    /** Whether the author chose the behavior (flag or prompt). A defaulted "context" inspects and
-     * reports only — it must never PATCH the sensitive scope into the app draft. */
+    /** Whether the author chose the behavior (flag or prompt). */
     explicit: boolean;
     note?: (message: string) => void;
     openUrl?: (url: string) => void;
 }): Promise<GroupBehaviorSetup>;
-/**
- * Create or resume the platform app behind `add feishu` / `add lark`. `target` is the AGENT DIR;
- * credentials land in its `.env` — whose real path is {@link dotEnvPath}, printed rather than spelled,
- * because `FASTAGENT_SECRETS_DIR` moves it and a hardcoded `.secrets/.env` would name a file this run
- * did not write. Returns credentials for the
- * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
- * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
- * irreversible and must not wait for the caller). Throws on refusal (a non-interactive lark run);
- * the caller surfaces that as a startup failure.
- */
+/** Create or resume the platform app behind `add feishu` / `add lark`. */
 export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehaviorChoice): Promise<Record<string, string> | undefined>;

package/dist/cli/add-feishu.js

@@ -1,13 +1,6 @@
 /**
- * `fastagent add feishu|lark` app onboarding — the cloud-facing half of runAdd, kept out of cli.ts
- * (which self-executes on import), mirroring models-view.ts/auth-view.ts. The POLICY already lives in
- * testable modules (register-app.ts, bootstrap-token.ts, lark/onboard.ts); this layer is the terminal
- * wiring: clack prompts, .env staging, browser opens, progress lines.
- *
- * Feishu (scan-to-create): the device flow creates the app and persists App ID/Secret at the
- * irreversible boundary. WebSocket stops there; webhook additionally captures the Verification Token
- * over a throwaway tunnel. Lark uses the unbound launcher + credential validation, then either stops
- * for WebSocket or probes the same webhook/token bootstrap with the config-route-404 manual fallback.
+ * `fastagent add feishu|lark` app onboarding — the cloud-facing half of runAdd, kept out of cli.ts (which
+ * self-executes on import), mirroring models-view.ts/auth-view.ts.
  */
 import { readFile } from "node:fs/promises";
 import { isCancel, log as clackLog, password, text as clackText } from "@clack/prompts";
@@ -36,14 +29,11 @@ export async function configureGroupBehavior(input) {
         scopes = [];
     }
     const granted = (name) => scopes.some((scope) => scope.name === name && scope.grantStatus === 1 && (scope.type === undefined || scope.type === "tenant"));
-    // Same type filter as `granted`: a user-type entry is not the tenant scope this path needs, so
-    // treating one as "on the app" would report an approval that can never arrive and skip the PATCH
-    // that would actually add it.
+    // Same type filter as `granted`: a user-type entry is not the tenant scope this path needs, so treating one as "on
+    // the app" would report an approval that can never arrive and skip the PATCH that would actually add it.
     const onApp = (name) => scopes.some((scope) => scope.name === name && (scope.type === undefined || scope.type === "tenant"));
-    // Both halves of the recommended path: delivery (the platform pushes un-mentioned group messages)
-    // and reading a quoted message (so a thread's opening ask carries what it replies to).
-    // The read capability has two spellings and `im:message` is the superset, so an app holding it needs
-    // nothing added — asking anyway would cost the author a second tenant-admin approval round.
+    // Both halves of the recommended path: delivery (the platform pushes un-mentioned group messages) and reading a
+    // quoted message (so a thread's opening ask carries what it replies to).
     const missing = FEISHU_CONTEXT_ONBOARDING_SCOPES.filter((entry) => !scopeSatisfied(entry, granted));
     const missingNames = missing.map((entry) => entry.request);
     if (behavior === "mentions") {
@@ -72,10 +62,7 @@ export async function configureGroupBehavior(input) {
         return { publishReady: true };
     }
     const permissionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/permission`;
-    // A missing scope is in one of two states, and they need different actions: already on the app but
-    // not yet approved (nothing to add — wait for the admin), or absent from the draft entirely.
-    // Same superset rule as `missing`: a draft already requesting `im:message` is awaiting approval, not
-    // missing something to add.
+    // A missing scope is in one of two states, and they need different actions.
     const awaitingApproval = missing.filter((entry) => scopeSatisfied(entry, onApp)).map((entry) => entry.request);
     const toRequest = missing.filter((entry) => !scopeSatisfied(entry, onApp)).map((entry) => entry.request);
     if (toRequest.length === 0) {
@@ -84,11 +71,8 @@ export async function configureGroupBehavior(input) {
         return { publishReady: false };
     }
     if (!explicit) {
-        // Defaulted, not chosen: report the gap and how to opt in, but leave the app's requested
-        // permission set untouched (a scripted re-run must not silently escalate a mention-only app).
-        // Name what is ACTUALLY missing: the common upgrade has the delivery scope already granted and
-        // only the read scope absent, and pointing at a granted permission sends the author looking in
-        // the wrong place.
+        // Defaulted, not chosen: report the gap and how to opt in, but leave the app's requested permission set untouched
+        // (a scripted re-run must not silently escalate a mention-only app).
         note(`[fastagent] ${missingNames.join(" + ")} not granted (or could not be verified) — group behavior was ` +
             `defaulted, so nothing was requested. Re-run with --group-behavior context to add ${missing.length > 1 ? "them" : "it"} ` +
             `to the app draft, or --group-behavior mentions to stay least-privilege: ${permissionUrl}`);
@@ -104,16 +88,7 @@ export async function configureGroupBehavior(input) {
     openUrl(permissionUrl);
     return { publishReady: false };
 }
-/**
- * Create or resume the platform app behind `add feishu` / `add lark`. `target` is the AGENT DIR;
- * credentials land in its `.env` — whose real path is {@link dotEnvPath}, printed rather than spelled,
- * because `FASTAGENT_SECRETS_DIR` moves it and a hardcoded `.secrets/.env` would name a file this run
- * did not write. Returns credentials for the
- * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
- * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
- * irreversible and must not wait for the caller). Throws on refusal (a non-interactive lark run);
- * the caller surfaces that as a startup failure.
- */
+/** Create or resume the platform app behind `add feishu` / `add lark`. */
 export async function onboardFeishuCloudApp(target, kind, ingress = "webhook", groupBehavior = { behavior: "context", explicit: false }) {
     const env = dotEnvPath(target); // the file actually written — never the default spelling
     const { envPrefix, apiBase, capabilities } = cloudFor(kind);
@@ -125,8 +100,7 @@ export async function onboardFeishuCloudApp(target, kind, ingress = "webhook", g
     const existing = await activeDotEnvValues(target, requiredNames);
     if (Object.keys(existing).length === requiredNames.length) {
         console.error(`[fastagent] ${requiredNames.join("/")} already set in ${env} — keeping them`);
-        // WebSocket still needs its console mode/publish guidance. A complete webhook can skip the rest of
-        // onboarding, but group visibility must still be inspected/configured on every explicit re-run.
+        // WebSocket still needs its console mode/publish guidance.
         if (ingress === "webhook") {
             const appId = existing[`${envPrefix}_APP_ID`];
             const appSecret = existing[`${envPrefix}_APP_SECRET`];
@@ -176,8 +150,7 @@ export async function onboardFeishuCloudApp(target, kind, ingress = "webhook", g
                     startTunnel: (port) => startCloudflareTunnel(port),
                     onTunnelReady: (url) => console.error(`[fastagent] temporary tunnel ready → ${url}; registering webhook mode now…`),
                     onPatchRetry: ({ error, attempt, attempts, retryMs }) => console.error(`[fastagent] Lark could not validate the fresh tunnel yet (${String(error)}); retrying PATCH ${attempt + 1}/${attempts} in ${Math.round(retryMs / 1000)}s…`),
-                    // A route-level 404 is definitive, not edge weather: fall back immediately. Retry only
-                    // actual edge/network weather; scope/auth/config failures remain immediate.
+                    // A route-level 404 is definitive, not edge weather: fall back immediately.
                     shouldRetryPatch: (error) => !isFeishuConfigApiMissing(error) && isTransientFeishuRegistrationError(error),
                 });
                 console.error(`[fastagent] Lark Verification Token captured; Subscription mode changed to webhook in the app draft`);
@@ -207,17 +180,7 @@ export async function onboardFeishuCloudApp(target, kind, ingress = "webhook", g
     });
     return Object.fromEntries(Object.entries(credentials).filter((entry) => typeof entry[1] === "string"));
 }
-/**
- * The scan-to-create flow `add feishu` runs by default. The device-authorization grant
- * creates a pre-configured agent app (bot capability, messaging scopes, event subscriptions) when the
- * user confirms a link, then persists App ID/Secret at the irreversible boundary. That completes
- * WebSocket credentials; webhook continues through challenge-captured Token persistence. The throwaway
- * Request URL is later replaced by `dev --tunnel` / `deploy --run`.
- *
- * Feishu is the reference cloud and the only kind that runs this BOUND device flow. Lark is an explicit
- * compatibility profile: its lagging control plane uses the unbound launcher + guided credentials,
- * then probes the canonical token/mode bootstrap with a manual fallback.
- */
+/** The scan-to-create flow `add feishu` runs by default. */
 async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
     const env = dotEnvPath(target); // the file actually written — never the default spelling
     const { apiBase } = cloudFor("feishu");
@@ -233,8 +196,7 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         const app = await registerFeishuApp({
             name: "{user}'s agent", // the platform expands {user} to the confirming user's name; editable on the page
             desc: "Served by fastagent",
-            // The agent template alone is not enough to SERVE (see feishuAppAddons). Sensitive group
-            // permission approval and version publishing remain explicit console work.
+            // The agent template alone is not enough to SERVE (see feishuAppAddons).
             addons: feishuAppAddons(),
             onVerificationUrl: ({ url, expiresInS }) => {
                 console.error(`\n  Opening the confirmation link in your browser (or open it in Feishu / render it as a QR code) — valid for ${Math.round(expiresInS / 60)} minutes:\n\n    ${url}\n\n  waiting for confirmation… (keep this running — the credentials are delivered here)`);
@@ -242,17 +204,13 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
             },
         });
         console.error(`[fastagent] app created: ${app.appId}${app.tenantBrand ? ` (${app.tenantBrand} tenant)` : ""}`);
-        // A cross-brand confirmation should be impossible (each confirm page refuses the other brand's
-        // code) — but if the platform ever reports one, the credentials would land in the WRONG kind's env
-        // namespace and serve the wrong cloud. Fail visibly instead of writing them.
+        // A cross-brand confirmation should be impossible (each confirm page refuses the other brand's code).
         if (app.tenantBrand && app.tenantBrand !== "feishu") {
             throw new Error(`the confirming account is a ${app.tenantBrand} tenant, but this is \`add feishu\` — run \`fastagent add ${app.tenantBrand}\` instead`);
         }
         appId = app.appId;
         appSecret = app.appSecret;
-        // IRREVERSIBLE BOUNDARY: the remote app now exists and its one-time Secret is in memory. Persist
-        // both before any config read, temporary tunnel, or Token bootstrap can be interrupted. Partial old
-        // lines are overwritten because these newly-minted credentials are authoritative as one pair.
+        // IRREVERSIBLE BOUNDARY: the remote app now exists and its one-time Secret is in memory.
         const staged = {
             FEISHU_APP_ID: appId,
             FEISHU_APP_SECRET: appSecret,
@@ -285,10 +243,6 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         return;
     }
     // The webhook channel authenticates plaintext events by the platform-generated Verification Token.
-    // Try the cheap read first (the v6 detail MAY someday return `encryption`), then the real path: the
-    // token's only programmatic delivery is the url_verification challenge during registration — capture
-    // it over a throwaway tunnel (bootstrap-token.ts). Failing both is a one-line manual copy; the staged
-    // ID/Secret pair makes a re-run resume this App rather than mint another one.
     const tokenVar = "FEISHU_VERIFICATION_TOKEN";
     const api = createFeishuApi({ baseUrl: apiBase, appId, appSecret });
     let token;
@@ -298,7 +252,7 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         token = cfg.verificationToken;
     }
     catch {
-        /* the read surface is best-effort — the bootstrap below is the real path */
+        // the read surface is best-effort — the bootstrap below is the real path
     }
     if (!token) {
         console.error(`[fastagent] capturing the Verification Token — a throwaway webhook registration delivers it (spinning up a temporary tunnel; can take a few minutes on a slow edge)…`);
@@ -312,14 +266,12 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
             console.error(`[fastagent] Verification Token captured`);
         }
         catch (e) {
-            // Transient tunnel weather is the usual cause. Do NOT suggest re-running `add feishu` as a new
-            // scan: the staged pair makes the re-run resume THIS app; manual copy completes it too.
+            // Transient tunnel weather is the usual cause.
             console.error(`[fastagent] warn: could not capture the Verification Token: ${String(e)} — usually a transient tunnel issue; finish this app with the manual copy below`);
         }
     }
     if (token) {
-        // Persist the second credential stage immediately too — opening the publish page and generic
-        // scaffold finalization happen only after the complete runtime credential set is durable.
+        // Persist the second credential stage immediately too.
         const staged = await appendChannelDotEnv(target, "feishu", { [tokenVar]: token }, [tokenVar]);
         console.error(`[fastagent] wrote ${staged.written.join(", ")} to ${env}`);
     }
@@ -327,8 +279,7 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         console.error(`[fastagent] copy it manually: developer console → Events & Callbacks → Encryption Strategy → Verification Token → ${tokenVar} in ${env}`);
     }
     if (webhookModeChanged) {
-        // The bootstrap's PATCH flipped event mode in the DRAFT. It takes effect only after a version
-        // publish, which has no API; later dev/deploy runs change only the Request URL immediately.
+        // The bootstrap's PATCH flipped event mode in the DRAFT.
         const versionUrl = `${apiBase}/app/${appId}/version`;
         if (groupSetup.publishReady) {
             console.error(`[fastagent] one console click remains: CREATE + PUBLISH a version (self-approved) — the switch to webhook mode takes effect on publish. Opening ${versionUrl}`);
@@ -339,8 +290,10 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         }
     }
 }
-/** Active agent `.env` (`.secrets/.env`) values for the requested names — decided by THE .env
- * parser, so this check can never disagree with what `loadEnvFile` reads. Empty/commented values are absent. */
+/**
+ * Active agent `.env` (`.secrets/.env`) values for the requested names — decided by THE .env parser, so this check can
+ * never disagree with what `loadDotEnv` reads.
+ */
 async function activeDotEnvValues(dir, names) {
     let content;
     try {

package/dist/cli/add-slack.d.ts

@@ -1,8 +1,10 @@
 import { type GroupBehaviorChoice } from "../scaffold/add-channel.ts";
-/** Interactive single-workspace internal-app creation + installation. Safe to re-run after interruption. */
+/** Interactive single-workspace internal-app creation + installation. */
 export declare function onboardSlackInternalApp(input: {
-    /** The AGENT DIR — credentials land in its `.env` ({@link dotEnvPath}: `FASTAGENT_SECRETS_DIR` moves
-     *  it, so messages print the resolved path rather than the default spelling). */
+    /**
+     * The AGENT DIR — credentials land in its `.env` ({@link dotEnvPath}: `FASTAGENT_SECRETS_DIR` moves it, so messages
+     * print the resolved path rather than the default spelling).
+     */
     target: string;
     stateRoot: string;
     groupBehavior: GroupBehaviorChoice;

package/dist/cli/add-slack.js

@@ -3,10 +3,9 @@ import { basename } from "node:path";
 import { isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { dotEnvPath, parseEnvContent } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
-import { installProxyFetch } from "../proxy.js";
 import { appendChannelDotEnv } from "../scaffold/add-channel.js";
 import { newSlackOnboardingState, onboardSlackApp } from "../channels/slack/onboard.js";
-import { readSlackOnboardingState, writeSlackOnboardingState } from "../channels/slack/onboarding-state.js";
+import { configTokenExpiry, readSlackOnboardingState, writeSlackOnboardingState, } from "../channels/slack/onboarding-state.js";
 import { startSlackSetupServer } from "../channels/slack/setup-server.js";
 import { startCloudflareTunnel } from "../tunnel.js";
 const CONFIG_TOKEN_URL = "https://api.slack.com/apps";
@@ -19,9 +18,39 @@ async function promptValue(message, hidden = false, initialValue) {
         throw new Error(`${message}: value is required`);
     return value;
 }
-/** Interactive single-workspace internal-app creation + installation. Safe to re-run after interruption. */
+/** The one place an App Configuration token pair is asked for and validated. */
+async function promptConfigTokens() {
+    console.error(`[fastagent] generate an App Configuration Token pair at ${CONFIG_TOKEN_URL}`);
+    openExternalUrl(CONFIG_TOKEN_URL);
+    const configToken = await promptValue("Slack configuration access token (xoxe.xoxp-…)", true);
+    const configRefreshToken = await promptValue("Slack configuration refresh token (xoxe-…)", true);
+    if (!configToken.startsWith("xoxe.") || !configRefreshToken.startsWith("xoxe-")) {
+        throw new Error("invalid Slack configuration token prefix (expected xoxe. access + xoxe- refresh)");
+    }
+    return { configToken, configRefreshToken, configTokenExpiresAt: configTokenExpiry() };
+}
+/** Keep the saved token pair, or paste a fresh one? `--replace-config` answers without asking. */
+async function chooseTokenAction(prompt) {
+    if (prompt.forced)
+        return "replace-config";
+    const answer = await select({
+        message: prompt.message,
+        initialValue: "keep",
+        options: [
+            { value: "keep", label: prompt.keepLabel },
+            {
+                value: "replace-config",
+                label: prompt.replaceLabel,
+                ...(prompt.replaceHint ? { hint: prompt.replaceHint } : {}),
+            },
+        ],
+    });
+    if (isCancel(answer))
+        throw new Error("Slack onboarding cancelled");
+    return answer;
+}
+/** Interactive single-workspace internal-app creation + installation. */
 export async function onboardSlackInternalApp(input) {
-    installProxyFetch();
     if (!(process.stdin.isTTY && process.stdout.isTTY)) {
         throw new Error("`add slack` needs an interactive terminal for internal-app creation and OAuth — " +
             "re-run in a terminal, or pass --no-onboard to scaffold only");
@@ -50,38 +79,15 @@ export async function onboardSlackInternalApp(input) {
             throw new Error(`the onboarded Slack app uses group behavior ${state.groupBehavior}; changing an installed app's ` +
                 "OAuth scopes is a migration. Keep the existing choice, or remove the app + Slack onboarding state and create a new app");
         }
-        let action = "replace-config";
-        if (!input.replaceConfig) {
-            const answer = await select({
-                message: `Slack app ${state.appId ?? "(unknown)"} is already installed${state.teamName ? ` in ${state.teamName}` : ""}`,
-                initialValue: "keep",
-                options: [
-                    { value: "keep", label: "Keep the installed app" },
-                    {
-                        value: "replace-config",
-                        label: "Replace App Configuration tokens",
-                        hint: "repair automatic dev/deploy Request URL updates",
-                    },
-                ],
-            });
-            if (isCancel(answer))
-                throw new Error("Slack onboarding cancelled");
-            action = answer;
-        }
+        const action = await chooseTokenAction({
+            forced: input.replaceConfig === true,
+            message: `Slack app ${state.appId ?? "(unknown)"} is already installed${state.teamName ? ` in ${state.teamName}` : ""}`,
+            keepLabel: "Keep the installed app",
+            replaceLabel: "Replace App Configuration tokens",
+            replaceHint: "repair automatic dev/deploy Request URL updates",
+        });
         if (action === "replace-config") {
-            console.error(`[fastagent] generate a fresh App Configuration Token pair at ${CONFIG_TOKEN_URL}`);
-            openExternalUrl(CONFIG_TOKEN_URL);
-            const configToken = await promptValue("Slack configuration access token (xoxe.xoxp-…)", true);
-            const configRefreshToken = await promptValue("Slack configuration refresh token (xoxe-…)", true);
-            if (!configToken.startsWith("xoxe.") || !configRefreshToken.startsWith("xoxe-")) {
-                throw new Error("invalid Slack configuration token prefix (expected xoxe. access + xoxe- refresh)");
-            }
-            writeSlackOnboardingState(input.stateRoot, {
-                ...state,
-                configToken,
-                configRefreshToken,
-                configTokenExpiresAt: Date.now() + 11 * 60 * 60_000,
-            });
+            writeSlackOnboardingState(input.stateRoot, { ...state, ...(await promptConfigTokens()) });
             console.error("[fastagent] replaced local Slack App Configuration tokens; runtime app credentials are unchanged");
         }
         else {
@@ -93,20 +99,10 @@ export async function onboardSlackInternalApp(input) {
         const appName = await promptValue("Slack app name", false, `FastAgent ${basename(input.target)}`);
         clackLog.info("Slack's configuration refresh token can manage apps owned by your user in this workspace. " +
             "FastAgent stores it only in owner-readable local state; it is never deployed.");
-        console.error(`[fastagent] generate an App Configuration Token at ${CONFIG_TOKEN_URL}`);
-        openExternalUrl(CONFIG_TOKEN_URL);
-        const configToken = await promptValue("Slack configuration access token (xoxe.xoxp-…)", true);
-        const configRefreshToken = await promptValue("Slack configuration refresh token (xoxe-…)", true);
-        if (!configToken.startsWith("xoxe."))
-            throw new Error("Slack configuration access token must start with xoxe.");
-        if (!configRefreshToken.startsWith("xoxe-")) {
-            throw new Error("Slack configuration refresh token must start with xoxe-");
-        }
         state = newSlackOnboardingState({
             appName,
             groupBehavior: input.groupBehavior.behavior,
-            configToken,
-            configRefreshToken,
+            ...(await promptConfigTokens()),
         });
         writeSlackOnboardingState(input.stateRoot, state);
     }
@@ -118,35 +114,17 @@ export async function onboardSlackInternalApp(input) {
         throw new Error(`a prior Slack app creation attempt at ${state.createAttemptedAt} returned no app ID — ` +
             `inspect ${CONFIG_TOKEN_URL}; delete any incomplete app and ${input.stateRoot}/channels/slack/onboarding.json before retrying`);
     }
-    // `--replace-config` also covers the created-but-not-installed state, where a revoked token would
-    // otherwise strand the resume (rotation fails and no menu offers replacement).
+    // `--replace-config` also covers the created-but-not-installed state, where a revoked token would otherwise strand
+    // the resume (rotation fails and no menu offers replacement).
     if (resumed && (!state.appId || input.replaceConfig)) {
-        let action = "replace-config";
-        if (!input.replaceConfig) {
-            const answer = await select({
-                message: "Resume Slack onboarding with which App Configuration tokens?",
-                initialValue: "keep",
-                options: [
-                    { value: "keep", label: "Use the saved token pair" },
-                    { value: "replace-config", label: "Paste a fresh token pair" },
-                ],
-            });
-            if (isCancel(answer))
-                throw new Error("Slack onboarding cancelled");
-            action = answer;
-        }
+        const action = await chooseTokenAction({
+            forced: input.replaceConfig === true,
+            message: "Resume Slack onboarding with which App Configuration tokens?",
+            keepLabel: "Use the saved token pair",
+            replaceLabel: "Paste a fresh token pair",
+        });
         if (action === "replace-config") {
-            console.error(`[fastagent] generate a fresh App Configuration Token pair at ${CONFIG_TOKEN_URL}`);
-            openExternalUrl(CONFIG_TOKEN_URL);
-            state = {
-                ...state,
-                configToken: await promptValue("Slack configuration access token (xoxe.xoxp-…)", true),
-                configRefreshToken: await promptValue("Slack configuration refresh token (xoxe-…)", true),
-                configTokenExpiresAt: Date.now() + 11 * 60 * 60_000,
-            };
-            if (!state.configToken.startsWith("xoxe.") || !state.configRefreshToken.startsWith("xoxe-")) {
-                throw new Error("invalid Slack configuration token prefix (expected xoxe. access + xoxe- refresh)");
-            }
+            state = { ...state, ...(await promptConfigTokens()) };
             writeSlackOnboardingState(input.stateRoot, state);
         }
     }
@@ -160,9 +138,8 @@ export async function onboardSlackInternalApp(input) {
     const redirectUrl = `${tunnel.url}${server.redirectPath}`;
     console.error(`[fastagent] temporary Slack setup tunnel ready → ${tunnel.url}`);
     try {
-        // No local readiness probe: Slack challenges requestUrl from ITS network during app creation, and
-        // that is the reachability that matters (#421) — this machine often cannot reach a fresh tunnel
-        // hostname for a minute. onboardSlackApp retries the create while Slack cannot verify it yet.
+        // No local readiness probe: Slack challenges requestUrl from ITS network during app creation, and that is the
+        // reachability that matters (#421).
         await onboardSlackApp({ stateRoot: input.stateRoot, state, requestUrl, redirectUrl }, {
             note: (message) => clackLog.info(message),
             openUrl: openExternalUrl,

package/dist/cli/auth-view.d.ts

@@ -1,23 +1,9 @@
-/**
- * CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). Kept out of cli.ts —
- * which self-executes on import — so the expired-vs-missing DECISION is unit-testable without a real
- * credential round-trip, mirroring models-view.ts.
- */
+/** CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). */
 /** A stored credential as `reportAuth` needs it: just its kind, for the status line. */
 export interface StoredCredentialInfo {
     type: string;
 }
-/**
- * Format the auth status for `spec`'s provider. `source` is {@link probeAuthSource}'s label (an env-var
- * name, "OAuth", a stored-key label) or undefined when nothing currently SATISFIES auth. Undefined has
- * TWO causes probeAuthSource can't distinguish (it swallows the throw): nothing stored, OR a credential
- * that IS stored but couldn't be made usable (an expired/revoked OAuth whose refresh failed). `stored`
- * — a refresh-FREE store read the caller does only in that case — tells them apart, so an expired login
- * reports "expired/unusable → `fastagent login`" instead of a misleading "(none found)" (which would then
- * be contradicted by the actual "OAuth refresh failed"). A malformed/unreadable store also reads as
- * undefined `stored` and lands in "(none found)" — but the store's own read warns about the corrupt file,
- * so the real signal is surfaced there; this line stays about credential PRESENCE.
- */
+/** Format the auth status for `spec`'s provider. */
 export declare function formatAuthReport(provider: string, authPath: string, source: string | undefined, stored: StoredCredentialInfo | undefined): {
     line: string;
     warn?: string;

package/dist/cli/auth-view.js

@@ -1,19 +1,5 @@
-/**
- * CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). Kept out of cli.ts —
- * which self-executes on import — so the expired-vs-missing DECISION is unit-testable without a real
- * credential round-trip, mirroring models-view.ts.
- */
-/**
- * Format the auth status for `spec`'s provider. `source` is {@link probeAuthSource}'s label (an env-var
- * name, "OAuth", a stored-key label) or undefined when nothing currently SATISFIES auth. Undefined has
- * TWO causes probeAuthSource can't distinguish (it swallows the throw): nothing stored, OR a credential
- * that IS stored but couldn't be made usable (an expired/revoked OAuth whose refresh failed). `stored`
- * — a refresh-FREE store read the caller does only in that case — tells them apart, so an expired login
- * reports "expired/unusable → `fastagent login`" instead of a misleading "(none found)" (which would then
- * be contradicted by the actual "OAuth refresh failed"). A malformed/unreadable store also reads as
- * undefined `stored` and lands in "(none found)" — but the store's own read warns about the corrupt file,
- * so the real signal is surfaced there; this line stays about credential PRESENCE.
- */
+/** CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). */
+/** Format the auth status for `spec`'s provider. */
 export function formatAuthReport(provider, authPath, source, stored) {
     if (source !== undefined)
         return { line: `auth:   ${source} (${provider}) — ${authPath}` };