@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/deploy/agentcore/plan.js

@@ -1,107 +1,58 @@
-/**
- * `fastagent deploy agentcore` — the AWS Bedrock AgentCore deploy PLAN, computed from the resolved
- * definition. Pure: facts in, artifact contents + an ordered runbook out; the CLI writes the files
- * and prints the runbook. AgentCore is the fourth target, and its shape differs from Fly/Railway in
- * kind, not degree:
- *
- *  1. **No public URL, no resident process.** The Runtime's only ingress is the SigV4
- *     `InvokeAgentRuntime` API, and compute is per-session microVMs that stop when idle. So the
- *     topology carries TWO extra pieces a Fly box never needs: a forwarder Lambda (public Function
- *     URL → envelope → InvokeAgentRuntime) fronting the webhooks, and EventBridge Scheduler rules
- *     delivering each cron slot (the container arms no resident timers — serve's externalClock mode).
- *  2. **One template is the whole topology.** CloudFormation (`AWS::BedrockAgentCore::Runtime` is a
- *     first-class resource type) declares Runtime + roles + forwarder + schedules in one stack —
- *     unlike Railway, identity DOES live in a committed file; the stack name pins it.
- *  3. **All ingress traffic shares ONE fixed runtime session** (`ingressSessionId`): fastagent's
- *     channel state is single-writer by design, and one session = at most one microVM at a time.
- *     AgentCore keeps a stopped session's id valid until the Runtime is deleted (a new compute is
- *     provisioned on the next invoke), so the fixed id needs no rotation. State lives on the
- *     platform's SessionStorage mount (`/mnt/state`) — persistent across compute stop/resume, no
- *     VPC/EFS required. Named trade-off: that state is tied to THIS Runtime resource — a stack
- *     replacement (renaming the runtime) starts blank. EFS (VPC mode) is the upgrade path when
- *     state must outlive the runtime; the runbook says so instead of silently shipping a VPC+NAT
- *     bill (~$35/mo) every deployment.
- *
- *  The image is the SAME portable container every host ships (containerArtifacts) — AgentCore's
- *  extras (PORT=8080, FASTAGENT_AGENTCORE=1, the state dir) ride the Runtime resource's environment,
- *  never a forked Dockerfile. The build must be linux/arm64 (the platform requirement) — the ONE
- *  host where the build runs on the operator's machine (docker buildx) instead of remotely.
- */
+/** `fastagent deploy agentcore` — the AWS Bedrock AgentCore deploy PLAN, computed from the resolved definition. */
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
 import { SECRETS_DIRNAME } from "../../paths.js";
 import { webhookKinds, webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
-import { deploymentSecrets, isEnvKey } from "../secrets.js";
-function agentcoreTopology(input, 
-/** Schedules EventBridge CAN express — the ones that become rules. */
-translatedSchedules) {
-    const webhooks = input.channels.some((channel) => channel.ingress === "webhook");
-    return {
-        webhooks,
-        forwarder: webhooks || translatedSchedules > 0 || input.selfSchedule,
-        wakeAlarms: input.selfSchedule,
-    };
+import { isEnvKey } from "../secrets.js";
+function agentcoreTopology(input) {
+    return { webhooks: input.channels.some((channel) => channel.ingress === "webhook") };
 }
-/** SessionStorage mount = FASTAGENT_STATE_DIR (AgentCore requires exactly `/mnt/<one-level>`). It is
- *  a fast LOCAL disk only: the platform wipes it on every runtime version update (= every deploy).
- *  Durability across deploys comes from the S3 snapshot (channels/agentcore-state.ts). */
-export const MOUNT = "/mnt/state";
-/**
- * FASTAGENT_SECRETS_DIR — the seeded-then-ROTATED auth.json, deliberately INSIDE the state root
- * rather than beside it.
- *
- * Every other host mounts a real volume and puts the two machinery dirs side by side (`/data/.state`
- * + `/data/.secrets`), because there the persistence boundary is the MOUNT POINT: anything under it
- * survives. AgentCore has no volume. Its persistence boundary is `packStateRoot(stateRoot)` — the one
- * directory tree the S3 snapshot copies out and back (channels/agentcore-state.ts) — while {@link MOUNT}
- * itself is wiped on every runtime version update, i.e. on every deploy.
- *
- * So the sibling layout would put credentials INSIDE the mount but OUTSIDE the snapshot: nothing
- * copies them out, the platform wipes them, and the next microVM re-seeds the deploy-time copy. With
- * single-use OAuth refresh tokens that is a slow-motion outage — the box works until the seeded token
- * is rotated away, then loses model access with only a redeploy to restore it.
- *
- * Nesting is what makes agentcore-state.ts's stated contract ("restores VERBATIM — including
- * auth.json") reachable at all; `packStateRoot` walks the whole tree, so no snapshot code knows about
- * this. Tests assert the containment, not just the two names — the sibling spelling looks tidier and
- * reintroduces the outage silently.
- */
+/** The platform's managed SessionStorage mount (AgentCore requires exactly `/mnt/<one-level>`). */
+export const MOUNT = "/mnt/data";
+/** Beside the state root on the one mount, as every volume-backed host does. */
 export const SECRETS_DIR = `${MOUNT}/${SECRETS_DIRNAME}`;
 /**
- * How long an idle session keeps its microVM. Memory is billed per second across the WHOLE session
- * — idle included, at the peak level reached — so this tail is the standing cost of every burst of
- * activity, while CPU stops billing the moment the agent stops working. 3 minutes rather than the
- * platform's 15: the tail shrinks 5×, and the cost is a cold start (image + Node + snapshot restore)
- * for anyone who returns after a longer gap. `/ping` reports HealthyBusy + time_of_last_update while
- * work is in flight (the FIELD is what the platform's idle measurement actually reads — agentcore.ts),
- * so this timer only ever starts once the agent has genuinely settled — a long turn is never cut short.
- * AWS accepts 60–28800.
+ * How long an idle session keeps its microVM when the config names no other value. Below AWS's own default (900) on
+ * purpose: memory bills for the whole idle tail, so the cheap posture is the default and a longer one is a choice.
  */
-export const IDLE_TIMEOUT_SECONDS = 180;
-/** The platform ceiling on one session's compute (8 h). The session ID outlives it: the next invoke
- *  simply gets fresh compute with the same storage. */
+export const DEFAULT_IDLE_TIMEOUT_SECONDS = 180;
+/** One session's compute lifetime — AWS's own default. Both lifecycle fields cap at 1209600 (14 d). */
 export const MAX_LIFETIME_SECONDS = 28800;
-/** The state snapshot's object key in the deployment bucket (one object; see agentcore-state.ts). */
-export const STATE_KEY = "state/snapshot.json.gz";
-/** The forwarder artifact. Named `index.js` because it IS the Lambda deployment package's entry:
- *  zipping it as-is produces a valid package (`Handler: index.handler`), with nothing to rename. */
 export const FORWARDER_FILE = "lambda/index.js";
-/** The deployment bucket: forwarder code + the state snapshot. Account-suffixed for S3's GLOBAL
- *  namespace, and created OUTSIDE the stack (like the ECR repo) so a `delete-stack` cannot take the
- *  agent's memory with it. Bucket names cap at 63 chars; `name` is already gated to 40. */
-export function stateBucketName(name, account) {
+/**
+ * Where the forwarder puts the one-shot schedule for a wake-up. The id inside the name is minted in the
+ * container, so this prefix is the only handle anything outside has on the alarms a deployment has pending.
+ */
+export function wakeAlarmPrefix(name) {
+    return `fa-${name}-wk-`;
+}
+/** Account-suffixed artifact bucket for S3's global namespace. */
+export function deploymentBucketName(name, account) {
     return `fa-${name}-${account}`;
 }
-/** AgentCore env values max 2048 chars — a real OAuth auth.json's base64 exceeds it, so the seed is
- *  CHUNKED across FASTAGENT_AUTH_SEED + _2… (collectAuthSeed reassembles at boot). 2000 keeps margin. */
-export const AUTH_SEED_CHUNK_SIZE = 2000;
-export const AUTH_SEED_MAX_CHUNKS = 4;
+/**
+ * AgentCore env values max 2048 chars — a real OAuth auth.json's base64 exceeds it, so each carrier is CHUNKED across
+ * `<NAME>` + `_2`… (collectChunked reassembles at boot): FASTAGENT_AUTH_SEED for the credential, FASTAGENT_ENV for the
+ * value file's variables.
+ */
+export const CARRIER_CHUNK_SIZE = 2000;
+export const CARRIER_MAX_CHUNKS = 4;
+/** The template's two chunked carriers: CloudFormation parameter prefix → container env-var name. */
+export const CARRIERS = [
+    { param: "FastagentAuthSeed", env: "FASTAGENT_AUTH_SEED", what: "base64 auth.json" },
+    { param: "FastagentEnv", env: "FASTAGENT_ENV", what: "base64 JSON of the value file's variables" },
+];
+/** Chunk `i` (0-based) of a carrier: its parameter and env-var names. */
+export function carrierChunk(carrier, i) {
+    return i === 0
+        ? { param: carrier.param, env: carrier.env }
+        : { param: `${carrier.param}${i + 1}`, env: `${carrier.env}_${i + 1}` };
+}
 /** The generated template's filename (namespaced under the kit in the agentDir layout). */
 export const TEMPLATE_FILE = "agentcore.template.yaml";
-/** The generated template's first-line marker — the ONE source for both the generator and the
- *  "did fastagent generate this?" check (deploy's drift gate), so they cannot drift apart. */
+/** The generated template's first-line marker. */
 export const GENERATED_TEMPLATE_MARKER = "# Generated by `fastagent deploy agentcore`";
 /** Whether an on-disk template is fastagent-generated (vs hand-written — kept, never gated). */
 export function isGeneratedAgentcoreTemplate(content) {
@@ -119,28 +70,48 @@ export function toRuntimeName(basename) {
     const slug = basename.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
     return (/^[a-zA-Z]/.test(slug) ? slug : `agent_${slug || "fastagent"}`).slice(0, 48);
 }
-/** The ONE fixed ingress session id (webhooks + schedule fires) — ≥ 33 chars (the API minimum),
- *  deterministic (the Lambda holds it in env), padded so any name clears the floor. */
-export function ingressSessionId(name) {
-    return `fastagent-ingress-${name}`.padEnd(33, "0").slice(0, 128);
+/** The forwarder Lambda's name — and therefore its log group, which AWS derives from it. */
+function forwarderFunctionName(name) {
+    return `${agentcoreStackName(name)}-forwarder`;
 }
-/** CFN parameter logical id for a secret env-var name: TELEGRAM_BOT_TOKEN → TelegramBotToken
- *  (parameter names must be alphanumeric). Deterministic — run.ts builds the same mapping. */
-export function cfnParamName(envName) {
-    return envName
-        .toLowerCase()
-        .split("_")
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-        .join("");
+/**
+ * The two names every part of this host derives from the deployment name, and the reason they are functions:
+ * a deploy CREATES them and a destroy LOOKS FOR them, so a drift between the two spellings is silent in the
+ * worst direction. `describe-repositories` on a mis-spelled repo answers `RepositoryNotFoundException`, which
+ * is "already gone" — the teardown would report nothing left to delete while the repository kept billing.
+ */
+export function agentcoreStackName(name) {
+    return `fastagent-${name}`;
+}
+export function agentcoreRepoName(name) {
+    return `fastagent/${name}`;
+}
+/**
+ * Where a RUNTIME's logs land, by the identifier the caller happens to hold: `fastagent logs` knows the runtime id
+ * from the stack's `RuntimeArn`, `destroy` knows only the {@link toRuntimeName} the template deployed — and AgentCore
+ * names the id `<AgentRuntimeName>-<suffix>`, so the same prefix serves both. MEASURED (ap-southeast-1, 2026-09-22):
+ * a deploy of `destroy-probe-yehg` produced `/aws/bedrock-agentcore/runtimes/destroy_probe_yehg-6oR1zq7pBZ-DEFAULT`.
+ *
+ * ONE OWNER because of what the callers do with it: `logs` picks a group to tail, `destroy` DELETES everything the
+ * prefix matches. The trailing `-` is what keeps `probe-` off `probe2-…`, and a second hand-spelled copy of this
+ * string is a copy that can lose it.
+ */
+export function runtimeLogGroupPrefix(runtimeOrName) {
+    return `/aws/bedrock-agentcore/runtimes/${runtimeOrName}-`;
 }
 /**
- * Remap ONE day-of-week field from standard cron numbering (0–7, 0/7 = Sunday) to EventBridge's
- * (1–7, 1 = Sunday). Parsed, not regex-replaced: only VALUES and RANGE ENDPOINTS are renumbered — a
- * step divisor (`*\/2`, `1-5/2`) is a count, not a weekday, and must pass through untouched. Names
- * (SUN..SAT) pass through. A numeric range whose endpoints INVERT under renumbering (`5-7` → `6-1`)
- * wraps across the week — not expressible as an EventBridge range — and is refused, never silently
- * reordered.
+ * Where the forwarder's logs land. Lambda creates this group itself, from the function name, so three parties have
+ * to agree on a string none of them can check against the others: the template that names the function, the runbook
+ * and `--run` summary that tell an operator to set its retention, and `fastagent logs --source forwarder`.
  */
+export function forwarderLogGroup(name) {
+    return `/aws/lambda/${forwarderFunctionName(name)}`;
+}
+/** The ONE fixed ingress session id (webhooks + routine fires). */
+export function ingressSessionId(name) {
+    return `fastagent-ingress-${name}`.padEnd(33, "0").slice(0, 128);
+}
+/** Remap ONE day-of-week field from standard cron numbering (0–7, 0/7 = Sunday) to EventBridge's (1–7, 1 = Sunday). */
 function mapDowField(dow) {
     const items = [];
     for (const item of dow.split(",")) {
@@ -175,16 +146,7 @@ function mapDowField(dow) {
     }
     return { value: items.join(",") };
 }
-/**
- * Translate a 5-field cron into EventBridge Scheduler's `cron(m h dom mon dow *)`, or say why it
- * can't be. The two dialects disagree exactly where silent translation would misfire:
- *  - EventBridge numbers day-of-week 1–7 (1 = Sunday); standard cron uses 0–6 (0/7 = Sunday) —
- *    numeric dow values and range endpoints are remapped ({@link mapDowField}); steps and names
- *    pass through; a range that wraps under renumbering is refused.
- *  - EventBridge requires `?` in dom or dow: a `*` on either side becomes `?`; BOTH restricted is
- *    standard cron's OR semantics, which EventBridge cannot express — refused, never approximated.
- *  - A 6-field (seconds) expression and L/# day-of-week forms are refused for the same reason.
- */
+/** Translate a 5-field cron into EventBridge Scheduler's `cron(m h dom mon dow *)`, or say why it can't be. */
 export function toEventBridgeCron(cron) {
     const fields = cron.trim().split(/\s+/);
     if (fields.length !== 5) {
@@ -194,13 +156,7 @@ export function toEventBridgeCron(cron) {
     if (/[L#]/i.test(dow) || /[L#]/i.test(dom)) {
         return { error: "L/# day forms don't translate to EventBridge numbering — set this schedule up manually" };
     }
-    // `?` FIRST, and not as a synonym for `*`. Croner treats it as a day field that matches everything
-    // and — unlike `*` — does NOT trigger cron's "one field is unrestricted, so the other governs"
-    // special case. It therefore ORs with the other field to mean EVERY DAY, whatever that field says.
-    // Measured against croner: `0 9 ? * MON` and `0 9 1 * ?` both fire daily, while `0 9 * * MON`
-    // fires on Mondays. Translating `?` to `*` would deploy a rule that fires on a DIFFERENT set of
-    // days than the same file fires on locally — the silent divergence this whole target exists to
-    // avoid — so a `?` in either field becomes an explicitly daily EventBridge rule.
+    // `?` FIRST, and not as a synonym for `*`.
     if (dom === "?" || dow === "?") {
         return { expression: `cron(${min} ${hour} * ${mon} ? *)` };
     }
@@ -222,36 +178,18 @@ function logicalId(name) {
     const slug = name.replace(/[^a-zA-Z0-9]+/g, "");
     return slug.charAt(0).toUpperCase() + slug.slice(1) || "Schedule";
 }
-/** YAML single-quoted scalar (the one escape: `'` doubles). Used for values carrying user input. */
+/** YAML single-quoted scalar (the one escape: `'` doubles). */
 function yamlSingleQuote(value) {
     return `'${value.replace(/'/g, "''")}'`;
 }
 /**
- * The forwarder Lambda source — `forwarder.js` beside this file, the ONE text both the deployment
- * package and the readable `lambda/index.js` artifact are generated from. A real file, not a template
- * literal: it is linted, and it needs no interpolation — the one value it once took from here
- * (`MAX_WEBHOOK_BODY_BYTES`) rides in as a Lambda environment variable. Zero-dependency: the
- * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: the package's entry lands as
- * `index.js` ({@link zipSingleFile}), where ESM `import` is a syntax error. Two
- * event shapes: a Function URL webhook (reconstructed verbatim into a `webhook` envelope; the
- * channel's REAL response rides back inside the transport reply and is re-emitted byte-exact —
- * Feishu's URL-verification challenge depends on it), and an EventBridge Scheduler fire
- * (`{ scheduleFire }`, slot = the scheduled instant — the container's idempotency key).
- *
- * It ships as an S3 object rather than inline `ZipFile`, so there is no 4096-byte ceiling on it — a
- * constraint this comment asserted for long after the template stopped inlining, which is the kind
- * of stale rule that stops the next person making a correct change.
+ * The forwarder Lambda source — `forwarder.js` beside this file, the ONE text both the deployment package and the
+ * readable `lambda/index.js` artifact are generated from.
  */
 export function forwarderSource() {
     return readFileSync(new URL("./forwarder.js", import.meta.url), "utf8");
 }
-/**
- * The EventBridge physical name for a schedule. A schedule's local name is an arbitrary MODULE FILE
- * NAME (`schedules/晨报.ts`, `schedules/deploy check.ts`), while AWS requires `[0-9A-Za-z-_.]+` within
- * 64 chars — and the `fa-<agent>-` prefix already eats up to 44 of them. So: sanitize, bound the
- * readable part, and end with a hash of the ORIGINAL name, which keeps distinct schedules distinct
- * where sanitizing or truncation would have merged them (one rule silently firing for two).
- */
+/** The EventBridge physical name for a schedule. */
 export function scheduleResourceName(agent, schedule) {
     const prefix = `fa-${agent}-`;
     const hash = createHash("sha256").update(schedule).digest("hex").slice(0, 8);
@@ -262,61 +200,38 @@ export function scheduleResourceName(agent, schedule) {
 /** The CloudFormation template — the whole topology in one stack. */
 function template(input, translated, topology) {
     const runtimeName = toRuntimeName(input.name);
-    const needsForwarder = topology.forwarder;
-    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
+    const idleTimeout = input.idleTimeoutSeconds ?? DEFAULT_IDLE_TIMEOUT_SECONDS;
     const forwarderFnArn = `!Sub arn:aws:lambda:\${AWS::Region}:\${AWS::AccountId}:function:fastagent-${input.name}-forwarder`;
-    // Secret env vars ride CFN NoEcho parameters. FASTAGENT_AUTH_SEED is always declared (Default "")
-    // so a `--run` OAuth carry has a slot; required secrets have NO default — `cloudformation deploy`
-    // fails loudly without a value instead of booting a half-configured box.
+    // Secret env vars ride CFN NoEcho parameters.
     const params = [
         `  ImageUri:`,
         `    Type: String`,
         `    Description: ECR image URI (linux/arm64) — <account>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>`,
     ];
-    if (needsForwarder) {
-        params.push(`  StateBucket:`, `    Type: String`, `    Description: S3 bucket holding the forwarder deployment package + the agent's state snapshot (created outside this stack)`, `  ForwarderS3Key:`, `    Type: String`, `    Description: key of the forwarder .zip in StateBucket — CONTENT-HASHED, so new code is a new value and CloudFormation rolls the function`);
-    }
+    params.push(`  ForwarderBucket:`, `    Type: String`, `    Description: S3 bucket holding the forwarder deployment package (created outside this stack)`, `  ForwarderS3Key:`, `    Type: String`, `    Description: content-hashed key of the forwarder .zip in ForwarderBucket`);
     const envLines = [
         `        PORT: "8080"`, // the Runtime service contract's fixed port (config.http.port does not apply here)
         `        FASTAGENT_AGENTCORE: "1"`, // serve mounts /invocations + /ping, arms no resident cron
-        `        FASTAGENT_STATE_DIR: ${MOUNT}`,
-        // Inside the state root on purpose — the snapshot is this host's only durable store, and it copies
-        // exactly one tree. See {@link SECRETS_DIR}: the sibling layout every other host uses would leave a
-        // rotated OAuth credential outside it, i.e. discarded with the microVM.
+        `        FASTAGENT_STORAGE_DIR: ${MOUNT}`,
+        `        FASTAGENT_STATE_DIR: ${MOUNT}/.state`,
         `        FASTAGENT_SECRETS_DIR: ${SECRETS_DIR}`,
     ];
-    // The auth seed is chunked (env values max 2048 chars — see AUTH_SEED_CHUNK_SIZE): N parameters,
-    // each riding its own env var; `start` reassembles them (collectAuthSeed). Empty defaults = unused.
-    for (let i = 1; i <= AUTH_SEED_MAX_CHUNKS; i++) {
-        const param = i === 1 ? "FastagentAuthSeed" : `FastagentAuthSeed${i}`;
-        const envName = i === 1 ? "FASTAGENT_AUTH_SEED" : `FASTAGENT_AUTH_SEED_${i}`;
-        params.push(`  ${param}:`, `    Type: String`, `    Default: ""`, `    NoEcho: true`, `    Description: base64 auth.json carried by --run, chunk ${i}/${AUTH_SEED_MAX_CHUNKS} (env values cap at 2048 chars); empty = unused`);
-        envLines.push(`        ${envName}: !Ref ${param}`);
-    }
-    for (const s of secrets) {
-        const p = cfnParamName(s.name);
-        params.push(`  ${p}:`, `    Type: String`);
-        if (!s.required)
-            params.push(`    Default: ""`);
-        params.push(`    NoEcho: true`, `    Description: ${s.hint}`);
-        envLines.push(`        ${s.name}: !Ref ${p}`);
-    }
-    if (needsForwarder) {
-        // The INGRESS secret authenticates forwarder→runtime envelopes. Without it the envelope union is
-        // an unauthenticated control plane: `InvokeAgentRuntime` is an ordinary IAM action, so any
-        // principal holding it could forge a `schedule-fire`, or ride `state`/`wake` on a public `invoke`
-        // to redirect the state snapshot (exfiltrating auth.json) or the wake-alarm callback (leaking the
-        // wake secret) to an address of their choosing. Public `invoke` stays unauthenticated by design —
-        // it is the programmatic data plane — but it may not carry internal fields.
-        params.push(`  FastagentIngressSecret:`, `    Type: String`, `    NoEcho: true`, `    Description: shared secret authenticating forwarder→runtime envelopes (any random string; --run mints one)`);
-        envLines.push(`        FASTAGENT_INGRESS_SECRET: !Ref FastagentIngressSecret`);
-    }
-    if (input.selfSchedule) {
-        // The wake-alarm shared secret: the container authenticates its alarm callbacks to the forwarder
-        // with it. Required (no default) — a selfSchedule deployment without it would silently degrade.
-        params.push(`  FastagentWakeSecret:`, `    Type: String`, `    NoEcho: true`, `    Description: shared secret between the container and the forwarder's wake-alarm callback (any random string; --run mints one)`);
-        envLines.push(`        FASTAGENT_WAKE_SECRET: !Ref FastagentWakeSecret`);
+    // Both carriers are chunked (env values max 2048 chars — see CARRIER_CHUNK_SIZE): N parameters, each riding its
+    // own env var; `start` reassembles them. ONE parameter set for every variable, so the template does not change
+    // when the value file gains a name.
+    for (const carrier of CARRIERS) {
+        for (let i = 0; i < CARRIER_MAX_CHUNKS; i++) {
+            const { param, env } = carrierChunk(carrier, i);
+            params.push(`  ${param}:`, `    Type: String`, `    Default: ""`, `    NoEcho: true`, `    Description: ${carrier.what} carried by --run, chunk ${i + 1}/${CARRIER_MAX_CHUNKS} (env values cap at 2048 chars); empty = unused`);
+            envLines.push(`        ${env}: !Ref ${param}`);
+        }
     }
+    // IAM invocation permission does not prove forwarder origin. Internal envelopes need a secret.
+    params.push(`  FastagentIngressSecret:`, `    Type: String`, `    NoEcho: true`, `    Description: shared secret authenticating forwarder→runtime envelopes (any random string; --run mints one)`);
+    envLines.push(`        FASTAGENT_INGRESS_SECRET: !Ref FastagentIngressSecret`);
+    // The wake-alarm shared secret: the container authenticates its alarm callbacks to the forwarder with it.
+    params.push(`  FastagentWakeSecret:`, `    Type: String`, `    NoEcho: true`, `    Description: shared secret between the container and the forwarder's wake-alarm callback (any random string; --run mints one)`);
+    envLines.push(`        FASTAGENT_WAKE_SECRET: !Ref FastagentWakeSecret`);
     const lines = [
         `${GENERATED_TEMPLATE_MARKER}. Edit freely — deploy then treats it as hand-written and never gates on drift.`,
         `AWSTemplateFormatVersion: "2010-09-09"`,
@@ -368,72 +283,43 @@ function template(input, translated, topology) {
         `      RoleArn: !GetAtt ExecutionRole.Arn`,
         `      ProtocolConfiguration: HTTP`,
         `      NetworkConfiguration: { NetworkMode: PUBLIC }`,
-        `      # SessionStorage is the agent's LOCAL disk: it survives compute stop/resume within a runtime`,
-        `      # version, but AWS wipes it on every VERSION UPDATE (= every deploy) and after 14 idle days.`,
-        `      # Durability therefore comes from the S3 snapshot the container pulls on its first`,
-        `      # invocation and pushes when work settles (presigned by the forwarder — the container holds`,
-        `      # no AWS credentials). A persistent MOUNT instead needs EfsAccessPoint + VPC mode, which`,
-        `      # forces a NAT gateway for model/channel egress (~$33/mo) — deliberately not the default.`,
+        `      # Managed SessionStorage: no VPC, no NAT, no operator-owned filesystem. It survives compute`,
+        `      # stop/resume, and AWS RESETS it on every runtime version update (= every deploy) and after`,
+        `      # 14 idle days — so a deploy replaces the state along with the image. Cross-deploy memory`,
+        `      # would need EFS or S3 Files, both VPC-only and therefore a standing NAT bill.`,
         `      FilesystemConfigurations:`,
         `        - SessionStorage: { MountPath: ${MOUNT} }`,
-        `      # Idle ${IDLE_TIMEOUT_SECONDS}s (the ping's HealthyBusy + time_of_last_update keeps BUSY sessions alive), max compute`,
-        `      # lifetime ${MAX_LIFETIME_SECONDS}s — the platform ceiling; the session id stays valid, so the next invoke`,
+        `      # Idle ${idleTimeout}s (the ping's HealthyBusy + time_of_last_update keeps BUSY sessions alive), max compute`,
+        `      # lifetime ${MAX_LIFETIME_SECONDS}s; the session id stays valid, so the next invoke`,
         `      # just gets fresh compute with the same storage. Memory bills per second for the whole`,
-        `      # session INCLUDING the idle tail, so a shorter tail is the main cost lever here.`,
-        `      LifecycleConfiguration: { IdleRuntimeSessionTimeout: ${IDLE_TIMEOUT_SECONDS}, MaxLifetime: ${MAX_LIFETIME_SECONDS} }`,
+        `      # session INCLUDING the idle tail, so a shorter tail is the main cost lever here —`,
+        `      # deploy.agentcore.idleTimeoutSeconds buys latency back for a chat workload.`,
+        `      LifecycleConfiguration: { IdleRuntimeSessionTimeout: ${idleTimeout}, MaxLifetime: ${MAX_LIFETIME_SECONDS} }`,
         `      EnvironmentVariables:`,
         ...envLines,
     ];
-    if (needsForwarder) {
-        lines.push(``, `  ForwarderRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: lambda.amazonaws.com }`, `            Action: sts:AssumeRole`, `      ManagedPolicyArns: [arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole]`, `      Policies:`, `        - PolicyName: invoke-runtime`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: bedrock-agentcore:InvokeAgentRuntime`, `                Resource:`, `                  - !GetAtt Runtime.AgentRuntimeArn`, `                  - !Sub "\${Runtime.AgentRuntimeArn}/*"`, `              - Effect: Allow # mint the presigned URLs the container uses for its state snapshot`, `                Action: [s3:GetObject, s3:PutObject]`, `                Resource: !Sub arn:aws:s3:::\${StateBucket}/${STATE_KEY}`, `              # Without s3:ListBucket, S3 folds "key absent" into 403 (anti-enumeration), which is`, `              # indistinguishable from a broken signature — so the container's restore contract`, `              # (agentcore-state.ts: ONLY 404 means first deploy) would dead-end every first deploy.`, `              # Scoped to the snapshot prefix: this grants "may know whether the snapshot exists",`, `              # not a listing of the whole deployment bucket.`, `              - Effect: Allow`, `                Action: s3:ListBucket`, `                Resource: !Sub arn:aws:s3:::\${StateBucket}`, `                Condition:`, `                  StringLike: { s3:prefix: state/* }`, ...(input.selfSchedule
-            ? [
-                `              - Effect: Allow # wake alarms: mirror pending wake-ups into one-shot schedules`,
-                `                Action: [scheduler:CreateSchedule, scheduler:UpdateSchedule]`,
-                `                Resource: !Sub arn:aws:scheduler:\${AWS::Region}:\${AWS::AccountId}:schedule/default/fa-${input.name}-wk-*`,
-                `              - Effect: Allow # hand the poke schedules their invoke role`,
-                `                Action: iam:PassRole`,
-                `                Resource: !GetAtt WakeSchedulerRole.Arn`,
-            ]
-            : []), ...(needsForwarder
-            ? [
-                `              - Effect: Allow # self-resolve callback URL for state-URL refresh / wake alarms`,
-                `                Action: lambda:GetFunctionUrlConfig`,
-                `                Resource: ${forwarderFnArn}`,
-            ]
-            : []), ``, `  Forwarder:`, `    Type: AWS::Lambda::Function`, `    Properties:`, `      FunctionName: fastagent-${input.name}-forwarder`, `      Runtime: nodejs22.x`, `      Handler: index.handler`, `      # Webhook ACKs are fast, but schedule-fire holds the connection for the WHOLE agent turn`, `      # (claim-before-run means a timeout never double-fires; the turn also continues and is`, `      # audited container-side). EventBridge→Lambda is async, so the long timeout costs nothing.`, `      Timeout: 900`, `      MemorySize: 256`, `      Role: !GetAtt ForwarderRole.Arn`, `      Environment:`, `        Variables:`, `          RUNTIME_ARN: !GetAtt Runtime.AgentRuntimeArn`, `          INGRESS_SESSION_ID: ${ingressSessionId(input.name)}`, ...(needsForwarder ? [`          STATE_REFRESH_SECRET: !Ref FastagentIngressSecret`] : []), ...(topology.webhooks ? [`          WEBHOOKS_ENABLED: "1"`] : []), ...(input.selfSchedule
-            ? [
-                `          WAKE_SECRET: !Ref FastagentWakeSecret`,
-                `          WAKE_ROLE_ARN: !GetAtt WakeSchedulerRole.Arn`,
-                `          WAKE_PREFIX: fa-${input.name}-wk-`,
-            ]
-            : []), `          INGRESS_SECRET: !Ref FastagentIngressSecret`, `          STATE_BUCKET: !Ref StateBucket`, `          STATE_KEY: ${STATE_KEY}`, `          MAX_WEBHOOK_BODY_BYTES: "${MAX_WEBHOOK_BODY_BYTES}"`, `      # From S3, not inline: the forwarder mints SigV4-presigned URLs for the state snapshot and`, `      # no longer fits CloudFormation's 4096-byte inline cap. The key is content-hashed, so a`, `      # code change is a parameter change — CloudFormation cannot miss it.`, `      Code:`, `        S3Bucket: !Ref StateBucket`, `        S3Key: !Ref ForwarderS3Key`);
-    }
-    if (needsForwarder) {
-        lines.push(``, `  ForwarderUrl:`, `    Type: AWS::Lambda::Url`, `    Properties:`, `      TargetFunctionArn: !GetAtt Forwarder.Arn`, `      # NONE is deliberate: webhook callers (Telegram/Feishu) cannot SigV4-sign. Authenticity is`, `      # verified downstream by each channel (secret token / signature), exactly as on every host.`, `      AuthType: NONE`, ``, `  ForwarderUrlPermission:`, `    Type: AWS::Lambda::Permission`, `    Properties:`, `      FunctionName: !Ref Forwarder`, `      Action: lambda:InvokeFunctionUrl`, `      Principal: "*"`, `      FunctionUrlAuthType: NONE`, ``, `  # Function URLs created after Oct 2025 require lambda:InvokeFunction IN ADDITION to`, `  # lambda:InvokeFunctionUrl for public (NONE) access — with only the first, every request 403s`, `  # (found by the first real deploy). InvokedViaFunctionUrl scopes it to URL traffic: without it`, `  # the bare * principal would also let any AWS principal call the Lambda API directly, bypassing`, `  # the Function URL event shape to forge internal events.`, `  ForwarderInvokePermission:`, `    Type: AWS::Lambda::Permission`, `    Properties:`, `      FunctionName: !Ref Forwarder`, `      Action: lambda:InvokeFunction`, `      Principal: "*"`, `      InvokedViaFunctionUrl: true`);
-        if (input.selfSchedule) {
-            lines.push(``, `  # The role the wake-poke schedules assume to invoke the forwarder. Its policy names the`, `  # function by CONSTRUCTED arn (not !Ref) — the forwarder's env references this role, so a`, `  # !Ref back would be a circular dependency.`, `  WakeSchedulerRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: scheduler.amazonaws.com }`, `            Action: sts:AssumeRole`, `            Condition:`, `              StringEquals: { aws:SourceAccount: !Ref AWS::AccountId }`, `      Policies:`, `        - PolicyName: poke-forwarder`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: lambda:InvokeFunction`, `                Resource: ${forwarderFnArn}`);
-        }
-    }
+    lines.push(``, `  ForwarderRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: lambda.amazonaws.com }`, `            Action: sts:AssumeRole`, `      ManagedPolicyArns: [arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole]`, `      Policies:`, `        - PolicyName: invoke-runtime`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: bedrock-agentcore:InvokeAgentRuntime`, `                Resource:`, `                  - !GetAtt Runtime.AgentRuntimeArn`, `                  - !Sub "\${Runtime.AgentRuntimeArn}/*"`, `              - Effect: Allow # wake alarms: mirror pending wake-ups into one-shot schedules`, `                Action: [scheduler:CreateSchedule, scheduler:UpdateSchedule]`, `                Resource: !Sub arn:aws:scheduler:\${AWS::Region}:\${AWS::AccountId}:schedule/default/${wakeAlarmPrefix(input.name)}*`, `              - Effect: Allow # hand the poke schedules their invoke role`, `                Action: iam:PassRole`, `                Resource: !GetAtt WakeSchedulerRole.Arn`, `              - Effect: Allow # self-resolve callback URL for state-URL refresh / wake alarms`, `                Action: lambda:GetFunctionUrlConfig`, `                Resource: ${forwarderFnArn}`, ``, `  Forwarder:`, `    Type: AWS::Lambda::Function`, `    Properties:`, `      FunctionName: ${forwarderFunctionName(input.name)}`, `      Runtime: nodejs22.x`, `      Handler: index.handler`, `      # Webhook ACKs are fast, but routine-fire holds the connection for the WHOLE agent turn`, `      # (claim-before-run means a timeout never double-fires; the turn also continues and is`, `      # audited container-side). EventBridge→Lambda is async, so the long timeout costs nothing.`, `      Timeout: 900`, `      MemorySize: 256`, `      Role: !GetAtt ForwarderRole.Arn`, `      Environment:`, `        Variables:`, `          RUNTIME_ARN: !GetAtt Runtime.AgentRuntimeArn`, `          INGRESS_SESSION_ID: ${ingressSessionId(input.name)}`, ...(topology.webhooks ? [`          WEBHOOKS_ENABLED: "1"`] : []), `          WAKE_SECRET: !Ref FastagentWakeSecret`, `          WAKE_ROLE_ARN: !GetAtt WakeSchedulerRole.Arn`, `          WAKE_PREFIX: ${wakeAlarmPrefix(input.name)}`, `          INGRESS_SECRET: !Ref FastagentIngressSecret`, `          MAX_WEBHOOK_BODY_BYTES: "${MAX_WEBHOOK_BODY_BYTES}"`, `      # A content-hashed key makes code changes visible to CloudFormation.`, `      Code:`, `        S3Bucket: !Ref ForwarderBucket`, `        S3Key: !Ref ForwarderS3Key`);
+    lines.push(``, `  ForwarderUrl:`, `    Type: AWS::Lambda::Url`, `    Properties:`, `      TargetFunctionArn: !GetAtt Forwarder.Arn`, `      # NONE is deliberate: webhook callers (Telegram/Feishu) cannot SigV4-sign. Authenticity is`, `      # verified downstream by each channel (secret token / signature), exactly as on every host.`, `      AuthType: NONE`, ``, `  ForwarderUrlPermission:`, `    Type: AWS::Lambda::Permission`, `    Properties:`, `      FunctionName: !Ref Forwarder`, `      Action: lambda:InvokeFunctionUrl`, `      Principal: "*"`, `      FunctionUrlAuthType: NONE`, ``, `  # Function URLs created after Oct 2025 require lambda:InvokeFunction IN ADDITION to`, `  # lambda:InvokeFunctionUrl for public (NONE) access — with only the first, every request 403s`, `  # (found by the first real deploy). InvokedViaFunctionUrl scopes it to URL traffic: without it`, `  # the bare * principal would also let any AWS principal call the Lambda API directly, bypassing`, `  # the Function URL event shape to forge internal events.`, `  ForwarderInvokePermission:`, `    Type: AWS::Lambda::Permission`, `    Properties:`, `      FunctionName: !Ref Forwarder`, `      Action: lambda:InvokeFunction`, `      Principal: "*"`, `      InvokedViaFunctionUrl: true`);
+    lines.push(``, `  # The role the wake-poke schedules assume to invoke the forwarder. Its policy names the`, `  # function by CONSTRUCTED arn (not !Ref) — the forwarder's env references this role, so a`, `  # !Ref back would be a circular dependency.`, `  WakeSchedulerRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: scheduler.amazonaws.com }`, `            Action: sts:AssumeRole`, `            Condition:`, `              StringEquals: { aws:SourceAccount: !Ref AWS::AccountId }`, `      Policies:`, `        - PolicyName: poke-forwarder`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: lambda:InvokeFunction`, `                Resource: ${forwarderFnArn}`);
     if (translated.length > 0) {
         lines.push(``, `  SchedulerRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: scheduler.amazonaws.com }`, `            Action: sts:AssumeRole`, `            Condition:`, `              StringEquals: { aws:SourceAccount: !Ref AWS::AccountId }`, `      Policies:`, `        - PolicyName: fire-forwarder`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: lambda:InvokeFunction`, `                Resource: !GetAtt Forwarder.Arn`);
         for (const { fact, expression } of translated) {
-            lines.push(``, `  Schedule${logicalId(fact.name)}:`, `    Type: AWS::Scheduler::Schedule`, `    Properties:`, `      Name: ${scheduleResourceName(input.name, fact.name)}`, `      ScheduleExpression: ${expression}`, `      ScheduleExpressionTimezone: ${fact.tz ?? "Etc/UTC"}`, `      FlexibleTimeWindow: { Mode: "OFF" }`, `      Target:`, `        Arn: !GetAtt Forwarder.Arn`, `        RoleArn: !GetAtt SchedulerRole.Arn`, `        # <aws.scheduler.scheduled-time> = the slot instant — the container's idempotency key`, `        # (EventBridge delivery is at-least-once; a duplicate slot must not double-fire).`, `        Input: ${yamlSingleQuote(JSON.stringify({ scheduleFire: { name: fact.name, slot: "<aws.scheduler.scheduled-time>" } }))}`);
+            lines.push(``, `  Schedule${logicalId(fact.name)}:`, `    Type: AWS::Scheduler::Schedule`, `    Properties:`, `      Name: ${scheduleResourceName(input.name, fact.name)}`, `      ScheduleExpression: ${expression}`, `      ScheduleExpressionTimezone: ${fact.tz ?? "Etc/UTC"}`, `      FlexibleTimeWindow: { Mode: "OFF" }`, `      Target:`, `        Arn: !GetAtt Forwarder.Arn`, `        RoleArn: !GetAtt SchedulerRole.Arn`, `        # <aws.scheduler.scheduled-time> is the clock's NAME for this occurrence: EventBridge repeats it`, `        # byte-identical on every redelivery, which is what makes the container's dedup work.`, `        Input: ${yamlSingleQuote(JSON.stringify({
+                scheduleFire: { name: fact.name, occurrence: "<aws.scheduler.scheduled-time>" },
+            }))}`);
         }
     }
     lines.push(``, `Outputs:`, `  RuntimeArn:`, `    Value: !GetAtt Runtime.AgentRuntimeArn`);
-    if (needsForwarder) {
-        lines.push(`  ForwarderUrl:`, `    Value: !GetAtt ForwarderUrl.FunctionUrl`);
-    }
+    lines.push(`  ForwarderUrl:`, `    Value: !GetAtt ForwarderUrl.FunctionUrl`);
     return `${lines.join("\n")}\n`;
 }
 /** Compute the AgentCore deploy plan from the resolved definition. */
 export function planAgentcoreDeploy(input) {
     const { name, channels } = input;
-    const stack = `fastagent-${name}`;
-    const repo = `fastagent/${name}`;
+    const stack = agentcoreStackName(name);
+    const repo = agentcoreRepoName(name);
     const prefix = input.agentPrefix;
-    // Translate every schedule; the ones EventBridge cannot express become explicit runbook warnings —
-    // a schedule silently missing from the template would be the worst failure mode (nothing ever fires).
+    // Translate every schedule; the ones EventBridge cannot express become explicit runbook warnings.
     const translated = [];
     const untranslatable = [];
     for (const fact of input.schedules) {
@@ -443,10 +329,9 @@ export function planAgentcoreDeploy(input) {
         else
             untranslatable.push({ name: fact.name, reason: result.error });
     }
-    // Identifier collisions: the author-side → AWS-side name mappings are lossy (logical ids strip
-    // punctuation; parameter names collapse underscores), so two DISTINCT legal inputs can land on one
-    // CloudFormation key — which would generate a silently wrong stack. Fail visibly at plan time; a
-    // rename is the fix (a hash-mangled allocator would trade readability for an edge case).
+    // Identifier collisions: the author-side → AWS-side name mappings are lossy (logical ids strip punctuation;
+    // parameter names collapse underscores), so two DISTINCT legal inputs can land on one CloudFormation key — which
+    // would generate a silently wrong stack.
     const logicalIds = new Map();
     for (const { fact } of translated) {
         const id = `Schedule${logicalId(fact.name)}`;
@@ -456,35 +341,21 @@ export function planAgentcoreDeploy(input) {
         }
         logicalIds.set(id, fact.name);
     }
-    const paramNames = new Map();
-    for (const s of deploymentSecrets(input.modelAuth, channels, input.extraSecrets)) {
-        const p = cfnParamName(s.name);
-        const clash = paramNames.get(p);
-        if (clash !== undefined && clash !== s.name) {
-            throw new Error(`secrets "${clash}" and "${s.name}" collapse to the same CloudFormation parameter (${p}) — rename one`);
-        }
-        paramNames.set(p, s.name);
-    }
-    const topology = agentcoreTopology(input, translated.length);
-    const needsForwarder = topology.forwarder;
+    const topology = agentcoreTopology(input);
     const artifacts = [
         { path: `${prefix}${TEMPLATE_FILE}`, content: template(input, translated, topology) },
-        ...(needsForwarder ? [{ path: `${prefix}${FORWARDER_FILE}`, content: forwarderSource() }] : []),
+        { path: `${prefix}${FORWARDER_FILE}`, content: forwarderSource() },
         ...containerArtifacts(input),
     ];
-    const secrets = deploymentSecrets(input.modelAuth, channels, input.extraSecrets);
-    const requiredSecrets = secrets.filter((s) => s.required);
-    const optionalSecrets = secrets.filter((s) => !s.required);
-    const paramHint = (list) => list.map((s) => `${cfnParamName(s.name)}=<value>`).join(" ");
+    const secrets = input.secrets ?? [];
     const image = `<account-id>.dkr.ecr.<region>.amazonaws.com/${repo}:<tag>`;
-    const bucketHint = stateBucketName(name, "<account-id>");
+    const bucketHint = deploymentBucketName(name, "<account-id>");
     const runbook = [
         `# Deploy "${name}" to AWS Bedrock AgentCore. ${prefix}${TEMPLATE_FILE} / Dockerfile(.dockerignore) are generated above.`,
         `# Prereqs: AWS CLI v2 with credentials + a region where AgentCore is available, and Docker with buildx`,
         `# (the image MUST be linux/arm64 — the one host whose build runs on YOUR machine, not remotely).`,
         ``,
-        `# 1. ECR repository + the deployment bucket (one-time; skip what exists). The bucket lives OUTSIDE`,
-        `#    the stack on purpose: it holds the agent's state snapshot, which must survive a delete-stack.`,
+        `# 1. ECR repository + the forwarder artifact bucket (one-time; skip what exists).`,
         `aws ecr create-repository --repository-name ${repo}`,
         `aws s3api create-bucket --bucket ${bucketHint} --region us-east-1   # us-east-1 ONLY`,
         `aws s3api create-bucket --bucket ${bucketHint} --region <region> \\   # every OTHER region`,
@@ -492,79 +363,46 @@ export function planAgentcoreDeploy(input) {
         `aws s3api put-public-access-block --bucket ${bucketHint} \\`,
         `  --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true`,
         ``,
-        ...(needsForwarder
-            ? [
-                `# 1b. Package the forwarder and upload it. Name the object by its CONTENT (a hash/date):`,
-                `#     CloudFormation rolls the function only when the ForwarderS3Key VALUE changes.`,
-                `(cd ${prefix}lambda && zip -q forwarder.zip index.js)`,
-                `aws s3 cp ${prefix}lambda/forwarder.zip s3://${bucketHint}/forwarder/<hash>.zip`,
-                ``,
-            ]
-            : []),
+        `# 1b. Package the forwarder and upload it. Name the object by its CONTENT (a hash/date):`,
+        `#     CloudFormation rolls the function only when the ForwarderS3Key VALUE changes.`,
+        `(cd ${prefix}lambda && zip -q forwarder.zip index.js)`,
+        `aws s3 cp ${prefix}lambda/forwarder.zip s3://${bucketHint}/forwarder/<hash>.zip`,
+        ``,
         `# 2. Build (linux/arm64) + push. Use a UNIQUE tag per deploy (a git sha / date): CloudFormation only`,
         `#    rolls the runtime when the ImageUri VALUE changes — re-pushing the same tag deploys nothing.`,
         `aws ecr get-login-password | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com`,
-        prefix
-            ? `docker buildx build --platform linux/arm64 -f ${prefix}Dockerfile -t ${image} --push .`
-            : `docker buildx build --platform linux/arm64 -t ${image} --push .`,
+        `docker buildx build --platform linux/arm64 -f ${prefix}Dockerfile -t ${image} --push .`,
         ``,
-        `# 3. Deploy the stack (runtime + ingress + schedules in one template). Secrets ride NoEcho parameters:`,
+        `# 3. Deploy the stack (runtime + ingress + schedules in one template).`,
     ];
-    if (requiredSecrets.length > 0) {
-        runbook.push(`#    Required parameters:`, ...requiredSecrets.map((s) => `#      ${cfnParamName(s.name)}: ${s.hint}`));
-    }
-    if (optionalSecrets.length > 0) {
-        runbook.push(`#    Optional parameters (set only when the matching feature is configured):`, ...optionalSecrets.map((s) => `#      ${cfnParamName(s.name)}: ${s.hint}`));
-    }
-    const wakeSecretHint = input.selfSchedule ? " FastagentWakeSecret=<any random string>" : "";
-    if (input.selfSchedule) {
-        runbook.push(`#      FastagentWakeSecret: the wake-alarm shared secret — any random string (\`--run\` mints one)`);
+    if (secrets.length > 0) {
+        runbook.push(`#    Variables ride ONE NoEcho parameter, FastagentEnv: base64 of a JSON object {"NAME": "value", …},`, `#    split every ${CARRIER_CHUNK_SIZE} chars across FastagentEnv, FastagentEnv2 … (\`--run\` builds it):`, ...secrets.map((s) => `#      ${s.name}: ${s.hint}`));
     }
-    runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${prefix}${TEMPLATE_FILE} \\`, `  --capabilities CAPABILITY_IAM \\`, `  --parameter-overrides ImageUri=${image}${needsForwarder ? ` StateBucket=${bucketHint} ForwarderS3Key=forwarder/<hash>.zip` : ""}${requiredSecrets.length > 0 ? ` ${paramHint(requiredSecrets)}` : ""}${wakeSecretHint}`, ``, needsForwarder
-        ? `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`
-        : `# 4. Read the outputs (the runtime ARN — this topology has NO public URL: nothing outside AWS`, ...(needsForwarder
-        ? []
-        : [`#    sends to it, so no Function URL is created and the agent is reachable only via SigV4).`]), `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, ...(needsForwarder
-        ? [
-            `# The ingress transport is a separate Lambda and therefore a separate log source:`,
-            `fastagent logs agentcore --source forwarder --follow`,
-        ]
-        : []));
-    // Model-auth guidance mirrors the other hosts: an env key became a parameter above; OAuth/stored
-    // can't be read at plan time — `--run` carries it as FastagentAuthSeed.
+    const wakeSecretHint = " FastagentWakeSecret=<any random string>";
+    runbook.push(`#      FastagentWakeSecret: the wake-alarm shared secret — any random string (\`--run\` mints one)`);
+    runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${prefix}${TEMPLATE_FILE} \\`, `  --capabilities CAPABILITY_IAM \\`, `  --parameter-overrides ImageUri=${image} ForwarderBucket=${bucketHint} ForwarderS3Key=forwarder/<hash>.zip${secrets.length > 0 ? " FastagentEnv=<base64 JSON>" : ""}${wakeSecretHint}`, ``, `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`, `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, `# The ingress transport is a separate Lambda and therefore a separate log source:`, `fastagent logs agentcore --source forwarder --follow`, ``, `# 6. Set a log retention period on EVERY group this stack writes to. Each is created by the service that`, `#    writes it, not by this template, and CloudWatch keeps log data indefinitely by default — which is`, `#    forever-billed storage, and the logs are where WHY a scheduled turn failed is recorded. Logs are the`, `#    ONE state path this host does not reclaim on its own.`, `aws logs put-retention-policy --log-group-name <the group \`fastagent logs agentcore\` resolves> --retention-in-days 14`, `# The forwarder is a separate Lambda, so its group is separate and defaults the same way:`, `aws logs put-retention-policy --log-group-name ${forwarderLogGroup(input.name)} --retention-in-days 14`);
+    // Model-auth guidance mirrors the other hosts: an env key became a parameter above; OAuth/stored can't be read at
+    // plan time — `--run` carries it as FastagentAuthSeed.
     if (!isEnvKey(input.modelAuth)) {
         runbook.push(``, input.modelAuth === undefined
-            ? `# Model auth: none found at the local auth path — pass --auth-path <file>, or \`--run\` carries it`
+            ? `# Model auth: none found at the local auth path — set FASTAGENT_AUTH_PATH, or \`--run\` carries it`
             : `# Model auth: your local auth is "${input.modelAuth}" — the plan can't read its value; \`--run\` carries it`, `#   as the FastagentAuthSeed parameter (base64 of auth.json), materialized on first boot.`);
     }
-    // Post-deploy webhook registration — the shared channel-ingress steps, pointed at the forwarder's
-    // Function URL (read from the stack outputs). `--run` REFUSES a long-connection channel here, but
-    // generate-only only warns and still prints this runbook, so the steps are filtered on ingress like
-    // every other host's rather than on the CLI having gated.
+    // Post-deploy webhook registration — the shared channel-ingress steps, pointed at the forwarder's Function URL
+    // (read from the stack outputs).
     const post = webhookRunbook(`<ForwarderUrl>`, channels);
-    // AgentCore asides the shared steps cannot carry: nothing else routes through a forwarder, and
-    // nothing else has a compute ceiling.
-    // Named rather than positional: the asides land after ALL the steps, so "the console" has to say
-    // WHICH console. One line for both kinds — an agent that declares feishu AND lark reads the same
-    // fact twice otherwise and looks for a second step that does not exist.
+    // AgentCore asides the shared steps cannot carry: nothing else routes through a forwarder, and nothing else has a
+    // compute ceiling.
     if (webhookKinds(channels).some((kind) => kind === "feishu" || kind === "lark")) {
         post.push(`# NOTE: the Feishu/Lark console's challenge rides through the forwarder to the channel and back`, `#   verbatim, so the stack must be deployed when you save the Request URL.`);
     }
-    if (channels.some((channel) => channel.name === "github")) {
-        post.push(`# NOTE: github turns are fire-and-forget with no replay — a compute reclaimed mid-review drops it`, `#   (the ping's HealthyBusy + time_of_last_update holds the session while turns run, but the 8 h compute ceiling is hard).`);
-    }
     if (post.length > 0)
         runbook.push(``, ...post);
     for (const u of untranslatable) {
         runbook.push(``, `# WARNING: schedule "${u.name}" has NO EventBridge rule — ${u.reason}.`, `#   It will NOT fire on this deployment until you create an equivalent trigger yourself.`);
     }
-    if (input.selfSchedule) {
-        runbook.push(``, `# selfSchedule: the agent's wake-ups are EventBridge-backed — each pending wake-up is mirrored`, `#   (via the forwarder, authenticated by FastagentWakeSecret) into a self-deleting one-shot`, `#   schedule (fa-${name}-wk-*) that wakes the container at the right instant. Reliable even when`, `#   the compute is reclaimed. Caveat: only for wake-ups set through the INGRESS surface (chat`, `#   channels/schedules); a wake set inside a direct InvokeAgentRuntime session stays in that`, `#   session's own storage and fires only while that session is awake.`);
-    }
-    runbook.push(``, `# Invoke the agent programmatically (any session id ≥ 33 chars; the response streams as SSE):`, `aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "my-conversation-000000000000000000" \\`, `  --payload '{"kind":"invoke","session":"cli","text":"hello"}' --cli-binary-format raw-in-base64-out /dev/stdout`);
-    if (needsForwarder) {
-        runbook.push(``, `# After a REDEPLOY, stop the ingress session so the new image serves immediately — a live session`, `# keeps its old compute (and the OLD image) until ${IDLE_TIMEOUT_SECONDS}s idle / the 8 h compute ceiling`, `# (\`--run\` does this automatically):`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`);
-    }
-    runbook.push(``, `# Redeploy = step 1b (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is a LOCAL disk — AWS wipes it on every runtime version update (i.e. every`, `# deploy) and after 14 idle days. What survives is the S3 snapshot under s3://${bucketHint}/${STATE_KEY}:`, `# the container restores it on its first invocation and pushes it whenever work settles. Keep that`, `# bucket and the agent keeps its sessions, channel state and pending wake-ups across deploys;`, `# delete it and the agent starts blank. (A persistent MOUNT would need EFS + VPC mode + a NAT`, `# gateway for model/channel egress — see the template comment.)`, `# CREDENTIALS RIDE THAT SNAPSHOT TOO: FASTAGENT_SECRETS_DIR is ${SECRETS_DIR}, inside the state`, `# root, so an OAuth auth.json ROTATED on the box persists (a refresh token is single-use — without`, `# this the next microVM would re-seed the deploy-time copy and eventually fail to authenticate).`, `# The bucket is therefore credential storage: it is created with public access blocked and`, `# versioning on, and deleting it costs model access until the next deploy re-seeds.`);
+    runbook.push(``, `# Wake-ups: the agent's own follow-up turns (the wake tool) are EventBridge-backed — each pending wake-up is mirrored`, `#   (via the forwarder, authenticated by FastagentWakeSecret) into a self-deleting one-shot`, `#   schedule (fa-${name}-wk-*) that wakes the container at the right instant. Reliable even when`, `#   the compute is reclaimed. The forwarder supplies the callback URL; use the deployment's`, `#   fixed runtime session id for programmatic calls too.`);
+    runbook.push(``, `# Invoke the agent programmatically (reuse the deployment session; conversations remain separate):`, `aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}" \\`, `  --payload '{"kind":"invoke","session":"cli","text":"hello"}' --cli-binary-format raw-in-base64-out /dev/stdout`);
+    runbook.push(``, `# Stop the fixed runtime session after redeploy so the next call uses the new image.`, `# \`--run\` does this automatically. In-flight turns are interrupted.`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`, ``, `# Redeploy = \`fastagent deploy agentcore\` (a new definition needs a fresh release manifest) + step 1b`, `# (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is managed SessionStorage. It keeps base/ (including unfinished work), .state/`, `# and .secrets/ across compute stop/resume — an idle-reclaimed agent resumes with its memory. AWS`, `# RESETS it on every runtime version update (i.e. every deploy) and after 14 idle days, so a deploy`, `# replaces the state along with the image: sessions, channel state and pending wake-ups start blank,`, `# and the model credential is re-seeded from FASTAGENT_AUTH_SEED. Deploying IS re-authenticating.`, `# An OAuth refresh token is single-use and shared with your machine, so the box can lose model`, `# access between deploys — deploy again to refresh it, or use a provider API key.`, `# Cross-deploy memory needs EFS or S3 Files, which are VPC-only (a NAT gateway for model/channel`, `# egress, ~$33/mo standing): use \`deploy fly\` or \`deploy railway\` for a real volume instead.`, `# Keep one runtime writer per workspace; use the fixed runtime session id printed above for every entry point.`);
     return { artifacts, runbook, untranslatableSchedules: untranslatable, topology };
 }