@fastagent-sh/fastagent 0.19.0 → 0.21.0

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

@@ -17,23 +17,9 @@
  * (one machine, the single-machine tier). Secrets go in via `secrets import` over stdin, so values
  * never land in argv/process listings.
  */
-import type { RegistrationOutcome } from "../../channels/registration.ts";
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Registrars } from "../channel-ingress.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import type { CliRunner } from "../runner.ts";
-/**
- * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
- * FASTAGENT_AUTH_SEED materialization. ABSENT-ONLY by design: a present file (a refreshed volume copy)
- * is never overwritten by the stale seed, so a box that ran its own OAuth refresh is not rolled back.
- */
-export declare function authSeedBytes(seed: string | undefined, fileExists: boolean): Buffer | undefined;
-/**
- * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
- * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
- * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
- * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
- * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
- */
-export declare function collectAuthSeed(env: NodeJS.ProcessEnv): string | undefined;
 export interface FlyRunPlan {
     appName: string;
     region: string;
@@ -42,8 +28,8 @@ export interface FlyRunPlan {
     secrets: Record<string, string>;
     /** Required secret names with NO local value — the run gates on these before any side effect. */
     missingSecrets: string[];
-    channels: ChannelKind[];
-    longConnectionChannels?: string[];
+    /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
+    channels: readonly DeclaredChannel[];
     /** fly.toml path passed to `fly deploy -c` (relative to the run cwd = the workspace root). */
     flyConfig: string;
     /** Dockerfile path passed explicitly (`fastagent/Dockerfile`, with the workspace as context —
@@ -58,9 +44,36 @@ export type FlyRunOutcome = {
     gate: string;
 };
 /**
- * Run the deploy through `fly`. `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.
+ * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an
+ * ingress address" is not the question the two allocate commands answer. An app holding only a `v6`
+ * passes the coarse test and still resolves `<app>.fly.dev` to an AAAA record alone, so an IPv4-only
+ * webhook sender (Telegram, GitHub) reproduces #425 against it.
+ *
+ * The list is EVERY assignment the app holds, and a Flycast or egress address carries a non-empty
+ * `Address` too — reading one as routable pre-empts flyctl's own first-deploy fallback, which returns
+ * early once any assignment exists.
+ *
+ * Output that is not a JSON array THROWS rather than reading as "no address": the caller turns that
+ * into a gate, because a list we cannot read is not a state we can act on.
+ */
+export declare function ingressAddresses(stdout: string): {
+    v4: boolean;
+    v6: boolean;
+};
+/**
+ * Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept
+ * both). Exported for the same reason railway's parsers are: what it encodes is an assumption about
+ * another tool's output, and the live probe checks that assumption against the real `flyctl`.
+ *
+ * THROWS on output that is not a JSON array, for the same reason {@link ingressAddresses} does —
+ * `false` here means "the host does not have it", and answering that for a list nobody could read
+ * creates a SECOND volume, or in teardown destroys nothing at all.
+ */
+export declare function listHasName(stdout: string, name: string): boolean;
+/**
+ * Run the deploy through `fly`. `log` reports progress; the injected {@link Registrars} perform the
+ * post-deploy webhook steps from the builder machine (Slack's control credential never travels to the
+ * host). A registrar the caller did not wire becomes the printed manual step. Every gate is
+ * fail-visible.
  */
-export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<FlyRunOutcome>;
+export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registrars: Registrars): Promise<FlyRunOutcome>;

package/dist/deploy/fly/run.js

@@ -1,50 +1,96 @@
-import { registrationGate } from "../registration-gate.js";
 /**
- * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
- * FASTAGENT_AUTH_SEED materialization. ABSENT-ONLY by design: a present file (a refreshed volume copy)
- * is never overwritten by the stale seed, so a box that ran its own OAuth refresh is not rolled back.
+ * `fastagent deploy fly --run` — drive flyctl to completion. The middle of the deploy (app / volume /
+ * secrets / deploy) that the plain runbook hands to the operator; `--run` executes it instead, so a
+ * coding agent runs ONE command. Idempotent (app/volume check-then-act; channel secrets come from the
+ * local env — NOT minted — so a re-run sets the same values) and resumable: it STOPS at a human gate
+ * (not logged in, a missing secret value, a taken app name, a failed webhook registration) with one actionable line and a non-zero
+ * exit, so the agent clears the gate and re-runs. A `generate` channel secret absent from `.env` is a
+ * gate too (`missingSecrets`), not a silent mint — fill it in `.env` (use the random string that
+ * `add <channel>` prints).
+ *
+ * flyctl is behind the shared {@link CliRunner} seam — production spawns `fly`, tests inject a fake that
+ * records the command sequence and scripts outputs. That seam is the benchmark: the agent's journey
+ * encoded as an asserted command sequence + gate behavior, validated without a real Fly account.
+ *
+ * Non-interactive incantations the agent would otherwise get wrong: `--remote-only` (build on Fly's
+ * builders — no local Docker in a sandbox), `--yes` (no prompts), `--ha=false` + the mounted volume
+ * (one machine, the single-machine tier). Secrets go in via `secrets import` over stdin, so values
+ * never land in argv/process listings.
  */
-export function authSeedBytes(seed, fileExists) {
-    return !seed || fileExists ? undefined : Buffer.from(seed, "base64");
+import { registerWebhooks } from "../channel-ingress.js";
+/** The `Type` values that put an app on `https://<app>.fly.dev`, BY FAMILY — one entry per allocate
+ *  command, because that is the granularity the answer is acted on at. The rest of flyctl's
+ *  vocabulary — `private_v6` (Flycast), `egress_v4`, `egress_v6`, `egress_pair` — is internal or
+ *  outbound. */
+const INGRESS_TYPES = { v4: ["v4", "shared_v4"], v6: ["v6"] };
+/**
+ * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an
+ * ingress address" is not the question the two allocate commands answer. An app holding only a `v6`
+ * passes the coarse test and still resolves `<app>.fly.dev` to an AAAA record alone, so an IPv4-only
+ * webhook sender (Telegram, GitHub) reproduces #425 against it.
+ *
+ * The list is EVERY assignment the app holds, and a Flycast or egress address carries a non-empty
+ * `Address` too — reading one as routable pre-empts flyctl's own first-deploy fallback, which returns
+ * early once any assignment exists.
+ *
+ * Output that is not a JSON array THROWS rather than reading as "no address": the caller turns that
+ * into a gate, because a list we cannot read is not a state we can act on.
+ */
+export function ingressAddresses(stdout) {
+    const entries = JSON.parse(stdout);
+    if (!Array.isArray(entries))
+        throw new Error(`expected a JSON array, got ${typeof entries}`);
+    const has = (types) => entries.some((entry) => typeof entry?.Address === "string" && entry.Address !== "" && types.includes(entry.Type));
+    return { v4: has(INGRESS_TYPES.v4), v6: has(INGRESS_TYPES.v6) };
 }
 /**
- * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
- * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
- * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
- * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
- * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
+ * Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept
+ * both). Exported for the same reason railway's parsers are: what it encodes is an assumption about
+ * another tool's output, and the live probe checks that assumption against the real `flyctl`.
+ *
+ * THROWS on output that is not a JSON array, for the same reason {@link ingressAddresses} does —
+ * `false` here means "the host does not have it", and answering that for a list nobody could read
+ * creates a SECOND volume, or in teardown destroys nothing at all.
  */
-export function collectAuthSeed(env) {
-    const first = env.FASTAGENT_AUTH_SEED;
-    if (!first)
-        return undefined;
-    let seed = first;
-    for (let i = 2;; i++) {
-        const part = env[`FASTAGENT_AUTH_SEED_${i}`];
-        if (!part)
-            break;
-        seed += part;
-    }
-    return seed;
+export function listHasName(stdout, name) {
+    const entries = JSON.parse(stdout);
+    if (!Array.isArray(entries))
+        throw new Error(`expected a JSON array, got ${typeof entries}`);
+    return entries.some((o) => o.Name === name || o.name === name);
 }
-/** Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept both). */
-function listHasName(stdout, name) {
+/**
+ * A read-only `fly … list --json`, reduced to the question the next step asks of it — or the gate for
+ * a list we cannot act on. THE place the three answers stay three: the command failed, the output was
+ * unreadable, or the host gave a verdict. Collapsing the middle one into `false` is what shipped #425
+ * and what would have skipped a teardown.
+ */
+async function readList(fly, args, read) {
+    // The command as RUN, not a restatement of it: a gate that tells the operator to run it themselves
+    // has to name one that works from their cwd, and `fly ips list --json` without `-a <app>` does not
+    // (fly.toml lives under the agent prefix, so flyctl finds no app).
+    const cmd = `fly ${args.join(" ")}`;
+    const result = await fly(args, { capture: true });
+    if (result.code !== 0)
+        return { gate: `\`${cmd}\` failed — see the flyctl output above; fix and re-run` };
     try {
-        const arr = JSON.parse(stdout);
-        return (Array.isArray(arr) &&
-            arr.some((o) => o.Name === name || o.name === name));
+        return { value: read(result.stdout) };
     }
-    catch {
-        return false;
+    catch (error) {
+        // The one place a parse failure is allowed to stop being an exception: this IS the boundary that
+        // turns it into the operator's gate (printed + non-zero exit), never a default answer.
+        return {
+            gate: `\`${cmd}\` was unreadable (${error instanceof Error ? error.message : String(error)}) — ` +
+                `run it yourself and check the flyctl version; fix and re-run`,
+        };
     }
 }
 /**
- * Run the deploy through `fly`. `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.
+ * Run the deploy through `fly`. `log` reports progress; the injected {@link Registrars} perform the
+ * post-deploy webhook steps from the builder machine (Slack's control credential never travels to the
+ * host). A registrar the caller did not wire becomes the printed manual step. Every gate is
+ * fail-visible.
  */
-export async function deployFlyRun(plan, fly, log, registerTelegram, registerFeishu, registerSlack) {
+export async function deployFlyRun(plan, fly, log, registrars) {
     const gate = (g) => ({ ok: false, gate: g });
     // 1. Auth is the one gate a coding agent can't clear itself (browser OAuth). `whoami` succeeds with
     //    either an interactive login or FLY_API_TOKEN, so one check covers both.
@@ -55,12 +101,13 @@ export async function deployFlyRun(plan, fly, log, registerTelegram, registerFei
     if (plan.missingSecrets.length > 0) {
         return gate(`no local value for: ${plan.missingSecrets.join(", ")} — set them in .env (or the environment) and re-run`);
     }
-    // 3. App — idempotent (create only if absent; a taken global name is a gate). A FAILED list is its own
-    //    gate: inferring "absent" from an errored query would then misreport the create as a name clash.
-    const appsList = await fly(["apps", "list", "--json"], { capture: true });
-    if (appsList.code !== 0)
-        return gate("`fly apps list` failed — see the flyctl output above; fix and re-run");
-    if (listHasName(appsList.stdout, plan.appName)) {
+    // 3. App — idempotent (create only if absent; a taken global name is a gate). An unusable list is its
+    //    own gate ({@link readList}): inferring "absent" from a query nobody could read would then
+    //    misreport the create as a name clash.
+    const appExists = await readList(fly, ["apps", "list", "--json"], (out) => listHasName(out, plan.appName));
+    if ("gate" in appExists)
+        return gate(appExists.gate);
+    if (appExists.value) {
         log(`app ${plan.appName} exists — skipping create`);
     }
     else {
@@ -72,10 +119,10 @@ export async function deployFlyRun(plan, fly, log, registerTelegram, registerFei
     }
     // 4. Volume — idempotent; region comes from fly.toml (must match the machine's region). A failed list
     //    gates for the same reason as the app list above.
-    const volList = await fly(["volumes", "list", "-a", plan.appName, "--json"], { capture: true });
-    if (volList.code !== 0)
-        return gate("`fly volumes list` failed — see the flyctl output above; fix and re-run");
-    if (listHasName(volList.stdout, "data")) {
+    const volumeExists = await readList(fly, ["volumes", "list", "-a", plan.appName, "--json"], (out) => listHasName(out, "data"));
+    if ("gate" in volumeExists)
+        return gate(volumeExists.gate);
+    if (volumeExists.value) {
         log(`volume data exists — skipping create`);
     }
     else {
@@ -85,7 +132,33 @@ export async function deployFlyRun(plan, fly, log, registerTelegram, registerFei
             return gate("`fly volumes create` failed — see the flyctl output above");
         }
     }
-    // 5. Secrets — staged (no deploy yet; we deploy with fly.toml next). Values over stdin, not argv.
+    // 5. Ingress address — `[http_service]` in fly.toml DECLARES a service; it does not create an address
+    //    to reach it on. `fly launch` allocates one as part of its flow, and this driver does not use it,
+    //    so without this step the deploy succeeds, the machine serves, and `https://<app>.fly.dev` has no
+    //    DNS record at all — reported as a healthy deploy, and handed to the webhook registrars as a URL
+    //    they then fail to reach.
+    const addresses = await readList(fly, ["ips", "list", "-a", plan.appName, "--json"], ingressAddresses);
+    if ("gate" in addresses)
+        return gate(addresses.gate);
+    // Check-then-act PER FAMILY: an app that already holds one must still be given the other, or the
+    // gate between the two allocations below heals into a permanent half-state — the re-run the gate
+    // asks for sees the v4 it just made, skips, and reports success on an app with no v6 (and, the way
+    // that matters, no v4). v4 SHARED and v6 are both free; a dedicated v4 is billed, so it stays an
+    // operator decision — `fly ips allocate-v4 -a <app>` after the fact, which this step reads as v4.
+    for (const [family, allocate] of [
+        ["v4", ["ips", "allocate-v4", "--shared", "-a", plan.appName]],
+        ["v6", ["ips", "allocate-v6", "-a", plan.appName]],
+    ]) {
+        if (addresses.value[family]) {
+            log(`public ${family} address exists — skipping allocate`);
+            continue;
+        }
+        log(`allocating a public ${family} address…`);
+        if ((await fly([...allocate])).code !== 0) {
+            return gate(`\`fly ${allocate.join(" ")}\` failed — see the flyctl output above`);
+        }
+    }
+    // 6. Secrets — staged (no deploy yet; we deploy with fly.toml next). Values over stdin, not argv.
     const keys = Object.keys(plan.secrets);
     if (keys.length > 0) {
         log(`setting ${keys.length} secret(s): ${keys.join(", ")}`);
@@ -94,7 +167,7 @@ export async function deployFlyRun(plan, fly, log, registerTelegram, registerFei
             return gate("`fly secrets import` failed — see the flyctl output above");
         }
     }
-    // 6. Deploy — remote builder (no local Docker), one machine. Context + Dockerfile are passed
+    // 7. Deploy — remote builder (no local Docker), one machine. Context + Dockerfile are passed
     //    explicitly (the workspace root is the context; the Dockerfile lives under fastagent/).
     log("deploying (remote build)…");
     const deployArgs = [
@@ -113,42 +186,15 @@ export async function deployFlyRun(plan, fly, log, registerTelegram, registerFei
     if ((await fly(deployArgs)).code !== 0) {
         return gate("`fly deploy` failed — see the flyctl output above; fix and re-run");
     }
-    // 7. Post-deploy webhook — telegram end-to-end (fastagent has the token + the live URL); github is a
-    //    repo-settings step only a human can do. Gate policy is the shared registration-gate kernel
-    //    (registrars report facts, it owns the policy); all channels are attempted first.
-    const reg = registrationGate(log, "re-run to retry registration (steps already done are skipped)");
-    if (plan.channels.includes("telegram")) {
-        log("registering telegram webhook…");
-        reg.track("telegram", await registerTelegram(`https://${plan.appName}.fly.dev`));
-    }
-    if (plan.channels.includes("github")) {
-        log(`github: set the webhook in the repo (Settings → Webhooks) → https://${plan.appName}.fly.dev/webhook`);
-        reg.track("github", "manual"); // always a human step — re-surface it after the registrar output
-    }
-    if (plan.channels.includes("slack")) {
-        const baseUrl = `https://${plan.appName}.fly.dev`;
-        if (registerSlack) {
-            log("registering slack event URL…");
-            reg.track("slack", await registerSlack(baseUrl));
-        }
-        else {
-            log(`slack: set Event Subscriptions → Request URL → ${baseUrl}/slack`);
-            reg.track("slack", "manual");
-        }
-    }
-    for (const kind of ["feishu", "lark"]) {
-        if (!plan.channels.includes(kind) || plan.longConnectionChannels?.includes(kind))
-            continue;
-        if (registerFeishu) {
-            log(`registering ${kind} event URL…`);
-            reg.track(kind, await registerFeishu(`https://${plan.appName}.fly.dev`, kind));
-        }
-        else {
-            log(`${kind}: set the event Request URL in the developer console (Events & Callbacks) → https://${plan.appName}.fly.dev/${kind} (the app must be running when you save)`);
-            reg.track(kind, "manual"); // no registrar wired — the console step above is the operator's
-        }
-    }
-    const registrationGateMsg = reg.gate();
+    // 8. Post-deploy webhook — which channels, in what words, and the gate policy are all the shared
+    //    kernel's; Fly contributes its deterministic URL and how to retry.
+    const registrationGateMsg = await registerWebhooks({
+        baseUrl: `https://${plan.appName}.fly.dev`,
+        channels: plan.channels,
+        registrars,
+        log,
+        retryHint: "re-run to retry registration (steps already done are skipped)",
+    });
     if (registrationGateMsg)
         return gate(registrationGateMsg);
     return { ok: true };

package/dist/deploy/hosts.d.ts

@@ -0,0 +1,5 @@
+/** The deploy targets, as a value: the CLI's `<host>` choices and the host-only-flag table's
+ *  exhaustiveness check both read it. Dependency-free, so `cli/program.ts` can import it at load
+ *  time without pulling a command module. */
+export declare const DEPLOY_HOSTS: readonly ["docker", "fly", "railway", "agentcore"];
+export type DeployHost = (typeof DEPLOY_HOSTS)[number];

package/dist/deploy/hosts.js

@@ -0,0 +1,4 @@
+/** The deploy targets, as a value: the CLI's `<host>` choices and the host-only-flag table's
+ *  exhaustiveness check both read it. Dependency-free, so `cli/program.ts` can import it at load
+ *  time without pulling a command module. */
+export const DEPLOY_HOSTS = ["docker", "fly", "railway", "agentcore"];

package/dist/deploy/preflight.d.ts

@@ -1,6 +1,6 @@
-import type { FastagentConfig } from "../engines/pi/config.ts";
+import { type FastagentConfig } from "../engines/pi/config.ts";
 import { type ResolvedPlacement } from "../paths.ts";
-import { type ChannelKind } from "../scaffold/add-channel.ts";
+import { type DeclaredChannel } from "../channels/discover.ts";
 import { type ContainerInput } from "./container.ts";
 /** A stderr line the CLI prints (`[fastagent] warn: …` / `[fastagent] note: …`). Host-neutral advisories. */
 interface DeployMessage {
@@ -10,11 +10,10 @@ interface DeployMessage {
 /** The resolved facts every host plan needs (the container shape, channels, model auth, ports/secrets). */
 interface DeployFacts {
     messages: DeployMessage[];
-    channels: ChannelKind[];
-    /** Every structurally detected HTTP-route channel basename, including custom channels. */
-    routeChannels: string[];
-    /** Every structurally detected long-connection channel basename, including custom channels. */
-    longConnectionChannels: string[];
+    /** Every declared channel with the ingress its module shape says it has, custom ones included. The
+     *  ONE channel fact the plans and drivers read: a consumer that needs a subset derives it (see
+     *  {@link webhookKinds}) rather than receiving a list someone else already filtered. */
+    channels: DeclaredChannel[];
     /** Whether the agent has TIME triggers — `schedules/` files or `selfSchedule` (the wake tool). Cron/wake
      *  has no external wake-up, so the deployment must keep one machine running: the fly plan forces
      *  `min_machines_running=1`, the railway runbook forbids App Sleeping. */

package/dist/deploy/preflight.js

@@ -14,15 +14,15 @@ import { basename, isAbsolute, join, relative, sep } from "node:path";
 import ignore from "ignore";
 import { classifyBind } from "../bind.js";
 import { resolveAuthPath } from "../engines/pi/config.js";
-import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
+import { resolveSecretsDir, resolveStateRoot, exists, readTextIfExists } from "../paths.js";
 import { inspectChannels } from "../channels/discover.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
 import { createPiModelRuntime, modelCredentialCarry, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
-import { exists } from "../paths.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "./container.js";
+import { CONTROL_TOKEN_ENV } from "../channels/control.js";
 import { isEnvKey } from "./secrets.js";
 /**
  * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore`
@@ -74,17 +74,19 @@ export async function preflightDeploy(input) {
         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.
+    // (steer, stop, rewrite or delete a session) rides the PUBLIC host URL, protected only by the bearer token. The token
+    // travels as a deploy secret (see extraSecrets below) so the caller has it; the reach still warrants
+    // a warning — 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)`,
+            text: `sessionControl: true — the deployed box serves /control/* (steer, stop, rewrite or delete a session) at its public URL, ` +
+                `protected only by a bearer token. Set ${CONTROL_TOKEN_ENV} (listed with the other secrets) and give the ` +
+                `same value to callers: attach --url <public-url> --token …. Unset, the box mints its own per boot — ` +
+                `readable only by shelling in (\`docker compose exec\`/\`fly ssh console\`: <stateRoot>/control.json, whose ` +
+                `url field is container-loopback) and replaced on every restart. Front the endpoint with real auth for ` +
+                `anything wider (docs/design/session-control.md §14)`,
         });
     }
     // Known channel kinds only — a custom channel's secrets/webhook are unknown to us; note and let the
@@ -93,20 +95,18 @@ export async function preflightDeploy(input) {
     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))
+    const channels = inspected.channels;
+    for (const { name, ingress } of channels) {
+        if (CHANNEL_KINDS.includes(name))
             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`,
+            text: ingress === "long-connection"
+                ? `long-connection channel "${name}" is custom — configure its secrets yourself; generated deploy plans keep the process running and skip webhook registration`
+                : `route channel "${name}" is custom — configure its secrets and webhook yourself`,
         });
     }
+    const longConnectionChannels = channels.filter((c) => c.ingress === "long-connection").map((c) => c.name);
     // 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
@@ -299,7 +299,7 @@ export async function preflightDeploy(input) {
     // `docker build` (so it is the file that actually decides `deploy docker`). Checking only the root one
     // left the credential gate not covering the path it was written for.
     for (const rel of [".dockerignore", `${agentPrefix}Dockerfile.dockerignore`]) {
-        const kept = await readFile(join(workspace, rel), "utf8").catch(() => undefined);
+        const kept = await readTextIfExists(join(workspace, rel));
         if (kept === undefined)
             continue;
         // One WE generated is regenerated by this very run under --force, so checking the stale content on
@@ -405,7 +405,13 @@ export async function preflightDeploy(input) {
     }
     // What the agent declared it needs on the box (fastagent.config deploy.secrets) — carried like channel
     // secrets: listed in the runbook, set from the local env under --run, gated if a value is missing.
-    const extraSecrets = config.deploy?.secrets ?? [];
+    const extraSecrets = [...(config.deploy?.secrets ?? [])];
+    // The plane's bearer token is the DEPLOYMENT's secret, not the container's: minted inside the box it
+    // is unreadable from outside and replaced on every restart, which is what makes a public /control/*
+    // unusable. Carried like any declared secret — listed in the runbook, taken from the local env under
+    // --run, gated when absent (never minted: a value minted per deploy rotates under its holder).
+    if (config.sessionControl === true)
+        extraSecrets.push(CONTROL_TOKEN_ENV);
     // deploy.apt only shapes the GENERATED Dockerfile. Warn ONLY when the kept Dockerfile is HAND-WRITTEN
     // (its apt won't include these) — a fastagent-generated one is handled by writeArtifacts. Don't suggest
     // --force here: it would overwrite the user's hand-written file.
@@ -423,8 +429,6 @@ export async function preflightDeploy(input) {
         ok: true,
         messages,
         channels,
-        routeChannels,
-        longConnectionChannels,
         hasTimeTriggers,
         modelAuth,
         modelKeyInDefinition,

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

@@ -21,7 +21,7 @@
  * the required-secret list. `railway.json`'s `healthcheckPath=/health` also fixes the "routed before the
  * server is listening" boot race Fly's deploy hit — Railway only routes once /health passes.
  */
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
 export interface RailwayPlanInput extends ContainerInput {
     /** The service name to create (`railway add --service`). Railway service names are project-scoped, not
@@ -29,10 +29,9 @@ 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;
-    /** 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[];
+    /** Every declared channel and its ingress — the source of the secret list, the webhook steps, and
+     *  whether App Sleeping must stay off for an outbound connection. */
+    channels: readonly DeclaredChannel[];
     /** 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
@@ -51,6 +50,11 @@ export interface RailwayPlan {
  *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
  *  convention); two mechanisms, two documented spellings, one fact each. */
 export declare const dockerfilePathVar: (prefix: string) => string;
+/** The name this tool gives BOTH the project and the service, derived from the workspace directory.
+ *  Railway names are project-scoped (not globally unique like a Fly app), so this only has to survive
+ *  the command — slug anything that would break `railway add --service <name>`, and name the fallback
+ *  rather than emitting an empty argument. Shared so the live probe tears down what the CLI creates. */
+export declare function toRailwayName(basename: string): string;
 /** Did fastagent generate this `railway.json`? Unparseable or unmarked reads as the author's. */
 export declare function isGeneratedRailwayJson(content: string): boolean;
 /** Compute the Railway deploy plan from the resolved definition. */

package/dist/deploy/railway/plan.js

@@ -1,3 +1,4 @@
+import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 /** State root = the volume mount path, kept in lockstep. `/data` matches the Fly recipe. */
@@ -7,8 +8,13 @@ const MOUNT = "/data";
  *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
  *  convention); two mechanisms, two documented spellings, one fact each. */
 export const dockerfilePathVar = (prefix) => `/${prefix}Dockerfile`;
-/** railway.json — build/deploy only (Railway's config-as-code scope). No env/volume/sleeping here: those
- *  are service settings the runbook applies via CLI. healthcheckPath gates routing on a live server. */
+/** The name this tool gives BOTH the project and the service, derived from the workspace directory.
+ *  Railway names are project-scoped (not globally unique like a Fly app), so this only has to survive
+ *  the command — slug anything that would break `railway add --service <name>`, and name the fallback
+ *  rather than emitting an empty argument. Shared so the live probe tears down what the CLI creates. */
+export function toRailwayName(basename) {
+    return basename.replace(/[^a-zA-Z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+}
 /** railway.json is JSON, so its ownership marker is a KEY rather than a comment line. Railway ignores
  *  unknown keys; the predicate below is what lets `--force` reset OUR file and keep a hand-written one. */
 const GENERATED_RAILWAY_KEY = "x-generated-by";
@@ -22,6 +28,8 @@ export function isGeneratedRailwayJson(content) {
         return false;
     }
 }
+/** railway.json — build/deploy only (Railway's config-as-code scope). No env/volume/sleeping here: those
+ *  are service settings the runbook applies via CLI. healthcheckPath gates routing on a live server. */
 function railwayJson(prefix) {
     return `${JSON.stringify({
         $schema: "https://railway.com/railway.schema.json",
@@ -45,7 +53,7 @@ export function planRailwayDeploy(input) {
         { path: configPath, content: railwayJson(input.agentPrefix) },
         ...containerArtifacts(input),
     ];
-    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets, input.longConnectionChannels);
+    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets);
     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
@@ -100,36 +108,20 @@ 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") ||
-        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")) {
-        runbook.push(`# Register the Telegram webhook (default route POST /telegram; if you remapped it in`, `# channels/telegram.ts, use your path). secret_token MUST equal TELEGRAM_SECRET_TOKEN:`, `curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \\`, `  -d url=https://<your-domain>/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`);
-    }
-    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) || 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}`);
+    // Mint only when something below needs it: with nothing to point at the domain (no channels, or only
+    // long-connection ones), "use it in the step(s) below" would refer to steps that do not follow.
+    const steps = webhookRunbook(`https://<your-domain>`, channels);
+    if (steps.length > 0) {
+        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`, ...steps);
     }
     // Scale-to-zero: App Sleeping is dashboard-only (no CLI/API) — a manual step, not a generated setting.
     // A github channel should NOT enable it: fire-and-forget reviews have no replay (unlike Telegram's L1
     // turn store), so a sleep mid-review would drop it — the same floor the Fly plan enforces via config.
-    runbook.push(``, channels.includes("github")
+    runbook.push(``, channels.some((channel) => channel.name === "github")
         ? `# 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.`
-            : (input.longConnectionChannels?.length ?? 0) > 0
+            : channels.some((channel) => channel.ingress === "long-connection")
                 ? `# 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 };