@deployfoundation/foundation-deploy 0.1.0

package/dist/bin/foundation-deploy.js

@@ -0,0 +1,1906 @@
+#!/usr/bin/env node
+// @bun
+import {
+  AGENT_DOCKERFILE,
+  FOUNDATION_ROOT,
+  INFRA_ROOT,
+  PACKAGE_ASSETS,
+  argv,
+  aws,
+  awsContext,
+  awsMutate,
+  callerAccountId,
+  cdkEnv,
+  createSecretString,
+  instanceBanner,
+  loadInstanceContext,
+  putSecretJson,
+  putSecretString,
+  readSecretJson,
+  readSecretString,
+  releaseContext,
+  releaseRequest,
+  resolveInstanceFilePath,
+  resolveRelease,
+  run,
+  runCapture,
+  secretExists,
+  stackExists,
+  stackOutput,
+  toolVersion
+} from "../chunk-v7tz8g50.js";
+import {
+  BASE_SLACK_EVENTS,
+  CAPABILITY_IDS,
+  CUSTOMIZATION_ARTIFACT_NAME,
+  instanceNames,
+  parseInstanceConfig,
+  parseSchedule,
+  requiredGithubPermissions,
+  requiredSlackCommands,
+  requiredSlackScopes,
+  skillsKey,
+  slackCommandPrefix
+} from "../chunk-9ddxyvq2.js";
+
+// src/deploy/config-sync.ts
+import { existsSync, mkdirSync, mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+function productSkillsDir(foundationRoot = FOUNDATION_ROOT) {
+  const dir = resolve(foundationRoot, "skills");
+  if (!existsSync(dir))
+    return;
+  const entries = readdirSync(dir).filter((name) => name !== "README.md");
+  return entries.length > 0 ? dir : undefined;
+}
+async function configSync(ctx, opts = {}) {
+  if (opts.runtimeConfigPath === undefined && ctx.instance.customization !== undefined)
+    throw new Error("customized instances require a freshly validated runtimeConfigPath; run through `deploy` or `config:sync`");
+  const source = opts.runtimeConfigPath ?? ctx.paths.configPath;
+  const bucket = opts.bucket ?? (ctx.dryRun === true ? `<${ctx.names.data}.BucketName>` : await stackOutput(ctx, ctx.names.data, "BucketName"));
+  await awsMutate(ctx, ["s3", "cp", source, `s3://${bucket}/${ctx.names.configKey}`]);
+  const skills = opts.release === undefined ? productSkillsDir(opts.foundationRoot) : await (opts.releaseSkillsDir ?? unpackReleaseSkills)(ctx, opts.release);
+  if (skills !== undefined)
+    await awsMutate(ctx, ["s3", "sync", `${skills}/`, `s3://${bucket}/skills/`, "--delete"]);
+  return bucket;
+}
+async function unpackReleaseSkills(ctx, release) {
+  const key = release.manifest?.skills.key ?? skillsKey(release.version);
+  const dir = mkdtempSync(join(tmpdir(), "foundation-skills-"));
+  const tarball = join(dir, "skills.tar.gz");
+  const contents = join(dir, "skills");
+  mkdirSync(contents, { recursive: true });
+  await awsMutate(ctx, ["s3", "cp", `s3://${release.bucket}/${key}`, tarball]);
+  await run(["tar", "-xzf", tarball, "-C", contents], { dryRun: ctx.dryRun });
+  return contents;
+}
+
+// src/deploy/deploy.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { createRequire } from "node:module";
+import { join as join3 } from "node:path";
+
+// ../connectors/src/github.ts
+var GITHUB_TOKEN_RESPONSE_MAX_BYTES = 128 * 1024;
+// ../connectors/src/google-errors.ts
+var MAX_ERROR_BODY_BYTES = 16 * 1024;
+
+// ../connectors/src/google-drive.ts
+var MAX_GOOGLE_TOKEN_RESPONSE_BYTES = 128 * 1024;
+
+// ../connectors/src/gmail.ts
+var GMAIL_LIST_SUMMARY_MAX_BYTES = 1024 * 1024;
+var GMAIL_SCOPES = [
+  "https://www.googleapis.com/auth/gmail.compose",
+  "https://www.googleapis.com/auth/gmail.modify"
+].join(" ");
+var MAX_PART_TEXT_BYTES = 200 * 1024;
+var MAX_GMAIL_DECODED_TEXT_BYTES = 512 * 1024;
+var MAX_GMAIL_JSON_RESPONSE_BYTES = 2 * 1024 * 1024;
+// ../connectors/src/google-calendar.ts
+var GOOGLE_CALENDAR_EVENT_SCOPE = "https://www.googleapis.com/auth/calendar.events";
+var GOOGLE_CALENDAR_FREEBUSY_SCOPE = "https://www.googleapis.com/auth/calendar.events.freebusy";
+var GOOGLE_CALENDAR_EVENTS_SCOPE = [
+  GOOGLE_CALENDAR_EVENT_SCOPE,
+  GOOGLE_CALENDAR_FREEBUSY_SCOPE
+].join(" ");
+var GOOGLE_CALENDAR_JSON_MAX_BYTES = 2 * 1024 * 1024;
+// ../connectors/src/otter.ts
+var OTTER_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+// ../connectors/src/knock.ts
+var KNOCK_REGISTER_URL = "https://mcp.knock.app/register";
+var KNOCK_MAX_RESPONSE_BYTES = 1024 * 1024;
+var KNOCK_MAX_REQUEST_BYTES = 256 * 1024;
+var MAX_CLIENT_ID_CHARS = 2048;
+var MAX_REDIRECT_URI_CHARS = 2048;
+class KnockResponseTooLargeError extends Error {
+  constructor() {
+    super(`Knock response exceeded ${KNOCK_MAX_RESPONSE_BYTES} bytes`);
+    this.name = "KnockResponseTooLargeError";
+  }
+}
+function parseKnockOAuthClient(raw) {
+  const value = parseJsonObject(raw, "Knock OAuth client");
+  const keys = Object.keys(value);
+  if (keys.length !== 2 || !keys.every((key) => key === "client_id" || key === "redirect_uri"))
+    throw new Error("Knock OAuth client must contain only client_id and redirect_uri");
+  return {
+    client_id: requiredOpaqueString(value.client_id, "Knock OAuth client: missing client_id", MAX_CLIENT_ID_CHARS),
+    redirect_uri: validRedirectUri(value.redirect_uri, "Knock OAuth client")
+  };
+}
+async function registerKnockPublicClient(args) {
+  const redirectUri = validRedirectUri(args.redirectUri, "Knock OAuth registration");
+  let response;
+  try {
+    response = await (args.fetchImpl ?? fetch)(KNOCK_REGISTER_URL, {
+      method: "POST",
+      redirect: "error",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({
+        client_name: "Foundation Knock read-only MCP",
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none"
+      })
+    });
+  } catch {
+    throw new Error("Knock OAuth registration could not be completed");
+  }
+  if (!response.ok)
+    throw new Error("Knock OAuth registration was rejected");
+  const body = parseJsonObject(await readBoundedKnockResponse(response), "Knock OAuth registration");
+  return {
+    client_id: requiredOpaqueString(body.client_id, "Knock OAuth registration: missing client_id", MAX_CLIENT_ID_CHARS),
+    redirect_uri: redirectUri
+  };
+}
+async function readBoundedKnockResponse(response, maxBytes = KNOCK_MAX_RESPONSE_BYTES) {
+  const declaredBytes = Number(response.headers.get("content-length") ?? "");
+  if (Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+    await response.body?.cancel().catch(() => {
+      return;
+    });
+    throw new KnockResponseTooLargeError;
+  }
+  const reader = response.body?.getReader();
+  if (reader === undefined)
+    return "";
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {
+        return;
+      });
+      throw new KnockResponseTooLargeError;
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+function parseJsonObject(raw, label) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error(`${label} must be valid JSON`);
+  }
+  if (!isPlainObject(value))
+    throw new Error(`${label} must be an object`);
+  return value;
+}
+function requiredOpaqueString(value, message, max) {
+  if (!isSafeOpaqueString(value, max))
+    throw new Error(message);
+  return value;
+}
+function validRedirectUri(value, label) {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_REDIRECT_URI_CHARS)
+    throw new Error(`${label}: missing redirect_uri`);
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${label}: redirect_uri must be an HTTPS URL`);
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.hash !== "" || url.toString() !== value)
+    throw new Error(`${label}: redirect_uri must be an HTTPS URL`);
+  return value;
+}
+function isSafeOpaqueString(value, max) {
+  return typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// ../connectors/src/crm.ts
+var CRM_MAX_REQUEST_BYTES = 512 * 1024;
+var CRM_MAX_RESPONSE_BYTES = 512 * 1024;
+// ../connectors/src/upwork.ts
+var UPWORK_MAX_RESPONSE_BYTES = 1024 * 1024;
+var UPWORK_MAX_ACCESS_TOKEN_TTL_SECONDS = 24 * 60 * 60;
+var UPWORK_GRAPHQL_DOCUMENTS = Object.freeze({
+  search_jobs: Object.freeze({
+    operationName: "SearchJobs",
+    query: `query SearchJobs($filter: MarketplaceJobPostingsSearchFilter) {
+  marketplaceJobPostingsSearch(
+    marketPlaceJobFilter: $filter
+    searchType: USER_JOBS_SEARCH
+    sortAttributes: [{ field: RECENCY }]
+  ) {
+    totalCount
+    edges {
+      node {
+        id
+        title
+        description
+        ciphertext
+        amount { displayValue currency }
+        skills { name }
+        client { totalFeedback }
+      }
+    }
+    pageInfo { endCursor hasNextPage }
+  }
+}`
+  }),
+  get_job: Object.freeze({
+    operationName: "JobDetails",
+    query: `query JobDetails($id: ID!) {
+  marketplaceJobPosting(id: $id) {
+    id
+    content { title description }
+    contractTerms { contractType }
+    clientCompanyPublic { id }
+  }
+}`
+  }),
+  list_proposals: Object.freeze({
+    operationName: "FreelancerVendorProposals",
+    query: `query FreelancerVendorProposals(
+  $filter: VendorProposalFilter!
+  $sortAttribute: VendorProposalSortAttribute!
+  $pagination: Pagination!
+) {
+  vendorProposals(
+    filter: $filter
+    sortAttribute: $sortAttribute
+    pagination: $pagination
+  ) {
+    totalCount
+    edges {
+      node {
+        id
+        status { status }
+        marketplaceJobPosting { id content { title } }
+        terms { chargeRate { displayValue } }
+      }
+    }
+    pageInfo { endCursor hasNextPage }
+  }
+}`
+  }),
+  connects_summary: Object.freeze({
+    operationName: "ConnectsSummary",
+    query: `query ConnectsSummary {
+  connectsSummary {
+    organizationId
+    connectsBalance
+    rolloverBalance
+    connectsBalanceFree
+    connectsBalancePaid
+  }
+}`
+  }),
+  submit_proposal: Object.freeze({
+    operationName: "createJobProposal",
+    query: `mutation createJobProposal($input: CreateJobProposalInput!) {
+  createJobProposal(input: $input) {
+    newProposalId
+    status
+    error
+  }
+}`
+  })
+});
+// src/deploy/config.ts
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+function adminsCsv(yamlText, source = "runtime config") {
+  const doc = parse(yamlText);
+  const admins = doc?.admins;
+  if (!Array.isArray(admins) || admins.length === 0)
+    throw new Error(`${source}: \`admins\` must be a non-empty list of Slack user ids`);
+  return admins.map((a) => {
+    if (typeof a !== "string" || a.trim() === "")
+      throw new Error(`${source}: admins entry is not a string: ${JSON.stringify(a)}`);
+    return a.trim();
+  }).join(",");
+}
+function adminsCsvFromFile(path) {
+  return adminsCsv(readFileSync(path, "utf8"), path);
+}
+
+// src/deploy/endpoint.ts
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join2 } from "node:path";
+function cliRunner(ctx) {
+  return {
+    capture: (args) => aws(ctx, args),
+    mutate: (args) => awsMutate(ctx, args),
+    sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms))
+  };
+}
+function runtimeIdFromArn(arn) {
+  const id = arn.split("/").pop() ?? "";
+  if (id === "")
+    throw new Error(`not an agent runtime arn: ${arn}`);
+  return id;
+}
+async function endpointState(runner, id, name) {
+  let text;
+  try {
+    text = await runner.capture([
+      "bedrock-agentcore-control",
+      "get-agent-runtime-endpoint",
+      "--agent-runtime-id",
+      id,
+      "--endpoint-name",
+      name,
+      "--query",
+      "[status, liveVersion]",
+      "--output",
+      "text"
+    ]);
+  } catch {
+    return;
+  }
+  const [status = "", liveVersion = ""] = text.trim().split(/\s+/);
+  return { status, liveVersion };
+}
+async function waitForEndpoint(runner, opts) {
+  const attempts = opts.attempts ?? 60;
+  const delayMs = opts.delayMs ?? 5000;
+  const log = opts.log ?? ((line) => console.log(line));
+  for (let i = 0;i < attempts; i++) {
+    const state = await endpointState(runner, opts.id, opts.name);
+    if (state !== undefined) {
+      log(`  ${opts.name} endpoint: ${state.status} (version ${state.liveVersion})`);
+      if (state.status === "READY" && state.liveVersion === opts.version)
+        return;
+      if (state.status.endsWith("_FAILED"))
+        throw new Error(`${opts.name} endpoint ${state.status}`);
+    }
+    await runner.sleep(delayMs);
+  }
+  throw new Error(`timed out waiting for the ${opts.name} endpoint to reach version ${opts.version}`);
+}
+async function ensureEndpoint(runner, opts) {
+  const log = opts.log ?? ((line) => console.log(line));
+  const create = [
+    "bedrock-agentcore-control",
+    "create-agent-runtime-endpoint",
+    "--agent-runtime-id",
+    opts.id,
+    "--name",
+    opts.name,
+    "--agent-runtime-version",
+    opts.version
+  ];
+  if (opts.dryRun === true) {
+    await runner.mutate(create);
+    return "created";
+  }
+  const state = await endpointState(runner, opts.id, opts.name);
+  if (state !== undefined) {
+    log(`  ${opts.name} endpoint already exists: ${state.status} (version ${state.liveVersion})`);
+    return "exists";
+  }
+  await runner.mutate(create);
+  await waitForEndpoint(runner, opts);
+  return "created";
+}
+async function promoteEndpoint(runner, opts) {
+  await runner.mutate([
+    "bedrock-agentcore-control",
+    "update-agent-runtime-endpoint",
+    "--agent-runtime-id",
+    opts.id,
+    "--endpoint-name",
+    opts.name,
+    "--agent-runtime-version",
+    opts.version
+  ]);
+  if (opts.dryRun === true)
+    return;
+  await waitForEndpoint(runner, opts);
+}
+async function currentRuntimeVersion(runner, id) {
+  const version = await runner.capture([
+    "bedrock-agentcore-control",
+    "get-agent-runtime",
+    "--agent-runtime-id",
+    id,
+    "--query",
+    "agentRuntimeVersion",
+    "--output",
+    "text"
+  ]);
+  if (version === "" || version === "None")
+    throw new Error(`runtime ${id} reports no version`);
+  return version;
+}
+var SMOKE_EXPECT = ['"authenticated":true', '"config_source":"s3"'];
+function smokeSessionId(prefix) {
+  return `${prefix}-${Math.floor(Date.now() / 1000)}`.padEnd(40, "0");
+}
+async function smokeInvoke(runner, opts) {
+  const log = opts.log ?? ((line) => console.log(line));
+  const payload = opts.payload ?? '{"_smoke_test":true}';
+  const args = [
+    "bedrock-agentcore",
+    "invoke-agent-runtime",
+    "--agent-runtime-arn",
+    opts.arn,
+    ...opts.qualifier === undefined ? [] : ["--qualifier", opts.qualifier],
+    "--runtime-session-id",
+    opts.sessionId,
+    "--payload",
+    Buffer.from(payload).toString("base64")
+  ];
+  if (opts.dryRun === true) {
+    await runner.mutate([...args, "/dev/stdout"]);
+    return;
+  }
+  const dir = await mkdtemp(join2(tmpdir2(), "foundation-smoke-"));
+  const outFile = join2(dir, "response.json");
+  let out;
+  try {
+    const printed = await runner.capture([...args, outFile]);
+    out = await readFile(outFile, "utf8").catch(() => "") || printed;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+  log(`  ${out.replaceAll(`
+`, `
+  `)}`);
+  for (const needle of opts.expect ?? SMOKE_EXPECT)
+    if (!out.includes(needle))
+      throw new Error(`smoke test: response does not contain ${needle}`);
+}
+
+// src/deploy/image.ts
+function imageTag(shortSha, dirty) {
+  const sha = shortSha.trim();
+  if (!/^[0-9a-f]{7,40}$/.test(sha))
+    throw new Error(`not a git short sha: ${JSON.stringify(sha)}`);
+  return dirty ? `${sha}-dirty` : sha;
+}
+function registryOf(repositoryUri) {
+  const host = repositoryUri.split("/")[0];
+  if (host === undefined || !host.includes(".dkr.ecr."))
+    throw new Error(`not an ECR repository URI: ${repositoryUri}`);
+  return host;
+}
+function ciCommitSha(env = process.env) {
+  const sha = env.CODEBUILD_RESOLVED_SOURCE_VERSION ?? env.GITHUB_SHA ?? "";
+  return /^[0-9a-f]{7,40}$/.test(sha) ? sha.slice(0, 7) : null;
+}
+async function currentImageTag(repoRoot) {
+  const ci = ciCommitSha();
+  if (ci !== null)
+    return imageTag(ci, false);
+  const sha = await runCapture(["git", "rev-parse", "--short", "HEAD"], { cwd: repoRoot });
+  const status = await runCapture(["git", "status", "--porcelain"], { cwd: repoRoot });
+  return imageTag(sha, status !== "");
+}
+async function ecrImageExists(ctx, opts) {
+  const args = [
+    "ecr",
+    "describe-images",
+    "--repository-name",
+    opts.repositoryName,
+    "--image-ids",
+    `imageTag=${opts.tag}`,
+    "--output",
+    "text"
+  ];
+  if (ctx.dryRun === true) {
+    console.log(`  $ ${argv(ctx, args).join(" ")}`);
+    return false;
+  }
+  try {
+    await aws(ctx, args);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/deploy/license-cache.ts
+function secretsManagerLicenseCache(ctx) {
+  const secretId = ctx.names.secretLicenseLastVerified;
+  return {
+    async read() {
+      if (ctx.dryRun === true)
+        return;
+      if (!await secretExists(ctx, secretId))
+        return;
+      const text = await readSecretString(ctx, secretId);
+      const value = JSON.parse(text);
+      return typeof value.verifiedAt === "string" ? value : undefined;
+    },
+    async write(value) {
+      const json = JSON.stringify(value);
+      if (ctx.dryRun !== true && !await secretExists(ctx, secretId)) {
+        await createSecretString(ctx, secretId, json, "Last successful Foundation license verification (no key material).");
+        return;
+      }
+      await putSecretString(ctx, secretId, json);
+    }
+  };
+}
+
+// src/deploy/license.ts
+var DEFAULT_LICENSE_ENDPOINT = "https://license.foundry41.com/v1/verify";
+var LICENSE_ENDPOINT_ENV = "FOUNDATION_LICENSE_ENDPOINT";
+var GRACE_DAYS = 30;
+var DAY_MS = 24 * 60 * 60 * 1000;
+function licenseEndpoint(explicit, env = process.env) {
+  return explicit ?? env[LICENSE_ENDPOINT_ENV] ?? DEFAULT_LICENSE_ENDPOINT;
+}
+async function verifyLicense(key, options) {
+  if (key === undefined || key === "")
+    return {
+      outcome: "skipped",
+      message: "no license.key in the instance file — skipping the Foundry 41 license check. Set license.key once your key is issued."
+    };
+  const endpoint = licenseEndpoint(options.endpoint);
+  const now = options.now ?? (() => new Date);
+  const attempts = options.attempts ?? 3;
+  const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+  const fetchImpl = options.fetchImpl ?? fetch;
+  let lastFailure = "";
+  for (let attempt = 1;attempt <= attempts; attempt++) {
+    let response;
+    try {
+      response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          key,
+          instanceId: options.instanceId,
+          version: options.version
+        }),
+        signal: AbortSignal.timeout(options.timeoutMs ?? 1e4)
+      });
+    } catch (error) {
+      lastFailure = error instanceof Error ? error.message : String(error);
+      if (attempt < attempts)
+        await sleep(2 ** (attempt - 1) * 1000);
+      continue;
+    }
+    if (response.status === 402 || response.status === 403)
+      throw new Error(`license refused for instance ${options.instanceId}: ${await failureText(response)}`);
+    if (!response.ok) {
+      lastFailure = `HTTP ${response.status}`;
+      if (attempt < attempts)
+        await sleep(2 ** (attempt - 1) * 1000);
+      continue;
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch (error) {
+      lastFailure = `unreadable response: ${error instanceof Error ? error.message : String(error)}`;
+      if (attempt < attempts)
+        await sleep(2 ** (attempt - 1) * 1000);
+      continue;
+    }
+    if (body.status === "invalid")
+      throw new Error(`license refused for instance ${options.instanceId}: ${body.message ?? "the key is not valid for this instance"}`);
+    if (body.status !== "valid") {
+      lastFailure = `unexpected status "${String(body.status)}"`;
+      if (attempt < attempts)
+        await sleep(2 ** (attempt - 1) * 1000);
+      continue;
+    }
+    const verifiedAt = now().toISOString();
+    await cacheQuietly(options.cache, {
+      verifiedAt,
+      version: options.version,
+      ...body.expiresAt === undefined ? {} : { expiresAt: body.expiresAt }
+    });
+    return {
+      outcome: "verified",
+      message: `license verified for ${options.instanceId}${body.expiresAt === undefined ? "" : ` (expires ${body.expiresAt})`}`,
+      ...body.expiresAt === undefined ? {} : { expiresAt: body.expiresAt }
+    };
+  }
+  return grace(lastFailure, options, now());
+}
+async function grace(failure, options, now) {
+  const cached = await readQuietly(options.cache);
+  if (cached === undefined)
+    throw new Error(`the Foundation license endpoint could not be reached (${failure}) and this instance has no cached verification to fall back on. Retry, or set ${LICENSE_ENDPOINT_ENV} if you use a private endpoint.`);
+  const verifiedAt = Date.parse(cached.verifiedAt);
+  if (Number.isNaN(verifiedAt))
+    throw new Error(`the Foundation license endpoint could not be reached (${failure}) and the cached verification is unreadable (verifiedAt: ${cached.verifiedAt})`);
+  const ageDays = (now.getTime() - verifiedAt) / DAY_MS;
+  if (ageDays > GRACE_DAYS)
+    throw new Error(`the Foundation license endpoint could not be reached (${failure}) and the last verification is ${Math.floor(ageDays)} days old, past the ${GRACE_DAYS}-day grace period`);
+  const remaining = Math.max(0, Math.ceil(GRACE_DAYS - ageDays));
+  return {
+    outcome: "grace",
+    message: `the Foundation license endpoint could not be reached (${failure}); continuing on the verification cached ${Math.floor(ageDays)} days ago — ${remaining} days of grace left`,
+    ...cached.expiresAt === undefined ? {} : { expiresAt: cached.expiresAt }
+  };
+}
+async function cacheQuietly(cache, value) {
+  if (cache === undefined)
+    return;
+  try {
+    await cache.write(value);
+  } catch (error) {
+    console.warn(`  could not cache the license verification: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function readQuietly(cache) {
+  if (cache === undefined)
+    return;
+  try {
+    return await cache.read();
+  } catch {
+    return;
+  }
+}
+async function plannedLicenseCheck(key, options) {
+  return {
+    outcome: "skipped",
+    message: key === undefined || key === "" ? "no license.key in the instance file — nothing to verify" : `dry run — would verify ${options.instanceId} (${options.version}) against ${licenseEndpoint(options.endpoint)}`
+  };
+}
+async function failureText(response) {
+  try {
+    const body = await response.json();
+    return body.message ?? `HTTP ${response.status}`;
+  } catch {
+    return `HTTP ${response.status}`;
+  }
+}
+
+// src/deploy/runtime-secret.ts
+var LIVE_ENDPOINT = "live";
+function composeRuntimeSecret(inputs) {
+  const { instance, slackApp, tableName, bucketName } = inputs;
+  const names = instanceNames(instance);
+  for (const [key, value] of [
+    ["bot_token", slackApp.bot_token],
+    ["bot_user_id", slackApp.bot_user_id],
+    ["table name", tableName],
+    ["bucket name", bucketName]
+  ]) {
+    if (typeof value !== "string" || value === "")
+      throw new Error(`runtime secret: missing ${key}`);
+  }
+  return {
+    FOUNDATION_INSTANCE: instance.name,
+    FOUNDATION_COMMAND_PREFIX: slackCommandPrefix(instance),
+    FOUNDATION_SLACK_BOT_TOKEN: slackApp.bot_token,
+    FOUNDATION_SLACK_BOT_USER_ID: slackApp.bot_user_id,
+    FOUNDATION_GITHUB_APP_SECRET_ID: names.secretGithubApp,
+    FOUNDATION_CODEX_SECRET_ID: names.secretCodex,
+    FOUNDATION_GOOGLE_AI_STUDIO_SECRET_ID: names.secretGoogleAiStudio,
+    FOUNDATION_GOOGLE_DRIVE_SECRET_ID: names.secretGoogleDrive,
+    FOUNDATION_GOOGLE_CALENDAR_SECRET_ID: names.secretGoogleCalendar,
+    FOUNDATION_GOOGLE_OAUTH_SECRET_ID: names.secretGoogleOauth,
+    FOUNDATION_TABLE_NAME: tableName,
+    ...inputs.itemsTableName !== undefined && inputs.itemsTableName !== "" ? { FOUNDATION_ITEMS_TABLE_NAME: inputs.itemsTableName } : {},
+    FOUNDATION_BUCKET_NAME: bucketName,
+    ...inputs.documentsBucketName !== undefined && inputs.documentsBucketName !== "" ? { FOUNDATION_DOCUMENTS_BUCKET_NAME: inputs.documentsBucketName } : {},
+    FOUNDATION_CONFIG_KEY: names.configKey,
+    FOUNDATION_DEFAULT_REPO: inputs.defaultRepo ?? names.defaultRepo,
+    FOUNDATION_GITHUB_ORG: instance.github.org,
+    ...instance.github.workflowWriteRepos !== undefined && instance.github.workflowWriteRepos.length > 0 ? {
+      FOUNDATION_GITHUB_WORKFLOW_WRITE_REPOS: JSON.stringify(instance.github.workflowWriteRepos)
+    } : {},
+    FOUNDATION_RUNTIME_NAME: names.runtimeName,
+    ...instance.github.appSlug !== "TBD" ? { FOUNDATION_GITHUB_APP_SLUG: instance.github.appSlug } : {},
+    ...inputs.webSearchUrl !== undefined && inputs.webSearchUrl !== "" ? { FOUNDATION_WEB_SEARCH_URL: inputs.webSearchUrl } : {},
+    ...inputs.invokeQueueUrl !== undefined && inputs.invokeQueueUrl !== "" ? { FOUNDATION_INVOKE_QUEUE_URL: inputs.invokeQueueUrl } : {},
+    ...inputs.routineSchedulerRoleArn !== undefined && inputs.routineSchedulerRoleArn !== "" ? { FOUNDATION_ROUTINE_SCHEDULER_ROLE_ARN: inputs.routineSchedulerRoleArn } : {},
+    ...inputs.agentRuntimeArn !== undefined && inputs.agentRuntimeArn !== "" ? { FOUNDATION_AGENT_RUNTIME_ARN: inputs.agentRuntimeArn } : {},
+    FOUNDATION_ROUTINE_GROUP: names.routineGroup,
+    FOUNDATION_AGENT_ENDPOINT: inputs.agentEndpoint !== undefined && inputs.agentEndpoint !== "" ? inputs.agentEndpoint : LIVE_ENDPOINT,
+    ...inputs.readOnlyRoleArn !== undefined && inputs.readOnlyRoleArn !== "" ? { FOUNDATION_AWS_READONLY_ROLE_ARN: inputs.readOnlyRoleArn } : {},
+    ...inputs.emailProxyFunctionArn !== undefined && inputs.emailProxyFunctionArn !== "" ? { FOUNDATION_EMAIL_PROXY_FUNCTION_ARN: inputs.emailProxyFunctionArn } : {},
+    ...inputs.browserProxyFunctionArn !== undefined && inputs.browserProxyFunctionArn !== "" ? { FOUNDATION_BROWSER_PROXY_FUNCTION_ARN: inputs.browserProxyFunctionArn } : {},
+    ...inputs.crmProxyFunctionArn !== undefined && inputs.crmProxyFunctionArn !== "" ? { FOUNDATION_CRM_PROXY_FUNCTION_ARN: inputs.crmProxyFunctionArn } : {},
+    ...inputs.crmPolicyFingerprint !== undefined && inputs.crmPolicyFingerprint !== "" ? { FOUNDATION_CRM_POLICY_FINGERPRINT: inputs.crmPolicyFingerprint } : {},
+    ...inputs.otterProxyFunctionArn !== undefined && inputs.otterProxyFunctionArn !== "" ? { FOUNDATION_OTTER_PROXY_FUNCTION_ARN: inputs.otterProxyFunctionArn } : {},
+    ...inputs.knockProxyFunctionArn !== undefined && inputs.knockProxyFunctionArn !== "" ? { FOUNDATION_KNOCK_PROXY_FUNCTION_ARN: inputs.knockProxyFunctionArn } : {},
+    ...inputs.upworkProxyFunctionArn !== undefined && inputs.upworkProxyFunctionArn !== "" ? { FOUNDATION_UPWORK_PROXY_ARN: inputs.upworkProxyFunctionArn } : {},
+    ...inputs.routineIngressFunctionArn !== undefined && inputs.routineIngressFunctionArn !== "" ? { FOUNDATION_ROUTINE_INGRESS_FUNCTION_ARN: inputs.routineIngressFunctionArn } : {},
+    FOUNDATION_MONGODB_SECRET_ID: names.secretMongodbReadonly,
+    FOUNDATION_SLACK_TEAM_ID: slackApp.team_id !== undefined && slackApp.team_id !== "" ? slackApp.team_id : instance.slack.teamId
+  };
+}
+
+// src/deploy/stage-customization.ts
+import {
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, isAbsolute, posix, relative, resolve as resolve2, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+function sourceRootFor(sourceDir) {
+  if (sourceDir === undefined || sourceDir === "")
+    throw new Error("Customization source is missing.");
+  let sourceStats;
+  try {
+    sourceStats = statSync(sourceDir);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      throw new Error("Customization source is missing.");
+    throw error;
+  }
+  if (!sourceStats.isDirectory())
+    throw new Error("Customization source must be a directory.");
+  return realpathSync(sourceDir);
+}
+function isNormalizedRelativePosixPath(path) {
+  return path.length > 0 && !path.includes("\\") && !posix.isAbsolute(path) && posix.normalize(path) === path && path !== "." && path.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+function assertCustomizationPath(path, label = "Customization path") {
+  if (!isNormalizedRelativePosixPath(path))
+    throw new Error(`${label} must be a normalized relative POSIX path.`);
+}
+function isWithin(root, candidate) {
+  const pathFromRoot = relative(root, candidate);
+  return pathFromRoot !== "" && pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`) && !isAbsolute(pathFromRoot);
+}
+function customizationFile(sourceRoot, configuredPath) {
+  assertCustomizationPath(configuredPath);
+  const candidate = resolve2(sourceRoot, ...configuredPath.split("/"));
+  if (!isWithin(sourceRoot, candidate))
+    throw new Error("Customization path escapes its source directory.");
+  return candidate;
+}
+function resolvedCustomizationFile(sourceRoot, configuredPath) {
+  customizationFile(sourceRoot, configuredPath);
+  const parts = configuredPath.split("/");
+  let current = sourceRoot;
+  for (const [index, part] of parts.entries()) {
+    const entry = resolve2(current, part);
+    let entryStats;
+    try {
+      entryStats = lstatSync(entry);
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return;
+      throw error;
+    }
+    current = entryStats.isSymbolicLink() ? realpathSync(entry) : entry;
+    if (current !== sourceRoot && !isWithin(sourceRoot, current))
+      throw new Error("Customization file escapes its source directory.");
+    const last = index === parts.length - 1;
+    const resolvedStats = statSync(current);
+    if (!last && !resolvedStats.isDirectory())
+      throw new Error("Customization path has a non-directory parent.");
+    if (last && !resolvedStats.isFile())
+      throw new Error("Customization path must identify a regular file.");
+  }
+  return current;
+}
+function stagedCustomizationPath(paths) {
+  return resolve2(paths.root, STAGING_DIRECTORY, `${paths.instance.name}.yaml`);
+}
+var STAGING_DIRECTORY = ".foundation-staging";
+function assertUnchanged(path, platform, tenant) {
+  if (!isDeepStrictEqual(platform, tenant))
+    throw new Error(`Customization changes platform-owned authorization or capability policy. Field: ${path}.`);
+}
+function protectedConfig(config) {
+  const { digestHour: _digestHour, ...todos } = config.capabilities.todos;
+  const { defined: _defined, ...routines } = config.capabilities.routines;
+  const { outreach: _outreach, ...crm2 } = config.capabilities.crm;
+  return {
+    ...config,
+    capabilities: {
+      ...config.capabilities,
+      todos,
+      routines,
+      crm: crm2
+    }
+  };
+}
+function assertProtectedPolicy(platform, tenant) {
+  assertUnchanged("config", protectedConfig(platform), protectedConfig(tenant));
+}
+function assertValidTenantRoutines(tenant) {
+  for (const routine of tenant.capabilities.routines.defined) {
+    const parsed = parseSchedule(routine.schedule);
+    if (!parsed.ok)
+      throw new Error(`Invalid defined routine "${routine.id}": ${parsed.reason}`);
+  }
+}
+function migrationFallback(required, log, platformConfigPath) {
+  if (required)
+    throw new Error("Customization file is missing.");
+  log("Customization file is absent; retaining the platform runtime configuration during migration.");
+  return { status: "migration-fallback", runtimeConfigPath: platformConfigPath };
+}
+function stageCustomization(options) {
+  const instance = options.paths.instance;
+  const env = options.env ?? process.env;
+  const platformConfigPath = options.paths.configPath;
+  const stagedPath = stagedCustomizationPath(options.paths);
+  if (options.dryRun !== true)
+    rmSync(stagedPath, { force: true });
+  const customization = instance.customization;
+  if (customization === undefined)
+    return { status: "not-configured", runtimeConfigPath: platformConfigPath };
+  const log = options.log ?? console.log;
+  const sourceDir = env[`CODEBUILD_SRC_DIR_${CUSTOMIZATION_ARTIFACT_NAME}`] ?? (customization.required === false ? env.CODEBUILD_SRC_DIR : undefined);
+  const sourceRoot = sourceRootFor(sourceDir);
+  const sourceFile = resolvedCustomizationFile(sourceRoot, customization.path);
+  if (sourceFile === undefined)
+    return migrationFallback(customization.required, log, platformConfigPath);
+  const yaml = readFileSync2(sourceFile);
+  const tenantConfig = parseInstanceConfig(yaml.toString("utf8"));
+  const platformConfig = parseInstanceConfig(readFileSync2(platformConfigPath, "utf8"));
+  if (tenantConfig.name !== instance.displayName)
+    throw new Error("Customization config name must match the selected instance.");
+  assertValidTenantRoutines(tenantConfig);
+  assertProtectedPolicy(platformConfig, tenantConfig);
+  if (options.dryRun !== true) {
+    mkdirSync2(dirname(stagedPath), { recursive: true });
+    writeFileSync(stagedPath, yaml);
+  }
+  return {
+    status: "staged",
+    runtimeConfigPath: options.dryRun === true ? sourceFile : stagedPath
+  };
+}
+
+// src/deploy/deploy.ts
+function buildxCacheFlags(mode, scope) {
+  if (mode === "gha")
+    return [
+      "--cache-from",
+      `type=gha,scope=${scope}`,
+      "--cache-to",
+      `type=gha,scope=${scope},mode=max`
+    ];
+  if (mode === "local")
+    return [];
+  return;
+}
+async function buildAndPushImage(ctx, opts) {
+  const foundationRoot = opts.foundationRoot ?? FOUNDATION_ROOT;
+  const repositoryUri = opts.repositoryUri ?? await stackOutput(ctx, ctx.names.agent, "RepositoryUri");
+  const registry = registryOf(repositoryUri);
+  const image = `${repositoryUri}:${opts.tag}`;
+  const exists = await (opts.imageExists ?? ecrImageExists)(ctx, {
+    repositoryName: ctx.names.ecrRepo,
+    tag: opts.tag
+  });
+  if (exists) {
+    console.log(`  image_tag_exists ${image} — skipping the build and push`);
+    return image;
+  }
+  const password = ctx.dryRun === true ? "<ecr-token>" : await aws(ctx, ["ecr", "get-login-password"]);
+  await run(["docker", "login", "--username", "AWS", "--password-stdin", registry], {
+    stdin: password,
+    dryRun: ctx.dryRun
+  });
+  const { app_id } = ctx.dryRun === true ? { app_id: `<${ctx.names.secretGithubApp}.app_id>` } : await readSecretJson(ctx, ctx.names.secretGithubApp);
+  const cacheMode = process.env.FOUNDATION_IMAGE_CACHE ?? "";
+  const buildArgs = [
+    "--platform",
+    "linux/arm64",
+    "--build-arg",
+    `FOUNDATION_GITHUB_APP_ID=${app_id}`,
+    "-f",
+    AGENT_DOCKERFILE,
+    "-t",
+    image
+  ];
+  const cacheFlags = buildxCacheFlags(cacheMode, ctx.names.ecrRepo);
+  if (cacheFlags !== undefined) {
+    await run(["docker", "buildx", "build", ...buildArgs, ...cacheFlags, "--push", "."], {
+      cwd: foundationRoot,
+      dryRun: ctx.dryRun
+    });
+  } else {
+    await run(["docker", "build", ...buildArgs, "."], {
+      cwd: foundationRoot,
+      dryRun: ctx.dryRun
+    });
+    await run(["docker", "push", image], { dryRun: ctx.dryRun });
+  }
+  return image;
+}
+function alarmEmailFor(ctx, explicit) {
+  return explicit ?? process.env.FOUNDATION_ALARM_EMAIL ?? ctx.instance.aws.alarmEmail ?? "";
+}
+function cdkCommand() {
+  try {
+    return [process.execPath, createRequire(import.meta.url).resolve("aws-cdk/bin/cdk")];
+  } catch {
+    return ["bunx", "cdk"];
+  }
+}
+function cdkAppCommand(infraRoot = INFRA_ROOT) {
+  const source = join3(infraRoot, "bin", "app.ts");
+  if (existsSync2(source))
+    return `bun run ${source}`;
+  return `${process.execPath} ${join3(infraRoot, "dist", "bin", "app.js")}`;
+}
+async function cdkDeploy(ctx, opts) {
+  const context = [
+    "-c",
+    `instanceFile=${ctx.paths.path}`,
+    "-c",
+    `admins=${opts.admins}`,
+    ...opts.alarmEmail === "" ? [] : ["-c", `alarmEmail=${opts.alarmEmail}`],
+    ...opts.phase1 === true ? ["-c", "deployRuntime=false"] : [],
+    ...opts.tag === undefined || opts.release !== undefined ? [] : ["-c", `agentImageTag=${opts.tag}`],
+    ...opts.release === undefined ? [] : releaseContext(opts.release)
+  ];
+  await run([
+    ...cdkCommand(),
+    "deploy",
+    "--all",
+    "--app",
+    cdkAppCommand(),
+    "--require-approval",
+    "never",
+    ...context
+  ], {
+    cwd: INFRA_ROOT,
+    env: cdkEnv(ctx),
+    dryRun: ctx.dryRun
+  });
+}
+async function optionalOutput(ctx, stack, key) {
+  try {
+    return await stackOutput(ctx, stack, key);
+  } catch {
+    return;
+  }
+}
+async function syncKnockOAuthClient(ctx, options = {}) {
+  if (!ctx.instance.integrations.knock)
+    return "skipped";
+  const redirectUri = options.redirectUri ?? (ctx.dryRun === true ? `<${ctx.names.api}.KnockOAuthRedirectUrl>` : await stackOutput(ctx, ctx.names.api, "KnockOAuthRedirectUrl"));
+  if (ctx.dryRun === true) {
+    await putSecretJson(ctx, ctx.names.secretKnockOauthClient, {
+      client_id: "<knock-dynamic-client-id>",
+      redirect_uri: redirectUri
+    });
+    return "registered";
+  }
+  try {
+    const existing = parseKnockOAuthClient(JSON.stringify(await readSecretJson(ctx, ctx.names.secretKnockOauthClient)));
+    if (existing.redirect_uri === redirectUri)
+      return "unchanged";
+  } catch {}
+  const client = await registerKnockPublicClient({
+    redirectUri,
+    ...options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }
+  });
+  await putSecretJson(ctx, ctx.names.secretKnockOauthClient, {
+    client_id: client.client_id,
+    redirect_uri: client.redirect_uri
+  });
+  return "registered";
+}
+async function syncRuntimeSecret(ctx) {
+  const dry = ctx.dryRun === true;
+  const { data, agent, api, secretSlackApp, secretRuntime } = ctx.names;
+  const tableName = dry ? `<${data}.TableName>` : await stackOutput(ctx, data, "TableName");
+  const bucketName = dry ? `<${data}.BucketName>` : await stackOutput(ctx, data, "BucketName");
+  const documentsBucketName = dry ? `<${data}.DocumentsBucketName>` : await optionalOutput(ctx, data, "DocumentsBucketName");
+  const itemsTableName = dry ? `<${data}.ItemsTableName>` : await optionalOutput(ctx, data, "ItemsTableName");
+  const webSearchUrl = dry ? `<${agent}.WebSearchGatewayUrl>` : await optionalOutput(ctx, agent, "WebSearchGatewayUrl");
+  const invokeQueueUrl = dry ? `<${api}.InvokeQueueUrl>` : await optionalOutput(ctx, api, "InvokeQueueUrl");
+  const routineSchedulerRoleArn = dry ? `<${api}.RoutineSchedulerRoleArn>` : await optionalOutput(ctx, api, "RoutineSchedulerRoleArn");
+  const agentRuntimeArn = dry ? `<${agent}.AgentRuntimeArn>` : await optionalOutput(ctx, agent, "AgentRuntimeArn");
+  const readOnlyRoleArn = dry ? `<${agent}.ReadOnlyRoleArn>` : await optionalOutput(ctx, agent, "ReadOnlyRoleArn");
+  const emailProxyFunctionArn = dry ? `<${api}.EmailProxyFunctionArn>` : await optionalOutput(ctx, api, "EmailProxyFunctionArn");
+  const browserProxyFunctionArn = dry ? `<${api}.BrowserProxyFunctionArn>` : await optionalOutput(ctx, api, "BrowserProxyFunctionArn");
+  const crmProxyFunctionArn = ctx.instance.integrations.crm ? dry ? `<${api}.CrmProxyFunctionArn>` : await optionalOutput(ctx, api, "CrmProxyFunctionArn") : undefined;
+  const crmPolicyFingerprint = ctx.instance.integrations.crm ? dry ? `<${api}.CrmPolicyFingerprint>` : await optionalOutput(ctx, api, "CrmPolicyFingerprint") : undefined;
+  const otterProxyFunctionArn = dry ? `<${api}.OtterProxyFunctionArn>` : await optionalOutput(ctx, api, "OtterProxyFunctionArn");
+  const knockProxyFunctionArn = ctx.instance.integrations.knock ? dry ? `<${api}.KnockProxyFunctionArn>` : await optionalOutput(ctx, api, "KnockProxyFunctionArn") : undefined;
+  const upworkProxyFunctionArn = ctx.instance.integrations.upwork ? dry ? `<${api}.UpworkProxyFunctionArn>` : await optionalOutput(ctx, api, "UpworkProxyFunctionArn") : undefined;
+  const routineIngressFunctionArn = dry ? `<${api}.RoutineIngressFunctionArn>` : await optionalOutput(ctx, api, "RoutineIngressFunctionArn");
+  const slackApp = dry ? {
+    bot_token: `<${secretSlackApp}.bot_token>`,
+    bot_user_id: `<${secretSlackApp}.bot_user_id>`
+  } : await readSecretJson(ctx, secretSlackApp);
+  const value = composeRuntimeSecret({
+    instance: ctx.instance,
+    slackApp,
+    tableName,
+    bucketName,
+    documentsBucketName,
+    ...itemsTableName === undefined ? {} : { itemsTableName },
+    ...webSearchUrl === undefined ? {} : { webSearchUrl },
+    ...invokeQueueUrl === undefined ? {} : { invokeQueueUrl },
+    ...routineSchedulerRoleArn === undefined ? {} : { routineSchedulerRoleArn },
+    ...agentRuntimeArn === undefined ? {} : { agentRuntimeArn },
+    ...readOnlyRoleArn === undefined ? {} : { readOnlyRoleArn },
+    ...emailProxyFunctionArn === undefined ? {} : { emailProxyFunctionArn },
+    ...browserProxyFunctionArn === undefined ? {} : { browserProxyFunctionArn },
+    ...crmProxyFunctionArn === undefined ? {} : { crmProxyFunctionArn },
+    ...crmPolicyFingerprint === undefined ? {} : { crmPolicyFingerprint },
+    ...otterProxyFunctionArn === undefined ? {} : { otterProxyFunctionArn },
+    ...knockProxyFunctionArn === undefined ? {} : { knockProxyFunctionArn },
+    ...upworkProxyFunctionArn === undefined ? {} : { upworkProxyFunctionArn },
+    ...routineIngressFunctionArn === undefined ? {} : { routineIngressFunctionArn }
+  });
+  await putSecretJson(ctx, secretRuntime, value);
+  return Object.keys(value);
+}
+async function promoteLive(ctx) {
+  const dry = ctx.dryRun === true;
+  const runner = cliRunner(ctx);
+  const arn = dry ? `<${ctx.names.agent}.AgentRuntimeArn>` : await stackOutput(ctx, ctx.names.agent, "AgentRuntimeArn");
+  const id = dry ? `<${ctx.names.agent}.runtimeId>` : runtimeIdFromArn(arn);
+  const version = dry ? "<version>" : await currentRuntimeVersion(runner, id);
+  await smokeInvoke(runner, {
+    arn,
+    qualifier: "DEFAULT",
+    sessionId: smokeSessionId("deploy-smoke"),
+    dryRun: ctx.dryRun
+  });
+  await promoteEndpoint(runner, { id, name: "live", version, dryRun: ctx.dryRun });
+  await smokeInvoke(runner, {
+    arn,
+    qualifier: "live",
+    sessionId: smokeSessionId("deploy-live"),
+    dryRun: ctx.dryRun
+  });
+}
+async function resolveReleaseFor(ctx, opts) {
+  if (opts.release === undefined)
+    return;
+  return (opts.resolveRelease ?? resolveRelease)(ctx, opts.release);
+}
+async function checkLicense(ctx, opts, release) {
+  const verify = opts.verifyLicense ?? (ctx.dryRun === true ? plannedLicenseCheck : verifyLicense);
+  const result = await verify(ctx.instance.license?.key, {
+    instanceId: ctx.instance.name,
+    version: release?.version ?? `v${toolVersion()}`,
+    cache: secretsManagerLicenseCache(ctx)
+  });
+  console.log(`▶ license: ${result.message}`);
+}
+function promotesInline(env = process.env) {
+  return env.GITHUB_ACTIONS !== "true" && env.FOUNDATION_SKIP_POST_DEPLOY !== "1";
+}
+async function deploy(ctx, opts) {
+  const release = await resolveReleaseFor(ctx, opts);
+  if (release !== undefined)
+    console.log(`▶ release ${release.version}${release.manifest === undefined ? " (dry run: not verified)" : " verified"} — ${release.manifestPath}`);
+  await checkLicense(ctx, opts, release);
+  const customization = stageCustomization({ paths: ctx.paths, dryRun: ctx.dryRun });
+  if (customization.status === "staged")
+    console.log("▶ staged reviewed runtime customization");
+  const admins = adminsCsvFromFile(ctx.paths.configPath);
+  const alarmEmail = alarmEmailFor(ctx, opts.alarmEmail);
+  const phase1 = opts.phase1 === true;
+  const tag = phase1 || release !== undefined ? undefined : opts.tag ?? await currentImageTag(FOUNDATION_ROOT);
+  if (!phase1 && release === undefined && opts.skipImage !== true && tag !== undefined) {
+    console.log(`▶ build + push agent image (${tag})`);
+    console.log(`  ${await buildAndPushImage(ctx, { tag })}`);
+  }
+  console.log(`▶ cdk deploy --all${phase1 ? " (phase 1: no runtime)" : release !== undefined ? ` (release ${release.version})` : ` (image ${tag})`}`);
+  await cdkDeploy(ctx, {
+    admins,
+    alarmEmail,
+    tag,
+    phase1,
+    ...release === undefined ? {} : { release }
+  });
+  if (ctx.instance.integrations.knock) {
+    console.log(`▶ Knock OAuth public-client registration (${ctx.names.secretKnockOauthClient})`);
+    console.log(`  ${await syncKnockOAuthClient(ctx)}`);
+  }
+  console.log(`▶ runtime secret refresh (${ctx.names.secretRuntime})`);
+  console.log(`  keys: ${(await syncRuntimeSecret(ctx)).join(", ")}`);
+  console.log("▶ config sync");
+  const bucket = await configSync(ctx, {
+    runtimeConfigPath: customization.runtimeConfigPath,
+    ...release === undefined ? {} : { release }
+  });
+  console.log(`config + skills synced to s3://${bucket}/`);
+  if (!phase1 && promotesInline()) {
+    console.log("▶ smoke test, then promote the `live` endpoint");
+    await promoteLive(ctx);
+  }
+}
+
+// src/deploy/github-app-manifest.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { join as join4 } from "node:path";
+import { parse as parseYaml } from "yaml";
+var GITHUB_APP_MANIFEST_PATH = join4(PACKAGE_ASSETS, "github-app-manifest.yml");
+function manifestUrl(instance) {
+  const repo = instance.github.defaultRepo ?? instanceNames(instance).defaultRepo;
+  return `https://github.com/${repo === "" ? instance.github.org : repo}`;
+}
+function renderAppManifest(template, instance) {
+  const values = {
+    displayName: instance.displayName,
+    url: manifestUrl(instance)
+  };
+  return template.replace(/\$\{(\w+)\}/g, (match, key) => {
+    const value = values[key];
+    if (value === undefined)
+      throw new Error(`app-manifest.yml: unknown placeholder ${match}`);
+    return value;
+  });
+}
+function loadAppManifest(instance, template) {
+  const text = template ?? readFileSync3(GITHUB_APP_MANIFEST_PATH, "utf8");
+  const manifest = parseYaml(renderAppManifest(text, instance));
+  if ("default_permissions" in manifest)
+    throw new Error("app-manifest.yml: default_permissions are generated from the capability registry; remove them from the template");
+  manifest.default_permissions = requiredGithubPermissions(["github"], {
+    workflowWrites: (instance.github.workflowWriteRepos?.length ?? 0) > 0
+  });
+  return manifest;
+}
+
+// src/deploy/github-app-create.ts
+async function githubAppCreate(options) {
+  const instance = options.paths.instance;
+  const names = instanceNames(instance);
+  const org = options.org ?? instance.github.org;
+  const port = options.port ?? 8765;
+  const secretName = options.secret ?? names.secretGithubApp;
+  const profile = options.profile ?? instance.aws.profile;
+  const region = options.region ?? instance.aws.region;
+  const manifest = loadAppManifest(instance);
+  if (options.dryRun === true) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return;
+  }
+  const redirectUrl = `http://localhost:${port}/callback`;
+  const state = crypto.randomUUID();
+  const body = JSON.stringify({ ...manifest, redirect_url: redirectUrl });
+  async function writeSecret(value) {
+    const run2 = async (cmd) => {
+      const p = Bun.spawn(["aws", ...cmd, "--profile", profile, "--region", region], {
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      p.stdin.write(value);
+      p.stdin.end();
+      const code = await p.exited;
+      return { code, err: await new Response(p.stderr).text() };
+    };
+    let r = await run2([
+      "secretsmanager",
+      "create-secret",
+      "--name",
+      secretName,
+      "--description",
+      `${instance.displayName} GitHub App: app_id, installation_id, private_key`,
+      "--secret-string",
+      "file:///dev/stdin"
+    ]);
+    if (r.code !== 0 && r.err.includes("ResourceExistsException"))
+      r = await run2([
+        "secretsmanager",
+        "put-secret-value",
+        "--secret-id",
+        secretName,
+        "--secret-string",
+        "file:///dev/stdin"
+      ]);
+    if (r.code !== 0)
+      throw new Error(`aws secretsmanager failed: ${r.err.trim()}`);
+  }
+  const server = Bun.serve({
+    port,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === "/") {
+        const html = `<!doctype html><title>Create ${instance.displayName} GitHub App</title><body style="font-family:system-ui;padding:2rem">
+<h2>Creating the <b>${instance.displayName}</b> GitHub App on <b>${org}</b>…</h2><p>If nothing happens, click the button.</p>
+<form id="f" method="post" action="https://github.com/organizations/${org}/settings/apps/new?state=${state}">
+<input type="hidden" name="manifest" id="m"><button>Create GitHub App</button></form>
+<script>document.getElementById('m').value=${JSON.stringify(body)};document.getElementById('f').submit();</script></body>`;
+        return new Response(html, { headers: { "content-type": "text/html" } });
+      }
+      if (url.pathname === "/callback") {
+        const code = url.searchParams.get("code");
+        if (url.searchParams.get("state") !== state || code === null)
+          return new Response("bad state/code", { status: 400 });
+        const res = await fetch(`https://api.github.com/app-manifests/${encodeURIComponent(code)}/conversions`, {
+          method: "POST",
+          headers: {
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28"
+          }
+        });
+        if (!res.ok)
+          return new Response(`conversion failed: HTTP ${res.status}`, { status: 502 });
+        const app = await res.json();
+        await writeSecret(JSON.stringify({ app_id: String(app.id), installation_id: "", private_key: app.pem }));
+        const installUrl = `https://github.com/apps/${app.slug}/installations/new`;
+        console.log(JSON.stringify({
+          app_id: app.id,
+          slug: app.slug,
+          html_url: app.html_url,
+          install_url: installUrl,
+          secret: secretName
+        }));
+        setTimeout(() => {
+          server.stop(true);
+          process.exit(0);
+        }, 500);
+        return new Response(`<!doctype html><body style="font-family:system-ui;padding:2rem"><h2>✅ App "${app.slug}" created (id ${app.id}); private key stored in Secrets Manager ${secretName}.</h2><p>Next: <a href="${installUrl}">install it on your repos</a>.</p></body>`, { headers: { "content-type": "text/html" } });
+      }
+      return new Response("not found", { status: 404 });
+    }
+  });
+  console.log(`Open http://localhost:${port}/ to create the app (waiting up to 10 minutes)…`);
+  setTimeout(() => {
+    console.error("timed out");
+    process.exit(1);
+  }, 10 * 60000);
+}
+
+// src/deploy/post-deploy.ts
+var LIVE = "live";
+var FS_PROBE_PAYLOAD = '{"_fs_probe":true}';
+var FS_PROBE_EXPECT = ['"writable":true'];
+async function postDeploy(ctx, opts = {}) {
+  const dry = ctx.dryRun === true;
+  const log = opts.log ?? ((line) => console.log(line));
+  const runner = opts.runner ?? cliRunner(ctx);
+  const arn = opts.arn ?? (dry ? `<${ctx.names.agent}.AgentRuntimeArn>` : await stackOutput(ctx, ctx.names.agent, "AgentRuntimeArn"));
+  const id = dry && opts.arn === undefined ? `<${ctx.names.agent}.runtimeId>` : runtimeIdFromArn(arn);
+  const version = dry ? "<version>" : await currentRuntimeVersion(runner, id);
+  log(`deployed runtime version ${version}`);
+  log("▶ smoke test — authenticated (new version)");
+  await smokeInvoke(runner, {
+    arn,
+    qualifier: "DEFAULT",
+    sessionId: smokeSessionId("ci-smoke"),
+    dryRun: ctx.dryRun,
+    log
+  });
+  log("▶ smoke test — persistent mount writable (new version)");
+  await smokeInvoke(runner, {
+    arn,
+    qualifier: "DEFAULT",
+    sessionId: smokeSessionId("ci-probe"),
+    payload: FS_PROBE_PAYLOAD,
+    expect: FS_PROBE_EXPECT,
+    dryRun: ctx.dryRun,
+    log
+  });
+  log(`▶ promote version ${version} to the ${LIVE} endpoint`);
+  await promoteEndpoint(runner, { id, name: LIVE, version, dryRun: ctx.dryRun, log });
+  log(`▶ smoke test — ${LIVE} endpoint answers`);
+  await smokeInvoke(runner, {
+    arn,
+    qualifier: LIVE,
+    sessionId: smokeSessionId("ci-live"),
+    expect: ['"authenticated":true'],
+    dryRun: ctx.dryRun,
+    log
+  });
+}
+
+// src/deploy/setup.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { resolve as resolve3 } from "node:path";
+
+// src/deploy/slack-manifest.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+import { join as join5 } from "node:path";
+import { parse as parse2 } from "yaml";
+var SLACK_APP_MANIFEST_PATH = join5(PACKAGE_ASSETS, "slack-app-manifest.yml");
+function buildSlackManifest(template, instance, env) {
+  const events = env.EVENTS_REQUEST_URL;
+  const commands = env.COMMANDS_REQUEST_URL ?? events?.replace(/\/events$/, "/commands");
+  const interactive = env.INTERACTIVE_REQUEST_URL ?? events?.replace(/\/events$/, "/interactive");
+  const manifest = parse2(template.replaceAll("${DISPLAY_NAME}", instance.displayName).replaceAll("${BOT_NAME}", instance.displayName.toLowerCase()).replaceAll("${COMMAND_PREFIX}", instance.commandPrefix).replaceAll("${EVENTS_REQUEST_URL}", events ?? "").replaceAll("${COMMANDS_REQUEST_URL}", commands ?? "").replaceAll("${INTERACTIVE_REQUEST_URL}", interactive ?? ""));
+  if (manifest.oauth_config?.scopes?.bot !== undefined)
+    throw new Error("app-manifest.yml: bot scopes are generated from the Foundation capability registry; remove them from the template");
+  manifest.oauth_config = { scopes: { bot: requiredSlackScopes(CAPABILITY_IDS) } };
+  const declared = new Set((manifest.features.slash_commands ?? []).map((c) => c.command));
+  for (const command of requiredSlackCommands(CAPABILITY_IDS, instance.commandPrefix))
+    if (!declared.has(command))
+      throw new Error(`app-manifest.yml: missing slash command ${command} required by a capability`);
+  if (events === undefined) {
+    manifest.settings.event_subscriptions = undefined;
+  } else {
+    manifest.settings.event_subscriptions = {
+      request_url: events,
+      bot_events: [...BASE_SLACK_EVENTS]
+    };
+  }
+  if (commands === undefined || commands === "")
+    manifest.features.slash_commands = undefined;
+  if (interactive === undefined || interactive === "")
+    manifest.settings.interactivity = undefined;
+  return manifest;
+}
+function slackManifestFor(instance, env) {
+  return buildSlackManifest(readFileSync4(SLACK_APP_MANIFEST_PATH, "utf8"), { displayName: instance.displayName, commandPrefix: slackCommandPrefix(instance) }, env);
+}
+
+// src/deploy/tracing.ts
+function cliTracingRunner(ctx) {
+  return {
+    capture: (args) => aws(ctx, args),
+    mutate: (args) => awsMutate(ctx, args)
+  };
+}
+var CLOUDWATCH_LOGS_DESTINATION = "CloudWatchLogs";
+var DEFAULT_INDEXING_RULE = "Default";
+var DEFAULT_SAMPLING_PERCENTAGE = 100;
+var SPANS_INGESTION_POLICY_NAME = "FoundationSpansIngestion";
+function spansIngestionPolicy(account, region) {
+  const statement = (sid, group) => ({
+    Sid: sid,
+    Effect: "Allow",
+    Principal: { Service: "xray.amazonaws.com" },
+    Action: ["logs:PutLogEvents", "logs:CreateLogStream"],
+    Resource: group.endsWith("*") ? `arn:aws:logs:${region}:${account}:log-group:${group}` : `arn:aws:logs:${region}:${account}:log-group:${group}:*`,
+    Condition: {
+      StringEquals: { "aws:SourceAccount": account },
+      ArnLike: { "aws:SourceArn": `arn:aws:xray:${region}:${account}:*` }
+    }
+  });
+  return JSON.stringify({
+    Version: "2012-10-17",
+    Statement: [
+      statement("SpansFromXray", "aws/spans"),
+      statement("ApplicationSignalsFromXray", "/aws/application-signals/data"),
+      statement("AgentCoreRuntimeSpansFromXray", "/aws/bedrock-agentcore/runtimes/*")
+    ]
+  });
+}
+function hasSpansIngestionPolicy(describeOutput) {
+  let policies;
+  try {
+    policies = JSON.parse(describeOutput).resourcePolicies;
+  } catch {
+    return false;
+  }
+  if (!Array.isArray(policies))
+    return false;
+  return policies.some((p) => {
+    const doc = String(p.policyDocument ?? "");
+    return doc.includes("aws/spans") && doc.includes("logs:CreateLogStream") && doc.includes("/aws/bedrock-agentcore/runtimes/");
+  });
+}
+function parseDestination(text) {
+  try {
+    return String(JSON.parse(text).Destination ?? "");
+  } catch {
+    return "";
+  }
+}
+function parseSamplingPercentage(text, ruleName) {
+  let rules;
+  try {
+    rules = JSON.parse(text).IndexingRules;
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(rules))
+    return null;
+  for (const rule of rules) {
+    if (rule.Name !== ruleName)
+      continue;
+    const percentage = rule.Rule?.Probabilistic?.DesiredSamplingPercentage;
+    return typeof percentage === "number" ? percentage : null;
+  }
+  return null;
+}
+async function ensureTransactionSearch(runner, options = {}) {
+  const percentage = options.samplingPercentage ?? DEFAULT_SAMPLING_PERCENTAGE;
+  const rule = JSON.stringify({ Probabilistic: { DesiredSamplingPercentage: percentage } });
+  if (options.dryRun === true) {
+    if (options.account !== undefined && options.region !== undefined) {
+      await runner.mutate([
+        "logs",
+        "put-resource-policy",
+        "--policy-name",
+        SPANS_INGESTION_POLICY_NAME,
+        "--policy-document",
+        spansIngestionPolicy(options.account, options.region)
+      ]);
+    }
+    await runner.mutate([
+      "xray",
+      "update-trace-segment-destination",
+      "--destination",
+      CLOUDWATCH_LOGS_DESTINATION
+    ]);
+    await runner.mutate([
+      "xray",
+      "update-indexing-rule",
+      "--name",
+      DEFAULT_INDEXING_RULE,
+      "--rule",
+      rule
+    ]);
+    return { destination: "updated", indexing: "updated", ingestionPolicy: "updated" };
+  }
+  let ingestionPolicy = "already-set";
+  if (options.account !== undefined && options.region !== undefined) {
+    if (!hasSpansIngestionPolicy(await runner.capture(["logs", "describe-resource-policies"]))) {
+      await runner.mutate([
+        "logs",
+        "put-resource-policy",
+        "--policy-name",
+        SPANS_INGESTION_POLICY_NAME,
+        "--policy-document",
+        spansIngestionPolicy(options.account, options.region)
+      ]);
+      ingestionPolicy = "updated";
+    }
+  }
+  let destination = "already-set";
+  if (parseDestination(await runner.capture(["xray", "get-trace-segment-destination"])) !== CLOUDWATCH_LOGS_DESTINATION) {
+    await runner.mutate([
+      "xray",
+      "update-trace-segment-destination",
+      "--destination",
+      CLOUDWATCH_LOGS_DESTINATION
+    ]);
+    destination = "updated";
+  }
+  let indexing = "already-set";
+  const current = parseSamplingPercentage(await runner.capture(["xray", "get-indexing-rules"]), DEFAULT_INDEXING_RULE);
+  if (current !== percentage) {
+    await runner.mutate([
+      "xray",
+      "update-indexing-rule",
+      "--name",
+      DEFAULT_INDEXING_RULE,
+      "--rule",
+      rule
+    ]);
+    indexing = "updated";
+  }
+  return { destination, indexing, ingestionPolicy };
+}
+
+// src/deploy/setup.ts
+function defaultCodexFile(instanceRoot) {
+  return resolve3(instanceRoot, ".foundation-local", "codex.json");
+}
+function step(n, title) {
+  console.log(`
+▶ ${n}. ${title}`);
+}
+async function syncSetupKnockOAuth(ctx, sync = syncKnockOAuthClient) {
+  return sync(ctx);
+}
+function placeholder(ctx, stack, key) {
+  if (key === "RepositoryUri")
+    return `${ctx.instance.aws.account}.dkr.ecr.${ctx.region}.amazonaws.com/${ctx.names.ecrRepo}`;
+  return `<${stack}.${key}>`;
+}
+async function output(ctx, stack, key) {
+  if (ctx.dryRun !== true)
+    return stackOutput(ctx, stack, key);
+  try {
+    return await stackOutput(ctx, stack, key);
+  } catch {
+    return placeholder(ctx, stack, key);
+  }
+}
+async function installDependencies(ctx) {
+  await run(["bun", "install", "--frozen-lockfile"], {
+    cwd: FOUNDATION_ROOT,
+    dryRun: ctx.dryRun
+  });
+}
+async function preflight(ctx) {
+  await installDependencies(ctx);
+  const expected = ctx.instance.aws.account;
+  const account = await callerAccountId(ctx);
+  if (account !== expected)
+    throw new Error(`profile ${ctx.profile} is account ${account}, expected ${expected} for instance ${ctx.instance.name}`);
+  console.log(`  account ${account} via profile ${ctx.profile} (${ctx.region})`);
+  if (ctx.dryRun === true) {
+    await run(["docker", "info"], { dryRun: true });
+  } else {
+    const docker = Bun.spawn(["docker", "info"], { stdout: "ignore", stderr: "ignore" });
+    if (await docker.exited !== 0)
+      throw new Error("docker is not running");
+    console.log("  docker ✓");
+  }
+  for (const id of [
+    ctx.names.secretSlackSigning,
+    ctx.names.secretSlackApp,
+    ctx.names.secretGithubApp
+  ]) {
+    if (!await secretExists(ctx, id))
+      throw new Error(`secret ${id} is missing — create it before running setup`);
+    console.log(`  secret ${id} ✓`);
+  }
+}
+async function bootstrap(ctx) {
+  if (ctx.dryRun !== true && await stackExists(ctx, "CDKToolkit")) {
+    console.log("  CDKToolkit already present — skipping bootstrap");
+    return;
+  }
+  await run([...cdkCommand(), "bootstrap", `aws://${ctx.instance.aws.account}/${ctx.region}`], {
+    cwd: INFRA_ROOT,
+    env: { AWS_PROFILE: ctx.profile, AWS_REGION: ctx.region, CDK_DEFAULT_REGION: ctx.region },
+    dryRun: ctx.dryRun
+  });
+}
+async function writeRuntimeSecret(ctx) {
+  console.log(`  keys: ${(await syncRuntimeSecret(ctx)).join(", ")}`);
+}
+async function seedCodex(ctx, codexFile) {
+  if (!existsSync3(codexFile))
+    throw new Error(`${codexFile} not found — sign in locally first, or pass --codex-file`);
+  const document = await Bun.file(codexFile).text();
+  JSON.parse(document);
+  await putSecretString(ctx, ctx.names.secretCodex, document);
+  console.log(`  ${ctx.names.secretCodex} seeded from ${codexFile}`);
+}
+async function reportSlackManifest(ctx) {
+  const { appId, teamId } = ctx.instance.slack;
+  const manifest = slackManifestFor(ctx.instance, {
+    EVENTS_REQUEST_URL: await output(ctx, ctx.names.api, "EventsUrl"),
+    COMMANDS_REQUEST_URL: await output(ctx, ctx.names.api, "CommandsUrl"),
+    INTERACTIVE_REQUEST_URL: await output(ctx, ctx.names.api, "InteractiveUrl")
+  });
+  console.log(`  manifest: ${JSON.stringify(manifest)}`);
+  console.log([
+    "  apply it from the instance repository, whose .slack/hooks.json runs",
+    "  `foundation-deploy slack-manifest --instance <path>`:",
+    `    slack manifest diff --app ${appId} --team ${teamId}`,
+    `    slack app install --app ${appId} --team ${teamId} --force`,
+    "  if scopes changed, re-approve in Slack when prompted"
+  ].join(`
+`));
+}
+async function smokeTest(ctx) {
+  const arn = await output(ctx, ctx.names.agent, "AgentRuntimeArn");
+  await smokeInvoke(cliRunner(ctx), {
+    arn,
+    sessionId: smokeSessionId("smoke"),
+    dryRun: ctx.dryRun
+  });
+}
+async function ensureLiveEndpoint(ctx) {
+  const runner = cliRunner(ctx);
+  const arn = await output(ctx, ctx.names.agent, "AgentRuntimeArn");
+  const id = ctx.dryRun === true ? `<${ctx.names.agent}.runtimeId>` : runtimeIdFromArn(arn);
+  const version = ctx.dryRun === true ? "<version>" : await currentRuntimeVersion(runner, id);
+  await ensureEndpoint(runner, { id, name: "live", version, dryRun: ctx.dryRun });
+}
+async function enableTransactionSearch(ctx) {
+  const result = await ensureTransactionSearch(cliTracingRunner(ctx), {
+    account: ctx.instance.aws.account,
+    region: ctx.region,
+    ...ctx.dryRun === true ? { dryRun: true } : {}
+  });
+  console.log(`  ingestion policy: ${result.ingestionPolicy}; destination: ${result.destination}; indexing rule: ${result.indexing}`);
+}
+async function connectionStatus(ctx, arn) {
+  try {
+    return await aws(ctx, [
+      "codeconnections",
+      "get-connection",
+      "--connection-arn",
+      arn,
+      "--query",
+      "Connection.ConnectionStatus",
+      "--output",
+      "text"
+    ]);
+  } catch {
+    return "UNKNOWN";
+  }
+}
+function connectionConsoleUrl(region) {
+  return `https://${region}.console.aws.amazon.com/codesuite/settings/connections?region=${region}`;
+}
+async function deployPipelineStack(ctx) {
+  const { deploy: deploy2 } = ctx.instance;
+  if (deploy2.via !== "codepipeline") {
+    console.log("  skipped — this instance is deployed by GitHub Actions");
+    return;
+  }
+  const arn = deploy2.connectionArn ?? "";
+  const status = ctx.dryRun === true ? "AVAILABLE" : await connectionStatus(ctx, arn);
+  console.log(`  connection ${arn}
+  status: ${status}`);
+  if (status !== "AVAILABLE") {
+    console.log(`  not deploying ${ctx.names.pipeline}: authorise the connection first, at
+  ${connectionConsoleUrl(ctx.region)}
+  then re-run setup.`);
+    return;
+  }
+  await run([
+    ...cdkCommand(),
+    "deploy",
+    ctx.names.pipeline,
+    "--require-approval",
+    "never",
+    "-c",
+    `instanceFile=${ctx.paths.path}`
+  ], { cwd: INFRA_ROOT, env: cdkEnv(ctx), dryRun: ctx.dryRun });
+}
+function deployRoleVariableName(instanceName) {
+  return `${instanceName.toUpperCase().replaceAll("-", "_")}_DEPLOY_ROLE_ARN`;
+}
+async function setDeployRoleVariable(ctx) {
+  const arn = await output(ctx, ctx.names.ci, "DeployRoleArn");
+  const name = deployRoleVariableName(ctx.instance.name);
+  const cmd = ["gh", "variable", "set", name, "--repo", ctx.instance.github.repo, "--body", arn];
+  if (ctx.dryRun !== true) {
+    try {
+      await runCapture(["gh", "auth", "status"]);
+    } catch {
+      console.log(`  gh is not authenticated — set it yourself: ${cmd.join(" ")}`);
+      return;
+    }
+  }
+  await run(cmd, { dryRun: ctx.dryRun });
+  console.log(`  ${name} = ${arn}`);
+}
+async function setup(ctx, opts = {}) {
+  const customization = stageCustomization({ paths: ctx.paths, dryRun: ctx.dryRun });
+  const runtimeConfigPath = customization.runtimeConfigPath;
+  const admins = adminsCsvFromFile(ctx.paths.configPath);
+  const alarmEmail = alarmEmailFor(ctx, opts.alarmEmail);
+  step(1, "preflight: dependencies, credentials, secrets");
+  await preflight(ctx);
+  step(2, "cdk bootstrap");
+  await bootstrap(ctx);
+  step(3, "enable CloudWatch Transaction Search");
+  await enableTransactionSearch(ctx);
+  step(4, "phase 1: deploy stacks without the AgentCore runtime");
+  await cdkDeploy(ctx, { admins, alarmEmail, phase1: true });
+  const knockOAuth = await syncSetupKnockOAuth(ctx);
+  if (knockOAuth !== "skipped")
+    console.log(`  Knock OAuth: ${knockOAuth}`);
+  step(5, `write ${ctx.names.secretRuntime}`);
+  await writeRuntimeSecret(ctx);
+  step(6, "sync config + skills to S3");
+  const bucket = await configSync(ctx, {
+    bucket: await output(ctx, ctx.names.data, "BucketName"),
+    runtimeConfigPath
+  });
+  console.log(`  s3://${bucket}/`);
+  step(7, "build + push the agent image");
+  const tag = await currentImageTag(FOUNDATION_ROOT);
+  const repositoryUri = await output(ctx, ctx.names.agent, "RepositoryUri");
+  console.log(`  ${repositoryUri}:${tag}`);
+  await buildAndPushImage(ctx, { tag, repositoryUri });
+  step(8, "phase 2: deploy the AgentCore runtime");
+  await cdkDeploy(ctx, { admins, alarmEmail, tag });
+  step(9, `refresh ${ctx.names.secretRuntime} with the runtime arn`);
+  await writeRuntimeSecret(ctx);
+  step(10, "create the pinned `live` endpoint");
+  await ensureLiveEndpoint(ctx);
+  step(11, `seed ${ctx.names.secretCodex}`);
+  if (opts.seedCodex === true)
+    await seedCodex(ctx, opts.codexFile ?? defaultCodexFile(ctx.paths.root));
+  else
+    console.log("  skipped (pass --seed-codex, or run `login` in Slack as an admin)");
+  step(12, "tell GitHub Actions which role to assume");
+  await setDeployRoleVariable(ctx);
+  step(13, "deploy the instance's own pipeline, if it has one");
+  await deployPipelineStack(ctx);
+  step(14, "the Slack app manifest for the deployed API");
+  await reportSlackManifest(ctx);
+  step(15, "smoke test the runtime");
+  await smokeTest(ctx);
+  console.log(`
+Done. Now say \`@${ctx.instance.displayName} hello\` in Slack.`);
+}
+
+// src/deploy/cli.ts
+var COMMANDS = [
+  "deploy",
+  "post-deploy",
+  "config:sync",
+  "setup",
+  "github-app-create",
+  "slack-manifest",
+  "stage-customization"
+];
+var USAGE = `usage: foundation-deploy <command> --instance <path> [options]
+
+commands
+  deploy               build and push the agent image, cdk deploy --all, refresh
+                       the runtime secret, sync config
+  post-deploy          smoke DEFAULT, probe the mount, promote \`live\`, smoke \`live\`
+  config:sync          upload the runtime config and product skills to S3
+  setup                first-deploy orchestration (idempotent)
+  github-app-create    create the instance's GitHub App from the shipped manifest
+  slack-manifest       print the instance's Slack app manifest as JSON
+  stage-customization  validate and stage a tenant-owned runtime config
+
+options
+  --instance <path>    REQUIRED: path to the deployment's instance YAML
+                       (or set FOUNDATION_INSTANCE_FILE)
+  --profile <p>        AWS profile (default: the instance's aws.profile; "" or
+                       FOUNDATION_NO_PROFILE=1 for the default credential chain)
+  --region <r>         AWS region (default: the instance's aws.region)
+  --alarm-email <a>    DLQ alarm subscriber (default: the instance's aws.alarmEmail)
+  --dry-run            print the commands without running them
+  -h, --help           this message
+
+release options (deploy, config:sync)
+  --release <vX.Y.Z>   deploy a published Foundation release: verify its signed
+                       manifest, then deploy the artifacts it names. A copy of
+                       this tool installed from npm defaults to its OWN version;
+                       a Foundation checkout defaults to building locally.
+  --manifest <ref>     that release's manifest, as a path or an s3:// URI
+  --release-bucket <b> where releases live (default: the Foundation bucket, or
+                       FOUNDATION_RELEASE_BUCKET)
+
+deploy options
+  --tag <tag>          image tag to deploy (default: git short sha, +"-dirty");
+                       ignored in release mode, which pins the image by digest
+  --skip-image         do not build/push; deploy the stacks against --tag
+  --phase1             bootstrap deploy: stacks only, no AgentCore runtime
+
+setup options
+  --seed-codex         copy a local Codex credential into the instance's secret
+  --codex-file <path>  where that credential is (default: beside the instance
+                       file, .foundation-local/codex.json)
+
+github-app-create options
+  --org <org>          GitHub org (default: the instance's github.org)
+  --port <n>           local callback port (default 8765)
+  --secret <id>        Secrets Manager id (default: the instance's github/app)`;
+function flag(args, name) {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+}
+function contextFor(args) {
+  const paths = loadInstanceContext(resolveInstanceFilePath(args, process.env));
+  return awsContext({
+    paths,
+    profile: flag(args, "--profile"),
+    region: flag(args, "--region"),
+    dryRun: args.includes("--dry-run")
+  });
+}
+async function main(argv2 = process.argv.slice(2)) {
+  const [command, ...args] = argv2;
+  if (command === undefined || command === "--help" || command === "-h") {
+    console.log(USAGE);
+    return command === undefined ? 1 : 0;
+  }
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!COMMANDS.includes(command)) {
+    console.error(`unknown command: ${command}
+
+${USAGE}`);
+    return 1;
+  }
+  if (command === "slack-manifest") {
+    const paths = loadInstanceContext(resolveInstanceFilePath(args, process.env));
+    console.log(JSON.stringify(slackManifestFor(paths.instance, {
+      ...process.env.EVENTS_REQUEST_URL === undefined ? {} : { EVENTS_REQUEST_URL: process.env.EVENTS_REQUEST_URL },
+      ...process.env.COMMANDS_REQUEST_URL === undefined ? {} : { COMMANDS_REQUEST_URL: process.env.COMMANDS_REQUEST_URL },
+      ...process.env.INTERACTIVE_REQUEST_URL === undefined ? {} : { INTERACTIVE_REQUEST_URL: process.env.INTERACTIVE_REQUEST_URL }
+    })));
+    return 0;
+  }
+  if (command === "github-app-create") {
+    const paths = loadInstanceContext(resolveInstanceFilePath(args, process.env));
+    console.log(instanceBanner(paths));
+    const port = flag(args, "--port");
+    await githubAppCreate({
+      paths,
+      ...flag(args, "--org") === undefined ? {} : { org: flag(args, "--org") },
+      ...port === undefined ? {} : { port: Number(port) },
+      ...flag(args, "--secret") === undefined ? {} : { secret: flag(args, "--secret") },
+      ...flag(args, "--profile") === undefined ? {} : { profile: flag(args, "--profile") },
+      ...flag(args, "--region") === undefined ? {} : { region: flag(args, "--region") },
+      dryRun: args.includes("--dry-run")
+    });
+    return 0;
+  }
+  const ctx = contextFor(args);
+  console.log(instanceBanner(ctx.paths));
+  if (ctx.dryRun === true)
+    console.log("dry run — no changes will be made");
+  switch (command) {
+    case "deploy": {
+      const tag = flag(args, "--tag");
+      const alarmEmail = flag(args, "--alarm-email");
+      const release = releaseRequest(args);
+      await deploy(ctx, {
+        ...tag === undefined ? {} : { tag },
+        skipImage: args.includes("--skip-image"),
+        phase1: args.includes("--phase1"),
+        ...alarmEmail === undefined ? {} : { alarmEmail },
+        ...release === undefined ? {} : { release }
+      });
+      return 0;
+    }
+    case "post-deploy":
+      await postDeploy(ctx);
+      return 0;
+    case "config:sync": {
+      const customization = stageCustomization({ paths: ctx.paths, dryRun: ctx.dryRun });
+      const bucket = flag(args, "--bucket");
+      const request = releaseRequest(args);
+      const release = request === undefined ? undefined : await resolveRelease(ctx, request);
+      const synced = await configSync(ctx, {
+        ...bucket === undefined ? {} : { bucket },
+        ...customization.runtimeConfigPath === undefined ? {} : { runtimeConfigPath: customization.runtimeConfigPath },
+        ...release === undefined ? {} : { release }
+      });
+      console.log(`config + product skills synced to s3://${synced}/`);
+      return 0;
+    }
+    case "setup": {
+      const codexFile = flag(args, "--codex-file");
+      const alarmEmail = flag(args, "--alarm-email");
+      await setup(ctx, {
+        seedCodex: args.includes("--seed-codex"),
+        ...codexFile === undefined ? {} : { codexFile },
+        ...alarmEmail === undefined ? {} : { alarmEmail }
+      });
+      return 0;
+    }
+    case "stage-customization": {
+      const result = stageCustomization({ paths: ctx.paths, dryRun: ctx.dryRun });
+      console.log(`  ${result.status}: ${result.runtimeConfigPath}`);
+      return 0;
+    }
+    default:
+      console.error(`unhandled command: ${command}
+
+${USAGE}`);
+      return 1;
+  }
+}
+
+// bin/foundation-deploy.ts
+try {
+  process.exit(await main());
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}