@fastagent-sh/fastagent 0.15.0 → 0.16.0

package/dist/channels/thread-participants.js

@@ -0,0 +1,132 @@
+/**
+ * SHARED: who the agent has HEARD in a group thread — the sole input to the participant model's summon
+ * rule. **The derivation lives in docs/design/participant-model.md §3** (why the rule is defined over
+ * observation rather than the thread's true membership, what the weaker claim costs in both
+ * directions, and why recording is never gated on configuration). Repeating it here would mean two
+ * copies to keep true; what follows is only what a caller of this module must not get wrong.
+ *
+ * - **The key MUST be the string the session uses.** A record here is a claim about that session's
+ *   memory, so the two cannot be keyed independently — including the channel brand
+ *   (`feishu:<chat>:<thread>`, `slack:<team>:<channel>:<thread_ts>`). This file is already per-channel
+ *   and would not need the prefix, but SESSION ids share one namespace across every channel in a
+ *   deployment, so dropping it would key participation to a session that is not the one that answered.
+ * - **Write both halves under one condition**, and gate that condition on STRUCTURAL facts only (is
+ *   this a group? a thread? a human speaking?) — never on configuration, which changes while records
+ *   outlive the change.
+ * - **Observations only accumulate.** Nothing here sheds: no platform signals that someone stopped
+ *   taking part, and the error directions are not symmetric — over-counting humans makes the agent ask
+ *   to be named, under-counting makes it speak into a crowd.
+ * - Keyed by `thread_id`, never a reply-chain root: Feishu's `root_id` moves with the chain, so it
+ *   cannot identify a side conversation at all.
+ */
+import { log } from "../log.js";
+import { loadStateFile, saveStateFile } from "./state.js";
+/** Cap on remembered threads. Losing one costs a mention to re-enter that thread, so an unbounded file
+ *  buys little — and a merge that carries new information rewrites the whole map synchronously, so the
+ *  map's size is the cost of every such write. What keeps that bounded is that only NEW information
+ *  writes at all (a repeat speaker, or any message once MAX_HUMANS is reached, returns before
+ *  persisting), and that the map stays small enough for state.ts's premise to hold — these writes land
+ *  synchronously on the acceptance path, so the whole file is the cost of each one. A thousand records
+ *  is tens of KB, and the records that matter (threads the agent takes part in) are far fewer than
+ *  that; the dominant traffic is bystanders, which is what the eviction policy below is aimed at.
+ *
+ *  Eviction prefers BYSTANDER threads — ones the agent has only listened to. They are written on the
+ *  same path and vastly outnumber the rest (every thread in every visible channel), yet losing one
+ *  costs nothing: the summon rule refuses a thread the agent has not spoken in anyway, so the record
+ *  would have to be rebuilt by the mention that admits it. Evicting purely by age would let this
+ *  traffic push out the threads the agent is actively serving, silently reverting them to
+ *  mention-only. This is also what makes it safe to record threads no rule currently reads (those
+ *  behind a custom route, or under a posture whose summon rule is off — see the header). */
+const MAX_THREADS = 1000;
+/** Cap on remembered humans per thread. The rule only asks "have I heard a second one?", so two is
+ *  already the whole answer and anything beyond it is weight nothing reads. */
+const MAX_HUMANS = 2;
+function isStoredParticipation(value) {
+    const record = value;
+    return (Array.isArray(record?.humans) &&
+        record.humans.every((human) => typeof human === "string") &&
+        typeof record.agentSpoke === "boolean");
+}
+export function createThreadParticipants(path, label) {
+    const raw = loadStateFile(path);
+    const records = new Map();
+    if (raw !== undefined) {
+        if (typeof raw === "object" &&
+            raw !== null &&
+            !Array.isArray(raw) &&
+            Object.values(raw).every(isStoredParticipation)) {
+            for (const [key, record] of Object.entries(raw)) {
+                records.set(key, { humans: record.humans, agentSpoke: record.agentSpoke });
+            }
+        }
+        else {
+            log.warn(`${label} unexpected shape in ${path} — starting with no thread participation`);
+        }
+    }
+    return {
+        admitsBareMessage(key) {
+            const heard = records.get(key);
+            return heard?.agentSpoke === true && heard.humans.length <= 1;
+        },
+        merge(key, heard) {
+            const previous = records.get(key);
+            const humans = new Set(previous?.humans ?? []);
+            for (const human of heard.humans ?? []) {
+                if (humans.size >= MAX_HUMANS)
+                    break;
+                humans.add(human);
+            }
+            const next = {
+                humans: [...humans],
+                agentSpoke: (previous?.agentSpoke ?? false) || (heard.agentSpoke ?? false),
+            };
+            // `humans` starts from `previous` and only grows, so equal size IS set equality here.
+            const unchanged = previous !== undefined &&
+                previous.agentSpoke === next.agentSpoke &&
+                previous.humans.length === next.humans.length;
+            // Re-insert so insertion order is "least recently TOUCHED first" — including when nothing
+            // changed. A thread in its steady state (the agent answers, the same person keeps talking) stops
+            // carrying new information and would otherwise never refresh its position again, leaving the
+            // thread being served right now at the head of the eviction order.
+            //
+            // PROCESS-LOCAL: a touch alone never writes, and such a thread has nothing left to write (it has
+            // reached MAX_HUMANS), so the refreshed order survives only until restart. That is the right
+            // trade for a cache — persisting recency would mean a whole-map write per message — and the
+            // consequence is bounded: after a restart, eviction order among participant threads is the order
+            // they last carried new information.
+            records.delete(key);
+            records.set(key, next);
+            if (unchanged)
+                return;
+            while (records.size > MAX_THREADS) {
+                // Oldest bystander first; only when every record is a thread the agent takes part in does age
+                // alone decide. NEVER the key just merged: it is the most recently touched record, so evicting
+                // it contradicts the recency policy re-established above — and worse, a channel that records a
+                // thread's humans and its own participation in two steps would then write the second half onto
+                // an empty record, producing "answered here, heard nobody" and a permanent bare-message admit.
+                let evict;
+                for (const [candidate, record] of records) {
+                    if (candidate === key)
+                        continue;
+                    if (!record.agentSpoke) {
+                        evict = candidate;
+                        break;
+                    }
+                    evict ??= candidate;
+                }
+                if (evict === undefined)
+                    break;
+                records.delete(evict);
+            }
+            try {
+                saveStateFile(path, Object.fromEntries(records));
+            }
+            catch (error) {
+                // Cache only: memory stays correct for this process, and the whole map is rewritten on the
+                // next successful merge — so a failed write costs durability only until then, and a thread
+                // whose record is lost simply needs a mention to re-enter.
+                log.warn(`${label} could not persist thread participation ${path}: ${String(error)}`);
+            }
+        },
+    };
+}

package/dist/channels/turn-queue.js

@@ -11,6 +11,7 @@
  * backend — an external queue with distributed locking (SPEC §11) — not this in-memory queue.
  */
 import { log } from "../log.js";
+import { beginWork } from "./busy.js";
 export function createTurnQueue(opts) {
     const { label, run, onQueuedBehind } = opts;
     // Per-session serial chains: a second turn for the same session waits its turn (FIFO) instead of
@@ -20,6 +21,11 @@ export function createTurnQueue(opts) {
         accept(rec) {
             if (chains.has(rec.session))
                 onQueuedBehind?.(rec);
+            // Process-wide busy signal (busy.ts): an accepted turn counts as in-flight work from acceptance
+            // until its run settles — serving surfaces that must not idle mid-turn (the AgentCore adapter's
+            // /ping) read it. Counted here, not in run(), so a QUEUED turn (accepted, waiting on the chain)
+            // already reads as busy.
+            const workDone = beginWork();
             const prev = chains.get(rec.session) ?? Promise.resolve();
             const task = async () => {
                 try {
@@ -32,6 +38,7 @@ export function createTurnQueue(opts) {
             const next = prev.then(task, task); // run after this session's previous turn, in arrival order
             chains.set(rec.session, next);
             void next.finally(() => {
+                workDone();
                 if (chains.get(rec.session) === next)
                     chains.delete(rec.session); // drop the entry when drained
             });

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

@@ -18,10 +18,13 @@ export declare function configureGroupBehavior(input: {
     openUrl?: (url: string) => void;
 }): Promise<GroupBehaviorSetup>;
 /**
- * Create or resume the platform app behind `add feishu` / `add lark`. Returns credentials for the
+ * 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 committable .env, a
- * non-interactive lark run); the caller surfaces that as a startup failure.
+ * irreversible and must not wait for the caller). Throws on refusal (a non-interactive lark run);
+ * the caller surfaces that as a startup failure.
  */
-export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", envIgnored: boolean, ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehaviorChoice): Promise<Record<string, string> | undefined>;
+export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehaviorChoice): Promise<Record<string, string> | undefined>;

package/dist/cli/add-feishu.js

@@ -10,15 +10,14 @@
  * for WebSocket or probes the same webhook/token bootstrap with the config-route-404 manual fallback.
  */
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { isCancel, log as clackLog, password, text as clackText } from "@clack/prompts";
 import { bootstrapFeishuVerificationToken } from "../channels/feishu/bootstrap-token.js";
-import { FEISHU_GROUP_CONTEXT_SCOPE, } from "../channels/feishu/setup-mode.js";
+import { FEISHU_GROUP_CONTEXT_SCOPE, FEISHU_CONTEXT_ONBOARDING_SCOPES, FEISHU_MESSAGE_READ_SCOPE, scopeSatisfied, } from "../channels/feishu/setup-mode.js";
 import { cloudFor } from "../channels/feishu/cloud.js";
 import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError, } from "../channels/feishu/feishu-api.js";
 import { registerFeishuApp } from "../channels/feishu/register-app.js";
 import { onboardLarkApp } from "../channels/lark/onboard.js";
-import { parseEnvContent } from "../env.js";
+import { dotEnvPath, parseEnvContent } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
 import { appendChannelDotEnv } from "../scaffold/add-channel.js";
 import { startCloudflareTunnel } from "../tunnel.js";
@@ -36,7 +35,17 @@ export async function configureGroupBehavior(input) {
         inspected = false;
         scopes = [];
     }
-    const groupScope = scopes.find((scope) => scope.name === FEISHU_GROUP_CONTEXT_SCOPE && (scope.type === undefined || scope.type === "tenant"));
+    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.
+    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.
+    const missing = FEISHU_CONTEXT_ONBOARDING_SCOPES.filter((entry) => !scopeSatisfied(entry, granted));
+    const missingNames = missing.map((entry) => entry.request);
     if (behavior === "mentions") {
         if (!inspected) {
             const permissionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/permission`;
@@ -44,60 +53,70 @@ export async function configureGroupBehavior(input) {
             openUrl(permissionUrl);
             return { publishReady: false };
         }
-        if (groupScope?.grantStatus === 1) {
+        if (granted(FEISHU_GROUP_CONTEXT_SCOPE)) {
             const permissionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/permission`;
             note(`[fastagent] warn: mention-only was selected, but ${FEISHU_GROUP_CONTEXT_SCOPE} is already granted — remove it before publishing a new version to restore least-privilege platform delivery. Opening ${permissionUrl}`);
             openUrl(permissionUrl);
             return { publishReady: false };
         }
-        note(`[fastagent] group behavior: mention-only — bare managed-thread replies and group context buffering are disabled`);
+        note(`[fastagent] group behavior: mention-only — bare replies in the Agent's threads and group context buffering are disabled. ` +
+            `Add ${FEISHU_MESSAGE_READ_SCOPE} by hand if you want an @mention to carry the message it quotes`);
         return { publishReady: true };
     }
     note(`[fastagent] group behavior: context-aware (recommended) — ${kind} will deliver all group messages; ` +
-        `FastAgent invokes @Agent + bare managed-thread replies and durably buffers other discussion`);
-    if (groupScope?.grantStatus === 1) {
-        note(`[fastagent] ${FEISHU_GROUP_CONTEXT_SCOPE} is already granted`);
+        `FastAgent invokes @Agent, answers bare replies in threads it takes part in, and durably buffers ` +
+        `other discussion. ${FEISHU_GROUP_CONTEXT_SCOPE} (delivery) is required; ${FEISHU_MESSAGE_READ_SCOPE} ` +
+        `(reading a quoted message) is requested with it — without it a quoted message degrades to a marker`);
+    if (missing.length === 0) {
+        note(`[fastagent] ${FEISHU_CONTEXT_ONBOARDING_SCOPES.map((entry) => entry.request).join(" + ")} are already granted`);
         return { publishReady: true };
     }
     const permissionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/permission`;
-    if (groupScope) {
-        note(`[fastagent] ${FEISHU_GROUP_CONTEXT_SCOPE} is awaiting approval — complete tenant-admin approval before publishing. Opening ${permissionUrl}`);
+    // 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.
+    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) {
+        note(`[fastagent] ${awaitingApproval.join(" + ")} awaiting approval — complete tenant-admin approval before publishing. Opening ${permissionUrl}`);
         openUrl(permissionUrl);
         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).
-        note(`[fastagent] ${FEISHU_GROUP_CONTEXT_SCOPE} is not granted (or could not be verified) — group behavior was ` +
-            `defaulted, so it was not requested. Re-run with --group-behavior context to add it to the app draft, ` +
-            `or --group-behavior mentions to stay least-privilege: ${permissionUrl}`);
+        // 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.
+        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}`);
         return { publishReady: false };
     }
     try {
-        await api.addAppScopes(appId, [FEISHU_GROUP_CONTEXT_SCOPE]);
-        note(`[fastagent] added ${FEISHU_GROUP_CONTEXT_SCOPE} to the app draft — complete tenant-admin approval before publishing. Opening ${permissionUrl}`);
+        await api.addAppScopes(appId, toRequest);
+        note(`[fastagent] added ${toRequest.join(" + ")} to the app draft — complete tenant-admin approval before publishing. Opening ${permissionUrl}`);
     }
     catch (error) {
-        note(`[fastagent] warn: could not add ${FEISHU_GROUP_CONTEXT_SCOPE} automatically: ${String(error)} — add it manually before publishing. Opening ${permissionUrl}`);
+        note(`[fastagent] warn: could not add ${toRequest.join(" + ")} automatically: ${String(error)} — add it manually before publishing. Opening ${permissionUrl}`);
     }
     openUrl(permissionUrl);
     return { publishReady: false };
 }
 /**
- * Create or resume the platform app behind `add feishu` / `add lark`. Returns credentials for the
+ * 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 committable .env, a
- * non-interactive lark run); the caller surfaces that as a startup failure.
+ * irreversible and must not wait for the caller). Throws on refusal (a non-interactive lark run);
+ * the caller surfaces that as a startup failure.
  */
-export async function onboardFeishuCloudApp(target, kind, envIgnored, ingress = "webhook", groupBehavior = { behavior: "context", explicit: false }) {
+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);
-    // The CLI must never materialize a real credential into a committable file — refuse, don't warn.
-    if (!envIgnored) {
-        throw new Error(kind === "feishu"
-            ? "`add feishu` creates an app and writes real credentials to .env — add .env to .gitignore/.fastagentignore first, then re-run"
-            : "`add lark` writes real app credentials to .env — add .env to .gitignore/.fastagentignore first, then re-run");
-    }
     const requiredNames = [
         `${envPrefix}_APP_ID`,
         `${envPrefix}_APP_SECRET`,
@@ -105,7 +124,7 @@ export async function onboardFeishuCloudApp(target, kind, envIgnored, ingress =
     ];
     const existing = await activeDotEnvValues(target, requiredNames);
     if (Object.keys(existing).length === requiredNames.length) {
-        console.error(`[fastagent] ${requiredNames.join("/")} already set in .env — keeping them`);
+        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.
         if (ingress === "webhook") {
@@ -200,13 +219,14 @@ export async function onboardFeishuCloudApp(target, kind, envIgnored, ingress =
  * then probes the canonical token/mode bootstrap with a manual fallback.
  */
 async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
+    const env = dotEnvPath(target); // the file actually written — never the default spelling
     const { apiBase } = cloudFor("feishu");
     let appId = existing.FEISHU_APP_ID;
     let appSecret = existing.FEISHU_APP_SECRET;
     if (appId && appSecret) {
         console.error(ingress === "webhook"
-            ? `[fastagent] resuming Feishu app ${appId} from .env to capture its missing Verification Token`
-            : `[fastagent] reusing Feishu app ${appId} from .env for WebSocket ingress`);
+            ? `[fastagent] resuming Feishu app ${appId} from ${env} to capture its missing Verification Token`
+            : `[fastagent] reusing Feishu app ${appId} from ${env} for WebSocket ingress`);
     }
     else {
         console.error(`[fastagent] creating the Feishu app (confirm in the app)…`);
@@ -247,8 +267,8 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         };
         await appendChannelDotEnv(target, "feishu", staged, Object.keys(staged), ingress);
         console.error(ingress === "webhook"
-            ? `[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to .env before Token bootstrap`
-            : `[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to .env`);
+            ? `[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to ${env} before Token bootstrap`
+            : `[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to ${env}`);
     }
     const groupSetup = await configureGroupBehavior({
         kind: "feishu",
@@ -308,10 +328,10 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         // 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.
         const staged = await appendChannelDotEnv(target, "feishu", { [tokenVar]: token }, [tokenVar]);
-        console.error(`[fastagent] wrote ${staged.written.join(", ")} to .env`);
+        console.error(`[fastagent] wrote ${staged.written.join(", ")} to ${env}`);
     }
     else {
-        console.error(`[fastagent] copy it manually: developer console → Events & Callbacks → Encryption Strategy → Verification Token → ${tokenVar} in .env`);
+        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
@@ -326,12 +346,12 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         }
     }
 }
-/** Active run-root `.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 `loadEnvFile` reads. Empty/commented values are absent. */
 async function activeDotEnvValues(dir, names) {
     let content;
     try {
-        content = await readFile(join(dir, ".env"), "utf8");
+        content = await readFile(dotEnvPath(dir), "utf8");
     }
     catch (e) {
         if (e.code === "ENOENT")

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

@@ -1,9 +1,10 @@
 import { type GroupBehaviorChoice } from "../scaffold/add-channel.ts";
 /** Interactive single-workspace internal-app creation + installation. Safe to re-run after interruption. */
 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). */
     target: string;
     stateRoot: string;
-    envIgnored: boolean;
     groupBehavior: GroupBehaviorChoice;
     /** `--replace-config`: go straight to replacing the local App Configuration token pair. */
     replaceConfig?: boolean;

package/dist/cli/add-slack.js

@@ -1,9 +1,8 @@
 import { readFile } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename } from "node:path";
 import { isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { waitForHealth } from "../channels/wait-health.js";
-import { ensureStateRootSelfIgnored } from "../engines/pi/definition.js";
-import { parseEnvContent } from "../env.js";
+import { dotEnvPath, parseEnvContent } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
 import { installProxyFetch } from "../proxy.js";
 import { appendChannelDotEnv } from "../scaffold/add-channel.js";
@@ -24,15 +23,10 @@ async function promptValue(message, hidden = false, initialValue) {
 /** Interactive single-workspace internal-app creation + installation. Safe to re-run after interruption. */
 export async function onboardSlackInternalApp(input) {
     installProxyFetch();
-    if (!input.envIgnored) {
-        throw new Error("`add slack` onboarding creates an app and writes real credentials to .env — " +
-            "add .env to .gitignore/.fastagentignore first, then re-run");
-    }
     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");
     }
-    await ensureStateRootSelfIgnored(input.target, input.stateRoot);
     let state = await readSlackOnboardingState(input.stateRoot);
     const resumed = state !== undefined;
     if (input.replaceConfig && !state) {
@@ -40,7 +34,7 @@ export async function onboardSlackInternalApp(input) {
             "Run `fastagent add slack` to onboard, or update the Request URL manually in the Slack console");
     }
     if (state?.installedAt) {
-        const env = await readFile(join(input.target, ".env"), "utf8")
+        const env = await readFile(dotEnvPath(input.target), "utf8")
             .then(parseEnvContent)
             .catch((error) => {
             if (error.code === "ENOENT")
@@ -56,7 +50,8 @@ export async function onboardSlackInternalApp(input) {
             "SLACK_SIGNING_SECRET",
         ].filter((name) => !((process.env[name] ?? env.get(name))?.trim() ?? ""));
         if (missingRuntime.length > 0) {
-            throw new Error(`Slack app ${state.appId ?? "(unknown)"} is installed but .env is missing ${missingRuntime.join(", ")} — ` +
+            throw new Error(`Slack app ${state.appId ?? "(unknown)"} is installed but ${dotEnvPath(input.target)} is missing ` +
+                `${missingRuntime.join(", ")} — ` +
                 "restore them from the Slack app console, or delete the app + onboarding state and create a new one");
         }
         if (input.groupBehavior.explicit && state.groupBehavior !== input.groupBehavior.behavior) {
@@ -193,7 +188,7 @@ export async function onboardSlackInternalApp(input) {
                 }
             },
         });
-        console.error("[fastagent] Slack app installed; rotating bot credentials and Signing Secret written to .env");
+        console.error(`[fastagent] Slack app installed; rotating bot credentials and Signing Secret written to ${dotEnvPath(input.target)}`);
         console.error(`[fastagent] run \`fastagent dev --tunnel\` next — FastAgent will rotate the config token and ` +
             "replace the temporary Events API URL automatically");
     }