@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/deploy/preflight.js

@@ -1,6 +1,6 @@
 /**
  * The host-NEUTRAL deploy pre-flight: everything `fastagent deploy <host>` computes and checks BEFORE
- * the host branch (fly.ts / railway.ts). Model-travel gate, channel discovery, model-auth probe, the
+ * the target branch (Docker / Fly / Railway). Model-travel gate, channel discovery, model-auth probe, the
  * container facts + their warnings, and the hand-written-Dockerfile apt warning are identical on every
  * host — so they live here, out of the CLI dispatcher, testable in isolation (call it against a temp dir
  * and assert the gate / messages / facts). The CLI stays thin: run this, print the messages, branch by host.
@@ -11,8 +11,8 @@
  */
 import { readFile } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
-import { defaultAuthPath, resolveStateRoot } from "../engines/pi/config.js";
-import { discoverChannelFiles } from "../engines/pi/channel.js";
+import { resolveAuthPath } from "../engines/pi/config.js";
+import { inspectChannels } from "../engines/pi/channel.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
 import { createPiModels, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
@@ -25,7 +25,7 @@ import { isGeneratedDockerfile } from "./container.js";
  * provider) — the CLI wraps the call in its `failStartup` so the fault surfaces and exits, never silently.
  */
 export async function preflightDeploy(input) {
-    const { target, agentDir, config, modelSpec, run, force, authPathOverride } = input;
+    const { target, agentDir, config, modelSpec, run, force, authPathFlag } = input;
     const messages = [];
     // The deployed box resolves the model from fastagent.config.ts ONLY (in the image); a model set via
     // env/flag/.env doesn't travel. `--run` would ship a known crash-loop — hard gate; generate-only warns.
@@ -35,20 +35,52 @@ export async function preflightDeploy(input) {
             return { ok: false, gate: modelIssue };
         messages.push({ level: "warn", text: modelIssue });
     }
+    // The control plane on a deployed box: `start` honors `sessionControl: true`, so `/control/*`
+    // (steer/abort/set_model) rides the PUBLIC host URL — protected only by a per-boot bearer token
+    // minted INSIDE the container (`<stateRoot>/control.json`), which external consumers cannot read.
+    // Publicly reachable yet unusable is the worst of both; the tunnel path warns loudly and deploy
+    // must not be the silent second way to break the loopback trust story.
+    if (config.sessionControl === true) {
+        messages.push({
+            level: "warn",
+            text: `sessionControl: true — the deployed box serves /control/* (steer/abort/set_model) at its public URL, ` +
+                `protected only by a per-boot token written inside the container. Read the TOKEN from ` +
+                `<stateRoot>/control.json on the box (its url field is container-loopback — pair the token with the ` +
+                `public host URL: attach --url <public-url> --token …), or front the endpoint with real auth (design §14)`,
+        });
+    }
     // Known channel kinds only — a custom channel's secrets/webhook are unknown to us; note and let the
     // author wire them.
-    const discovered = await discoverChannelFiles(agentDir);
+    const inspected = await inspectChannels(agentDir);
+    if (inspected.failures.length > 0) {
+        throw new Error(`cannot inspect channel modules: ${inspected.failures.map((failure) => `${failure.label}: ${failure.message}`).join("; ")}`);
+    }
+    const discovered = inspected.channels;
     const channels = discovered.filter((c) => CHANNEL_KINDS.includes(c));
+    const routeChannels = inspected.routeChannels;
+    const longConnectionChannels = inspected.longConnectionChannels;
     for (const c of discovered) {
-        if (!channels.includes(c)) {
-            messages.push({ level: "note", text: `channel "${c}" is custom — set its secrets and webhook yourself` });
-        }
+        if (channels.includes(c))
+            continue;
+        messages.push({
+            level: "note",
+            text: longConnectionChannels.includes(c)
+                ? `long-connection channel "${c}" is custom — configure its secrets yourself; generated deploy plans keep the process running and skip webhook registration`
+                : `route channel "${c}" is custom — configure its secrets and webhook yourself`,
+        });
     }
     // Time triggers (static schedules or self-scheduling) need a machine kept running — unlike a webhook,
     // nothing external wakes a scale-to-zero box for a cron instant or a wake-up. The note is CONDITIONAL
     // ("the generated plan…"): in KEEP mode an existing fly.toml is not rewritten — the CLI warns separately
     // when a kept fly.toml still scales to zero.
     const hasTimeTriggers = (await discoverScheduleFiles(agentDir)).length > 0 || !!config.selfSchedule;
+    if (longConnectionChannels.length > 0) {
+        messages.push({
+            level: "note",
+            text: `long-connection channel present (${longConnectionChannels.join(", ")}) — a GENERATED plan keeps one machine running ` +
+                `(an outbound connection cannot wake a scaled-to-zero service).`,
+        });
+    }
     if (hasTimeTriggers) {
         messages.push({
             level: "note",
@@ -58,7 +90,7 @@ export async function preflightDeploy(input) {
     }
     // Probe auth from the SAME project-level file the opener/login use — not the global default, which would
     // miss a `fastagent login` credential and falsely report "none configured".
-    const authPath = authPathOverride ?? defaultAuthPath(resolveStateRoot(target));
+    const authPath = resolveAuthPath(target, authPathFlag);
     const modelAuth = modelSpec ? await probeAuthSource(createPiModels({ authPath }), modelSpec) : undefined;
     // Container facts (shared by every host) + the warnings that follow. Repo-as-workspace layout
     // (agentDir ≠ target): the facts describe the KIT — its package.json/runtime/lockfile drive the
@@ -68,8 +100,9 @@ export async function preflightDeploy(input) {
     const kitDir = agentDir === target ? undefined : relative(target, agentDir).split(sep).join("/");
     const factsDir = kitDir ? agentDir : target;
     if (kitDir && run) {
-        // Generate + runbook fully support the layout; the fly/railway --run drivers do not yet (their
-        // command sequences assume root artifacts). Fail at the gate, not mid-drive.
+        // The repo-as-workspace deployment shape remains experimental for every target. Generation +
+        // runbook are supported; automated runners stay gated until an explicit end-to-end smoke validates
+        // context packing, ignore rules, installed deps, state, and write-back for this layout.
         return {
             ok: false,
             gate: `--run is not yet supported for the agentDir layout — run the same deploy without --run and follow the printed runbook`,
@@ -172,7 +205,19 @@ export async function preflightDeploy(input) {
             });
         }
     }
-    return { ok: true, messages, channels, hasTimeTriggers, modelAuth, authPath, container, port, extraSecrets };
+    return {
+        ok: true,
+        messages,
+        channels,
+        routeChannels,
+        longConnectionChannels,
+        hasTimeTriggers,
+        modelAuth,
+        authPath,
+        container,
+        port,
+        extraSecrets,
+    };
 }
 /**
  * Why the resolved model won't reach the deployed box, or undefined if it will — host-neutral. `fastagent.config.ts`

package/dist/deploy/railway/plan.d.ts

@@ -29,8 +29,10 @@ export interface RailwayPlanInput extends ContainerInput {
     serviceName: string;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** Channels discovered in the workspace — each contributes its secret metadata + webhook step. */
+    /** Known first-party channels — each contributes its secret metadata + webhook step. */
     channels: ChannelKind[];
+    /** All long-connection channel basenames, including custom channels — no App Sleeping. */
+    longConnectionChannels?: string[];
     /** Extra secret env-var names (fastagent.config deploy.secrets) — added to the runbook's secret list. */
     extraSecrets?: string[];
     /** Time triggers present (schedules/ or selfSchedule) — the runbook forbids App Sleeping: cron/wake has

package/dist/deploy/railway/plan.js

@@ -23,7 +23,7 @@ export function planRailwayDeploy(input) {
         { path: configPath, content: railwayJson(input.kitDir) },
         ...containerArtifacts(input),
     ];
-    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets);
+    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets, input.longConnectionChannels);
     const requiredSecrets = secrets.filter((secret) => secret.required);
     const optionalSecrets = secrets.filter((secret) => !secret.required);
     // Order matters, not cosmetics: `railway init` creates a PROJECT with no service, but the volume and
@@ -76,7 +76,10 @@ export function planRailwayDeploy(input) {
     // The public URL is minted, not deterministic (unlike Fly's <app>.fly.dev) — ONE mint step, then each
     // channel's webhook uses that domain (mint once even when both channels are present).
     const hasFeishuCloudChannel = ["feishu", "lark"].some((kind) => channels.includes(kind));
-    if (channels.includes("telegram") || channels.includes("github") || hasFeishuCloudChannel) {
+    if (channels.includes("telegram") ||
+        channels.includes("github") ||
+        channels.includes("slack") ||
+        hasFeishuCloudChannel) {
         runbook.push(``, `# Public URL — Railway mints a *.up.railway.app domain (NOT deterministic). Generate it, then read`, `# the printed https URL and use it as <your-domain> in the webhook step(s) below:`, `railway domain`);
     }
     if (channels.includes("telegram")) {
@@ -85,8 +88,11 @@ export function planRailwayDeploy(input) {
     if (channels.includes("github")) {
         runbook.push(`# Set the GitHub webhook (repo Settings → Webhooks). Default route POST /webhook; if you remapped it`, `# in channels/github.ts, use your path:`, `#   Payload URL = https://<your-domain>/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
     }
+    if (channels.includes("slack")) {
+        runbook.push(`# Set Slack Event Subscriptions → Request URL (default route POST /slack; the running service`, `# answers Slack's challenge), and match scopes/subscriptions to channels/slack.ts groupBehavior:`, `#   Request URL = https://<your-domain>/slack`);
+    }
     for (const kind of ["feishu", "lark"]) {
-        if (!channels.includes(kind))
+        if (!channels.includes(kind) || input.longConnectionChannels?.includes(kind))
             continue;
         const label = kind === "feishu" ? "Feishu" : "Lark";
         runbook.push(`# Set the ${label} event Request URL (developer console → Events & Callbacks). Default route`, `# POST /${kind}; the service must be RUNNING when you save (the console verifies with a challenge):`, `#   Request URL = https://<your-domain>/${kind}`);
@@ -98,6 +104,8 @@ export function planRailwayDeploy(input) {
         ? `# Scale-to-zero: do NOT enable App Sleeping — github turns have no replay, a sleep mid-review is lost.`
         : input.hasTimeTriggers
             ? `# Scale-to-zero: do NOT enable App Sleeping — schedules/wake-ups have no external wake-up; a sleeping service sleeps through them.`
-            : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping.`, `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
+            : (input.longConnectionChannels?.length ?? 0) > 0
+                ? `# Scale-to-zero: do NOT enable App Sleeping — a long-connection channel must remain connected.`
+                : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping.`, `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
     return { artifacts, runbook };
 }

package/dist/deploy/railway/run.d.ts

@@ -38,6 +38,7 @@ export interface RailwayRunPlan {
     /** Required secret names with NO local value — the run gates on these before any side effect. */
     missingSecrets: string[];
     channels: ChannelKind[];
+    longConnectionChannels?: string[];
     /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. Off
      *  by default so `--run` only creates on an unlinked dir and never deploys into a pre-existing (possibly
      *  unrelated/production) project; the flag is the operator's explicit "yes, this project". */
@@ -76,9 +77,9 @@ export declare function parseDomainUrl(stdout: string): string | undefined;
  */
 export declare function parseHasVolume(stdout: string, mountPath: string): boolean;
 /**
- * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` /
- * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
- * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * Run the deploy through `railway`. `log` reports progress; the injected Telegram/Feishu/Slack
+ * registrars perform post-deploy webhook steps from the builder machine (Slack's control credential
+ * never travels to the host). Absent, the manual console
  * instruction is printed. Every gate is fail-visible.
  */
-export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>): Promise<RailwayRunOutcome>;
+export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<RailwayRunOutcome>;

package/dist/deploy/railway/run.js

@@ -62,12 +62,12 @@ export function parseHasVolume(stdout, mountPath) {
     return jsonStrings(stdout).includes(mountPath);
 }
 /**
- * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` /
- * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
- * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * Run the deploy through `railway`. `log` reports progress; the injected Telegram/Feishu/Slack
+ * registrars perform post-deploy webhook steps from the builder machine (Slack's control credential
+ * never travels to the host). Absent, the manual console
  * instruction is printed. Every gate is fail-visible.
  */
-export async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu) {
+export async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu, registerSlack) {
     const gate = (g) => ({ ok: false, gate: g });
     // Every --service below targets plan.name — the name this tool gives BOTH the project and the service
     // (`init --name` + `add --service`). On a fresh create they match; on `--into-linked` into a hand-made
@@ -179,8 +179,18 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram, reg
         log(`github: set the webhook in the repo (Settings → Webhooks) → ${url}/webhook`);
         reg.track("github", "manual"); // always a human step — re-surface it after the registrar output
     }
+    if (plan.channels.includes("slack")) {
+        if (registerSlack) {
+            log("registering slack event URL…");
+            reg.track("slack", await registerSlack(url));
+        }
+        else {
+            log(`slack: set Event Subscriptions → Request URL → ${url}/slack`);
+            reg.track("slack", "manual");
+        }
+    }
     for (const kind of ["feishu", "lark"]) {
-        if (!plan.channels.includes(kind))
+        if (!plan.channels.includes(kind) || plan.longConnectionChannels?.includes(kind))
             continue;
         if (registerFeishu) {
             log(`registering ${kind} event URL…`);

package/dist/deploy/runner.d.ts

@@ -1,14 +1,17 @@
-export interface RunResult {
+interface RunResult {
     code: number;
     /** Captured stdout (for `--json` queries); empty when the command streamed to the terminal. The CLI's
      *  stderr is always inherited straight to the terminal, so it is not a field here. */
     stdout: string;
 }
 /** Run `bin args`: `capture` collects stdout (for `--json` queries), else the command streams to the
- *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv). */
+ *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv).
+ *  `env` adds child-only environment values — Docker Compose interpolates secrets from it without putting
+ *  values in argv or mutating the long-lived CLI process. */
 export type CliRunner = (args: string[], opts?: {
     capture?: boolean;
     input?: string;
+    env?: NodeJS.ProcessEnv;
 }) => Promise<RunResult>;
 /**
  * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the
@@ -16,3 +19,4 @@ export type CliRunner = (args: string[], opts?: {
  * ENOENT (the CLI not on PATH) resolves to code 127 so the caller can gate with an install hint.
  */
 export declare function spawnRunner(bin: string, cwd: string): CliRunner;
+export {};

package/dist/deploy/runner.js

@@ -13,6 +13,7 @@ export function spawnRunner(bin, cwd) {
     return (args, opts) => new Promise((res) => {
         const child = spawn(bin, args, {
             cwd,
+            env: opts?.env ? { ...process.env, ...opts.env } : process.env,
             stdio: [opts?.input ? "pipe" : "inherit", opts?.capture ? "pipe" : "inherit", "inherit"],
         });
         let out = "";

package/dist/deploy/secrets.d.ts

@@ -17,7 +17,7 @@ export declare function isEnvKey(source: string | undefined): source is string;
  * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[]): {
+export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[], longConnectionChannels?: string[]): {
     name: string;
     hint: string;
     required: boolean;
@@ -40,6 +40,7 @@ export declare function assembleSecrets(input: {
     modelAuth: string | undefined;
     authFile: Buffer | undefined;
     channels: ChannelKind[];
+    longConnectionChannels?: string[];
     /** Extra secret env-var names from `fastagent.config` deploy.secrets — carried like channel secrets. */
     extraSecrets?: string[];
     env: NodeJS.ProcessEnv;

package/dist/deploy/secrets.js

@@ -19,13 +19,15 @@ export function isEnvKey(source) {
  * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export function deploymentSecrets(modelAuth, channels, extraSecrets = []) {
+export function deploymentSecrets(modelAuth, channels, extraSecrets = [], longConnectionChannels = []) {
     const secrets = [];
     if (isEnvKey(modelAuth))
         secrets.push({ name: modelAuth, hint: "your model provider key", required: true });
     for (const kind of channels) {
-        for (const e of channelSetup(kind).env)
+        const setupMode = longConnectionChannels.includes(kind) ? "websocket" : "webhook";
+        for (const e of channelSetup(kind, setupMode).env) {
             secrets.push({ name: e.name, hint: e.hint, required: e.required });
+        }
     }
     // Dedup: a name already covered by the model key / a channel secret must not appear twice in the runbook.
     for (const name of extraSecrets) {
@@ -67,7 +69,8 @@ export function assembleSecrets(input) {
         needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
     }
     for (const kind of input.channels) {
-        for (const e of channelSetup(kind).env) {
+        const setupMode = input.longConnectionChannels?.includes(kind) ? "websocket" : "webhook";
+        for (const e of channelSetup(kind, setupMode).env) {
             const v = input.env[e.name];
             if (v)
                 secrets[e.name] = v; // optional channel values travel when configured
@@ -76,6 +79,23 @@ export function assembleSecrets(input) {
             }
         }
     }
+    // Slack bot-token rotation is an all-or-nothing credential bundle. Its fields remain optional so a
+    // manually configured long-lived token works, but a partial bundle must gate before the container
+    // reaches slackChannel construction.
+    if (input.channels.includes("slack")) {
+        const rotation = [
+            "SLACK_BOT_REFRESH_TOKEN",
+            "SLACK_BOT_TOKEN_EXPIRES_AT",
+            "SLACK_CLIENT_ID",
+            "SLACK_CLIENT_SECRET",
+        ];
+        if (rotation.some((name) => !!input.env[name])) {
+            for (const name of rotation) {
+                if (!input.env[name] && !missingSecrets.includes(name))
+                    missingSecrets.push(name);
+            }
+        }
+    }
     for (const name of input.extraSecrets ?? []) {
         if (name in secrets || missingSecrets.includes(name))
             continue; // already covered by model/channel — no dup

package/dist/dev-supervisor.d.ts

@@ -1,5 +1,3 @@
-/** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
-export declare const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
 /**
  * chokidar `ignored` matcher for the narrow watch scope (true = ignore). Ignoring a directory prunes
  * the whole subtree, so everything outside the allowlist — .fastagent state, node_modules, .git, and

package/dist/dev-supervisor.js

@@ -13,13 +13,13 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { loadConfig, resolveAgentDir } from "./engines/pi/config.js";
+import { loadConfig, resolveAgentDir, resolveStateRoot } from "./engines/pi/config.js";
 import { log } from "./log.js";
 import { installProxyFetch } from "./proxy.js";
 import { openExternalUrl } from "./open-url.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
-export const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
+const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
 /**
  * chokidar `ignored` matcher for the narrow watch scope (true = ignore). Ignoring a directory prunes
  * the whole subtree, so everything outside the allowlist — .fastagent state, node_modules, .git, and
@@ -100,7 +100,11 @@ export async function runDevSupervisor(dir, options = {}) {
                 void startCloudflareTunnel(m.port).then((t) => {
                     if (t) {
                         tunnel = t;
-                        void announceWebhooks(agentDir, t.url, { openUrl: openExternalUrl });
+                        void announceWebhooks(dir, t.url, {
+                            openUrl: openExternalUrl,
+                            routeChannels: m.routeChannels,
+                            stateRoot: resolveStateRoot(dir),
+                        });
                     }
                 });
             }

package/dist/engines/pi/auth.js

@@ -12,22 +12,24 @@
  * token and persisting the new one elsewhere leaves global stale for every other consumer.
  *
  * Sharing is still SAFE the right way: point everything at ONE file (`FASTAGENT_AUTH_PATH` → the
- * global path). One file means one refresh lifecycle under `FileAuthStorageBackend`'s cross-process
- * lock (refresh re-reads the latest token under the lock) — the documented same-machine pattern.
+ * global path). One file means one refresh lifecycle under the store's cross-process write lock
+ * (refresh re-reads the latest token under the lock), the documented same-machine pattern.
  * fastagent's store stays SEPARATE from the pi CLI's `~/.pi/agent/auth.json` for the same single-
  * lifecycle reason: two uncoordinated files over one grant would each rotate and break the other.
  *
- * Persistence + locking reuse pi's `FileAuthStorageBackend` (a cross-process file lock) on the WRITE
- * path only. `read` is pi-ai's per-request hot path, so it stays UNLOCKED; the backend's in-place
- * write opens only a sub-millisecond torn-read window, which `read` absorbs by re-reading. The write
- * path refuses to overwrite a corrupt file (never clobbering other providers' credentials).
+ * Locking is vendored here on `proper-lockfile`, with the same parameters pi's file backend used
+ * before pi 0.80.8 stopped exporting it (upstream's stated migration path for SDK consumers is a
+ * custom pi-ai `CredentialStore`, which this file is). The lock guards the WRITE path only. `read`
+ * is pi-ai's per-request hot path, so it stays UNLOCKED; the in-place locked write opens only a
+ * sub-millisecond torn-read window, which `read` absorbs by re-reading. The write path refuses to
+ * overwrite a corrupt file (never clobbering other providers' credentials).
  */
-import { existsSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { log } from "../../log.js";
 import { setTimeout as sleep } from "node:timers/promises";
-import { FileAuthStorageBackend } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
 /**
  * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`). The project-level default is
  * `<dir>/.fastagent/auth.json` (computed by the opener and by `fastagent login`); this is only the
@@ -42,57 +44,169 @@ function pick(creds, providerId) {
     const cred = creds[providerId];
     return cred && (cred.type === "oauth" || cred.type === "api_key") ? cred : undefined;
 }
+const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: 0o600 };
 /**
- * Parse the credentials JSON for a WRITE: a corrupt file must THROW — serializing `{}` over it would
- * wipe every other provider's credentials. The throw aborts the locked write, leaving the file intact.
+ * Serialized cross-process read-modify-write of the credentials file: exponential-backoff retries,
+ * 30s staleness, and compromise detection (the parameters pi's `FileAuthStorageBackend` used).
+ * Ensures the file exists first (0700 dir, 0600 file, EXCLUSIVE create: a concurrent first write
+ * must never be clobbered by the init) because `proper-lockfile` locks an existing path. A
+ * compromised lock aborts before the write rather than clobbering a concurrent writer, and a
+ * failed unlock after a successful operation rejects instead of leaving a stale lock silently.
  */
-function parseForWrite(raw, where) {
-    if (!raw)
-        return {};
+async function withLockedAuthFile(authPath, fn) {
+    const dir = dirname(authPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (!existsSync(authPath)) {
+        try {
+            writeFileSync(authPath, "{}", { ...AUTH_FILE_WRITE_OPTIONS, flag: "wx" });
+            chmodSync(authPath, 0o600);
+        }
+        catch (error) {
+            // EEXIST: another process created the file between the existence check and this exclusive
+            // create; its content (possibly already-written credentials) must not be clobbered.
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    let compromised;
+    const throwIfCompromised = () => {
+        if (compromised)
+            throw compromised;
+    };
+    const release = await lockfile.lock(authPath, {
+        retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10_000, randomize: true },
+        stale: 30_000,
+        onCompromised: (error) => {
+            compromised = error;
+        },
+    });
+    let result;
+    try {
+        throwIfCompromised();
+        const current = existsSync(authPath) ? readFileSync(authPath, "utf8") : undefined;
+        const out = await fn(current);
+        throwIfCompromised();
+        if (out.next !== undefined) {
+            writeFileSync(authPath, out.next, AUTH_FILE_WRITE_OPTIONS);
+            chmodSync(authPath, 0o600);
+        }
+        throwIfCompromised();
+        result = out.result;
+    }
+    catch (error) {
+        // The primary failure stays the signal; unlock noise must not mask it.
+        try {
+            await release();
+        }
+        catch {
+            // Secondary: a compromised or stale-reclaimed lock often cannot release cleanly.
+        }
+        throw error;
+    }
+    // Success path: a failed release is a real cleanup failure (the leftover auth.json.lock stalls
+    // the next writer for the staleness window with zero diagnostics), so it surfaces instead of
+    // resolving a silently degraded operation. A compromise detected after the last in-band check
+    // surfaces here too.
+    try {
+        await release();
+    }
+    catch (releaseError) {
+        if (compromised === undefined)
+            throw releaseError;
+    }
+    throwIfCompromised();
+    return result;
+}
+/**
+ * Decode the credentials JSON, shared by the read and write paths. The root must be a plain
+ * non-null, non-array object: `[]`, `null`, and scalar roots pass JSON.parse but break the record
+ * semantics (an array root even swallows writes, since JSON.stringify drops string keys on arrays).
+ * Structurally invalid = corrupt, exactly like unparsable text.
+ */
+function decodeCreds(raw) {
+    let parsed;
     try {
-        return JSON.parse(raw);
+        parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error(`refusing to overwrite corrupt auth file ${where} — fix or remove it`);
+        return undefined;
     }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    return parsed;
+}
+/**
+ * Tolerant UNLOCKED read of the whole credentials file, shared by `read` and `list`. The only race
+ * is a sub-millisecond in-place write during an OAuth rotation, which can yield an empty/partial
+ * file; re-read a few times before concluding it is corrupt. A missing file reads as undefined
+ * silently (normal not-configured); a valid file returns immediately, so the common case costs one
+ * read.
+ */
+async function readCreds(authPath, warn) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        let raw;
+        try {
+            raw = readFileSync(authPath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined; // missing/deleted
+            warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
+            return undefined;
+        }
+        if (raw !== "") {
+            const creds = decodeCreds(raw);
+            if (creds !== undefined)
+                return creds;
+            // A partial read mid-write parses as garbage; fall through and retry. A structurally invalid
+            // root lands here too and is reported as corrupt below.
+        }
+        if (attempt < 2)
+            await sleep(2);
+    }
+    warn(`[fastagent] corrupt auth file ${authPath}: fix or remove it`);
+    return undefined;
+}
+/**
+ * Parse the credentials JSON for a WRITE: a corrupt file must THROW, because serializing `{}` over
+ * it would wipe every other provider's credentials. The throw aborts the locked write, leaving the
+ * file intact.
+ */
+function parseForWrite(raw, where) {
+    if (!raw)
+        return {};
+    const creds = decodeCreds(raw);
+    if (creds === undefined) {
+        throw new Error(`refusing to overwrite corrupt auth file ${where}: fix or remove it`);
+    }
+    return creds;
 }
 /** A read-write `CredentialStore` backed by the given credentials file (default {@link GLOBAL_AUTH_PATH};
  *  the directory opener passes the project-level `<dir>/.fastagent/auth.json`). */
 export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options = {}) {
     const warn = options.warn ?? ((message) => log.warn(message));
-    const backend = new FileAuthStorageBackend(authPath);
     return {
         async read(providerId) {
-            // UNLOCKED hot path: the only race is a sub-millisecond in-place write during an OAuth rotation,
-            // which can yield an empty/partial file. Re-read a few times before concluding it is corrupt;
-            // a valid `{}` (provider absent) returns immediately, so a not-configured read costs nothing.
-            for (let attempt = 0; attempt < 3; attempt++) {
-                let raw;
-                try {
-                    raw = readFileSync(authPath, "utf8");
-                }
-                catch (error) {
-                    if (error.code === "ENOENT")
-                        return undefined; // missing/deleted
-                    warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
-                    return undefined;
-                }
-                if (raw !== "") {
-                    try {
-                        return pick(JSON.parse(raw), providerId);
-                    }
-                    catch {
-                        // A partial read mid-write parses as garbage — fall through and retry.
-                    }
+            const creds = await readCreds(authPath, warn);
+            return creds ? pick(creds, providerId) : undefined;
+        },
+        async list() {
+            // Metadata only, never secrets (the pi-ai `list` contract). Foreign/old entries are filtered
+            // with the same validation as `read`, so both surfaces agree on what "configured" means.
+            const creds = await readCreds(authPath, warn);
+            if (!creds)
+                return [];
+            const infos = [];
+            for (const [providerId, cred] of Object.entries(creds)) {
+                if (cred && (cred.type === "oauth" || cred.type === "api_key")) {
+                    infos.push({ providerId, type: cred.type });
                 }
-                if (attempt < 2)
-                    await sleep(2);
             }
-            warn(`[fastagent] corrupt auth file ${authPath} — fix or remove it`);
-            return undefined;
+            return infos;
         },
         modify(providerId, fn) {
-            return backend.withLockAsync(async (current) => {
+            return withLockedAuthFile(authPath, async (current) => {
                 const creds = parseForWrite(current, authPath); // corrupt → throw → no clobber
                 const next = await fn(pick(creds, providerId));
                 if (next === undefined)
@@ -102,11 +216,11 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
             });
         },
         async delete(providerId) {
-            // No-op when nothing is stored: do NOT take the lock (which would create the file via the
-            // backend's ensureFileExists) on a machine that never stored this provider.
+            // No-op when nothing is stored: do NOT take the lock (which would create the file) on a
+            // machine that never stored this provider.
             if (!existsSync(authPath))
                 return;
-            await backend.withLockAsync(async (current) => {
+            await withLockedAuthFile(authPath, async (current) => {
                 const creds = parseForWrite(current, authPath);
                 if (!(providerId in creds))
                     return { result: undefined }; // absent: no write