@moinulmoin/eden 0.9.0 → 0.11.0

package/README.md

@@ -12,15 +12,15 @@ If you already have an Eve project, start with `eden deploy`.
 Use any one of these package managers:
 
 ```sh
-npm install --global @moinulmoin/eden@0.9.0
+npm install --global @moinulmoin/eden@0.11.0
 ```
 
 ```sh
-pnpm add --global @moinulmoin/eden@0.9.0
+pnpm add --global @moinulmoin/eden@0.11.0
 ```
 
 ```sh
-bun add --global @moinulmoin/eden@0.9.0
+bun add --global @moinulmoin/eden@0.11.0
 ```
 
 Then confirm the CLI is available:

package/dist/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: eden
+description: Deploy, update, check, or remove a Vercel Eve agent on the user's own Cloudflare account with the Eden CLI. Use when someone wants to run an Eve project off Vercel, check whether an Eve project is ready for Cloudflare, ship a change to an Eden deployment, upgrade Eve on one, or tear one down.
+---
+
+# Eden: run an Eve agent on Cloudflare
+
+Eden (`@moinulmoin/eden`) builds an existing Eve project as-is and runs it in a
+Cloudflare Container behind a Worker on the user's own account. It never
+rewrites the project; you make any needed changes yourself, guided by
+preflight.
+
+`npx @moinulmoin/eden skill` prints this guide for the installed CLI version.
+Docs: https://github.com/moinulmoin/eden (failure and warning codes:
+`docs/troubleshooting.md`).
+
+## The loop
+
+1. Check the machine and account (below).
+2. Write the env file (below).
+3. Run preflight and read the JSON:
+
+   ```sh
+   npx @moinulmoin/eden preflight --env-file ~/.config/<agent>/preview.env --json
+   ```
+
+   Preflight builds and boots the agent locally and checks Cloudflare access.
+   It changes nothing on Cloudflare. It prints one JSON object:
+   `ok`, `checks[]` (`id`, `status`, `message`, `remediation`) and
+   `warnings[]` (`id`, `message`, `remediation`).
+4. Fix every failed check, then every warning, using its `remediation`. Re-run
+   until `ok` is `true` and no warning applies. A warning does not block a
+   deploy, but each one names something that breaks or loses data on
+   Cloudflare; only leave one if the user accepts that.
+5. A clean preflight means the project can run on Cloudflare. It does not
+   check that keys are real: before deploying, make sure the user has replaced
+   every placeholder secret in the env file.
+6. Deploy, then verify with a real message (below). Confirm with the user
+   first for production.
+
+## Machine and account
+
+- macOS or Linux, Node `>=24.17.0`
+- Docker or OrbStack running, with linux/amd64 support
+- Cloudflare Workers Paid plan (Containers need it), and Wrangler logged in:
+  `npx wrangler@4.147.0 login` (the user must do this in a browser)
+
+## Project setup Cloudflare needs
+
+These are what preflight checks most often. Fix them before the first run to
+save a build.
+
+- **One lockfile.** Either a root `package-lock.json`, or an exact
+  `"packageManager": "pnpm@x.y.z"` with a root `pnpm-lock.yaml`. Not both, not
+  Bun. Dependency install scripts do not run.
+- **Sandbox.** Add `just-bash` as a production dependency. On Eve `0.83.0` and
+  later, also select it explicitly in `agent/sandbox.ts` (or
+  `agent/sandbox/sandbox.ts` if an `agent/sandbox/` folder exists):
+
+  ```ts
+  import { defineSandbox } from 'eve/sandbox';
+  import { JustBashSandbox } from 'eve/sandbox/just-bash';
+
+  export const environment = JustBashSandbox.environment();
+  export default defineSandbox(() => environment.open());
+  ```
+
+  Vercel Sandbox, Docker, and other providers do not run on Eden.
+- **Channel auth (`EVE_AUTH_SCAFFOLD`).** The `eve init` auth in
+  `agent/channels/eve.ts` (`vercelOidc()`, `localDev()`, `placeholderAuth()`)
+  rejects every Cloudflare caller with 401. Replace it with a real
+  authenticator, for example a bearer token read from the env file. Keep
+  `localDev()` so `eve dev` still works locally; it is ignored in production:
+
+  ```ts
+  import { localDev, type AuthFn } from "eve/channels/auth";
+  import { eveChannel } from "eve/channels/eve";
+
+  const authenticate: AuthFn<Request> = (request) => {
+    const expected = process.env.AGENT_AUTH_TOKEN;
+    if (!expected || request.headers.get("authorization") !== `Bearer ${expected}`) {
+      return null;
+    }
+    return {
+      attributes: {},
+      authenticator: "bearer-token",
+      principalId: "app-client",
+      principalType: "app",
+    };
+  };
+
+  export default eveChannel({ auth: [authenticate, localDev()] });
+  ```
+
+- **Model key (`EVE_AI_GATEWAY_KEY_MISSING`).** A string model such as
+  `"openai/gpt-5"` goes through Vercel AI Gateway. On Vercel that
+  authenticates automatically; on Cloudflare it needs `AI_GATEWAY_API_KEY` in
+  the env file. A direct provider such as `openai("…")` from `@ai-sdk/openai`
+  needs that provider's key instead.
+- **Vercel Connect (`EVE_VERCEL_CONNECT`).** `connect()` from
+  `@vercel/connect/eve` gets credentials using an identity only Vercel
+  provides, so those connections fail on Cloudflare. Put the service's own key
+  or bot token in the env file and replace `connect(...)` in the connection
+  with `auth: { getToken: async () => ({ token: process.env.SERVICE_TOKEN! }) }`.
+  For per-user sign-in, use `defineInteractiveAuthorization` from
+  `eve/connections` with your own OAuth app. Having `@vercel/connect` in
+  `package.json` without importing it is fine.
+- **Durable state (`EVE_WORLD_LOCAL`).** The default local Workflow World loses
+  sessions and pending approvals on every update. Use one of:
+  - `@moinulmoin/eden-world-cloudflare`: no database; sessions also survive Eve
+    upgrades. Add it as a production dependency and set in `agent/agent.ts`:
+
+    ```ts
+    experimental: { workflow: { world: "@moinulmoin/eden-world-cloudflare" } },
+    ```
+
+  - `@workflow/world-postgres` with a direct, unpooled Postgres URL in the env
+    file.
+
+## Env file and secrets
+
+- Lives **outside the project**, mode 600, for example
+  `~/.config/<agent>/preview.env`. Passed with `--env-file`.
+- Exactly `KEY=value` per line: no quotes (they become part of the value), no
+  spaces around the name, `#` comment lines allowed.
+- Holds the model key and every secret the agent reads (auth token, service
+  keys, database URL).
+- Never print, log, or commit it, and never pass a secret as a command
+  argument. Ask the user to fill in values you do not have.
+
+## Commands
+
+```sh
+# deploy to preview; the name comes from package.json
+npx @moinulmoin/eden deploy --env-file ~/.config/<agent>/preview.env --json
+
+# ship a change: the same command updates in place, on the same URL
+npx @moinulmoin/eden deploy --env-file ~/.config/<agent>/preview.env --json
+
+# production always needs an explicit --name
+npx @moinulmoin/eden deploy --env production --name <name> --env-file <file> --json
+
+# remove one target (always needs the exact --name deploy printed;
+# add --env production for a production target)
+npx @moinulmoin/eden destroy --name <name> --json
+```
+
+- `--project <dir>` selects a project other than the current directory.
+- A fresh deploy takes a few minutes, mostly building the container. The
+  result's `deployment.stableWorkersDevOrigin` is the live URL.
+- An `eve init` project's `npm run deploy` script still deploys to Vercel, not
+  Eden.
+- Confirm with the user before any `destroy` or production deploy. Destroy
+  deletes the agent immediately, even mid-conversation, and with the Cloudflare
+  World also its stored sessions. An external Postgres database is not touched.
+
+## Verify
+
+Health only proves the server started; it needs no auth:
+
+```sh
+curl -s https://<url>/eve/v1/health   # expect "status":"ready"
+```
+
+Then prove auth, the model key, and the agent work with a real message, using
+the channel's credential (the bearer token from the env file):
+
+```sh
+curl -s -X POST https://<url>/eve/v1/session \
+  -H "Authorization: Bearer $AGENT_AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Reply with one word: ready"}'
+# {"ok":true,"sessionId":"wrun_…"}; then read the reply:
+curl -s -N https://<url>/eve/v1/session/<sessionId>/stream \
+  -H "Authorization: Bearer $AGENT_AUTH_TOKEN"
+```
+
+Load the token into the shell from the env file without printing it. The
+first request after the agent sleeps takes about 10–15 seconds.
+
+## Upgrading Eve
+
+- Bump `eve`, then reinstall so the lockfile matches. Keep
+  `@moinulmoin/eden-world-cloudflare` on its latest version.
+- Moving an `eve init` project to Eve `1.0` also needs `@vercel/connect`
+  `2.7.0` or later; otherwise npm fails with `ERESOLVE`.
+- Then deploy as usual. With the current Cloudflare World, existing sessions
+  continue on the new version. With the Postgres World or an older Cloudflare
+  World they return HTTP 409 `session_stranded` and users start new ones.
+
+## Limits to tell the user
+
+- The sandbox is `just-bash`, a simulated shell: files, grep, sed, jq,
+  sqlite3, and curl work; python, git, and npm do not.
+- One container per agent, `workers.dev` URL only, no custom domains yet.
+- The container sleeps after 1 hour idle and wakes on the next request.
+  Standard 5-field cron schedules still fire while it sleeps; other cron forms
+  only fire while it is awake (`EVE_SCHEDULE_UNSUPPORTED`).
+
+## When something fails
+
+- Checks run before anything changes on Cloudflare. Fix the first failed
+  check by its `remediation` and run again.
+- `VAL-CLI-007-TARGET-CONFLICT`: a resource with that name exists that Eden
+  cannot prove it owns. For a brand-new agent, pick another `--name`; never
+  delete the resource to make room.
+- `VAL-CLI-007-CLOUDFLARE-ACCESS`: Wrangler is not logged in or the account
+  lacks Workers Paid/Containers. The user has to fix this
+  (`npx wrangler@4.147.0 whoami`).
+- `DEPLOY_INDETERMINATE`: Eden could not prove the result; the old version
+  usually keeps serving. Check the URL's health, then retry with the exact
+  same `--project`, `--env`, and `--name`. Never switch to a new name to get
+  past it, never delete resources by prefix, and never delete the project's
+  `.eden/` folder: it is the ownership proof `destroy` needs.
+- Look up any other code in `docs/troubleshooting.md`.

package/dist/eve-control-plane.d.ts

@@ -128,6 +128,11 @@ export interface EveDeploymentIdentity {
     readonly sourceDigest: string;
     readonly generationId: string;
     readonly deploymentId: string;
+    readonly releaseId?: string;
+    readonly eveVersion?: string;
+    readonly affinityContract?: number;
+    readonly retainedDeployments?: Readonly<Record<string, EveAffinityDeployment>>;
+    readonly pendingRetirements?: Readonly<Record<string, EveAffinityDeployment>>;
     readonly environment: EveCliEnvironment;
     readonly name: string;
     readonly accountId: string;
@@ -144,6 +149,28 @@ export type EveDeploymentIdentityProof = Partial<EveDeploymentIdentity> & {
     /** The deployment the serving Container verifiably started under; set only by a deployed Eden host that proves its running image before stamping. */
     readonly startedDeploymentId?: string;
 };
+export interface EveAffinityDeployment {
+    readonly image: string;
+    readonly generationId: string;
+    readonly runtimeRevisionHandle?: string;
+    readonly eveVersion?: string;
+    readonly affinityContract?: number;
+    readonly releaseId?: string;
+    readonly worldRpcAuth?: boolean;
+}
+export interface EveDeploymentDrainState {
+    readonly liveRuns: number;
+    readonly liveSessions: number;
+    readonly pendingMessages: number;
+    readonly unfinishedTransfers: number;
+    readonly drained: boolean;
+}
+export type EveDeploymentRpcRunner = (request: {
+    readonly origin: string;
+    readonly operation: "deployments.drainState" | "deployments.retire";
+    readonly deploymentIds: readonly string[];
+    readonly controlToken: string;
+}) => Promise<unknown>;
 export interface EveDeploymentPublicationRequest {
     readonly identity: EveDeploymentIdentity;
     readonly hostConfig: EveHostConfig;
@@ -233,6 +260,7 @@ export interface EvePreflightOptions {
     readonly protectedStore?: EveRuntimeProtectedStore;
     readonly publish?: EveDeploymentPublicationRunner;
     readonly publishImage?: EveImagePublicationRunner;
+    readonly deploymentRpc?: EveDeploymentRpcRunner;
     readonly compensate?: EveDeploymentCompensationRunner;
     readonly health?: EveDeploymentHealthRunner;
     readonly afterPromotion?: () => void | Promise<void>;

package/dist/eve-control-plane.js

@@ -1,3 +1,4 @@
+import { setTimeout as waitForActivation } from "node:timers/promises";
 import { createRequire, } from "node:module";
 import { createHash, randomUUID, } from "node:crypto";
 import { join, dirname, relative, } from "node:path";
@@ -11,7 +12,7 @@ import { EveCliError, EVE_NAME_PATTERN, } from "./eve.js";
 import { buildEveProjectSnapshot, checkEveSandboxProvider, createDockerEveProjectBuilder, revalidateEveProjectCandidateInputs, EvePackagingError, IMAGE_ID_PATTERN, } from "./eve-packaging.js";
 import { buildEveRuntimeImage, discardEveRuntimeImage, revalidateEveRuntimeCandidate, validateEveHostRequirements, } from "./eve-runtime-image.js";
 import { EveRuntimeConfigError, prepareEveRuntimeInjection, redactEveRuntimeOutput, } from "./eve-runtime-config.js";
-import { createEveHostConfig, generateEveHostWorkerSource, parseEveScheduleCron, resolveStableWorkersDevOrigin, } from "@moinulmoin/eden-runtime-cloudflare";
+import { EDEN_AFFINITY_CONTRACT, callDeploymentControlRpc, createEveHostConfig, generateEveHostWorkerSource, parseEveScheduleCron, resolveStableWorkersDevOrigin, } from "@moinulmoin/eden-runtime-cloudflare";
 const execFileAsync = promisify(execFile);
 const require = createRequire(import.meta.url);
 const wranglerEntrypoint = require.resolve("wrangler");
@@ -32,6 +33,54 @@ export const DEFAULT_EVE_NODE_IMAGE = Object.freeze({
 });
 /** The single tag Eden pushes to the managed Cloudflare registry per generation. */
 const EVE_REGISTRY_IMAGE_TAG = "candidate";
+function validateDeploymentDrainStates(value, ids) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw deploymentFailure("EVE_AFFINITY_DRAIN_UNPROVEN", "The authenticated World did not return deployment drain states.");
+    }
+    const states = value;
+    for (const id of ids) {
+        const state = states[id];
+        if (typeof state !== "object" || state === null ||
+            typeof state.drained !== "boolean" ||
+            [state.liveRuns, state.liveSessions, state.pendingMessages, state.unfinishedTransfers]
+                .some((count) => !Number.isSafeInteger(count) || count < 0) ||
+            state.drained !== (state.liveRuns + state.liveSessions + state.pendingMessages + state.unfinishedTransfers === 0)) {
+            throw deploymentFailure("EVE_AFFINITY_DRAIN_UNPROVEN", `The authenticated World returned an invalid drain state for ${id}.`);
+        }
+    }
+    return states;
+}
+const defaultDeploymentRpc = async (request) => {
+    // A successful Cloudflare secret write creates an active deployment, but
+    // existing stateless Worker isolates may briefly serve the preceding secret.
+    // Only the first read-only drain call following our own rotation may wait
+    // for that exact in-memory credential. All other failures remain terminal.
+    const activationRead = request.operation === "deployments.drainState";
+    const deadline = Date.now() + 60_000;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            throw deploymentFailure("EVE_AFFINITY_CONTROL_ACTIVATION_TIMEOUT", "The freshly rotated deployment-control credential did not activate within 60 seconds; publication was refused.");
+        }
+        try {
+            return await callDeploymentControlRpc({
+                origin: request.origin,
+                token: request.controlToken,
+                operation: request.operation,
+                args: [{ deploymentIds: request.deploymentIds }],
+                signal: AbortSignal.timeout(remaining),
+            });
+        }
+        catch (error) {
+            if (!activationRead || typeof error !== "object" || error === null ||
+                !("status" in error) || error.status !== 401)
+                throw error;
+            const delay = Math.min(1_000, deadline - Date.now());
+            if (delay > 0)
+                await waitForActivation(delay);
+        }
+    }
+};
 function safeText(value) {
     return redactEveRuntimeOutput(value)
         .replace(/(?:^|[\s"'=])(?:Bearer|Token)\s+\S+/giu, "$1[redacted]")
@@ -214,6 +263,56 @@ function pooledPostgresReason(connectionString) {
     }
     return undefined;
 }
+const EVE_WORLD_LOCAL_REMEDIATION = 'For durable state without a database, add @moinulmoin/eden-world-cloudflare and set experimental: { workflow: { world: "@moinulmoin/eden-world-cloudflare" } } in agent.ts; sessions survive Eve upgrades. Alternatively, add @workflow/world-postgres, select it as the workflow world, and put WORKFLOW_POSTGRES_URL with a direct, unpooled Postgres URL in --env-file.';
+/** Static, dynamic, side-effect, or require imports of @vercel/connect or a subpath. */
+function importsVercelConnect(source) {
+    return /\b(?:from|import|require)\s*\(?\s*["']@vercel\/connect(?:\/[^"']*)?["']/u
+        .test(source.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/gu, ""));
+}
+async function vercelConnectSourcePaths(projectRoot) {
+    const paths = [];
+    const visit = async (path) => {
+        const entries = await readdir(join(projectRoot, path), { withFileTypes: true })
+            .catch(() => []);
+        for (const entry of entries) {
+            if (entry.name === "node_modules" || entry.isSymbolicLink())
+                continue;
+            const child = `${path}/${entry.name}`;
+            if (entry.isDirectory())
+                await visit(child);
+            else if (entry.isFile() && /\.[cm]?[jt]sx?$/u.test(entry.name)) {
+                const source = await readFile(join(projectRoot, child), "utf8").catch(() => "");
+                if (importsVercelConnect(source))
+                    paths.push(child);
+            }
+        }
+    };
+    await visit("agent");
+    await visit("agents");
+    return paths.sort();
+}
+/** Eve persists its compile-time routing decision, including its default model. */
+async function collectEveGatewayWarnings(candidate, runtimeConfig) {
+    if (runtimeConfig?.withProtectedValues((values) => (values.AI_GATEWAY_API_KEY?.trim().length ?? 0) > 0) === true)
+        return [];
+    try {
+        const manifest = JSON.parse(await readFile(join(candidate.snapshotRoot, EVE_COMPILED_MANIFEST_PATH), "utf8"));
+        if (manifest?.config?.model?.routing?.kind !== "gateway")
+            return [];
+        const source = typeof manifest.config.source?.logicalPath === "string"
+            ? manifest.config.source.logicalPath
+            : "agent/agent.ts";
+        return [{
+                id: "EVE_AI_GATEWAY_KEY_MISSING",
+                message: `The model in ${source} routes through Vercel AI Gateway, but --env-file has no non-blank AI_GATEWAY_API_KEY. Cloudflare has no Vercel OIDC project identity, so model calls fail.`,
+                remediation: 'Add AI_GATEWAY_API_KEY from https://vercel.com/dashboard/ai/api-keys to your --env-file, or use a direct provider such as openai("gpt-5") from @ai-sdk/openai with OPENAI_API_KEY in that file.',
+            }];
+    }
+    catch {
+        // Unknown or older compiled formats are not evidence of Gateway routing.
+        return [];
+    }
+}
 /**
  * Recognizes the generated channel, not arbitrary user authentication policies.
  * The calls below match the Eve 0.82 initializer's agent/channels/eve.ts.
@@ -228,6 +327,14 @@ async function collectEveSetupWarnings(projectRoot) {
             return "";
         }
     };
+    const connectPaths = await vercelConnectSourcePaths(projectRoot);
+    if (connectPaths.length > 0) {
+        warnings.push({
+            id: "EVE_VERCEL_CONNECT",
+            message: `Vercel Connect imports in ${connectPaths.join(", ")} get credentials using a Vercel project identity (OIDC) that only Vercel injects; these connections fail on Cloudflare.`,
+            remediation: "Put each service's own API key or bot token in --env-file and replace connect(...) in the connection with auth: { getToken: async () => ({ token: process.env.SERVICE_TOKEN! }) }. For per-user sign-in, use defineInteractiveAuthorization from eve/connections with your own OAuth app.",
+        });
+    }
     const channel = (await source("agent/channels/eve.ts"))
         .replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/gu, "")
         .replace(/\s+/gu, "");
@@ -246,7 +353,7 @@ async function collectEveSetupWarnings(projectRoot) {
             warnings.push({
                 id: "EVE_WORLD_LOCAL",
                 message: "Local World stores memory on container disk; updates or a lost sleep snapshot reset sessions and approvals.",
-                remediation: "Configure @workflow/world-postgres; see docs/deploy.md#durable-state-postgres-world.",
+                remediation: EVE_WORLD_LOCAL_REMEDIATION,
             });
         }
         if (manifest.dependencies?.["just-bash"] === undefined &&
@@ -301,7 +408,7 @@ async function collectEveWorldWarnings(candidate, runtimeConfig) {
             warnings.push({
                 id: "EVE_WORLD_LOCAL",
                 message: "Local World stores memory on container disk; updates or a lost sleep snapshot reset sessions and approvals.",
-                remediation: "Configure a durable Workflow World such as @workflow/world-postgres; see docs/deploy.md#durable-state-postgres-world.",
+                remediation: EVE_WORLD_LOCAL_REMEDIATION,
             });
         }
     }
@@ -471,13 +578,13 @@ function safeDockerEnvironment() {
         DOCKER_CONTEXT: process.env.DOCKER_CONTEXT,
     };
 }
-async function readWranglerJson(args) {
+async function readWranglerJson(args, timeoutMs = 30_000) {
     try {
         const result = await execFileAsync(process.execPath, [wranglerEntrypoint, ...args], {
             env: safeWranglerEnvironment(),
             cwd: wranglerCwd,
             maxBuffer: 2 * 1024 * 1024,
-            timeout: 30_000,
+            timeout: timeoutMs,
         });
         const parsed = JSON.parse(result.stdout.trim());
         return { value: parsed, failed: false };
@@ -813,11 +920,33 @@ async function resolveEveTargetOwnership(request, result) {
             evidence.containerNamespaceId === evidence.workerContainerNamespaceId);
     const remoteProven = evidence !== undefined && workerProven && containerProven;
     if (!remoteProven) {
+        const failures = [];
+        if (evidence === undefined)
+            failures.push("provider evidence unavailable");
+        if (result.target.observed?.worker === true) {
+            if (evidence?.settingsReadable !== true)
+                failures.push("Worker settings unreadable");
+            else if (evidence.workerDeploymentId === undefined)
+                failures.push("Worker deployment stamp absent");
+            else if (!recordedDeploymentIds.has(evidence.workerDeploymentId))
+                failures.push("Worker deployment stamp differs from recorded identities");
+        }
+        if (result.target.observed?.container === true) {
+            if (evidence?.containerSchedulingPolicy !== "durable_object")
+                failures.push("Container scheduling policy unproven");
+            if (evidence?.containerNamespaceId === undefined)
+                failures.push("Container namespace unreadable");
+            if (evidence?.workerContainerNamespaceId === undefined)
+                failures.push("Worker Container binding namespace unreadable");
+            if (evidence?.containerNamespaceId !== undefined && evidence.workerContainerNamespaceId !== undefined &&
+                evidence.containerNamespaceId !== evidence.workerContainerNamespaceId)
+                failures.push("Container and Worker binding namespaces differ");
+        }
         return {
             ...result,
             target: {
                 ...result.target,
-                message: "The exact Worker or Container target exists, and although a local Eden record matches, provider state cannot prove it is the one Eden deployed — the target may have been recreated outside Eden.",
+                message: `The exact Worker or Container target exists, and although a local Eden record matches, provider state cannot prove it is the one Eden deployed — the target may have been recreated outside Eden. Unproven: ${failures.join("; ")}.`,
                 remediation: "Inspect the Worker at its workers.dev origin and the recorded deployment history before redeploying; if it is not Eden's, deploy under a different --name or delete it yourself.",
             },
         };
@@ -995,11 +1124,17 @@ function transportIdentityMatches(expected, observed) {
         "generationId",
         "stableWorkersDevOrigin",
         "workerName",
-        "stableContainerInstanceName",
     ];
     if (!required.every((key) => observed[key] === expected[key])) {
         return false;
     }
+    const expectedInstance = expected.retainedDeployments === undefined ||
+        expected.deploymentId === "eden-cloudflare"
+        ? expected.stableContainerInstanceName
+        : `${expected.stableContainerInstanceName}:${expected.deploymentId}`;
+    if (observed.stableContainerInstanceName !== expectedInstance ||
+        observed.releaseId !== expected.releaseId)
+        return false;
     return expected.runtimeRevisionHandle === undefined
         ? observed.runtimeRevisionHandle === undefined
         : observed.runtimeRevisionHandle === expected.runtimeRevisionHandle;
@@ -1012,6 +1147,7 @@ function identityMatches(expected, observed) {
         "sourceDigest",
         "generationId",
         "deploymentId",
+        "releaseId",
         "environment",
         "name",
         "accountId",
@@ -1039,6 +1175,11 @@ function safeIdentity(identity) {
         sourceDigest: identity.sourceDigest,
         generationId: identity.generationId,
         deploymentId: identity.deploymentId,
+        releaseId: identity.releaseId,
+        eveVersion: identity.eveVersion,
+        affinityContract: identity.affinityContract,
+        retainedDeployments: identity.retainedDeployments,
+        pendingRetirements: identity.pendingRetirements,
         environment: identity.environment,
         name: identity.name,
         accountId: identity.accountId,
@@ -1281,6 +1422,7 @@ function responseIdentity(response, body) {
     read("sourceDigest", "x-eden-eve-source-digest");
     read("generationId", "x-eden-eve-generation-id");
     read("deploymentId", "x-eden-eve-deployment-id");
+    read("releaseId", "x-eden-eve-release-id");
     read("environment", "x-eden-eve-environment");
     read("name", "x-eden-eve-name");
     read("accountId", "x-eden-eve-account-id");
@@ -1341,7 +1483,7 @@ function defaultHealthRunner() {
                 // must wait until the *served container* verifiably runs this
                 // generation's image (the host stamps the header only after
                 // inspecting the running instance).
-                if (observedIdentity.startedDeploymentId !== request.identity.deploymentId) {
+                if (observedIdentity.startedDeploymentId !== (request.identity.releaseId ?? request.identity.deploymentId)) {
                     lastReason =
                         "The served Container has not verifiably started this deployment's image yet; waiting for the rollout to land.";
                     await wait();
@@ -1460,8 +1602,8 @@ async function promoteEveTargetPointer(deploymentRoot, pointerKey, generationRoo
     }
     return currentPath;
 }
-async function writeEveDeploymentRecord(candidate, identity, hostConfig, status, extra = {}) {
-    await writeFile(join(candidate.generationRoot, "deployment.json"), `${JSON.stringify({
+async function writeEveDeploymentRecord(candidate, identity, hostConfig, status, extra = {}, filename = "deployment.json") {
+    await writeFile(join(candidate.generationRoot, filename), `${JSON.stringify({
         version: 1,
         status,
         identity: safeIdentity(identity),
@@ -1474,6 +1616,10 @@ async function writeEveDeploymentRecord(candidate, identity, hostConfig, status,
         flag: "wx",
     });
 }
+async function deploymentRecordPath(generationRoot) {
+    const path = join(generationRoot, "deployment.json");
+    return await lstat(path).then(() => path, () => join(generationRoot, "deployment-intent.json"));
+}
 async function writeEveIndeterminateEvidence(candidate, evidence, extra = {}) {
     await writeFile(join(candidate.generationRoot, "deployment-attempt.json"), `${JSON.stringify({
         version: 1,
@@ -1538,6 +1684,14 @@ async function runEveDeployment(request, options, collected) {
     }
     const priorIdentity = prior?.identity;
     const priorDurableObjects = prior?.durableObjects;
+    const worldManifest = collected.workflowWorld === "@moinulmoin/eden-world-cloudflare"
+        ? await readInstalledManifest(candidate.snapshotRoot, collected.workflowWorld)
+        : undefined;
+    const affinityEnabled = worldManifest?.eden?.capabilities?.deploymentAffinity === true;
+    const worldRpcAuth = worldManifest?.eden?.capabilities?.worldRpcAuth === true;
+    if (!affinityEnabled && priorIdentity?.retainedDeployments !== undefined) {
+        throw deploymentFailure("EVE_AFFINITY_REQUIRED", "This target retains affinity deployments; install a World package declaring deploymentAffinity before updating it.");
+    }
     const superseded = isUpdate
         ? {
             generationId: priorIdentity?.generationId,
@@ -1553,8 +1707,12 @@ async function runEveDeployment(request, options, collected) {
         if (durableWorld) {
             resultWarnings.push({
                 id: "EVE_UPDATE_IN_FLIGHT",
-                message: "This update replaces the running Container; durable World runs in flight resume on the new code — Cloudflare has no deployment pinning, so keep step names and payload shapes backward compatible.",
-                remediation: "Let pending approvals and long runs settle before updating, or keep step names, queue names, and serialized payloads compatible across the change.",
+                message: affinityEnabled
+                    ? "This update retains pinned deployments until their sessions, queue messages, and transfers drain."
+                    : "This update replaces the running Container; an Eve version change can strand existing sessions because the installed World does not declare deployment affinity.",
+                remediation: affinityEnabled
+                    ? "End old sessions to allow their deployment images to retire."
+                    : "Let sessions settle before changing Eve versions, or install an affinity-capable World package.",
             });
         }
         if (prior?.worldCloudflare !==
@@ -1595,6 +1753,80 @@ async function runEveDeployment(request, options, collected) {
         throw deploymentFailure("EVE_IMAGE_IDENTITY_UNAVAILABLE", "The deploy candidate did not provide an immutable runtime image digest.");
     }
     const targetKey = stableDeploymentKey(collected.projectId, accountId, request.environment, request.name);
+    const releaseId = `eve-deploy-${randomUUID()}`;
+    let previousEveVersion = priorIdentity?.eveVersion;
+    if (previousEveVersion === undefined && prior !== undefined) {
+        previousEveVersion = (await readInstalledManifest(join(prior.generationRoot, "container/snapshot"), "eve"))?.version;
+    }
+    const retainedDeployments = {
+        ...priorIdentity?.retainedDeployments,
+    };
+    if (affinityEnabled && priorIdentity?.retainedDeployments === undefined &&
+        priorIdentity?.containerImage !== undefined && priorIdentity.generationId !== undefined) {
+        retainedDeployments["eden-cloudflare"] = {
+            image: priorIdentity.containerImage,
+            generationId: priorIdentity.generationId,
+            ...(previousEveVersion === undefined ? {} : { eveVersion: previousEveVersion }),
+            affinityContract: EDEN_AFFINITY_CONTRACT,
+            ...(priorIdentity.runtimeRevisionHandle === undefined ? {} : { runtimeRevisionHandle: priorIdentity.runtimeRevisionHandle }),
+        };
+    }
+    const matchingDeployment = Object.entries(retainedDeployments).find(([, entry]) => entry.eveVersion === candidate.eveVersion && entry.affinityContract === EDEN_AFFINITY_CONTRACT)?.[0];
+    const deploymentId = !affinityEnabled ? releaseId : matchingDeployment ??
+        `eden-affinity-${createHash("sha256").update(`${candidate.eveVersion}:${EDEN_AFFINITY_CONTRACT}`).digest("hex").slice(0, 24)}`;
+    const retiringDeployments = { ...priorIdentity?.pendingRetirements };
+    delete retiringDeployments[deploymentId];
+    if (priorIdentity?.deploymentId !== undefined)
+        delete retiringDeployments[priorIdentity.deploymentId];
+    for (const id of prior?.protectedDeploymentIds ?? [])
+        delete retiringDeployments[id];
+    const hasRetainedNoncurrentDeployments = priorIdentity?.retainedDeployments !== undefined &&
+        Object.keys(retainedDeployments).some((id) => id !== priorIdentity.deploymentId);
+    const controlToken = `${randomUUID()}${randomUUID()}`;
+    if (affinityEnabled && (hasRetainedNoncurrentDeployments || Object.keys(retiringDeployments).length > 0)) {
+        await (options.protectedStore ?? defaultProtectedStore(request.name)).put({
+            targetId: targetKey, revision: `eve-affinity-control-${randomUUID()}`,
+            inputIdentity: {
+                token: `eve-affinity-control-input-${randomUUID()}`,
+                byteLength: Buffer.byteLength(controlToken),
+                digest: createHash("sha256").update(controlToken).digest("hex"),
+            },
+            variableNames: ["EDEN_EVE_CONTROL_TOKEN"], values: { EDEN_EVE_CONTROL_TOKEN: controlToken },
+        });
+    }
+    if (affinityEnabled && hasRetainedNoncurrentDeployments) {
+        const ids = Object.keys(retainedDeployments);
+        const raw = await (options.deploymentRpc ?? defaultDeploymentRpc)({
+            origin: stableWorkersDevOrigin, operation: "deployments.drainState", deploymentIds: ids,
+            controlToken,
+        });
+        const states = validateDeploymentDrainStates(raw, ids);
+        const eligible = ids.filter((id) => id !== deploymentId && id !== priorIdentity.deploymentId &&
+            !prior?.protectedDeploymentIds?.includes(id) && states[id]?.drained === true);
+        const remainingCount = ids.length - eligible.length + (deploymentId in retainedDeployments ? 0 : 1);
+        if (remainingCount <= 10 && eligible.length > 0) {
+            // Drain snapshots are not fences. Retire only noncurrent targets, and
+            // obtain the World's durable admission fence before dropping routes.
+            const retired = await (options.deploymentRpc ?? defaultDeploymentRpc)({
+                origin: stableWorkersDevOrigin, operation: "deployments.retire",
+                deploymentIds: eligible, controlToken,
+            });
+            if (typeof retired !== "object" || retired === null || !("retired" in retired) ||
+                !Array.isArray(retired.retired) ||
+                eligible.some((id) => !retired.retired.includes(id))) {
+                throw deploymentFailure("EVE_AFFINITY_RETIRE_UNPROVEN", "The World did not prove the noncurrent deployments durably fenced for retirement.");
+            }
+            for (const id of eligible) {
+                retiringDeployments[id] = retainedDeployments[id];
+                delete retainedDeployments[id];
+            }
+        }
+        if (Object.keys(retainedDeployments).length + (deploymentId in retainedDeployments ? 0 : 1) > 10) {
+            const blockers = Object.entries(states).filter(([id]) => id in retainedDeployments)
+                .map(([id, state]) => `${id}: ${state.liveSessions} live sessions, ${state.liveRuns} live runs, ${state.pendingMessages} pending messages, ${state.unfinishedTransfers} unfinished transfers`);
+            throw deploymentFailure("EVE_AFFINITY_LIMIT", `Deployment refused before image/code publication: at most 10 affinity deployments may be retained. Blocking deployments: ${blockers.join("; ")}`);
+        }
+    }
     let imageReference = options.containerImageReference;
     if (imageReference !== undefined) {
         if (imageDigestFromReference(imageReference) !== imageDigest) {
@@ -1607,7 +1839,7 @@ async function runEveDeployment(request, options, collected) {
         if (localImageReference === undefined || localImageReference.length === 0) {
             throw deploymentFailure("EVE_IMAGE_IDENTITY_UNAVAILABLE", "The deploy candidate did not return an exact local image handle for publication.");
         }
-        const imageRepository = `eden-eve-${targetKey}-${candidate.generationId}`;
+        const imageRepository = `eden-eve-${targetKey}-${affinityEnabled ? deploymentId : candidate.generationId}`;
         const imageTag = `${imageRepository}:${EVE_REGISTRY_IMAGE_TAG}`;
         const targetImageReference = `registry.cloudflare.com/${accountId}/${imageRepository}@${imageDigest}`;
         const imagePublication = await (options.publishImage ??
@@ -1669,7 +1901,6 @@ async function runEveDeployment(request, options, collected) {
             throw deploymentFailure("DEPLOY_INDETERMINATE", reason);
         }
     }
-    const deploymentId = `eve-deploy-${randomUUID()}`;
     const containerApplicationName = boundedResourceName(request.name, "container");
     const stableContainerInstanceName = boundedResourceName(request.name, "instance");
     const runtimeVariableNames = candidate.runtimeVariableNames;
@@ -1678,6 +1909,24 @@ async function runEveDeployment(request, options, collected) {
         sourceDigest: candidate.sourceDigest,
         generationId: candidate.generationId,
         deploymentId,
+        releaseId,
+        eveVersion: candidate.eveVersion,
+        ...(affinityEnabled ? {
+            affinityContract: EDEN_AFFINITY_CONTRACT,
+            retainedDeployments: {
+                ...retainedDeployments,
+                [deploymentId]: {
+                    image: imageReference,
+                    generationId: candidate.generationId,
+                    eveVersion: candidate.eveVersion,
+                    affinityContract: EDEN_AFFINITY_CONTRACT,
+                    releaseId,
+                    worldRpcAuth,
+                    ...(runtimeInjection?.protectedHandle === undefined ? {} : { runtimeRevisionHandle: runtimeInjection.protectedHandle }),
+                },
+            },
+            pendingRetirements: retiringDeployments,
+        } : {}),
         environment: request.environment,
         name: request.name,
         accountId,
@@ -1698,6 +1947,11 @@ async function runEveDeployment(request, options, collected) {
         containerApplicationName: identity.containerApplicationName,
         stableContainerInstanceName: identity.stableContainerInstanceName,
         deploymentId: identity.deploymentId,
+        worldRpcAuth,
+        ...(identity.releaseId === undefined ? {} : { releaseId: identity.releaseId }),
+        ...(identity.eveVersion === undefined ? {} : { eveVersion: identity.eveVersion }),
+        ...(identity.affinityContract === undefined ? {} : { affinityContract: identity.affinityContract }),
+        ...(identity.retainedDeployments === undefined ? {} : { retainedDeployments: identity.retainedDeployments }),
         generationId: identity.generationId,
         stableWorkersDevOrigin: identity.stableWorkersDevOrigin,
         containerImage: identity.containerImage,
@@ -1753,6 +2007,7 @@ async function runEveDeployment(request, options, collected) {
                 throw error;
         }
     };
+    await writeEveDeploymentRecord(candidate, identity, hostConfig, "indeterminate", { evidence: "publication-intent" }, "deployment-intent.json");
     try {
         eveProgress(options, "publishing Worker and Container application");
         publication = await publishOne(publicationRequest);
@@ -1955,7 +2210,40 @@ async function runEveDeployment(request, options, collected) {
     await promoteEveTargetPointer(join(request.projectRoot, ".eden", "eve-deploy"), `${request.environment}-${request.name}`, candidate.generationRoot);
     await options.afterPromotion?.();
     let supersededImageCleanup;
-    if (isUpdate) {
+    if (affinityEnabled && Object.keys(retiringDeployments).length > 0) {
+        const ids = Object.keys(retiringDeployments);
+        const completedRetirements = [];
+        try {
+            const result = await (options.deploymentRpc ?? defaultDeploymentRpc)({
+                origin: stableWorkersDevOrigin, operation: "deployments.retire", deploymentIds: ids,
+                controlToken,
+            });
+            if (typeof result !== "object" || result === null ||
+                !("retired" in result) || !Array.isArray(result.retired) ||
+                ids.some((id) => !result.retired.includes(id)))
+                throw new Error("Retirement was not proven.");
+            for (const [id, retained] of Object.entries(retiringDeployments)) {
+                const repository = ownedRegistryRepository({
+                    ...identity, deploymentId: id, containerImage: retained.image, generationId: retained.generationId,
+                }, request.environment, request.name, accountId);
+                if (repository !== undefined && await (options.deleteRegistryRepository ??
+                    defaultRegistryRepositoryDelete)({ repository }) === "indeterminate") {
+                    throw new Error(`Repository deletion was not proven: ${repository}`);
+                }
+                completedRetirements.push(id);
+            }
+            supersededImageCleanup = check("VAL-LIFE-007", "passed", "Drained deployment instances and their owned registry repositories were retired.");
+        }
+        catch {
+            supersededImageCleanup = check("VAL-LIFE-007", "failed", "The deployment is healthy, but drained resource retirement was not proven; exact pending retirement records were retained for retry.", "Retry deploy to finish only recorded drained resource cleanup.");
+        }
+        if (completedRetirements.length > 0) {
+            // Keep the immutable deployment record as evidence, but exclude proven
+            // cleanup from the next deploy's active retry set.
+            await writeFile(join(candidate.generationRoot, "completed-retirements.json"), `${JSON.stringify(completedRetirements)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        }
+    }
+    if (isUpdate && !affinityEnabled) {
         // The superseded generation's registry repository is generation-scoped
         // and no longer referenced once CURRENT promotes this generation; only
         // then is it safe to delete. Every tag in the repository goes with it —
@@ -2182,6 +2470,7 @@ async function collectEvePreflight(request, options) {
     if (localHint !== -1)
         warnings.splice(localHint, 1);
     warnings.push(...(await collectEveWorldWarnings(candidate, undefined)));
+    warnings.push(...await collectEveGatewayWarnings(candidate, runtimeConfig));
     const schedules = await readCompiledSchedules(candidate);
     const expressible = schedules.filter((schedule) => parseEveScheduleCron(schedule.cron) !== undefined);
     const unexpressible = schedules.filter((schedule) => parseEveScheduleCron(schedule.cron) === undefined);
@@ -2512,7 +2801,7 @@ async function readEveDestroyRecord(projectRoot, environment, name) {
     if (generationRoot === undefined) {
         return readEveDestroyRecordFromGenerations(projectRoot, environment, name);
     }
-    const parsed = await parseEveDestroyRecord(join(generationRoot, "deployment.json"), environment, name);
+    const parsed = await parseEveDestroyRecord(await deploymentRecordPath(generationRoot), environment, name);
     return parsed === undefined
         ? undefined
         : { ...parsed, generationRoot };
@@ -2526,7 +2815,7 @@ async function readEveDestroyRecordFromGenerations(projectRoot, environment, nam
         const details = await lstat(generationRoot).catch(() => undefined);
         if (details === undefined || !details.isDirectory())
             continue;
-        const recordDetails = await lstat(join(generationRoot, "deployment.json")).catch(() => undefined);
+        const recordDetails = await lstat(await deploymentRecordPath(generationRoot)).catch(() => undefined);
         if (recordDetails !== undefined && recordDetails.isFile()) {
             withRecords.push({
                 generationRoot,
@@ -2536,7 +2825,7 @@ async function readEveDestroyRecordFromGenerations(projectRoot, environment, nam
     }
     withRecords.sort((left, right) => right.modifiedAt - left.modifiedAt);
     for (const { generationRoot } of withRecords) {
-        const parsed = await parseEveDestroyRecord(join(generationRoot, "deployment.json"), environment, name);
+        const parsed = await parseEveDestroyRecord(await deploymentRecordPath(generationRoot), environment, name);
         if (parsed !== undefined) {
             return { ...parsed, generationRoot };
         }
@@ -2581,7 +2870,35 @@ async function parseEveDestroyRecord(recordPath, environment, name) {
     if (identity.environment !== environment || identity.name !== name) {
         return undefined;
     }
+    const metadata = {};
+    for (const key of ["deploymentId", "eveVersion", "releaseId", "runtimeRevisionHandle"]) {
+        if (typeof identity[key] === "string")
+            Object.assign(metadata, { [key]: identity[key] });
+    }
+    if (typeof identity.affinityContract === "number")
+        Object.assign(metadata, { affinityContract: identity.affinityContract });
+    for (const key of ["retainedDeployments", "pendingRetirements"]) {
+        const value = identity[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return undefined;
+        for (const [id, deployment] of Object.entries(value)) {
+            if (!/^(?:eden-cloudflare|eden-affinity-[a-f0-9]{24})$/u.test(id) ||
+                typeof deployment !== "object" || deployment === null ||
+                typeof deployment.image !== "string" || imageDigestFromReference(deployment.image) === undefined ||
+                typeof deployment.generationId !== "string" ||
+                (deployment.eveVersion !== undefined && typeof deployment.eveVersion !== "string") ||
+                (deployment.affinityContract !== undefined && typeof deployment.affinityContract !== "number") ||
+                (deployment.releaseId !== undefined && typeof deployment.releaseId !== "string") ||
+                (deployment.worldRpcAuth !== undefined && typeof deployment.worldRpcAuth !== "boolean") ||
+                (deployment.runtimeRevisionHandle !== undefined && typeof deployment.runtimeRevisionHandle !== "string"))
+                return undefined;
+        }
+        Object.assign(metadata, { [key]: value });
+    }
     const verified = {
+        ...metadata,
         workerName: identity.workerName,
         containerApplicationName: identity.containerApplicationName,
         stableContainerInstanceName: identity.stableContainerInstanceName,
@@ -2620,7 +2937,7 @@ async function readEveDeploymentRecord(projectRoot, environment, name, accountId
     const deploymentIds = new Set();
     for (const entry of entries) {
         const generationRoot = join(generationsRoot, entry);
-        const recordPath = join(generationRoot, "deployment.json");
+        const recordPath = await deploymentRecordPath(generationRoot);
         const details = await lstat(recordPath).catch(() => undefined);
         if (details === undefined || !details.isFile())
             continue;
@@ -2653,7 +2970,7 @@ async function readEveDeploymentRecord(projectRoot, environment, name, accountId
                 live = pinned;
             }
             else {
-                const parsed = await parseEveDeploymentRecord(join(generationRoot, "deployment.json"), environment, name);
+                const parsed = await parseEveDeploymentRecord(await deploymentRecordPath(generationRoot), environment, name);
                 if (parsed !== undefined &&
                     !((accountId !== undefined &&
                         parsed.identity.accountId !== accountId) ||
@@ -2669,10 +2986,31 @@ async function readEveDeploymentRecord(projectRoot, environment, name, accountId
     // Newest record carrying a usable DO history wins, regardless of its
     // deployment outcome: a tag it published must never be replayed.
     const historySource = scanned.find((entry) => entry.record.durableObjects !== undefined);
+    // CURRENT is only a health/promotion pointer. A newer uncertain publication
+    // may already serve sessions; preserve every such image until a later deploy
+    // can prove it drained, never infer absence from a failed health check.
+    const unresolved = scanned.filter((entry) => entry.modifiedAt > live.modifiedAt);
+    const retainedDeployments = { ...live.record.identity.retainedDeployments };
+    const pendingRetirements = { ...live.record.identity.pendingRetirements };
+    const protectedDeploymentIds = new Set();
+    if (live.record.identity.retainedDeployments === undefined) {
+        protectedDeploymentIds.add("eden-cloudflare");
+    }
+    for (const entry of unresolved.slice().reverse()) {
+        Object.assign(retainedDeployments, entry.record.identity.retainedDeployments);
+        Object.assign(pendingRetirements, entry.record.identity.pendingRetirements);
+        if (entry.record.deploymentId !== undefined)
+            protectedDeploymentIds.add(entry.record.deploymentId);
+    }
     return {
         recordPath: live.record.recordPath,
         generationRoot: live.generationRoot,
-        identity: live.record.identity,
+        identity: {
+            ...live.record.identity,
+            ...(Object.keys(retainedDeployments).length === 0 ? {} : { retainedDeployments }),
+            ...(Object.keys(pendingRetirements).length === 0 ? {} : { pendingRetirements }),
+        },
+        protectedDeploymentIds: [...protectedDeploymentIds],
         status: live.record.status,
         deploymentIds: [...deploymentIds],
         worldCloudflare: live.record.worldCloudflare,
@@ -2683,6 +3021,19 @@ async function parseEveDeploymentRecord(recordPath, environment, name) {
     const base = await parseEveDestroyRecord(recordPath, environment, name);
     if (base === undefined)
         return undefined;
+    let identity = base.identity;
+    try {
+        const completed = JSON.parse(await readFile(join(dirname(recordPath), "completed-retirements.json"), "utf8"));
+        if (Array.isArray(completed) && completed.every((id) => typeof id === "string")) {
+            const pendingRetirements = { ...identity.pendingRetirements };
+            for (const id of completed)
+                delete pendingRetirements[id];
+            identity = { ...identity, pendingRetirements };
+        }
+    }
+    catch {
+        // Missing or unreadable cleanup evidence must not suppress a retry.
+    }
     let parsed;
     try {
         parsed = JSON.parse(await readFile(recordPath, "utf8"));
@@ -2726,7 +3077,7 @@ async function parseEveDeploymentRecord(recordPath, environment, name) {
         Array.isArray(rawMigrations);
     const invalidHistory = () => ({
         recordPath,
-        identity: base.identity,
+        identity,
         status,
         deploymentId,
         worldCloudflare: rawVars?.EDEN_EVE_WORLD_CLOUDFLARE === true,
@@ -2753,7 +3104,7 @@ async function parseEveDeploymentRecord(recordPath, environment, name) {
     }
     return {
         recordPath,
-        identity: base.identity,
+        identity,
         status,
         deploymentId,
         worldCloudflare: rawVars?.EDEN_EVE_WORLD_CLOUDFLARE === true,
@@ -2775,7 +3126,7 @@ async function defaultDestroyTargetRead(request) {
             "images",
             "list",
             "--json",
-        ]);
+        ], WRANGLER_OPERATION_TIMEOUT_MS);
         const tagsByRepository = registryTagsByRepository(images.value);
         if (!images.failed && tagsByRepository !== undefined) {
             const present = [];
@@ -2854,12 +3205,13 @@ async function defaultContainerDelete(request) {
  * repository is deleted individually.
  */
 async function defaultRegistryRepositoryDelete(request) {
+    // Catalog reads include Cloudflare snapshot tags and can exceed 30 seconds.
     const images = await readWranglerJson([
         "containers",
         "images",
         "list",
         "--json",
-    ]);
+    ], WRANGLER_OPERATION_TIMEOUT_MS);
     const collection = jsonCollection(images.value);
     if (images.failed || collection === undefined)
         return "indeterminate";
@@ -2885,9 +3237,11 @@ async function defaultRegistryRepositoryDelete(request) {
             deletedAny = true;
             continue;
         }
-        if (!/(?:does not exist|not found|404)/iu.test(result.stderr)) {
-            return "indeterminate";
-        }
+    }
+    const after = await readWranglerJson(["containers", "images", "list", "--json"], WRANGLER_OPERATION_TIMEOUT_MS);
+    const remaining = after.failed ? undefined : registryTagsByRepository(after.value);
+    if (remaining === undefined || (remaining.get(request.repository)?.length ?? 0) > 0) {
+        return "indeterminate";
     }
     return deletedAny ? "deleted" : "absent";
 }
@@ -2905,13 +3259,13 @@ function ownedRegistryRepository(identity, environment, name, accountId) {
         identity.accountId !== accountId) {
         return undefined;
     }
-    const repository = `eden-eve-${stableDeploymentKey(identity.projectId, identity.accountId, environment, name)}-${identity.generationId}`;
-    const expected = `registry.cloudflare.com/${identity.accountId}/${repository}@`;
-    if (!identity.containerImage.startsWith(expected) ||
-        imageDigestFromReference(identity.containerImage) === undefined) {
+    const prefix = `eden-eve-${stableDeploymentKey(identity.projectId, identity.accountId, environment, name)}-`;
+    const suffixes = [identity.generationId];
+    if (identity.retainedDeployments !== undefined && identity.deploymentId !== undefined)
+        suffixes.push(identity.deploymentId);
+    if (imageDigestFromReference(identity.containerImage) === undefined)
         return undefined;
-    }
-    return repository;
+    return suffixes.map((suffix) => `${prefix}${suffix}`).find((repository) => identity.containerImage.startsWith(`registry.cloudflare.com/${identity.accountId}/${repository}@`));
 }
 /**
  * The registry repository an indeterminate deploy attempt provably pushed.
@@ -2964,17 +3318,31 @@ async function collectEveDestroyRegistryRepositories(projectRoot, environment, n
     const generationsRoot = join(projectRoot, ".eden", "eve-deploy", "generations");
     const entries = await readdir(generationsRoot).catch(() => []);
     const repositories = new Set();
+    const addRetained = (identity) => {
+        for (const [id, retained] of Object.entries({
+            ...identity.retainedDeployments, ...identity.pendingRetirements,
+        })) {
+            const repository = ownedRegistryRepository({
+                ...identity, deploymentId: id, containerImage: retained.image, generationId: retained.generationId,
+            }, environment, name, record.accountId);
+            if (repository !== undefined)
+                repositories.add(repository);
+        }
+    };
+    addRetained(record);
     const targetKey = record.projectId === undefined
         ? undefined
         : stableDeploymentKey(record.projectId, record.accountId, environment, name);
     for (const entry of entries) {
         const generationRoot = join(generationsRoot, entry);
-        const parsed = await parseEveDestroyRecord(join(generationRoot, "deployment.json"), environment, name);
+        const parsed = await parseEveDestroyRecord(await deploymentRecordPath(generationRoot), environment, name);
         const deployedRepository = parsed === undefined
             ? undefined
             : ownedRegistryRepository(parsed.identity, environment, name, record.accountId);
         if (deployedRepository !== undefined)
             repositories.add(deployedRepository);
+        if (parsed !== undefined)
+            addRetained(parsed.identity);
         if (targetKey === undefined)
             continue;
         const attemptRepository = await attemptRegistryRepository(join(generationRoot, "deployment-attempt.json"), record.accountId, targetKey);

package/dist/eve-runtime-config.d.ts

@@ -1,4 +1,4 @@
-export declare const EVE_RESERVED_HOST_VARIABLES: readonly ["HOST", "NITRO_HOST", "PORT", "NITRO_PORT", "NODE_ENV", "NODE_EXTRA_CA_CERTS", "WORKFLOW_LOCAL_BASE_URL", "EDEN_WORLD_URL", "EDEN_EVE_DEPLOYMENT_ID", "EDEN_EVE_GENERATION_ID"];
+export declare const EVE_RESERVED_HOST_VARIABLES: readonly ["HOST", "NITRO_HOST", "PORT", "NITRO_PORT", "NODE_ENV", "NODE_EXTRA_CA_CERTS", "WORKFLOW_LOCAL_BASE_URL", "EDEN_WORLD_URL", "EDEN_WORLD_TOKEN", "EDEN_EVE_WORLD_RPC_AUTH", "EDEN_EVE_DEPLOYMENT_ID", "EDEN_EVE_GENERATION_ID", "EDEN_EVE_RELEASE_ID", "EDEN_EVE_DEPLOYMENTS", "EDEN_AFFINITY_CONTRACT", "EVE_SCHEDULES_DISABLED", "EDEN_EVE_CONTROL_TOKEN"];
 export type EveReservedHostVariable = (typeof EVE_RESERVED_HOST_VARIABLES)[number];
 export declare const EVE_START_COMMAND: readonly ["./node_modules/.bin/eve", "start", "--host", "0.0.0.0", "--port", "8080"];
 export declare const EVE_HOST_ENVIRONMENT: Readonly<{

package/dist/eve-runtime-config.js

@@ -10,8 +10,15 @@ export const EVE_RESERVED_HOST_VARIABLES = Object.freeze([
     "NODE_EXTRA_CA_CERTS",
     "WORKFLOW_LOCAL_BASE_URL",
     "EDEN_WORLD_URL",
+    "EDEN_WORLD_TOKEN",
+    "EDEN_EVE_WORLD_RPC_AUTH",
     "EDEN_EVE_DEPLOYMENT_ID",
     "EDEN_EVE_GENERATION_ID",
+    "EDEN_EVE_RELEASE_ID",
+    "EDEN_EVE_DEPLOYMENTS",
+    "EDEN_AFFINITY_CONTRACT",
+    "EVE_SCHEDULES_DISABLED",
+    "EDEN_EVE_CONTROL_TOKEN",
 ]);
 export const EVE_START_COMMAND = Object.freeze([
     "./node_modules/.bin/eve",

package/dist/eve-runtime-image.js

@@ -458,6 +458,7 @@ COPY node_modules /candidate/node_modules
 ${sandboxContextCopy}${sourceEntries.map((entry) => `COPY ${JSON.stringify([entry, `/candidate/${entry}`])}`).join("\n")}
 
 FROM --platform=linux/amd64 ${imageReference(nodeImage)} AS runtime
+RUN apt-get update && apt-get install -y --no-install-recommends python3 && rm -rf /var/lib/apt/lists/*
 WORKDIR /workspace
 ENV HOST=0.0.0.0 \\
     NITRO_HOST=0.0.0.0 \\
@@ -582,6 +583,8 @@ function runtimeContainerEnvironment(request) {
         ...(request.workflowWorld === "@moinulmoin/eden-world-cloudflare"
             ? {
                 EDEN_WORLD_URL: `${request.publicOrigin ?? "http://localhost:8080"}/__eden/world/rpc`,
+                EDEN_EVE_DEPLOYMENT_ID: `eden-smoke-${request.candidate.generationId}`,
+                EDEN_EVE_RELEASE_ID: `eden-smoke-${request.candidate.generationId}`,
                 CBOR_NATIVE_ACCELERATION_DISABLED: "true",
             }
             : {}),

package/dist/index.js

@@ -17,6 +17,7 @@ Commands:
   preflight  Build and inspect a local Eve candidate without remote mutation
   deploy     Deploy the selected Eve project to the exact named target
   destroy    Remove the exact owned Eve target
+  skill      Print the bundled Eden skill for coding agents
 
 preflight and deploy default to the current directory, the preview
 environment, and a target name derived from package.json. destroy and
@@ -177,6 +178,24 @@ export async function runEdenCli(args, options = {}) {
             stdout(edenVersion());
             return 0;
         }
+        if (args[0] === "skill") {
+            if (args.length === 2 && (args[1] === "--help" || args[1] === "-h")) {
+                stdout("Usage: eden skill");
+                return 0;
+            }
+            if (args.length !== 1) {
+                throw new EveCliError({
+                    code: "EVE_ARGUMENT_UNKNOWN",
+                    message: "eden skill takes no arguments or options.",
+                });
+            }
+            const skill = readFileSync(new URL("./SKILL.md", import.meta.url), "utf8");
+            if (options.stdout === undefined)
+                process.stdout.write(skill);
+            else
+                options.stdout(skill);
+            return 0;
+        }
         if (!EVE_CLI_COMMANDS.includes(args[0] ?? "")) {
             throw new EveCliError({
                 code: "COMMAND_UNKNOWN",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moinulmoin/eden",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Deploy existing Eve projects to your own Cloudflare account.",
   "keywords": [
     "ai",
@@ -27,11 +27,12 @@
     "dist/**/*.js",
     "dist/**/*.mjs",
     "dist/**/*.d.ts",
+    "dist/SKILL.md",
     "LICENSE",
     "NOTICE"
   ],
   "dependencies": {
-    "@moinulmoin/eden-runtime-cloudflare": "0.9.0",
+    "@moinulmoin/eden-runtime-cloudflare": "0.11.0",
     "wrangler": "4.147.0"
   },
   "devDependencies": {
@@ -54,7 +55,7 @@
   },
   "scripts": {
     "build": "tsc -b",
-    "postbuild": "chmod 755 dist/index.js",
+    "postbuild": "chmod 755 dist/index.js && cp ../../skills/eden/SKILL.md dist/SKILL.md",
     "typecheck": "tsc -b --pretty false",
     "lint": "eslint src --max-warnings 0",
     "test": "pnpm --dir ../.. exec vitest run packages/cli/test --passWithNoTests --maxWorkers=1"