@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/cli/commands/deploy/railway.js

@@ -1,24 +1,24 @@
 /**
- * `deploy railway`: a thin config file, scale-to-zero is a manual dashboard step, the URL is minted (see
+ * `deploy railway`: no config file of its own, scale-to-zero is a manual dashboard step, the URL is minted (see
  * planRailwayDeploy).
  */
 import { basename } from "node:path";
-import { dockerfilePathVar, isGeneratedRailwayJson, planRailwayDeploy, toRailwayName, } from "../../../deploy/railway/plan.js";
+import { planRailwayDeploy, toRailwayName } from "../../../deploy/railway/plan.js";
 import { deployRailwayRun } from "../../../deploy/railway/run.js";
 import { spawnRunner } from "../../../deploy/runner.js";
 import { assembleSecrets } from "../../../deploy/secrets.js";
 import { processShell } from "../../../deploy/box-shell.js";
 import { failStartup } from "../../fail.js";
-import { isInteractive } from "../../shared.js";
+import { RAILWAY_LOGIN, hostLogin } from "./host-login.js";
 import { boxLoginStep, registrarsFor } from "./shared.js";
 export const railwayHost = {
-    isOurs: (path, content) => path.endsWith("railway.json") && isGeneratedRailwayJson(content),
-    artifact: "railway.json",
-    shell: async ({ workspace }) => railwayShell(toRailwayName(basename(workspace)), workspace),
+    // Railway's only artifacts are the container's, which planArtifacts owns for every host.
+    isOurs: () => false,
+    shell: async (agentDir) => railwayShell(toRailwayName(basename(agentDir)), agentDir),
     async deploy(ctx) {
-        const { opts, agentDir, workspace, pre, channels, write } = ctx;
+        const { opts, agentDir, pre, channels, write } = ctx;
         const { hasCron, modelAuth, boxLogin, container, declaredSecrets, values, valueFile } = pre;
-        const serviceName = toRailwayName(basename(workspace));
+        const serviceName = toRailwayName(basename(agentDir));
         const plan = planRailwayDeploy({
             serviceName,
             boxLogin,
@@ -29,36 +29,29 @@ export const railwayHost = {
         });
         await write(plan.artifacts, { force: !!opts.force });
         if (opts.run) {
-            // The BUILD entry is guaranteed by the RAILWAY_DOCKERFILE_PATH service variable the runner sets (Railway's
-            // documented non-root-Dockerfile route), and Railway's default restart policy already equals the file's
-            // ON_FAILURE — the dashboard-only Config-as-code pointer only adds the /health deploy gate (boot-crash
-            // visibility), so it is an OPTIONAL note, not a gate.
-            console.error(`[fastagent] note: optional — point the service at fastagent/railway.json (Service → Settings → ` +
-                `Config-as-code, dashboard-only) so the /health healthcheck marks a boot-crashing deploy as FAILED; ` +
-                `the build already uses fastagent/Dockerfile via the RAILWAY_DOCKERFILE_PATH variable`);
             return runDeployRailway({
                 agentDir,
-                workspace,
                 name: serviceName,
                 modelAuth,
                 boxLogin,
-                input: opts.input !== false && isInteractive(),
+                answerer: ctx.answerer,
+                rerun: ctx.rerun,
                 channels,
                 declaredSecrets,
                 values,
                 valueFile,
                 intoLinked: !!opts.intoLinked,
-                dockerfilePath: dockerfilePathVar(pre.container.agentPrefix),
             });
         }
         console.log(plan.runbook.join("\n"));
-        return;
+        // Railway mints the domain when the runbook's step generates it.
+        return undefined;
     },
 };
 /** `deploy railway --run`: drive the railway CLI to completion. */
 async function runDeployRailway(params) {
-    const { agentDir, workspace, name, channels, intoLinked, dockerfilePath } = params;
-    const railway = spawnRunner("railway", workspace);
+    const { agentDir, name, channels, intoLinked } = params;
+    const railway = spawnRunner("railway", agentDir);
     // Fail fast if the railway CLI is absent (spawn ENOENT → 127), with the install link.
     if ((await railway(["--version"], { capture: true })).code === 127) {
         failStartup(new Error(`railway CLI not found — install it: https://docs.railway.com/guides/cli, then re-run`));
@@ -76,15 +69,17 @@ async function runDeployRailway(params) {
         valueFile: params.valueFile,
         channels,
         intoLinked,
-        dockerfilePath,
-        ...boxLoginStep("railway", params, () => railwayShell(name, workspace)),
-    }, railway, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
+        ...boxLoginStep("railway", params, () => railwayShell(name, agentDir)),
+        ...hostLogin(RAILWAY_LOGIN, params.answerer, agentDir),
+        forAgent: `${params.rerun} --json`,
+    }, railway, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir, params.values, params.answerer));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → ${outcome.url}`);
+    return outcome.url;
 }
 /** `railway ssh` into the service, in the project and environment this directory is linked to. */
-function railwayShell(service, workspace) {
+function railwayShell(service, agentDir) {
     // One quoted word: the command reaches the box as ONE line its shell parses, the way OpenSSH hands it over.
-    return processShell("railway", (command) => ["ssh", "--service", service, "--", `sh -c '${command}'`], workspace);
+    return processShell("railway", (command) => ["ssh", "--service", service, "--", `sh -c '${command}'`], agentDir);
 }

package/dist/cli/commands/deploy/shared.d.ts

@@ -1,9 +1,9 @@
 import type { DeclaredChannel } from "../../../channels/discover.ts";
 import type { Registrars } from "../../../deploy/channel-ingress.ts";
 import type { DeployPreflight } from "../../../deploy/preflight.ts";
-import type { FastagentConfig } from "../../../engines/pi/config.ts";
-import { type ResolvedPlacement } from "../../../paths.ts";
+import type { AgentConfig } from "../../../harnesses/pi-durable/define.ts";
 import { type BoxLoginStep, type BoxShell } from "../../../deploy/box-shell.ts";
+import type { TicketStep } from "../../ticket.ts";
 import type { DeployHost } from "../../../deploy/hosts.ts";
 export interface DeployOptions {
     run?: boolean;
@@ -12,23 +12,49 @@ export interface DeployOptions {
     intoLinked?: boolean;
     /** false ⇔ `--no-input`. */
     input?: boolean;
+    /** `--json`: a coding agent's `--run`, run in a ticket that hands each step only a person can take to its user. */
+    json?: boolean;
+    /** `--check <ticket>`: where such a deploy stands. */
+    check?: string;
+    /** `--code <code>` (with `--check`): the code a host's approval page showed, when it could not reach this machine. */
+    code?: string;
+    /** `--stop` (with `--check`): stop that deploy where it is. */
+    stop?: boolean;
+    /** `--timeout <seconds>`: how long it stays open. */
+    timeout?: string;
+    /** `--ticket <id>`: the process that runs it. */
+    ticket?: string;
 }
 /**
- * What the dispatcher resolved before handing off: the placement, the flags, the config and the host-neutral
+ * Who takes a deploy's steps only a person can (a host account's sign-in, a production app's confirmation, the box's
+ * model login): the person at this terminal, a coding agent's person through the deploy's ticket, or nobody (CI, or a
+ * script), for whom such a step stops the deploy naming how to give it.
+ */
+export type Answerer = {
+    kind: "terminal";
+} | {
+    kind: "ticket";
+    step: TicketStep;
+} | {
+    kind: "nobody";
+};
+/**
+ * What the dispatcher resolved before handing off: the agent directory, the flags, the config and the host-neutral
  * pre-flight, plus the channel lists every host asks about.
  */
 interface DeployContext {
     opts: DeployOptions;
+    answerer: Answerer;
+    /** The command that runs this deploy again, from where it ran: its agent directory and flags. */
+    rerun: string;
     agentDir: string;
-    workspace: string;
-    config: FastagentConfig;
+    config: AgentConfig;
     pre: Extract<DeployPreflight, {
         ok: true;
     }>;
     channels: readonly DeclaredChannel[];
     webhookChannels: readonly DeclaredChannel[];
-    longConnectionChannels: readonly DeclaredChannel[];
-    /** Write this host's planned artifacts into the workspace under the ownership rule. */
+    /** Write this host's planned artifacts into the agent directory under the ownership rule. */
     write(artifacts: {
         path: string;
         content: string;
@@ -41,26 +67,28 @@ interface DeployContext {
 export interface HostDeploy {
     /** Did this host generate the file at `path`? */
     isOurs(path: string, content: string): boolean;
-    /** The file in the agent dir whose presence says this workspace deploys to the host. */
-    artifact: string;
-    /** The shell into this workspace's running box (`fastagent login --deployment`). */
-    shell(placement: ResolvedPlacement): Promise<BoxShell>;
+    /** The shell into this agent's running box (`fastagent login --deployment`). */
+    shell(agentDir: string): Promise<BoxShell>;
+    validate?(ctx: Pick<DeployContext, "opts" | "agentDir" | "pre">): void;
     /**
      * Plan the artifacts from the pre-flight facts and what is on disk, write them, then either drive the host CLI
-     * (`--run`) or print the runbook.
+     * (`--run`) or print the runbook. Answers the URL the deployment is reached at, when this host knows it.
      */
-    deploy(ctx: DeployContext): Promise<void>;
+    deploy(ctx: DeployContext): Promise<string | undefined>;
 }
-/** The registrars every host driver gets. */
-export declare function registrarsFor(agentDir: string): Registrars;
+/** Where a step left to the person goes for `answerer`: a ticket's `afterwards`; nowhere else but the log. */
+export declare function leftToPerson(answerer: Answerer): ((step: string) => void) | undefined;
+/** The registrars every host driver gets; a channel's manual step also goes to `answerer`'s person. */
+export declare function registrarsFor(agentDir: string, values: ReadonlyMap<string, string>, answerer: Answerer): Registrars;
 /**
  * The login `--run` starts on the box it just deployed, before any webhook is pointed at it (a host driver's `boxLogin`): for
  * the model's provider, keeping a credential the box already holds (a redeploy), and asking only when a person can
  * answer. None when the model's credential travels as a variable.
  */
-export declare function boxLoginStep<Args extends unknown[]>(host: DeployHost, params: ResolvedPlacement & {
+export declare function boxLoginStep<Args extends unknown[]>(host: DeployHost, params: {
+    agentDir: string;
     boxLogin: string | undefined;
-    input: boolean;
+    answerer: Answerer;
 }, 
 /** The shell, from whatever the driver learns only after deploying (AgentCore's runtime ARN). */
 shell: (...args: Args) => BoxShell): {

package/dist/cli/commands/deploy/shared.js

@@ -3,23 +3,29 @@
  * ownership rule.
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { registerFeishuWebhook } from "../../../channels/feishu/register-webhook.js";
 import { DEPLOY_REGISTRATION_ATTEMPTS } from "../../../channels/registration.js";
 import { registerSlackWebhook } from "../../../channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "../../../channels/telegram/register-webhook.js";
-import { isGeneratedDockerfile, isGeneratedDockerignore } from "../../../deploy/container.js";
-import { RELEASE_FILE } from "../../../deploy/workspace.js";
+import { BUILD_OUTPUTS, IMAGE_DEFINITION_DIR, isGeneratedDockerfile, isGeneratedDockerignore, } from "../../../deploy/container.js";
 import { exists, resolveStateRoot } from "../../../paths.js";
 import { deploymentLoginCommand } from "../../../deploy/box-shell.js";
-import { loginOnBox } from "../../box-login.js";
-/** The registrars every host driver gets. */
-export function registrarsFor(agentDir) {
+import { loginOnBox, ticketLoginIO } from "../../box-login.js";
+/** Where a step left to the person goes for `answerer`: a ticket's `afterwards`; nowhere else but the log. */
+export function leftToPerson(answerer) {
+    return answerer.kind === "ticket" ? (step) => answerer.step.person.afterwards(step) : undefined;
+}
+/** The registrars every host driver gets; a channel's manual step also goes to `answerer`'s person. */
+export function registrarsFor(agentDir, values, answerer) {
     const attempts = DEPLOY_REGISTRATION_ATTEMPTS;
+    const env = Object.fromEntries(values);
+    const leave = leftToPerson(answerer);
     return {
-        telegram: (baseUrl) => registerTelegramWebhook(baseUrl, { attempts }),
-        slack: (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir), attempts }),
-        feishu: (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind, { attempts }),
+        ...(leave === undefined ? {} : { leave }),
+        telegram: (baseUrl) => registerTelegramWebhook(baseUrl, { attempts, env }),
+        slack: (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir), environment: "production", attempts }),
+        feishu: (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind, { attempts, env }),
     };
 }
 /**
@@ -33,11 +39,24 @@ shell) {
     const provider = params.boxLogin;
     if (provider === undefined)
         return {};
-    const placement = { agentDir: params.agentDir, workspace: params.workspace };
+    const command = deploymentLoginCommand(host, provider);
+    const { answerer } = params;
     return {
         boxLogin: {
-            command: deploymentLoginCommand(host, provider),
-            run: (...args) => loginOnBox({ host, shell: shell(...args), placement, provider, ifMissing: true, input: params.input }),
+            command,
+            run: async (...args) => {
+                const request = { host, shell: shell(...args), provider, ifMissing: true };
+                if (answerer.kind !== "ticket")
+                    return loginOnBox({ ...request, input: answerer.kind === "terminal" });
+                // An account sign-in: a key cannot be typed into a ticket.
+                const io = ticketLoginIO(answerer.step, command);
+                const failed = await loginOnBox({ ...request, method: "oauth", input: true, io });
+                if (failed !== undefined)
+                    return io.refusal() ?? failed;
+                // Logged in: what follows (the webhooks) is the deploy finishing, never cut by the person's deadline.
+                answerer.step.person.carriesOn();
+                return undefined;
+            },
         },
     };
 }
@@ -54,7 +73,7 @@ export async function planArtifacts(target, artifacts, options) {
     for (const a of artifacts) {
         const abs = join(target, a.path);
         // Pure build output, not operator-owned configuration. It must track the generated template/runbook.
-        if (a.path.endsWith(`/${RELEASE_FILE}`) || options.alwaysWrite?.includes(a.path)) {
+        if (BUILD_OUTPUTS.includes(basename(a.path)) || options.alwaysWrite?.includes(a.path)) {
             write(a.path, abs, a.content);
             continue;
         }
@@ -67,7 +86,7 @@ export async function planArtifacts(target, artifacts, options) {
                 (a.path.endsWith(".dockerignore")
                     ? `; see the preflight warnings for what it must exclude`
                     : a.path.endsWith("Dockerfile")
-                        ? `; deploy still assumes it listens on $PORT and runs \`fastagent start /app\``
+                        ? `; deploy still assumes it listens on $PORT and runs \`fastagent start ${IMAGE_DEFINITION_DIR}\``
                         : ``));
             continue;
         }
@@ -88,7 +107,7 @@ export async function planArtifacts(target, artifacts, options) {
 export async function applyArtifactPlan(plan) {
     for (const step of plan.steps) {
         if (step.content !== undefined) {
-            await mkdir(dirname(step.abs), { recursive: true }); // artifacts live under fastagent/
+            await mkdir(dirname(step.abs), { recursive: true });
             await writeFile(step.abs, step.content);
         }
         console.error(step.message);

package/dist/cli/commands/deploy.d.ts

@@ -1,7 +1,3 @@
-/**
- * `fastagent deploy <host> [dir]`: generate host artifacts from the resolved definition and print an ordered deploy
- * runbook.
- */
 import type { DeployHost } from "../../deploy/hosts.ts";
 import { type DeployOptions, type HostDeploy, applyArtifactPlan, planArtifacts } from "./deploy/shared.ts";
 export { applyArtifactPlan, planArtifacts };

package/dist/cli/commands/deploy.js

@@ -1,12 +1,28 @@
+/**
+ * `fastagent deploy <host> [agent]`: generate host artifacts from the resolved definition and print an ordered deploy
+ * runbook.
+ */
+import { relative } from "node:path";
+import { cloudFor } from "../../channels/feishu/cloud.js";
+import { FEISHU_INGRESS_SETTINGS } from "../../channels/feishu/setup-mode.js";
+import { assembleSecrets, divergentSettingsGate, missingValuesGate } from "../../deploy/secrets.js";
+import { dotEnvPath, loadEnvValues } from "../../env.js";
+import { unmarkDevServe } from "../../serving-command.js";
+import { assertIndependentFeishuApps, feishuAppSecretNames, larkCredentialsNeeded, prepareFeishuApps, unpreparedFeishuApps, } from "../add-feishu.js";
+import { displayPath, selectAgentEnvironment } from "../../paths.js";
 import { preflightDeploy } from "../../deploy/preflight.js";
-import { loadConfig } from "../../engines/pi/config.js";
+import { apiReport, deploymentApi, writeApiKey } from "../../deploy/api.js";
+import { unprotectedSecretsNote } from "../../value-file.js";
+import { loadConfig } from "../../harnesses/pi-durable/open.js";
 import { failStartup, failUsage } from "../fail.js";
-import { enterAgentDirectory } from "../shared.js";
+import { enterAgentDirectory, isInteractive, shellArg } from "../shared.js";
+import { terminalPerson } from "../person.js";
+import { checkTicket, printReport, refusedCheck, runTicket, startTicket, stopTicket, ticketExitCode, ticketReport, } from "../ticket.js";
 import { agentcoreHost } from "./deploy/agentcore.js";
 import { dockerHost } from "./deploy/docker.js";
 import { flyHost } from "./deploy/fly.js";
 import { railwayHost } from "./deploy/railway.js";
-import { applyArtifactPlan, planArtifacts } from "./deploy/shared.js";
+import { applyArtifactPlan, planArtifacts, } from "./deploy/shared.js";
 export { applyArtifactPlan, planArtifacts };
 /** Every host, by the name the CLI takes. */
 export const HOSTS = {
@@ -50,59 +66,230 @@ export function warnHostOnlyFlags(host, opts) {
         console.error(`[fastagent] warn: ${rule.flag}: ${rule.owner}-only — ${instead}`);
     }
 }
+/** The command that reads a deploy's ticket, as every such ticket records it. */
+const deployCheck = (host) => `fastagent deploy ${host} --check`;
+/** How long a coding agent's deploy stays open: a build, and the person's steps between. */
+const TICKET_TIMEOUT_SECONDS = 3600;
 export async function runDeploy(host, dirArg, opts) {
+    if (opts.check !== undefined)
+        return checkDeploy(host, opts.check, opts);
+    if (opts.stop)
+        failUsage("--stop stops a deploy started with --json: pass --check <ticket> too");
+    if (opts.ticket !== undefined) {
+        // The process `startTicket` started: it takes the ticket before the pre-flight (seconds of building the
+        // definition), then does the whole deploy, its person the ticket's.
+        await runTicket(opts.ticket, (step) => deploy(host, dirArg, opts, step));
+        process.exit(0);
+    }
+    await deploy(host, dirArg, opts);
+}
+/** The deploy itself: through a ticket's `step` when one runs it, else at this terminal or with nobody to ask. */
+async function deploy(host, dirArg, opts, step) {
+    if (opts.code !== undefined)
+        failUsage("--code hands a code to a deploy's ticket: pass --check <ticket> too");
     if (opts.tunnel && host !== "docker") {
         // A flag/host combination the parser cannot see (host is an argument) — usage class, exit 2.
         failUsage(`deploy stopped: --tunnel is supported only by the local Docker target`);
     }
-    // The picker's write-back lands the model in fastagent.config.ts.
-    const placement = await enterAgentDirectory(dirArg, opts);
-    // ONE deploy semantic: bake the WORKSPACE (WYSIWYG).
-    const { agentDir, workspace } = placement;
-    const { config } = await loadConfig(agentDir).catch(failStartup);
-    // The host-neutral pre-flight (the model and its source, channel discovery, model-auth probe, container facts +
-    // their warnings) lives in deploy/preflight.ts.
-    const pre = await preflightDeploy({
-        placement,
+    if (opts.json && !opts.run)
+        failUsage("--json reports a deploy --run drives: pass --run too");
+    selectAgentEnvironment("production");
+    const { agentDir } = await enterAgentDirectory(dirArg, opts);
+    const config = await loadConfig(agentDir).catch(failStartup);
+    // Never `dev`, whatever spawned this; and what decides a channel's shape is read here as the box will read it.
+    unmarkDevServe();
+    const shaped = divergentSettingsGate(FEISHU_INGRESS_SETTINGS, process.env, loadEnvValues(dotEnvPath(agentDir)), relative(agentDir, dotEnvPath(agentDir)));
+    if (shaped)
+        failStartup(new Error(`deploy stopped: ${shaped}`));
+    const independentApps = (values) => {
+        try {
+            assertIndependentFeishuApps(agentDir, ["feishu", "lark"], values);
+        }
+        catch (error) {
+            failStartup(error);
+        }
+    };
+    independentApps(loadEnvValues(dotEnvPath(agentDir)));
+    const api = deploymentApi({
         config,
-        run: !!opts.run,
-        force: !!opts.force,
-        externalClock: host === "agentcore", // cron rides EventBridge there — the resident-host notes don't apply
-        // AgentCore DOES get a public URL (the forwarder's, AuthType NONE) — but nothing of ours answers behind it:
-        // that relay reaches the channels' routes only, each verifying its platform's signature (agentcore-service.ts).
-        publicUrl: host !== "agentcore",
-    }).catch(failStartup);
-    if (!pre.ok)
-        failStartup(new Error(`deploy stopped: ${pre.gate}`));
-    for (const m of pre.messages)
-        console.error(`[fastagent] ${m.level}: ${m.text}`);
-    const { channels } = pre;
-    warnHostOnlyFlags(host, opts);
+        hostServes: host !== "agentcore",
+        values: loadEnvValues(dotEnvPath(agentDir)),
+    });
     const target = HOSTS[host];
-    await target.deploy({
-        opts,
-        agentDir,
-        workspace,
-        config,
-        pre,
-        channels,
-        webhookChannels: channels.filter((channel) => channel.ingress === "webhook"),
-        longConnectionChannels: channels.filter((channel) => channel.ingress === "long-connection"),
-        // The ownership predicate is bound HERE, from the same lookup that chose the host, so no host module can pass
-        // one.
-        // Reporting a stale artifact is enough when only generating them — the operator reads the line and decides. But
-        // `--run` would then deploy FROM it: a determinate mismatch between what ships and what the definition says,
-        // the same class as a Dockerfile that cannot read the manifest, and gated the
-        // same way. `--force` regenerates ours; a file we did not generate is never touched by either, and the marker
-        // line is how an operator takes a path back on purpose.
-        write: async (artifacts, options) => {
-            const plan = await planArtifacts(workspace, artifacts, { ...options, isOurs: target.isOurs });
-            if (opts.run && plan.stale.length > 0) {
-                failStartup(new Error(`deploy stopped: ${plan.stale.join(", ")} no longer match what this definition generates, and --run ` +
-                    `would deploy from them. Re-run with --force to regenerate, or remove each file's generated-by ` +
-                    `marker to own it yourself.`));
+    const preflight = async () => {
+        const facts = await preflightDeploy({
+            agentDir,
+            config,
+            run: !!opts.run,
+            force: !!opts.force,
+            noResidentProcess: host === "agentcore", // alarms and webhooks wake the container there — no machine to keep up
+            // Every AgentCore deployment starts the storage over (core.md §9).
+            storageResets: host === "agentcore",
+            servesApi: api.served,
+        }).catch(failStartup);
+        if (!facts.ok)
+            failStartup(new Error(`deploy stopped: ${facts.gate}`));
+        target.validate?.({ opts, agentDir, pre: facts });
+        return facts;
+    };
+    let pre = await preflight();
+    const agentArg = displayPath(process.cwd(), agentDir);
+    const rerun = `fastagent deploy ${host}${agentArg === undefined ? "" : ` ${shellArg(agentArg)}`}` +
+        `${opts.tunnel ? " --tunnel" : ""}${opts.intoLinked ? " --into-linked" : ""} --run`;
+    const unprepared = opts.run ? unpreparedFeishuApps(pre.channels, pre.values) : [];
+    if (opts.json && step === undefined) {
+        // A coding agent's deploy: what this machine can refuse is refused above, at once; the rest runs in a ticket.
+        if (unprepared.some(({ kind }) => kind === "lark")) {
+            const needed = await larkCredentialsNeeded(agentDir, rerun).catch(failStartup);
+            if (needed !== undefined) {
+                printReport(true, needed.json, needed.text);
+                process.exit(0);
             }
-            await applyArtifactPlan(plan);
-        },
-    });
+        }
+        const timeout = opts.timeout === undefined ? TICKET_TIMEOUT_SECONDS : Number(opts.timeout);
+        if (!Number.isInteger(timeout) || timeout <= 0)
+            failUsage("--timeout must be a whole number of seconds");
+        const ticket = await startTicket({
+            subject: `deploy:${host}:${agentDir}`,
+            fields: { deployment: host },
+            action: `deploy the agent to ${host}`,
+            check: deployCheck(host),
+            restart: rerun,
+            timeoutSeconds: timeout,
+            waitsFirst: false,
+            // A deploy stopped halfway leaves the host half-changed: one already running is the answer.
+            whenRunning: "join",
+            command: {
+                file: process.execPath,
+                args: [
+                    ...process.execArgv,
+                    process.argv[1],
+                    "deploy",
+                    host,
+                    agentDir,
+                    ...(opts.tunnel ? ["--tunnel"] : []),
+                    ...(opts.force ? ["--force"] : []),
+                    ...(opts.intoLinked ? ["--into-linked"] : []),
+                    "--run",
+                    "--json",
+                ],
+                cwd: process.cwd(),
+            },
+        });
+        reportDeploy(ticket, "started");
+        process.exit(ticketExitCode(ticket));
+    }
+    /** Everything past the pre-flight, its person's steps taken by `answerer`; the URL and what the API report says. */
+    const deployWith = async (answerer) => {
+        if (unprepared.length > 0) {
+            const supplied = unprepared.flatMap(({ kind, ingress }) => feishuAppSecretNames(kind, ingress));
+            const kinds = unprepared.map(({ kind }) => kind);
+            const { values } = pre;
+            const absent = supplied.filter((name) => !values.get(name)?.trim());
+            const { missingSecrets } = assembleSecrets({
+                modelAuth: pre.modelAuth,
+                declared: pre.declaredSecrets,
+                values: pre.values,
+            });
+            const missing = missingValuesGate(missingSecrets.filter((name) => !supplied.includes(name)), pre.valueFile);
+            if (missing)
+                failStartup(new Error(`deploy stopped: ${missing}`));
+            if (host === "docker" && !opts.tunnel && unprepared.some(({ ingress }) => ingress === "webhook")) {
+                failStartup(new Error(`deploy stopped: ${kinds.join(", ")} receive by webhook here, and this Docker deployment has no ` +
+                    `public URL to point the app at — re-run with --tunnel (the app is prepared then), or set up your own ` +
+                    `ingress and supply ${absent.join(", ")} from a separate production app in ${pre.valueFile}, or ` +
+                    `set ${kinds.map((kind) => `${cloudFor(kind).envPrefix}_INGRESS=websocket`).join(", ")} there`));
+            }
+            if (answerer.kind === "nobody") {
+                failUsage(`deploy stopped: ${pre.valueFile} has no ${absent.join(", ")}: setting up the separate production app ` +
+                    `needs a person — run this deploy in a terminal; from a coding agent, run \`${rerun} --json\`, which ` +
+                    `hands their part to its user`);
+            }
+            const person = answerer.kind === "ticket" ? answerer.step.person : terminalPerson;
+            const again = answerer.kind === "ticket" ? `${rerun} --json` : rerun;
+            await prepareFeishuApps(agentDir, unprepared, again, person).catch(failStartup);
+            pre = await preflight();
+        }
+        independentApps(pre.values);
+        if (api.served && api.generatesKey) {
+            // Past every refusal the pre-flight makes, and read again, so this deploy carries it.
+            const unprotected = await writeApiKey(agentDir).catch(failStartup);
+            if (unprotected !== undefined)
+                console.error(`[fastagent] note: ${unprotectedSecretsNote(unprotected)}`);
+            pre = await preflight();
+        }
+        for (const m of pre.messages)
+            console.error(`[fastagent] ${m.level}: ${m.text}`);
+        const { channels } = pre;
+        warnHostOnlyFlags(host, opts);
+        // What follows is the host's work: a deadline meant for the person must never cut it halfway. Its own steps for
+        // the person (a host sign-in, the box's login) wait again, and are bounded again.
+        if (answerer.kind === "ticket")
+            answerer.step.person.carriesOn();
+        const reachedAt = await target.deploy({
+            opts,
+            answerer,
+            rerun,
+            agentDir,
+            config,
+            pre,
+            channels,
+            webhookChannels: channels.filter((channel) => channel.ingress === "webhook"),
+            // The ownership predicate is bound HERE, from the same lookup that chose the host, so no host module can pass
+            // one.
+            // Reporting a stale artifact is enough when only generating them — the operator reads the line and decides. But
+            // `--run` would then deploy FROM it: a determinate mismatch between what ships and what the definition says,
+            // the same class as a Dockerfile that cannot read the manifest, and gated the
+            // same way. `--force` regenerates ours; a file we did not generate is never touched by either, and the marker
+            // line is how an operator takes a path back on purpose.
+            write: async (artifacts, options) => {
+                const plan = await planArtifacts(agentDir, artifacts, { ...options, isOurs: target.isOurs });
+                if (opts.run && plan.stale.length > 0) {
+                    failStartup(new Error(`deploy stopped: ${plan.stale.join(", ")} no longer match what this definition generates, and --run ` +
+                        `would deploy from them. Re-run with --force to regenerate, or remove each file's generated-by ` +
+                        `marker to own it yourself.`));
+                }
+                await applyArtifactPlan(plan);
+            },
+        });
+        const notes = apiReport(api, { valueFile: pre.valueFile, agentArg }, reachedAt);
+        for (const line of notes)
+            console.error(`[fastagent] ${line}`);
+        return { ...(reachedAt === undefined ? {} : { url: reachedAt }), notes };
+    };
+    if (step !== undefined)
+        return deployWith({ kind: "ticket", step });
+    return deployWith(opts.input === false || !isInteractive() ? { kind: "nobody" } : { kind: "terminal" });
+}
+/** `deploy <host> --check <ticket> [--code <code>]`. */
+async function checkDeploy(host, id, opts) {
+    const refused = refusedCheck(id, deployCheck(host));
+    if (refused !== undefined)
+        failUsage(refused);
+    // There: refusedCheck read it, and a ticket is pruned only a day after it ends.
+    const ticket = opts.stop ? await stopTicket(id) : (await checkTicket(id, opts.code));
+    reportDeploy(ticket, "checked");
+    process.exit(ticketExitCode(ticket));
+}
+/** A deploy's ticket for the agent that started or checked it, always as JSON: `--json` is how one started. */
+function reportDeploy(ticket, when) {
+    const report = ticketReport(ticket, when, (result) => ({
+        fields: result,
+        text: [],
+        next: result.url === undefined
+            ? "Deployed. Tell the user what the notes say."
+            : `Deployed to ${String(result.url)}. Tell the user what the notes say.`,
+    }));
+    const running = ticket.status === "starting" || ticket.status === "working" || ticket.status === "need_user_action";
+    if (!running) {
+        printReport(true, report.json, []);
+        return;
+    }
+    // A deploy finishing is never cut by its deadline, so one that hangs there ends only on someone's say.
+    const stop = `${ticket.check} ${ticket.ticket} --stop --json`;
+    const hung = ticket.status === "need_user_action"
+        ? ""
+        : " If its log has shown no progress for a long while, stop_command stops it where it is, which can leave the " +
+            "host half-changed: ask the user first.";
+    printReport(true, { ...report.json, stop_command: stop, agent_next_steps: `${String(report.json.agent_next_steps)}${hung}` }, []);
 }