@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/deploy/agentcore/zip.d.ts

@@ -1,17 +1,4 @@
-/**
- * A minimal, DETERMINISTIC single-file ZIP writer — just enough to package the forwarder Lambda.
- *
- * WHY NOT A DEPENDENCY: this runs in the deploy path of a tool whose whole promise is "no build
- * step"; pulling an archiver in for ~40 lines of well-specified format would be the wrong trade.
- * WHY NOT `zip(1)`: it is absent on plenty of machines (and on Windows), and its output embeds the
- * current time — the forwarder's S3 key is CONTENT-HASHED, so identical source must produce
- * identical bytes or every deploy would look like a code change to CloudFormation.
- *
- * STORE (no compression) on purpose: the payload is a few KB of JavaScript, and the format's stored
- * form is trivially verifiable. Fixed 1980-01-01 timestamps keep the output byte-stable.
- */
+/** A minimal, DETERMINISTIC single-file ZIP writer — just enough to package the forwarder Lambda. */
 import { Buffer } from "node:buffer";
-/**
- * Build a ZIP archive containing exactly one stored entry. Byte-identical for identical inputs.
- */
+/** Build a ZIP archive containing exactly one stored entry. */
 export declare function zipSingleFile(name: string, content: Buffer): Buffer;

package/dist/deploy/agentcore/zip.js

@@ -1,23 +1,10 @@
-/**
- * A minimal, DETERMINISTIC single-file ZIP writer — just enough to package the forwarder Lambda.
- *
- * WHY NOT A DEPENDENCY: this runs in the deploy path of a tool whose whole promise is "no build
- * step"; pulling an archiver in for ~40 lines of well-specified format would be the wrong trade.
- * WHY NOT `zip(1)`: it is absent on plenty of machines (and on Windows), and its output embeds the
- * current time — the forwarder's S3 key is CONTENT-HASHED, so identical source must produce
- * identical bytes or every deploy would look like a code change to CloudFormation.
- *
- * STORE (no compression) on purpose: the payload is a few KB of JavaScript, and the format's stored
- * form is trivially verifiable. Fixed 1980-01-01 timestamps keep the output byte-stable.
- */
+/** A minimal, DETERMINISTIC single-file ZIP writer — just enough to package the forwarder Lambda. */
 import { Buffer } from "node:buffer";
 import { crc32 } from "node:zlib";
 /** MS-DOS epoch (1980-01-01 00:00:00) — the earliest the format can express, and a constant. */
 const DOS_DATE = 0x0021;
 const DOS_TIME = 0x0000;
-/**
- * Build a ZIP archive containing exactly one stored entry. Byte-identical for identical inputs.
- */
+/** Build a ZIP archive containing exactly one stored entry. */
 export function zipSingleFile(name, content) {
     const nameBytes = Buffer.from(name, "utf8");
     const sum = crc32(content);
@@ -49,8 +36,7 @@ export function zipSingleFile(name, content) {
     centralHeader.writeUInt16LE(0, 32); // file comment length
     centralHeader.writeUInt16LE(0, 34); // disk number start
     centralHeader.writeUInt16LE(0, 36); // internal attributes
-    // External attributes: regular file, rw-r--r-- in the high 16 bits. `>>> 0` because JS bitwise
-    // operators are 32-bit SIGNED — the shifted value is negative without it.
+    // External attributes: regular file, rw-r--r-- in the high 16 bits.
     centralHeader.writeUInt32LE((0o100644 << 16) >>> 0, 38);
     centralHeader.writeUInt32LE(0, 42); // local header offset (single entry: always 0)
     const centralSize = centralHeader.byteLength + nameBytes.byteLength;

package/dist/deploy/build-context.d.ts

@@ -0,0 +1,21 @@
+import type { DeployReport } from "./preflight.ts";
+/** Workspace-relative paths the build context may hold and the image must not. */
+export interface BuildContextPaths {
+    /** The resolved machinery dirs the generated ignore excludes by path (ContainerInput.machineryPaths). */
+    machineryPaths: string[];
+    /** Credential files that exist right now — a kept ignore file that lets one through bakes it. */
+    leakCandidates: string[];
+    /** The state root, when it exists inside the context. */
+    stateShips?: string;
+    /** The node_modules dirs that exist, the agent's and the workspace's. */
+    depDirs: string[];
+}
+export declare function buildContextPaths(workspace: string, agentDir: string, agentPrefix: string, authPath: string): Promise<BuildContextPaths>;
+/** Interrogate BOTH ignore files deploy emits, when the author kept them. */
+export declare function checkKeptIgnoreFiles(ctx: {
+    workspace: string;
+    agentDir: string;
+    agentPrefix: string;
+    force: boolean;
+    paths: BuildContextPaths;
+}, report: DeployReport): Promise<void>;

package/dist/deploy/build-context.js

@@ -0,0 +1,137 @@
+/**
+ * What a deploy's BUILD CONTEXT (the workspace) holds that must not ship, and whether an ignore file the author kept
+ * still keeps it out. A kept workspace-root `.dockerignore` silently replaces the generated one's protections, so the
+ * pre-flight asks it the same questions the generated one answers by construction.
+ */
+import { readdir } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, sep } from "node:path";
+import ignore from "ignore";
+import { exists, readTextIfExists, resolveSecretsDir, resolveStateRoot } from "../paths.js";
+import { isGeneratedDockerignore } from "./container.js";
+/**
+ * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore` matcher (the same
+ * library the workspace ignore files use), so `!` negation and last-match-wins are the library's problem, not ours.
+ */
+function dockerignoreMatcher(text) {
+    const anchored = text
+        .split("\n")
+        .map((raw) => {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#"))
+            return line;
+        const negated = line.startsWith("!");
+        const pattern = negated ? line.slice(1) : line;
+        if (pattern.startsWith("/") || pattern.startsWith("**/"))
+            return line;
+        return `${negated ? "!" : ""}/${pattern}`;
+    })
+        .join("\n");
+    const matcher = ignore({ ignorecase: false }).add(anchored);
+    return (path) => matcher.ignores(path);
+}
+export async function buildContextPaths(workspace, agentDir, agentPrefix, authPath) {
+    const inContext = (p) => {
+        const rel = relative(workspace, p);
+        return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? undefined : rel.split(sep).join("/");
+    };
+    // The secrets DIR is the unit of RESPONSIBILITY, but never the unit of the leak QUESTION below.
+    const secretsRel = inContext(resolveSecretsDir(agentDir));
+    const authRel = inContext(authPath);
+    const authElsewhere = authRel !== undefined && (secretsRel === undefined || !authRel.startsWith(`${secretsRel}/`));
+    const secretPaths = [...(secretsRel ? [secretsRel] : []), ...(authElsewhere ? [authRel] : [])];
+    // ONE rule for every checked path: a file that is not there cannot be baked, so gating on it would be a refusal
+    // about a spelling rather than about what would ship (an agent that has never run `login` has no auth.json).
+    const present = async (rels) => {
+        const found = [];
+        for (const rel of rels)
+            if (await exists(join(workspace, rel)))
+                found.push(rel);
+        return found;
+    };
+    // State gets the same treatment (a custom in-tree FASTAGENT_STATE_DIR is invisible to the name-based `**/.state`),
+    // at warn level.
+    const stateRel = inContext(resolveStateRoot(agentDir));
+    // Existence gates the WARNING, never the generated exclude (same split as secretPaths vs leakCandidates).
+    const stateShips = stateRel !== undefined && (await exists(join(workspace, stateRel))) ? stateRel : undefined;
+    // The `.env` family at the two levels fastagent is RESPONSIBLE for: the agent dir and the workspace root.
+    const dotEnvFiles = async (relDir) => {
+        const names = await readdir(join(workspace, relDir || ".")).catch(() => []);
+        // POSIX separators, like every other context-relative path here (`inContext`).
+        return names
+            .filter((n) => (n === ".env" || n.startsWith(".env.")) && n !== ".env.example")
+            .map((n) => join(relDir, n).split(sep).join("/"));
+    };
+    const envFiles = (await Promise.all([...new Set(["", agentPrefix])].map(dotEnvFiles))).flat();
+    // Everything ACTUALLY inside the secrets dir, minus the two tracked scaffolds the image ships on purpose (they
+    // carry no values; the generated ignore re-includes them by name).
+    const secretDirFiles = async (dirRel) => {
+        const entries = await readdir(join(workspace, dirRel), { withFileTypes: true }).catch(() => []);
+        const files = [];
+        for (const entry of entries) {
+            if (entry.name === ".gitignore" || entry.name === ".env.example")
+                continue;
+            if (entry.isDirectory())
+                files.push(...(await secretDirFiles(`${dirRel}/${entry.name}`)));
+            else
+                files.push(`${dirRel}/${entry.name}`);
+        }
+        return files;
+    };
+    const leakCandidates = [
+        ...(secretsRel ? await secretDirFiles(secretsRel) : []),
+        ...(await present(authElsewhere && authRel !== undefined ? [authRel] : [])),
+        ...envFiles,
+    ];
+    // Same existence rule: a node_modules that is not there cannot be uploaded.
+    const depDirs = await present([...new Set([`${agentPrefix}node_modules`, "node_modules"])]);
+    const machineryPaths = [...secretPaths, ...(stateRel ? [stateRel] : [])];
+    return { machineryPaths, leakCandidates, stateShips, depDirs };
+}
+/** Interrogate BOTH ignore files deploy emits, when the author kept them. */
+export async function checkKeptIgnoreFiles(ctx, report) {
+    const { workspace, agentDir, agentPrefix, force } = ctx;
+    const { leakCandidates, stateShips, depDirs } = ctx.paths;
+    for (const rel of [".dockerignore", `${agentPrefix}Dockerfile.dockerignore`]) {
+        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 disk would
+        // gate a deploy on a file about to be replaced.
+        const keptIsOurs = isGeneratedDockerignore(kept);
+        if (force && keptIsOurs)
+            continue;
+        const remedy = (lines) => keptIsOurs
+            ? `Re-run with --force to regenerate it.`
+            : `Add ${lines.map((p) => `\`${p}\``).join(" and ")} before deploying (the same lines the generated ${rel} writes).`;
+        const excluded = dockerignoreMatcher(kept);
+        // Asked as a DIRECTORY (trailing slash), which is what it is.
+        if (excluded(`${basename(agentDir)}/`)) {
+            const text = `your ${rel} (kept) excludes \`${basename(agentDir)}\` — the build context would ship WITHOUT the ` +
+                `agent entirely (the deployed box has no persona/config and crash-loops). Remove that rule ` +
+                `before deploying.`;
+            report.issue(text);
+        }
+        // Resolved paths, not spellings: dockerignore patterns are root-anchored (unlike .gitignore), so a bare
+        // `.secrets` line does not cover `fastagent/.secrets`.
+        const leaks = leakCandidates.filter((p) => !excluded(p));
+        if (leaks.length > 0) {
+            const text = `your ${rel} (kept) does not exclude ${leaks.map((p) => `\`${p}\``).join(", ")} — the build ` +
+                `context would BAKE SECRETS INTO THE IMAGE. ${remedy(leaks.map((p) => `/${p}`))}`;
+            report.issue(text);
+        }
+        if (stateShips && !excluded(`${stateShips}/sessions`)) {
+            report.warn(`your ${rel} (kept) does not exclude \`${stateShips}\` — the build machine's sessions/channel state would ship in the image. ${remedy([`/${stateShips}`])}`);
+        }
+        // Both the agent's own node_modules and the workspace's.
+        const unexcludedDeps = depDirs.filter((p) => !excluded(`${p}/.package-lock.json`));
+        if (unexcludedDeps.length > 0) {
+            report.warn(`your ${rel} does not exclude ${unexcludedDeps.map((p) => `\`${p}\``).join(" or ")} — the ` +
+                `build machine's deps (native binaries for YOUR OS) would be uploaded and clobber the image's ` +
+                `freshly-installed ones. ${remedy(unexcludedDeps.map((p) => `/${p}`))}`);
+        }
+        if (excluded(".git/HEAD")) {
+            report.note(`your ${rel} excludes .git — the baked copy ships WITHOUT history/remote, so the agent ` +
+                `cannot pull/commit/push it; it must \`git clone\` its repo in the workspace instead (or remove the .git line).`);
+        }
+    }
+}

package/dist/deploy/channel-ingress.d.ts

@@ -1,54 +1,25 @@
-/**
- * HOW A RUNNING CHANNEL IS REACHED — the URL-neutral half of "point this channel at the agent": its
- * default route, whether anything can set that URL end-to-end, and the words an operator needs when
- * nothing can. Only the base URL varies, which is the argument every function here takes — a deploy
- * host's (`<app>.fly.dev`, a minted Railway domain, a Function URL) or `dev --tunnel`'s Quick Tunnel.
- * It lives under `deploy/` because that is where its answers are mostly consumed and where the gate
- * policy it composes with lives; the serving path reads the same answers through `tunnel.ts`.
- *
- * It exists because that knowledge belongs to the CHANNEL and was written per HOST: three runbook
- * plans, three `--run` drivers, a path table in the docker plan and the `--tunnel` announcer each
- * hand-wrote the same five-branch if-chain. A rule spelled seven times drifts, and it did — the
- * long-connection exception reached only the feishu/lark branches, so a long-connection Telegram
- * deploy printed `setWebhook` in its runbook, which makes `getUpdates` return 409 and stops the
- * channel the operator just deployed.
- *
- * Every function here takes the {@link DeclaredChannel} list and filters it ITSELF. Taking a
- * pre-filtered list would put the rule back at the call sites, which is where it drifted from: the
- * `--tunnel` announcer trusted its caller that way and had a default that passed every channel,
- * long-connection ones included.
- *
- * A host adds its base URL and its own asides; it does not restate which channels have a webhook.
- */
+/** HOW A RUNNING CHANNEL IS REACHED — the URL-neutral half of "point this channel at the agent". */
 import type { DeclaredChannel } from "../channels/discover.ts";
 import type { RegistrationOutcome } from "../channels/registration.ts";
 import type { ChannelKind } from "../scaffold/add-channel.ts";
-/** The registrars a host can drive. `telegram` is always available (fastagent holds the token and the
- *  URL); the others are optional so a caller without their credentials falls back to a manual step. */
 export interface Registrars {
     telegram: (baseUrl: string) => Promise<RegistrationOutcome>;
     slack?: (baseUrl: string) => Promise<RegistrationOutcome>;
     feishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>;
 }
 /**
- * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool
- * knows how to instruct. ONE answer for every host and every path — the runbooks, the `--run`
- * drivers, the docker ingress note, `--tunnel`. A custom channel is skipped here and reported by the
- * pre-flight instead: its URL is its author's to set.
+ * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool knows how to
+ * instruct.
  */
 export declare function webhookKinds(channels: readonly DeclaredChannel[]): ChannelKind[];
 /** Default route keys for {@link webhookKinds}, in the same order (the docker plan's ingress note). */
 export declare function webhookPaths(channels: readonly DeclaredChannel[]): string[];
-/** The runbook block for every channel that needs a URL set by hand, `baseUrl` spelled the host's way
- *  (a literal `https://app.fly.dev`, or a placeholder like `<your-domain>` the operator fills in). */
-export declare function webhookRunbook(baseUrl: string, channels: readonly DeclaredChannel[]): string[];
 /**
- * Point every channel that has a webhook at `baseUrl`, reporting what each one ended as. All channels
- * are attempted — one failure does not skip the rest — and a channel whose registrar the caller did
- * not wire reports `manual` with the operator's instruction. The two callers differ in what they do
- * with the outcomes, not in how they are produced: a deploy gates on them, a long-running serve
- * cannot ({@link registerWebhooks} is the gating half).
+ * The runbook block for every channel that needs a URL set by hand, `baseUrl` spelled the host's way (a literal
+ * `https://app.fly.dev`, or a placeholder like `<your-domain>` the operator fills in).
  */
+export declare function webhookRunbook(baseUrl: string, channels: readonly DeclaredChannel[]): string[];
+/** Point every channel that has a webhook at `baseUrl`, reporting what each one ended as. */
 export declare function pointChannelsAt(input: {
     baseUrl: string;
     channels: readonly DeclaredChannel[];
@@ -58,11 +29,27 @@ export declare function pointChannelsAt(input: {
     kind: ChannelKind;
     outcome: RegistrationOutcome;
 }[]>;
+/** Poll a public `/health` until it answers 200; false on timeout. Injected by tests. */
+export type PublicHealthProbe = (healthUrl: string) => Promise<boolean>;
 /**
- * {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS: an exit 0 claims the
- * deployment is reachable, so a failed registration has to become a non-zero one. Returns the gate
- * message, or undefined when nothing gates.
+ * The readiness floor a host clears BEFORE {@link registerWebhooks}: `setWebhook` does not verify that anything
+ * answers the URL, so a deploy whose app crash-loops would otherwise point a live channel at a dead address and
+ * report success. The channels that DO verify (Slack/Feishu challenge) would fail here too, but as "registration
+ * failed" — a diagnosis that hides the actual cause.
+ *
+ * Asked ONLY when this deployment actually has a webhook to point. A definition with none (schedules only, the
+ * built-in `POST /invoke`, or long-connection channels) needs no inbound reachability at all, and demanding it would
+ * invent a failure for a deploy run from a network that cannot reach the platform's edge.
  */
+export declare function publicHealthGate(input: {
+    baseUrl: string;
+    channels: readonly DeclaredChannel[];
+    log: (msg: string) => void;
+    /** How THIS host is inspected and re-run — the only per-host words in the gate. */
+    inspectHint: string;
+    probe?: PublicHealthProbe;
+}): Promise<string | undefined>;
+/** {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS. */
 export declare function registerWebhooks(input: {
     baseUrl: string;
     channels: readonly DeclaredChannel[];

package/dist/deploy/channel-ingress.js

@@ -1,4 +1,5 @@
 import { registrationGate } from "./registration-gate.js";
+import { waitForHealth } from "../channels/wait-health.js";
 const feishuCloud = (kind, label) => ({
     path: `/${kind}`,
     register: (r, baseUrl) => r.feishu?.(baseUrl, kind),
@@ -22,17 +23,6 @@ const INGRESS = {
             `  -d url=${baseUrl}/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`,
         ],
     },
-    github: {
-        path: "/webhook",
-        // The env-var name is the part a first-time operator cannot guess, and this line is all `--tunnel`
-        // prints — there is no runbook beside it to carry the detail.
-        manual: (baseUrl) => `github: set the webhook in the repo (Settings → Webhooks) → ${baseUrl}/webhook (content type application/json, secret = GITHUB_WEBHOOK_SECRET)`,
-        runbook: (baseUrl) => [
-            `# Set the GitHub webhook (repo Settings → Webhooks). Default route POST /webhook; if you remapped`,
-            `# it in channels/github.ts, use your path:`,
-            `#   Payload URL = ${baseUrl}/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`,
-        ],
-    },
     slack: {
         path: "/slack",
         register: (r, baseUrl) => r.slack?.(baseUrl),
@@ -47,10 +37,8 @@ const INGRESS = {
     lark: feishuCloud("lark", "Lark"),
 };
 /**
- * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool
- * knows how to instruct. ONE answer for every host and every path — the runbooks, the `--run`
- * drivers, the docker ingress note, `--tunnel`. A custom channel is skipped here and reported by the
- * pre-flight instead: its URL is its author's to set.
+ * The first-party channels this deployment must point at a URL: webhook ingress, and a kind this tool knows how to
+ * instruct.
  */
 export function webhookKinds(channels) {
     const declared = new Set(channels.filter((c) => c.ingress === "webhook").map((c) => c.name));
@@ -60,24 +48,20 @@ export function webhookKinds(channels) {
 export function webhookPaths(channels) {
     return webhookKinds(channels).map((kind) => INGRESS[kind].path);
 }
-/** The runbook block for every channel that needs a URL set by hand, `baseUrl` spelled the host's way
- *  (a literal `https://app.fly.dev`, or a placeholder like `<your-domain>` the operator fills in). */
+/**
+ * The runbook block for every channel that needs a URL set by hand, `baseUrl` spelled the host's way (a literal
+ * `https://app.fly.dev`, or a placeholder like `<your-domain>` the operator fills in).
+ */
 export function webhookRunbook(baseUrl, channels) {
     return webhookKinds(channels).flatMap((kind) => INGRESS[kind].runbook(baseUrl));
 }
-/**
- * Point every channel that has a webhook at `baseUrl`, reporting what each one ended as. All channels
- * are attempted — one failure does not skip the rest — and a channel whose registrar the caller did
- * not wire reports `manual` with the operator's instruction. The two callers differ in what they do
- * with the outcomes, not in how they are produced: a deploy gates on them, a long-running serve
- * cannot ({@link registerWebhooks} is the gating half).
- */
+/** Point every channel that has a webhook at `baseUrl`, reporting what each one ended as. */
 export async function pointChannelsAt(input) {
     const outcomes = [];
     for (const kind of webhookKinds(input.channels)) {
         const ingress = INGRESS[kind];
         // Calling IS the question: a channel whose registrar the caller did not wire returns undefined.
-        const running = ingress.register?.(input.registrars, input.baseUrl);
+        const running = ingress.register(input.registrars, input.baseUrl);
         if (!running) {
             input.log(ingress.manual(input.baseUrl));
             outcomes.push({ kind, outcome: "manual" }); // a human's step — re-surfaced after registrar output
@@ -89,10 +73,55 @@ export async function pointChannelsAt(input) {
     return outcomes;
 }
 /**
- * {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS: an exit 0 claims the
- * deployment is reachable, so a failed registration has to become a non-zero one. Returns the gate
- * message, or undefined when nothing gates.
+ * How long a just-deployed public URL gets to answer `/health`: the FIRST boot seeds the whole workspace onto the
+ * volume before it binds a port, so this budget covers a copy on slow host storage, not a listen.
  */
+const PUBLIC_HEALTH_TIMEOUT_MS = 180_000;
+/** How often the wait announces itself, so a crash-looping app is not three silent minutes. */
+const WAIT_NOTICE_MS = 15_000;
+/**
+ * The readiness floor a host clears BEFORE {@link registerWebhooks}: `setWebhook` does not verify that anything
+ * answers the URL, so a deploy whose app crash-loops would otherwise point a live channel at a dead address and
+ * report success. The channels that DO verify (Slack/Feishu challenge) would fail here too, but as "registration
+ * failed" — a diagnosis that hides the actual cause.
+ *
+ * Asked ONLY when this deployment actually has a webhook to point. A definition with none (schedules only, the
+ * built-in `POST /invoke`, or long-connection channels) needs no inbound reachability at all, and demanding it would
+ * invent a failure for a deploy run from a network that cannot reach the platform's edge.
+ */
+export async function publicHealthGate(input) {
+    if (webhookKinds(input.channels).length === 0)
+        return undefined;
+    const healthUrl = `${input.baseUrl}/health`;
+    input.log(`waiting for ${healthUrl} (up to ${PUBLIC_HEALTH_TIMEOUT_MS / 1000}s)…`);
+    const probe = input.probe ?? ((url) => waitForHealth(url, PUBLIC_HEALTH_TIMEOUT_MS, 500, announce(input.log)));
+    if (await probe(healthUrl))
+        return undefined;
+    // The infrastructure is up and only the webhook is missing, so hand over the manual route rather than leaving
+    // `re-run` as the only way out (a Fly re-run repeats the remote build).
+    for (const line of webhookRunbook(input.baseUrl, input.channels))
+        input.log(line);
+    return (`the deployed agent did not become healthy at ${healthUrl}, so no webhook was registered — ${input.inspectHint}. ` +
+        `To point the channels by hand instead, use the lines above.`);
+}
+/**
+ * Keep the wait visible. This occupies `waitForHealth`'s liveness slot without answering it: neither Fly nor Railway
+ * has a liveness question cheaper than the wait it would shorten (each is a CLI round trip, unlike docker's local
+ * `compose ps`), so the hook reports progress and never cuts the budget short.
+ */
+function announce(log) {
+    const started = Date.now();
+    let last = started;
+    return async () => {
+        const now = Date.now();
+        if (now - last >= WAIT_NOTICE_MS) {
+            last = now;
+            log(`still waiting for /health (${Math.round((now - started) / 1000)}s)…`);
+        }
+        return true;
+    };
+}
+/** {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS. */
 export async function registerWebhooks(input) {
     const reg = registrationGate(input.log, input.retryHint);
     for (const { kind, outcome } of await pointChannelsAt(input))

package/dist/deploy/container.d.ts

@@ -2,25 +2,19 @@ export interface Artifact {
     path: string;
     content: string;
 }
-/** Fixed first-line prefix of a fastagent-generated Dockerfile — the ONE source both the generator (the
- *  `head` below) and the "is this ours?" check (cli deploy's kept-Dockerfile apt warn) share, so they
- *  can't drift into detecting a marker the generator no longer writes. */
+/** Fixed first-line prefix of a fastagent-generated Dockerfile. */
 export declare const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
-/** The ONE predicate for "did fastagent generate this Dockerfile?" — a generated file opens with the
- *  marker, so a hand-written one (or a file where the marker was dropped to take ownership) reads false.
- *  Both the "keep vs flag-as-stale" decision and the apt warning share this; a split would let them
- *  disagree on the same file (e.g. a marker not at byte 0). */
+/** The ONE predicate for "did fastagent generate this Dockerfile?". */
 export declare function isGeneratedDockerfile(content: string): boolean;
-/** Did fastagent generate this `.dockerignore`? (Same ownership rule as {@link isGeneratedDockerfile}.) */
 export declare function isGeneratedDockerignore(content: string): boolean;
 export interface ContainerInput {
+    /** Stable for one release; generated once by the deploy preflight, never on container restart. */
+    releaseId: string;
     /** Whether the agent has a package.json (a code agent); else a pure markdown/skills agent. */
     hasPackageJson: boolean;
-    /** The package manager the generated image targets: `bun` (packageManager: bun / a bun lockfile) gets an
-     *  `oven/bun` base + `bun install` + `bun run fastagent`; otherwise npm on `node:22-slim`. */
+    /** The package manager the generated image targets. */
     runtime: "node" | "bun";
-    /** Whether the runtime's lockfile exists (package-lock.json for npm, bun.lock/bun.lockb for bun) — a
-     *  frozen/ci install needs it; without it the build resolves versions at build time (not reproducible). */
+    /** Whether the runtime's lockfile exists (package-lock.json for npm, bun.lock/bun.lockb for bun). */
     hasLockfile: boolean;
     /** For `runtime: "bun"`, the `FROM oven/bun:<tag>` version (from packageManager `bun@x`), else `"1"`. */
     bunVersion?: string;
@@ -28,30 +22,22 @@ export interface ContainerInput {
     version: string;
     /** Extra apt packages (fastagent.config deploy.apt) baked in for the agent's tools — git, ripgrep, …. */
     apt?: string[];
-    /** Where deploy's artifacts and the agent's own files sit, relative to the BUILD CONTEXT (which is
-     *  always the workspace): the agent directory's name plus a slash when it sits INSIDE the workspace,
-     *  `""` when the agent IS the workspace. ONE derived value — an earlier shape branched on a `nested`
-     *  boolean at fifteen separate sites, and each site was a chance for the two to disagree. */
+    /**
+     * The model this deployment resolved, recorded in the release manifest — set only when the deployed environment's
+     * VALUE FILE named it (a `config.model` needs nothing: the config ships too). The manifest is the carrier because
+     * it is rebuilt and rewritten on every deploy, so the answer cannot go stale, and nothing on the way in can
+     * interpolate the operator's shell.
+     */
+    modelSpec?: string;
+    /**
+     * Where deploy's artifacts and the agent's own files sit, relative to the BUILD CONTEXT (which is always the
+     * workspace).
+     */
     agentPrefix: string;
-    /** Workspace-relative machinery paths the NAME-based excludes below would miss — a
-     *  `FASTAGENT_SECRETS_DIR`/`FASTAGENT_STATE_DIR` pointed at an in-tree directory not called
-     *  `.secrets`/`.state`. Preflight resolves them; excluding by PATH is what keeps `COPY . .` from
-     *  baking a credential (or the build machine's sessions). */
+    /** Workspace-relative machinery paths the NAME-based excludes below would miss. */
     machineryPaths?: string[];
-    /** Whether the baked workspace ships a `.git` (preflight fact). When true, preflight has already
-     *  merged "git" into `apt` (the write-back loop needs history + binary together); the plans word
-     *  their runbook's freshness/write-back guidance from the same fact. */
+    /** Whether the baked workspace ships a `.git` (preflight fact). */
     shipsGit?: boolean;
 }
-/**
- * The Dockerfile + ignore artifacts — spread into any host's artifact list. Everything is prefixed with
- * {@link ContainerInput.agentPrefix}, so a NESTED agent's Dockerfile lands under `fastagent/` (never
- * colliding with one the workspace already owns) while an agent that IS the workspace lands it at the root, where it IS
- * the agent's own file. The ignore ships in TWO forms because context packing is host-CLI-owned and
- * inconsistent: (1) a ROOT `.dockerignore` — the only form flyctl/railway's own context packers
- * reliably read (kept if the workspace already has one — preflight then checks the machinery/secret
- * excludes it must carry) — and (2) a per-Dockerfile `Dockerfile.dockerignore` for plain docker/buildx
- * builds. When the agent sits inside the workspace that root file is the ONE write deploy makes outside the agent dir, and
- * only at deploy time — without it the host CLI's packer would bake `.secrets/` into the image.
- */
+/** The Dockerfile + ignore artifacts — spread into any host's artifact list. */
 export declare function containerArtifacts(input: ContainerInput): Artifact[];