@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/tenant/{environments.js → agents.js}

@@ -1,49 +1,53 @@
 /**
- * Environments (D55, D56, protocol 11): `PUT`, `GET` and `DELETE /v1/environments/{id}`, the
- * list by label, stop, reset and the lifecycle stream; sessions naming one with `environment`,
- * and the checks every turn start makes on it.
+ * Agents (protocol 16; Environments from protocol 11, D55, D56): `PUT`, `GET` and `DELETE
+ * /v1/agents/{id}`, the list, stop, reset, fork and the lifecycle stream; sessions on one, and the
+ * checks every turn start makes on it.
  *
- * - **No scope.** The Runtime decides nothing about who uses an Environment: the app maps its
- *   people and agents to ids. It stores the id, kind, recipe, labels and the optional owner
- *   guard; the session body names the Environment (`Session.environmentId`), and deleting a
- *   session (a sessions reset) only detaches it.
- * - **One sandbox, one vault.** Kind `virtual` (a just-bash workspace in the harness container,
- *   keyed by the Environment id and created on the first tool call), `pod` (an agent-sandbox pod
- *   on the Tenant's cluster, Host feature `sandbox-pods`, created at once) or `none` (no compute).
- *   Each has one vault (`vault/service.ts`), created and deleted with it in one transaction.
- * - **Made once, never changed** (protocol 14, D63). An Environment is made from one version of
- *   an environment manifest (`manifest: "name"` or `"name@n"`, `environment-manifests.ts`) or
- *   from an inline manifest (the fields of the `PUT`, its `recipe`), and keeps what it runs for
- *   life: a `PUT` on an existing id may change its labels and owner guard, a field that matches
- *   what it runs is accepted (so get-or-create stays one call), and anything else is
- *   `409 environment_immutable`, naming the fork that makes a new Environment instead.
- *   `version` and `appliedVersion` stay 1 for an Environment made since then.
- * - **Secret slots** (D64): when what it runs declares `secrets`, a secret write sends only the
+ * - **The instance of a manifest.** An Agent is made from one version of a saved agent manifest
+ *   (`manifest: "name"`, tracking, or `"name@n"`, pinned; `agent-manifests.ts`) and runs one
+ *   version of it at a time (`resolvedVersion`). A `PUT` on an existing id may change its labels
+ *   and owner guard, and moves it to the version its `manifest` names (track T3,
+ *   `agent-versions.ts`; `?dryRun=true` answers the plan); a save moves every Agent that tracks
+ *   the manifest. Its manifest's name, kind, harness and storage are fixed for its life: a fork
+ *   makes a new Agent to change them. Its kind is its manifest's `runtime.kind` (`none` without a
+ *   runtime section).
+ * - **No scope, no main session** (D70, D71). The Runtime decides nothing about who uses an
+ *   Agent or which sessions it has: the app opens sessions on it with ids it picks, and deleting
+ *   a session (a sessions reset) only detaches it.
+ * - **Its environment: one sandbox, one vault.** Kind `virtual` (a just-bash workspace in the
+ *   harness container, keyed by the Agent id and created on the first tool call), `pod` (an
+ *   agent-sandbox pod on the Tenant's cluster, Host feature `sandbox-pods`, created at once) or
+ *   `none` (no compute). Each has one vault (`vault/service.ts`), created and deleted with it in
+ *   one transaction. The store calls this part the Agent's environment (`Environment`, keyed by
+ *   the Agent's id).
+ * - **State on read.** `state` is derived when it is read, the first rule that holds: `paused`
+ *   (desired `off`, track T6), `failing` (its compute failed or was lost, or a session's last
+ *   turn failed), `input_required` (a session waits on a person), `working` (a turn runs),
+ *   `sleeping`; `attention` names the sessions behind each that holds (`stateOf`).
+ * - **Secret slots** (D64): when its manifest declares `secrets`, a secret write sends only the
  *   value, the binding comes from the slot, and a name it does not declare is
  *   `409 secret_not_in_manifest` (`secretRequestFor`).
- * - **Access.** An application key reaches every Environment, and so does an application key
- *   acting for a subject (`Nylorun-Subject`), which needs `environments:write` to change one. A
- *   token caller reaches only the ids its grants match, and changes them only with
- *   `environments:write`; any other id is the 404 of a missing one.
- * - **The owner guard.** When `ownerUserId` is set, only that owner's sessions may name the
- *   Environment, checked when a session opens and at every turn start (`403
- *   environment_owner_mismatch`; the opaque 404 to a caller acting for a person).
- * - **Parallel turns (D66).** Sessions on one Environment run their turns at the same time and
- *   share its `/workspace`; one turn per session stays. Which sessions work on one disk, and when,
- *   is the app's call. Disk work (snapshot, restore, stop, reset) waits until no turn runs
- *   (`409 environment_busy`), and a turn waits while a seed copies a disk.
+ * - **Access.** An application key reaches every Agent, and so does an application key acting
+ *   for a subject (`Nylorun-Subject`), which needs `agents:write` to change one. A token caller
+ *   reaches only the ids its Agent grants match, and changes them only with `agents:write`; any
+ *   other id is the 404 of a missing one.
+ * - **The owner guard.** When `owner` is set, only that owner's sessions may run on the Agent,
+ *   checked when a session opens and at every turn start (`403 agent_owner_mismatch`; the opaque
+ *   404 to a caller acting for a person).
+ * - **Parallel turns (D66).** Sessions on one Agent run their turns at the same time and share
+ *   its `/workspace`; one turn per session stays. Disk work (snapshot, restore, stop, reset)
+ *   waits until no turn runs (`409 agent_busy`), and a turn waits while a seed copies a disk.
  * - **Lifecycle.** `POST .../stop` suspends a pod (the volume is kept; the next turn starts it),
- *   `POST .../reset` gives it a new pod on a new volume. A lost pod refuses turns
- *   (`environment_lost`) until a reset. `lifecycle.deleteAfter` deletes an Environment unused
- *   for that long (the Tenant sweep, `sweepUnusedEnvironments`). Deleting a pod Environment keeps
- *   its row (`desired: deleted`, invisible here) until its Sandbox is gone; its vault goes at once.
- * - **Lifecycle events** go to the Environment's own stream in the record (`Tx.environmentEvent`,
- *   `record/environment.ts`); the session's log records `environment.attached` too.
+ *   `POST .../reset` gives it a new pod on a new volume. A lost pod refuses turns (`agent_lost`)
+ *   until a reset. `lifecycle.deleteAfter` deletes an Agent unused for that long (the Tenant
+ *   sweep, `sweepUnusedAgents`). Deleting a pod Agent keeps its row (`desired: deleted`, invisible
+ *   here) until its Sandbox is gone; its vault goes at once.
+ * - **Lifecycle events** go to the Agent's own stream in the record (`Tx.agentEvent`,
+ *   `record/agent.ts`); the session's log records `agent.attached` too.
  */
 import { randomUUID } from "node:crypto";
-import { environmentGranted, parseEnvironmentManifestRef, PutEnvironmentSecretRequestSchema, PutEnvironmentSecretValueRequestSchema, } from "@nylorun/core/contracts";
-import { hashManifest } from "@nylorun/core/compatibility";
-import { isWorkflowManifest, parseSandboxDuration } from "@nylorun/core/define";
+import { agentGranted, parseAgentManifestRef, PutAgentSecretRequestSchema, PutAgentSecretValueRequestSchema, } from "@nylorun/core/contracts";
+import { isWorkflowManifest, parseSandboxDuration, runtimeOf } from "@nylorun/core/define";
 import { canonical } from "../store/canonical.js";
 import { resolveRecipe } from "../sandbox/resolve.js";
 import { sandboxWorkspaceKey } from "../sandbox/records.js";
@@ -53,15 +57,18 @@ import { podLifecycleConfig } from "../sandbox/pods/spec.js";
 import { SETUP_FAILED } from "../sandbox/pods/lifecycle.js";
 import { requirePods } from "../sandbox/placement.js";
 import { deleteDiskArtifact, forkSeedOf, runPendingSeed, snapshotEnvironment } from "../artifacts/disk.js";
-import { manifestChanges, manifestRecipeRequest } from "./environment-manifests.js";
+import { manifestChanges, manifestRecipeRequest } from "./agent-manifests.js";
+import { idleMsOf, moveAgent, planMove, resumeMove, switchTo, waitingFor } from "./agent-versions.js";
+import { slotHolds } from "../vault/service.js";
 import { labelIssues, limitIssues, limitsInForce, manifestShapeIssues, readTenantLimits, secretRequestIssues, } from "./limits.js";
 import { readRuntimeLimits } from "./runtime-limits.js";
+import { armAgentTriggers, createAgentTriggers } from "./triggers.js";
 import { harnessOf, sessionOf } from "./context.js";
 import { fail, failRetryLater } from "./http.js";
 import { hostTuning } from "../tuning.js";
-/** The Environment grants that limit `scope`, or undefined when it reaches every Environment. */
-export function environmentGrantsOf(scope) {
-    return scope.kind === "token" ? (scope.environments ?? []) : undefined;
+/** The Agent grants that limit `scope`, or undefined when it reaches every Agent. */
+export function agentGrantsOf(scope) {
+    return scope.kind === "token" && scope.agents !== "*" ? [...scope.agents] : undefined;
 }
 /** The subject a request acts for, when it acts for one. */
 function subjectOf(scope) {
@@ -71,21 +78,21 @@ function subjectOf(scope) {
 export function actorOf(scope) {
     return subjectOf(scope) ?? "application";
 }
-const notFound = () => fail(404, "Environment not found");
-/** The Environment, when `grants` reach it; otherwise the 404 of a missing one. */
+const notFound = () => fail(404, "Agent not found");
+/** The Agent, when `grants` reach it; otherwise the 404 of a missing one. */
 function reachable(grants, id) {
-    if (grants !== undefined && !environmentGranted(grants, id))
+    if (grants !== undefined && !agentGranted(grants, id))
         notFound();
 }
-/** Refuses (the 404 of a missing one) Environment `id` when the caller's grants miss it. */
+/** Refuses (the 404 of a missing one) Agent `id` when the caller's grants miss it. */
 export function assertReaches(scope, id) {
-    reachable(environmentGrantsOf(scope), id);
+    reachable(agentGrantsOf(scope), id);
 }
-/** A pod Environment being deleted is no longer an Environment, here. */
+/** A pod Agent being deleted is no longer an Agent, here. */
 function live(row) {
     return row?.pod?.desired === "deleted" ? undefined : row;
 }
-/** An Environment, unless it is gone or being deleted. */
+/** An Agent's row, unless it is gone or being deleted. */
 export async function liveEnvironment(t, id, options = {}) {
     return live(await t.environment(id, options));
 }
@@ -97,113 +104,147 @@ function podState(pod) {
         return "creating";
     return "stopped";
 }
+/** The order the states rank in: the first that holds is the Agent's. */
+const STATE_RANK = ["paused", "failing", "input_required", "working", "sleeping"];
+/**
+ * An Agent's state (protocol 16), from its desired state, its compute and its sessions, and
+ * every state that holds with the session behind it (`attention`), highest first. A session waits
+ * on a person while it is paused (an approval or an interaction) or uncertain, and the Agent while
+ * a move waits for its required secrets (track T3); a session's last turn
+ * failed while it is `failed`; a turn runs while it is `running`, `runnable` or `waiting`.
+ */
+export function stateOf(agent, sessions) {
+    const attention = [];
+    if (agent.desiredState === "off")
+        attention.push({ state: "paused", reason: "desired off" });
+    // A move that waits for a person to set its required secrets (track T3).
+    if (agent.targetVersion !== undefined && agent.appliedVersion === agent.version)
+        attention.push({ state: "input_required", reason: `secret_required: version ${agent.targetVersion} waits for its required secrets` });
+    const pod = agent.pod;
+    if (pod && (pod.observed === "failed" || pod.observed === "lost") && pod.desired !== "deleted")
+        attention.push({ state: "failing", reason: `compute ${pod.observed}${pod.reason ? `: ${pod.reason}` : ""}` });
+    // A start on a new version failed and went back (track T3): until a start on a new one succeeds.
+    if (agent.failedVersion !== undefined)
+        attention.push({ state: "failing", reason: `start_failed: version ${agent.failedVersion} did not start` });
+    for (const session of sessions) {
+        const status = String(session.status);
+        const state = status === "failed"
+            ? "failing"
+            : status === "paused" || status === "uncertain"
+                ? "input_required"
+                : status === "running" || status === "runnable" || status === "waiting"
+                    ? "working"
+                    : undefined;
+        if (state)
+            attention.push({ state, sessionId: session.id, reason: status });
+    }
+    attention.sort((a, b) => STATE_RANK.indexOf(a.state) - STATE_RANK.indexOf(b.state));
+    return { state: attention[0]?.state ?? "sleeping", attention };
+}
+/** How an Agent names its manifest: `name` when it tracks it, `name@n` when pinned. */
+export function manifestRefOf(agent) {
+    return agent.manifestRef === "tracking" ? agent.manifestName : `${agent.manifestName}@${agent.manifestVersion}`;
+}
 async function viewOf(ctx, t, environment, owner) {
     const sessions = await t.sessionsOnEnvironment(environment.id);
     const record = environment.kind === "virtual"
         ? await t.get("sandboxes", sandboxWorkspaceKey(ctx.config.tenantId, environment.id))
         : undefined;
     const pod = environment.pod;
-    const slots = await slotsOf(t, environment);
+    const visible = sessions.filter((session) => owner === undefined || session.ownerUserId === owner);
+    const { state, attention } = stateOf(environment, visible);
     return {
         id: environment.id,
+        manifest: manifestRefOf(environment),
+        resolvedVersion: environment.manifestVersion,
+        manifestHash: environment.manifestHash,
+        tracking: environment.manifestRef,
+        targetVersion: environment.targetVersion ?? null,
+        waitingFor: waitingFor(environment),
+        failedVersion: environment.failedVersion ?? null,
+        startCheck: environment.startCheck
+            ? { from: environment.startCheck.from.manifestVersion, startedAt: environment.startCheck.startedAt }
+            : null,
         kind: environment.kind,
+        harness: environment.applied.harness,
+        owner: environment.ownerUserId ?? null,
         labels: environment.labels,
-        manifest: environment.recipe,
-        ...(environment.manifestName === undefined ? {} : { manifestName: environment.manifestName }),
-        ...(environment.manifestVersion === undefined ? {} : { manifestVersion: environment.manifestVersion }),
-        ...(environment.manifestHash === undefined ? {} : { manifestHash: environment.manifestHash }),
+        state,
+        attention,
+        desired: environment.desiredState,
+        nextWakeAt: await t.nextWakeAt(environment.id),
+        compute: {
+            state: pod ? podState(pod) : environment.kind === "none" ? "ready" : (record?.state ?? "ready"),
+            ...(pod
+                ? {
+                    pod: {
+                        desired: pod.desired,
+                        observed: pod.observed,
+                        volumeGeneration: pod.volumeGen,
+                        hostEpoch: pod.hostEpoch,
+                        ...(pod.reason ? { reason: pod.reason } : {}),
+                        ...(pod.imageDigest ? { imageDigest: pod.imageDigest } : {}),
+                    },
+                }
+                : {}),
+        },
+        runtime: environment.applied,
         limits: limitsInForce(await readTenantLimits(t), environment.applied.limits),
-        ...(environment.forkedFrom === undefined ? {} : { forkedFrom: environment.forkedFrom }),
-        ...(slots === undefined ? {} : { slots }),
-        version: environment.version,
-        appliedVersion: environment.appliedVersion,
-        ownerUserId: environment.ownerUserId ?? null,
-        state: pod ? podState(pod) : environment.kind === "none" ? "ready" : (record?.state ?? "ready"),
-        ...(pod
-            ? {
-                pod: {
-                    desired: pod.desired,
-                    observed: pod.observed,
-                    volumeGeneration: pod.volumeGen,
-                    hostEpoch: pod.hostEpoch,
-                    ...(pod.reason ? { reason: pod.reason } : {}),
-                    ...(pod.imageDigest ? { imageDigest: pod.imageDigest } : {}),
-                },
-            }
-            : {}),
-        lastUsedAt: environment.lastUsedAt,
+        sessions: visible.map((session) => ({
+            id: session.id,
+            ownerUserId: session.ownerUserId,
+            status: String(session.status),
+            activeTurnId: session.activeTurnId,
+        })),
+        slots: (await slotsOf(t, environment)) ?? [],
         ...(environment.kind === "none"
             ? {}
             : {
                 disk: {
                     latestVersion: (await t.diskArtifact(environment.id))?.latestVersion || null,
-                    ...(diskHeld(environment)
+                    operation: diskHeld(environment)
                         ? {
-                            operation: {
-                                kind: environment.diskOp.kind,
-                                ...(environment.diskOp.version === undefined ? {} : { version: environment.diskOp.version }),
-                                startedAt: environment.diskOp.startedAt,
-                            },
+                            kind: environment.diskOp.kind,
+                            ...(environment.diskOp.version === undefined ? {} : { version: environment.diskOp.version }),
+                            startedAt: environment.diskOp.startedAt,
                         }
-                        : {}),
+                        : null,
                 },
             }),
-        sessions: sessions
-            .filter((session) => owner === undefined || session.ownerUserId === owner)
-            .map((session) => ({ id: session.id, activeTurnId: session.activeTurnId })),
+        forkedFrom: environment.forkedFrom ?? null,
+        lastUsedAt: environment.lastUsedAt,
         createdAt: environment.createdAt,
         updatedAt: environment.updatedAt,
     };
 }
-/** Each secret slot `environment` declares, and whether its vault holds a value for it. */
+/**
+ * The secret slots a secret write fills (D64): the version `environment` moves to while it is
+ * outdated (track T3), so its new slots can be set before it applies, else the one it runs.
+ */
+async function slotsAhead(t, environment) {
+    if (environment.targetVersion === undefined)
+        return environment.applied.secrets;
+    // Waiting for its pod's start, `recipe` is the target's runtime.
+    if (environment.appliedVersion !== environment.version)
+        return environment.recipe.secrets;
+    const target = await t.agentManifest(environment.manifestName, environment.targetVersion);
+    return target ? runtimeOf(target.body).secrets : environment.applied.secrets;
+}
+/** Each secret slot `environment` declares (`slotsAhead`), and whether its vault holds a value that fills it. */
 async function slotsOf(t, environment) {
-    const declared = environment.recipe.secrets;
+    const declared = await slotsAhead(t, environment);
     if (declared === undefined)
         return undefined;
     const vault = await t.vaultOfEnvironment(environment.id);
-    const held = new Set(vault ? (await t.credentialsForVault(vault.id)).map((row) => row.name) : []);
+    const rows = vault ? await t.credentialsForVault(vault.id) : [];
     return Object.entries(declared)
         .sort(([a], [b]) => a.localeCompare(b))
-        .map(([name, slot]) => ({ name, type: slot.type, required: slot.required ?? false, set: held.has(name) }));
-}
-/** The inline fields of a `PUT`: what it would run, besides labels, owner and `from`. */
-const INLINE_FIELDS = [
-    "kind",
-    "image",
-    "resources",
-    "storage",
-    "network",
-    "harness",
-    "lifecycle",
-    "setup",
-    "files",
-    "limits",
-    "secrets",
-];
-/** The hash of what an Environment runs, recorded when it is made. */
-function recipeHash(recipe) {
-    return hashManifest(recipe);
-}
-/** What a `PUT` asks of the recipe: its fields over `existing`'s (fixed `storage` kept). */
-function recipeRequest(body, existing) {
-    const recipe = existing?.recipe;
-    const pick = (key, sent) => sent !== undefined ? { [key]: sent } : recipe?.[key] !== undefined ? { [key]: recipe[key] } : {};
-    return {
-        ...pick("image", body.image),
-        ...pick("resources", body.resources),
-        ...(recipe?.storage !== undefined
-            ? { storage: recipe.storage }
-            : body.storage !== undefined
-                ? { storage: body.storage }
-                : {}),
-        ...pick("network", body.network),
-        ...pick("harness", body.harness),
-        ...pick("lifecycle", body.lifecycle),
-        ...pick("setup", body.setup),
-        ...pick("files", body.files),
-        ...pick("limits", body.limits),
-        ...pick("secrets", body.secrets),
-    };
+        .map(([name, slot]) => ({
+        name,
+        type: slot.type,
+        required: slot.required ?? false,
+        set: rows.some((row) => row.name === name && slotHolds(slot, row)),
+    }));
 }
 /**
  * Why input files cannot be used: each that is not a version of a Tenant-wide artifact (a
@@ -241,7 +282,7 @@ function checkGuard(scope, asked, current) {
     if (subject === undefined || asked === undefined)
         return;
     if (asked === null ? (current !== undefined && current !== subject) : asked !== subject)
-        fail(403, "A request acting for a person may set ownerUserId only to that person.");
+        fail(403, "A request acting for a person may set owner only to that person.");
 }
 /** Asks for a pod's reconcile once the transaction commits (the sandbox signal outbox). */
 function reconcileAfter(t, id) {
@@ -268,7 +309,8 @@ async function wantRunning(t, environment, now) {
         await t.updateEnvironmentPod(environment.id, { observed: "creating", startedAt: now, lastActiveAt: now, reason: null }, now);
         return;
     }
-    if (environment.appliedVersion !== environment.version)
+    // A move whose runtime waits for this start switches now (track T3).
+    if (!(await switchTo(t, environment, now)) && environment.appliedVersion !== environment.version)
         await t.updateEnvironment(environment.id, { applied: environment.recipe, appliedVersion: environment.version }, now);
     await t.updateEnvironmentPod(environment.id, {
         desired: "running",
@@ -280,87 +322,48 @@ async function wantRunning(t, environment, now) {
     }, now);
 }
 /**
- * `PUT /v1/environments/{id}`: creates the Environment and its vault (within the Tenant's limit
- * on their number) from an environment manifest's version or from the inline fields, or finds
- * the one with this id, so "get or create" is one call. An existing one never changes what it
- * runs (D63): its labels and owner guard may change, fields that match are accepted, and any
- * other difference is `409 environment_immutable`. Every `PUT` counts as the Environment's use.
+ * `PUT /v1/agents/{id}`: creates the Agent and its vault (within the Tenant's limit on their
+ * number) from a saved agent manifest's version, or finds the one with this id, so "get or
+ * create" is one call. On an existing one, its labels and owner guard may change, and `manifest`
+ * moves it to the version it names (track T3, `moveAgent`): `name` tracks the latest (unless that
+ * failed to start), `name@n` pins `n`. Another manifest name is `409 agent_fixed_field`. Every
+ * `PUT` counts as the Agent's use.
  */
-export async function putEnvironment(ctx, id, body, scope, options = {}) {
+export async function putAgent(ctx, id, body, scope, options = {}) {
     const fork = options.fork;
-    reachable(environmentGrantsOf(scope), id);
-    const ref = body.manifest === undefined ? undefined : parseEnvironmentManifestRef(body.manifest);
-    if (body.manifest !== undefined) {
-        if (ref === undefined)
-            fail(400, "manifest is an environment manifest's name, or name@version such as analyst-box@3.");
-        const inline = INLINE_FIELDS.filter((field) => body[field] !== undefined);
-        if (inline.length > 0)
-            fail(400, `An Environment made from manifest ${body.manifest} runs what the manifest says: send no ${inline.join(", ")} with it.`);
-    }
-    if (body.kind === "pod")
-        await requirePods(ctx.pods, "A pod Environment");
-    const immutable = (fields, existing) => fail(409, `Environment ${id} exists and never changes what it runs (${fields.join(", ")} differ${fields.length === 1 ? "s" : ""}): fork it into a new Environment with POST /v1/environments/${encodeURIComponent(id)}/fork, or use another id.`, {
-        code: "environment_immutable",
-        details: {
-            fields: [...fields],
-            ...(existing.manifestName === undefined
-                ? {}
-                : { manifest: `${existing.manifestName}@${existing.manifestVersion}` }),
-        },
-    });
+    reachable(agentGrantsOf(scope), id);
+    const ref = parseAgentManifestRef(body.manifest) ??
+        fail(400, "manifest is an agent manifest's name, or name@version such as triage@3.");
     const view = await ctx.store.tx(async (t) => {
         const now = new Date().toISOString();
         const config = effectiveSandboxConfig(await readSandboxConfig(t));
         const tenantLimits = await readTenantLimits(t);
         const runtimeLimits = await readRuntimeLimits(t);
-        // `limits` and the manifest's shape are checked against the Tenant's only when an Environment
-        // is made: a get-or-create on one made before the Tenant lowered a limit still answers, and
-        // the lower limit applies. Labels are checked whenever they are set.
+        // Labels are checked whenever they are set; what it runs only when it is made, so a
+        // get-or-create on one made before the Tenant lowered a limit still answers.
         const labels = labelIssues(body.labels, runtimeLimits);
         if (labels.length > 0)
             fail(400, labels.join(" "));
-        const resolve = (kind, request, creating) => {
-            const resolved = resolveRecipe(kind, request, config);
-            const errors = [
-                ...(resolved.kind === "error" ? resolved.errors : []),
-                ...(creating ? [...limitIssues(request.limits, tenantLimits), ...manifestShapeIssues(request, runtimeLimits)] : []),
-            ];
-            return resolved.kind === "error" || errors.length > 0 ? fail(400, errors.join(" ")) : resolved.recipe;
-        };
         const deleting = (row) => {
             if (row && !live(row))
-                failRetryLater(`Environment ${id} is being deleted. Try again once it is gone.`, "environment_busy");
+                failRetryLater(`Agent ${id} is being deleted. Try again once it is gone.`, "agent_busy");
         };
         const found = async (existing) => {
             if (fork !== undefined)
-                fail(409, `Environment ${id} exists: a fork makes a new Environment, so name another id.`);
+                fail(409, `Agent ${id} exists: a fork makes a new Agent, so name another id.`);
             if (body.from !== undefined)
-                fail(409, `Environment ${id} exists: from applies only when a PUT creates one.`);
-            if (ref !== undefined) {
-                // A bare name matches the manifest it was made from, whatever its latest version is now.
-                if (ref.name !== existing.manifestName)
-                    immutable(["manifest"], existing);
-                if (ref.version !== undefined && ref.version !== existing.manifestVersion)
-                    immutable(["manifest"], existing);
-            }
-            else if (INLINE_FIELDS.some((field) => body[field] !== undefined)) {
-                if (body.kind !== undefined && body.kind !== existing.kind)
-                    immutable(["kind"], existing);
-                if (body.storage !== undefined && body.storage !== existing.recipe.storage)
-                    immutable(["storage"], existing);
-                const recipe = resolve(existing.kind, recipeRequest(body, existing), false);
-                const differing = Object.keys({ ...recipe, ...existing.recipe })
-                    .filter((field) => canonical(recipe[field]) !== canonical(existing.recipe[field]))
-                    .sort();
-                if (differing.length > 0)
-                    immutable(differing, existing);
-            }
-            checkGuard(scope, body.ownerUserId, existing.ownerUserId);
+                fail(409, `Agent ${id} exists: from applies only when a PUT creates one.`);
+            checkGuard(scope, body.owner, existing.ownerUserId);
+            const move = await moveOf(t, existing, ref);
+            // A tracking Agent named as it is made (get-or-create) stays where it can move to.
+            const stays = move.plan.applies === "refused" && ref.version === undefined && existing.manifestRef === "tracking";
+            if (!stays)
+                await moveAgent(t, existing, move, now);
             const patch = { lastUsedAt: now };
             if (body.labels !== undefined && canonical(body.labels) !== canonical(existing.labels))
                 patch.labels = body.labels;
-            if (body.ownerUserId !== undefined && (body.ownerUserId ?? undefined) !== existing.ownerUserId)
-                patch.ownerUserId = body.ownerUserId;
+            if (body.owner !== undefined && (body.owner ?? undefined) !== existing.ownerUserId)
+                patch.ownerUserId = body.owner;
             await t.updateEnvironment(id, patch, now);
             return viewOf(ctx, t, (await t.environment(id)) ?? existing, subjectOf(scope));
         };
@@ -368,21 +371,30 @@ export async function putEnvironment(ctx, id, body, scope, options = {}) {
         deleting(existing);
         if (existing)
             return found(existing);
-        checkGuard(scope, body.ownerUserId);
-        const manifest = ref === undefined
-            ? undefined
-            : ((await t.environmentManifest(ref.name, ref.version)) ??
-                fail(404, ref.version === undefined
-                    ? `No environment manifest is named ${ref.name}: save it first (PUT /v1/environment-manifests/${ref.name}).`
-                    : `Environment manifest ${ref.name} has no version ${ref.version}.`, { code: "manifest_not_found" }));
-        const kind = manifest ? (manifest.body.kind ?? "virtual") : (body.kind ?? "virtual");
-        if (manifest && kind === "pod")
-            await requirePods(ctx.pods, `Environment manifest ${manifest.name} is of kind pod, and a pod Environment`);
-        const recipe = resolve(kind, manifest ? manifestRecipeRequest(manifest.body) : recipeRequest(body), true);
+        checkGuard(scope, body.owner);
+        const version = fork?.version ?? ref.version;
+        const manifest = (await t.agentManifest(ref.name, version)) ??
+            fail(404, version === undefined
+                ? `No agent manifest is named ${ref.name}: save it first (PUT /v1/agent-manifests/${ref.name}).`
+                : `Agent manifest ${ref.name} has no version ${version}.`, { code: "manifest_not_found" });
+        const runtime = runtimeOf(manifest.body);
+        const kind = runtime.kind;
+        if (kind === "pod")
+            await requirePods(ctx.pods, `Agent manifest ${manifest.name} is of kind pod, and a pod Agent`);
+        const resolved = resolveRecipe(kind, manifestRecipeRequest(manifest.body), config);
+        const errors = [
+            ...(resolved.kind === "error" ? resolved.errors : []),
+            ...limitIssues(runtime.limits, tenantLimits),
+            ...manifestShapeIssues(runtime, runtimeLimits),
+        ];
+        if (resolved.kind === "error" || errors.length > 0)
+            return fail(400, errors.join(" "));
+        const recipe = resolved.recipe;
         await checkFiles(t, recipe.files);
         const from = body.from === undefined ? undefined : await forkSource(t, scope, kind, body.from);
         // A fork onto other setup runs it on the written disk (Q17).
         const seed = from && fork?.setup ? { ...from, setup: true } : from;
+        const tracking = ref.version === undefined ? "tracking" : "pinned";
         const row = {
             id,
             kind,
@@ -391,13 +403,16 @@ export async function putEnvironment(ctx, id, body, scope, options = {}) {
             applied: recipe,
             version: 1,
             appliedVersion: 1,
-            ...(body.ownerUserId ? { ownerUserId: body.ownerUserId } : {}),
+            ...(body.owner ? { ownerUserId: body.owner } : {}),
             lastUsedAt: now,
             createdAt: now,
             updatedAt: now,
-            ...(manifest ? { manifestName: manifest.name, manifestVersion: manifest.version } : {}),
-            manifestHash: recipeHash(recipe),
-            ...(fork ? { forkedFrom: { environment: fork.source, disk: seed?.version ?? null } } : {}),
+            manifestName: manifest.name,
+            manifestVersion: manifest.version,
+            manifestRef: tracking,
+            manifestHash: manifest.hash,
+            desiredState: "on",
+            ...(fork ? { forkedFrom: { agent: fork.source, disk: seed?.version ?? null } } : {}),
             ...(seed
                 ? {
                     diskSeed: seed,
@@ -426,7 +441,7 @@ export async function putEnvironment(ctx, id, body, scope, options = {}) {
         };
         const created = await t.createEnvironment(row, config.limits.environments);
         if (created === "limit")
-            fail(409, `This Tenant allows at most ${config.limits.environments} Environments.`, {
+            fail(409, `This Tenant allows at most ${config.limits.environments} Agents.`, {
                 code: "limit_exceeded",
                 details: { limit: "environments", max: config.limits.environments },
             });
@@ -436,22 +451,26 @@ export async function putEnvironment(ctx, id, body, scope, options = {}) {
             deleting(again);
             return found(again);
         }
+        // Its triggers start active (D74); armed after the commit.
+        await createAgentTriggers(t, row);
+        // A fork starts with the source's memories as they are now, with no history (T5).
+        if (fork)
+            await t.copyMemories(fork.source, id, now);
         const vaultId = await ctx.vault.createEnvironmentVault(t, id, actorOf(scope), fork?.sealed?.vaultId);
         if (fork?.sealed)
             fork.copied = await ctx.vault.insertEnvironmentSecretCopies(t, vaultId, fork.source, actorOf(scope), fork.sealed.copies);
-        const madeFrom = manifest ? { manifest: { name: manifest.name, version: manifest.version } } : {};
-        await t.environmentEvent(id, "environment.created", {
+        await t.agentEvent(id, "agent.created", {
             kind,
             labels: row.labels,
-            ...madeFrom,
-            ...(seed ? { from: { environment: body.from.environment, version: seed.version } } : {}),
+            manifest: { name: manifest.name, version: manifest.version, tracking },
+            ...(seed ? { from: { agent: body.from.agent, version: seed.version } } : {}),
             ...(row.forkedFrom ? { forkedFrom: row.forkedFrom } : {}),
         });
         if (fork)
-            await t.environmentEvent(fork.source, "environment.forked", {
+            await t.agentEvent(fork.source, "agent.forked", {
                 to: id,
                 disk: seed?.version ?? null,
-                ...madeFrom,
+                manifest: { name: manifest.name, version: manifest.version },
                 secrets: fork.copied?.copied.length ?? 0,
             });
         if (row.pod) {
@@ -462,13 +481,60 @@ export async function putEnvironment(ctx, id, body, scope, options = {}) {
         }
         return viewOf(ctx, t, row, subjectOf(scope));
     });
+    await armAgentTriggers(ctx, id);
     // A virtual fork's workspace is written at once (a pod's once its engine connects).
     if (body.from !== undefined && view.kind === "virtual") {
         await runPendingSeed(ctx, id);
-        return getEnvironment(ctx, id, scope);
+        return getAgent(ctx, id, scope);
     }
     return view;
 }
+/**
+ * The move a `PUT` naming `ref` asks of existing Agent `agent` (track T3): to version `n` for
+ * `name@n` (pinned), else to the latest version (tracking), unless that one failed to start, when
+ * it stays on what it runs. Another manifest name is `409 agent_fixed_field`.
+ */
+async function moveOf(t, agent, ref) {
+    if (ref.name !== agent.manifestName)
+        fail(409, `Agent ${agent.id} runs agent manifest ${agent.manifestName}, which is fixed for its life: fork it into a new Agent made from ${ref.name} with POST /v1/agents/${encodeURIComponent(agent.id)}/fork.`, { code: "agent_fixed_field", details: { fields: [{ field: "manifest", from: agent.manifestName, to: ref.name }] } });
+    const missing = () => fail(404, `Agent manifest ${ref.name} has no version ${ref.version}.`, { code: "manifest_not_found" });
+    let target = (await t.agentManifest(ref.name, ref.version)) ?? missing();
+    if (ref.version === undefined && target.version === agent.failedVersion)
+        target = (await t.agentManifest(ref.name, agent.manifestVersion)) ?? target;
+    return planMove(t, agent, target, ref.version === undefined ? "tracking" : "pinned");
+}
+/**
+ * `PUT /v1/agents/{id}?dryRun=true` (track T3): what moving existing Agent `id` to the version
+ * `body.manifest` names would do (`AgentMovePlan`), with nothing changed.
+ */
+export async function planAgentPut(ctx, id, body, scope) {
+    reachable(agentGrantsOf(scope), id);
+    const ref = parseAgentManifestRef(body.manifest) ??
+        fail(400, "manifest is an agent manifest's name, or name@version such as triage@3.");
+    return ctx.store.tx(async (t) => {
+        const agent = (await liveEnvironment(t, id)) ?? fail(404, "Agent not found: a dry run plans the move of an existing Agent.");
+        return { dryRun: true, plan: (await moveOf(t, agent, ref)).plan };
+    });
+}
+/**
+ * After a secret write on Agent `id`: a move that waited for its required secrets goes on once
+ * they are set (track T3). Best effort: the write stands either way.
+ */
+export async function secretWritten(ctx, id) {
+    try {
+        await ctx.store.tx(async (t) => {
+            const agent = await liveEnvironment(t, id, { lock: true });
+            if (agent)
+                await resumeMove(t, agent, new Date().toISOString());
+        });
+    }
+    catch (error) {
+        ctx.config.logger.warn("agent move not resumed after a secret write", {
+            environmentId: id,
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 /**
  * The secret write `raw` asks of Environment `id` (D64). When what it runs declares secret
  * slots, the name must be one (`409 secret_not_in_manifest`), and the body is `{ value }` (or
@@ -484,32 +550,35 @@ export async function secretRequestFor(ctx, id, name, raw) {
     return request;
 }
 async function parseSecretRequest(ctx, id, name, raw) {
-    const environment = await ctx.store.tx((t) => liveEnvironment(t, id));
-    const slots = environment?.recipe.secrets;
+    const { environment, slots } = await ctx.store.tx(async (t) => {
+        const environment = await liveEnvironment(t, id);
+        return { environment, slots: environment && (await slotsAhead(t, environment)) };
+    });
     if (!environment || slots === undefined)
-        return PutEnvironmentSecretRequestSchema.parse(raw);
+        return PutAgentSecretRequestSchema.parse(raw);
+    const named = `${environment.manifestName}@${environment.targetVersion ?? environment.manifestVersion}`;
     const slot = slots[name] ??
-        fail(409, `What Environment ${id} runs declares no secret ${name}${environment.manifestName ? ` (manifest ${environment.manifestName}@${environment.manifestVersion})` : ""}: add the slot to the manifest, then make or fork an Environment from the new version.`, { code: "secret_not_in_manifest", details: { declared: Object.keys(slots).sort() } });
+        fail(409, `Agent ${id}'s manifest (${named}) declares no secret ${name}: add the slot to the manifest's runtime section, then move the Agent to the new version.`, { code: "secret_not_in_manifest", details: { declared: Object.keys(slots).sort() } });
     const full = slotRequest(slot);
     if (raw !== null && typeof raw === "object" && "type" in raw) {
-        const body = PutEnvironmentSecretRequestSchema.parse(raw);
+        const body = PutAgentSecretRequestSchema.parse(raw);
         const { requestId: _, value: _v, headers: _h, ...binding } = body;
         if (canonical(binding) !== canonical(full))
-            fail(409, `Secret ${name}'s type and binding come from what Environment ${id} runs: send only its value ({ "value": "…" }).`, {
+            fail(409, `Secret ${name}'s type and binding come from Agent ${id}'s manifest: send only its value ({ "value": "…" }).`, {
                 code: "secret_not_in_manifest",
             });
         return body;
     }
-    const { requestId, value, headers } = PutEnvironmentSecretValueRequestSchema.parse(raw);
+    const { requestId, value, headers } = PutAgentSecretValueRequestSchema.parse(raw);
     const withId = requestId === undefined ? {} : { requestId };
     if (slot.type === "headers") {
         if (headers === undefined)
             fail(400, `Secret ${name} is a headers credential: send { "headers": { … } }.`);
-        return PutEnvironmentSecretRequestSchema.parse({ ...withId, ...full, headers });
+        return PutAgentSecretRequestSchema.parse({ ...withId, ...full, headers });
     }
     if (value === undefined)
         fail(400, `Secret ${name} takes a value: send { "value": "…" }.`);
-    return PutEnvironmentSecretRequestSchema.parse({ ...withId, ...full, value });
+    return PutAgentSecretRequestSchema.parse({ ...withId, ...full, value });
 }
 /** A slot's type and binding, as a secret write's fields (without the value). */
 function slotRequest(slot) {
@@ -522,49 +591,49 @@ function slotRequest(slot) {
  */
 async function forkSource(t, scope, kind, from) {
     if (kind === "none")
-        fail(400, "from is for an Environment with a disk: kind none has none.");
-    reachable(environmentGrantsOf(scope), from.environment);
-    const source = (await liveEnvironment(t, from.environment)) ?? notFound();
+        fail(400, "from is for an Agent with a disk: kind none has none.");
+    reachable(agentGrantsOf(scope), from.agent);
+    const source = (await liveEnvironment(t, from.agent)) ?? notFound();
     const subject = subjectOf(scope);
     if (subject !== undefined && source.ownerUserId !== undefined && source.ownerUserId !== subject)
         notFound();
-    return forkSeedOf(t, from);
+    return forkSeedOf(t, { environment: from.agent, version: from.version });
 }
 /**
- * `POST /v1/environments/{id}/fork` (Q15): how an Environment gets a new manifest version. A new
- * Environment `body.id` is made from the manifest version (default the source's manifest at its
- * latest), its disk started from a version of the source's (`latest` takes a snapshot first,
- * refused during a turn), and its secrets copied inside the Runtime. A fork onto other setup
- * runs that setup on the copied disk before its first turn (Q17). The source keeps what it runs,
- * its disk and its sessions. With `dryRun`, the plan only.
+ * `POST /v1/agents/{id}/fork` (Q15): copies an Agent into a new one, which is how an Agent changes
+ * what is fixed for its life (its manifest, kind, harness or storage). A new Agent `body.id` is made from the manifest
+ * (default the source's manifest name, tracking, at its latest version), its disk started from a
+ * version of the source's (`latest` takes a snapshot first, refused during a turn), and its
+ * secrets copied inside the Runtime. A fork onto other setup runs that setup on the copied disk
+ * before its first turn (Q17). The source keeps what it runs, its disk and its sessions. With
+ * `dryRun`, the plan only.
  */
-export async function forkEnvironment(ctx, sourceId, body, scope) {
-    const grants = environmentGrantsOf(scope);
+export async function forkAgent(ctx, sourceId, body, scope) {
+    const grants = agentGrantsOf(scope);
     reachable(grants, sourceId);
     reachable(grants, body.id);
     if (body.id === sourceId)
-        fail(400, "A fork is a new Environment: give it another id.");
+        fail(400, "A fork is a new Agent: give it another id.");
     const { plan: planned, slots } = await ctx.store.tx(async (t) => {
         const source = (await liveEnvironment(t, sourceId)) ?? notFound();
         const subject = subjectOf(scope);
         if (subject !== undefined && source.ownerUserId !== undefined && source.ownerUserId !== subject)
             notFound();
-        const ref = body.manifest === undefined ? undefined : parseEnvironmentManifestRef(body.manifest);
-        if (body.manifest !== undefined && ref === undefined)
-            fail(400, "manifest is an environment manifest's name, or name@version such as analyst-box@3.");
-        const name = ref?.name ??
-            source.manifestName ??
-            fail(400, `Environment ${sourceId} was made from inline fields, not a manifest: name the manifest to fork it onto (manifest).`);
-        const manifest = (await t.environmentManifest(name, ref?.version)) ??
-            fail(404, ref?.version === undefined
-                ? `No environment manifest is named ${name}.`
-                : `Environment manifest ${name} has no version ${ref.version}.`, { code: "manifest_not_found" });
-        const kind = manifest.body.kind ?? "virtual";
+        const ref = body.manifest === undefined
+            ? { name: source.manifestName }
+            : (parseAgentManifestRef(body.manifest) ??
+                fail(400, "manifest is an agent manifest's name, or name@version such as triage@3."));
+        const manifest = (await t.agentManifest(ref.name, ref.version)) ??
+            fail(404, ref.version === undefined
+                ? `No agent manifest is named ${ref.name}.`
+                : `Agent manifest ${ref.name} has no version ${ref.version}.`, { code: "manifest_not_found" });
+        const runtime = runtimeOf(manifest.body);
+        const kind = runtime.kind;
         const resolved = resolveRecipe(kind, manifestRecipeRequest(manifest.body), effectiveSandboxConfig(await readSandboxConfig(t)));
         const errors = [
             ...(resolved.kind === "error" ? resolved.errors : []),
-            ...limitIssues(manifest.body.limits, await readTenantLimits(t)),
-            ...manifestShapeIssues(manifest.body, await readRuntimeLimits(t)),
+            ...limitIssues(runtime.limits, await readTenantLimits(t)),
+            ...manifestShapeIssues(runtime, await readRuntimeLimits(t)),
             ...labelIssues(body.labels, await readRuntimeLimits(t)),
         ];
         if (resolved.kind === "error" || errors.length > 0)
@@ -589,7 +658,7 @@ export async function forkEnvironment(ctx, sourceId, body, scope) {
             disk,
             setup: kind === "pod" &&
                 disk !== null &&
-                recipeHash(recipe) !== source.manifestHash &&
+                canonical(recipe) !== canonical(source.applied) &&
                 Boolean(recipe.setup?.length || recipe.files?.length),
             secrets: {
                 copied,
@@ -599,8 +668,9 @@ export async function forkEnvironment(ctx, sourceId, body, scope) {
                     .map(([item]) => item)
                     .sort(),
             },
-            changes: manifestChanges(source.recipe, recipe),
+            changes: manifestChanges(source.applied, recipe),
             sessions: (await t.sessionsOnEnvironment(sourceId)).length,
+            memories: await t.countMemories(sourceId),
         };
         const slots = recipe.secrets === undefined
             ? null
@@ -617,25 +687,31 @@ export async function forkEnvironment(ctx, sourceId, body, scope) {
     const sealed = (body.secrets ?? "copy") === "copy"
         ? { vaultId, copies: await ctx.keys.sealEnvironmentSecretCopies(sourceId, vaultId, slots) }
         : undefined;
-    const fork = { source: sourceId, setup: planned.setup, ...(sealed ? { sealed } : {}) };
-    const environment = await putEnvironment(ctx, body.id, {
+    const fork = {
+        source: sourceId,
+        version: planned.manifest.version,
+        setup: planned.setup,
+        ...(sealed ? { sealed } : {}),
+    };
+    const agent = await putAgent(ctx, body.id, {
         ...(body.requestId === undefined ? {} : { requestId: body.requestId }),
-        manifest: `${planned.manifest.name}@${planned.manifest.version}`,
+        // Tracking unless the request pinned a version; either way the plan's version is made.
+        manifest: body.manifest ?? planned.manifest.name,
         ...(body.labels === undefined ? {} : { labels: body.labels }),
-        ...(body.ownerUserId === undefined ? {} : { ownerUserId: body.ownerUserId }),
-        ...(disk === null ? {} : { from: { environment: sourceId, version: disk } }),
+        ...(body.owner === undefined ? {} : { owner: body.owner }),
+        ...(disk === null ? {} : { from: { agent: sourceId, version: disk } }),
     }, scope, { fork });
     const copied = fork.copied ?? { copied: [], dropped: planned.secrets.copied };
     const dropped = [...new Set([...planned.secrets.dropped, ...copied.dropped])].sort();
     return {
-        environment,
+        agent,
         plan: {
             ...planned,
             disk,
             secrets: {
                 copied: copied.copied,
                 dropped,
-                missing: Object.entries(environment.manifest.secrets ?? {})
+                missing: Object.entries(agent.runtime.secrets ?? {})
                     .filter(([item, slot]) => slot.required === true && !copied.copied.includes(item))
                     .map(([item]) => item)
                     .sort(),
@@ -643,24 +719,44 @@ export async function forkEnvironment(ctx, sourceId, body, scope) {
         },
     };
 }
-/** `GET /v1/environments/{id}`. */
-export async function getEnvironment(ctx, id, scope) {
-    reachable(environmentGrantsOf(scope), id);
+/** `GET /v1/agents/{id}`. */
+export async function getAgent(ctx, id, scope) {
+    reachable(agentGrantsOf(scope), id);
     return ctx.store.tx(async (t) => {
         const environment = (await liveEnvironment(t, id)) ?? notFound();
         return viewOf(ctx, t, environment, subjectOf(scope));
     });
 }
-/** `GET /v1/environments?label=k=v`: every Environment with all the labels, that the caller reaches. */
-export async function listEnvironments(ctx, labels, scope) {
-    const grants = environmentGrantsOf(scope);
+/**
+ * `GET /v1/agents?label=k=v&state=s&manifest=m`: every Agent with all the labels, in the state
+ * and made from the manifest, that the caller reaches, by id. With `page`, at most `limit` after
+ * the Agent id `after` (the cursor), and the id to continue from.
+ */
+export async function listAgents(ctx, filters, scope, page) {
+    const grants = agentGrantsOf(scope);
     return ctx.store.tx(async (t) => {
-        const found = await t.listEnvironments({ labels });
+        const found = await t.listEnvironments({ labels: filters.labels });
         const views = [];
-        for (const environment of found)
-            if (live(environment) && (grants === undefined || environmentGranted(grants, environment.id)))
-                views.push(await viewOf(ctx, t, environment, subjectOf(scope)));
-        return { environments: views };
+        let next = null;
+        for (const environment of found) {
+            if (!live(environment) || (grants !== undefined && !agentGranted(grants, environment.id)))
+                continue;
+            if (filters.manifest !== undefined && environment.manifestName !== filters.manifest)
+                continue;
+            if (filters.outdated !== undefined && (environment.targetVersion !== undefined) !== filters.outdated)
+                continue;
+            if (page?.after !== undefined && environment.id <= page.after)
+                continue;
+            const view = await viewOf(ctx, t, environment, subjectOf(scope));
+            if (filters.state !== undefined && view.state !== filters.state)
+                continue;
+            if (page !== undefined && views.length === page.limit) {
+                next = views.at(-1).id;
+                break;
+            }
+            views.push(view);
+        }
+        return { agents: views, next };
     });
 }
 /**
@@ -669,15 +765,15 @@ export async function listEnvironments(ctx, labels, scope) {
  */
 export async function wakePod(ctx, id) {
     if (!ctx.pods)
-        fail(409, `Environment ${id} is a pod Environment, and this Runtime has no sandbox pods.`, { code: "environment_unavailable" });
+        fail(409, `Agent ${id} runs on a pod, and this Runtime has no sandbox pods.`, { code: "agent_unavailable" });
     await ctx.store.tx(async (t) => {
         const environment = await liveEnvironment(t, id, { lock: true });
         const pod = environment?.pod;
         if (!environment || !pod)
             return;
         if (pod.observed === "lost")
-            fail(409, `Environment ${id} was lost (${pod.reason ?? "its volume is gone"}). Reset or restore it.`, {
-                code: "environment_lost",
+            fail(409, `Agent ${id}'s pod was lost (${pod.reason ?? "its volume is gone"}). Reset or restore it.`, {
+                code: "agent_lost",
             });
         const now = new Date().toISOString();
         if (pod.desired !== "running" || pod.observed === "failed") {
@@ -695,13 +791,13 @@ export function diskHeld(environment, now = Date.now()) {
 /** Refused while a snapshot or restore copies the disk (a pending seed does not count). */
 export function refuseDiskCopy(environment) {
     if (diskHeld(environment) && environment.diskOp.kind !== "seed")
-        failRetryLater(`Environment ${environment.id}'s disk is being copied (${environment.diskOp.kind}). Try again shortly.`, "environment_busy");
+        failRetryLater(`Agent ${environment.id}'s disk is being copied (${environment.diskOp.kind}). Try again shortly.`, "agent_busy");
 }
 /** Refused while a session that names Environment `id` has a turn running. */
 async function refuseBusy(t, id) {
     const busy = (await t.sessionsOnEnvironment(id)).some((session) => session.activeTurnId !== null);
     if (busy)
-        failRetryLater(`Environment ${id} has a turn running. Cancel it, or wait for it to end.`, "environment_busy");
+        failRetryLater(`Agent ${id} has a turn running. Cancel it, or wait for it to end.`, "agent_busy");
 }
 /**
  * Deletes `environment` (locked, live) in `t`: its vault and credentials at once, its workspace
@@ -709,7 +805,11 @@ async function refuseBusy(t, id) {
  */
 async function deleteIn(ctx, t, environment, actor, reason) {
     const id = environment.id;
-    await t.environmentEvent(id, "environment.deleted", { reason });
+    await t.agentEvent(id, "agent.deleted", { reason });
+    // Its triggers and their runs go with it; a timer still armed finds no row.
+    await t.deleteAgentTriggers(id);
+    // So do its memories and their versions (T5).
+    await t.deleteAgentMemories(id);
     await ctx.vault.deleteEnvironmentVault(t, id, actor);
     // Its disk versions go with it; their manifests' bytes are the caller's, after the commit.
     const keys = await deleteDiskArtifact(ctx, t, id);
@@ -729,12 +829,12 @@ async function deleteKeys(ctx, keys) {
         await ctx.blobs.delete(key).catch(() => undefined);
 }
 /**
- * `DELETE /v1/environments/{id}`: deletes the Environment, its vault and its workspace. Refused
+ * `DELETE /v1/agents/{id}`: deletes the Environment, its vault and its workspace. Refused
  * while a session that names it has an active turn. Sessions keep its id: their next turn is
- * refused (`environment_unavailable`) unless an Environment with this id exists again.
+ * refused (`agent_unavailable`) unless an Environment with this id exists again.
  */
-export async function deleteEnvironment(ctx, id, scope) {
-    reachable(environmentGrantsOf(scope), id);
+export async function deleteAgent(ctx, id, scope) {
+    reachable(agentGrantsOf(scope), id);
     const deleted = await ctx.store.tx(async (t) => {
         const environment = await liveEnvironment(t, id, { lock: true });
         if (!environment)
@@ -755,7 +855,7 @@ export async function deleteEnvironment(ctx, id, scope) {
  * change, secret write, stop or reset since. One with a turn running waits for the next sweep.
  * Run by the Tenant sweep.
  */
-export async function sweepUnusedEnvironments(ctx, now = Date.now()) {
+export async function sweepUnusedAgents(ctx, now = Date.now()) {
     const due = (await ctx.store.tx((t) => t.listEnvironments())).filter((environment) => {
         const after = environment.recipe.lifecycle.deleteAfter;
         const ms = after === undefined ? undefined : parseSandboxDuration(after);
@@ -794,15 +894,15 @@ export async function sweepUnusedEnvironments(ctx, now = Date.now()) {
 async function podEnvironment(t, id) {
     const environment = (await liveEnvironment(t, id, { lock: true })) ?? notFound();
     if (!environment.pod)
-        return fail(400, `Environment ${id} is of kind ${environment.kind}: only a pod Environment stops and resets`);
+        return fail(400, `Agent ${id} is of kind ${environment.kind}: only a pod Agent stops and resets`);
     return environment;
 }
 /**
- * `POST /v1/environments/{id}/stop`: suspends a pod Environment. Its volume is kept, and the next
+ * `POST /v1/agents/{id}/stop`: suspends a pod Environment. Its volume is kept, and the next
  * turn of a session that names it starts it again. Refused during a turn.
  */
-export async function stopEnvironment(ctx, id, scope) {
-    reachable(environmentGrantsOf(scope), id);
+export async function stopAgent(ctx, id, scope) {
+    reachable(agentGrantsOf(scope), id);
     return ctx.store.tx(async (t) => {
         const environment = await podEnvironment(t, id);
         await refuseBusy(t, id);
@@ -811,7 +911,7 @@ export async function stopEnvironment(ctx, id, scope) {
         if (pod.desired === "running" && pod.observed !== "lost") {
             const epoch = pod.hostEpoch + 1;
             await t.updateEnvironmentPod(id, { desired: "suspended", rev: pod.rev + 1, hostEpoch: epoch }, now);
-            await t.environmentEvent(id, "environment.suspended", { reason: "stop" });
+            await t.agentEvent(id, "agent.suspended", { reason: "stop" });
             await reconcileAfter(t, id);
             await revokeHost(t, id, epoch);
         }
@@ -820,23 +920,65 @@ export async function stopEnvironment(ctx, id, scope) {
     });
 }
 /**
- * `POST /v1/environments/{id}/reset`: a new pod on a new, empty volume (the next volume
+ * `POST /v1/agents/{id}/restart` (track T3): applies a pending version now, refused during a
+ * turn. With `retry`, it first moves the Agent to the version that failed to start again. A
+ * running pod stops, so the next turn starts it on the version; a stopped or failed one is asked
+ * to run at once. Kinds `virtual` and `none` apply a version at once anyway.
+ */
+export async function restartAgent(ctx, id, options, scope) {
+    reachable(agentGrantsOf(scope), id);
+    return ctx.store.tx(async (t) => {
+        let agent = (await liveEnvironment(t, id, { lock: true })) ?? notFound();
+        await refuseBusy(t, id);
+        refuseDiskCopy(agent);
+        const now = new Date().toISOString();
+        if (options.retry && agent.failedVersion !== undefined) {
+            const failed = (await t.agentManifest(agent.manifestName, agent.failedVersion)) ??
+                fail(404, `Agent manifest ${agent.manifestName} has no version ${agent.failedVersion}.`, { code: "manifest_not_found" });
+            await moveAgent(t, agent, await planMove(t, agent, failed, agent.manifestRef), now);
+            agent = (await t.environment(id, { lock: true }));
+        }
+        const pod = agent.pod;
+        if (pod && waitingFor(agent) === "start") {
+            if (!ctx.pods)
+                fail(409, `Agent ${id} runs on a pod, and this Runtime has no sandbox pods.`, { code: "agent_unavailable" });
+            if (pod.observed === "lost")
+                fail(409, `Agent ${id}'s pod was lost (${pod.reason ?? "its volume is gone"}). Reset it to continue.`, { code: "agent_lost" });
+            if (pod.desired === "running" && pod.observed !== "failed") {
+                // Stopped now; the next turn starts it on the version.
+                const epoch = pod.hostEpoch + 1;
+                await t.updateEnvironmentPod(id, { desired: "suspended", rev: pod.rev + 1, hostEpoch: epoch }, now);
+                await t.agentEvent(id, "agent.suspended", { reason: "restart" });
+                await reconcileAfter(t, id);
+                await revokeHost(t, id, epoch);
+            }
+            else {
+                await wantRunning(t, agent, now);
+                await reconcileAfter(t, id);
+            }
+        }
+        await t.updateEnvironment(id, { lastUsedAt: now }, now);
+        return viewOf(ctx, t, (await t.environment(id)) ?? agent, subjectOf(scope));
+    });
+}
+/**
+ * `POST /v1/agents/{id}/reset`: a new pod on a new, empty volume (the next volume
  * generation), with a new join token and the recipe applied; the old Sandbox and volume are
  * deleted. Leaves `lost` and `failed`. Refused during a turn, and while an earlier reset's
  * Sandbox is still being deleted.
  */
-export async function resetEnvironment(ctx, id, scope) {
-    reachable(environmentGrantsOf(scope), id);
+export async function resetAgent(ctx, id, scope) {
+    reachable(agentGrantsOf(scope), id);
     // A missing Environment is a 404, and one of another kind a 400, with or without sandbox pods.
     await ctx.store.tx((t) => podEnvironment(t, id));
-    await requirePods(ctx.pods, "Resetting a pod Environment");
+    await requirePods(ctx.pods, "Resetting a pod Agent");
     return ctx.store.tx(async (t) => {
         const environment = await podEnvironment(t, id);
         await refuseBusy(t, id);
         refuseDiskCopy(environment);
         const pod = environment.pod;
         if (pod.retiring !== undefined)
-            failRetryLater(`Environment ${id} is still deleting its previous volume. Try again shortly.`, "environment_busy");
+            failRetryLater(`Agent ${id} is still deleting its previous volume. Try again shortly.`, "agent_busy");
         await newVolume(ctx, t, environment);
         return viewOf(ctx, t, (await t.environment(id)) ?? environment, subjectOf(scope));
     });
@@ -853,6 +995,8 @@ export async function newVolume(ctx, t, environment, options = {}) {
     const now = new Date().toISOString();
     const volumeGen = pod.volumeGen + 1;
     const epoch = pod.hostEpoch + 1;
+    // A move whose runtime waits for a start switches now (track T3).
+    await switchTo(t, environment, now);
     await t.updateEnvironment(id, {
         applied: environment.recipe,
         appliedVersion: environment.version,
@@ -884,7 +1028,7 @@ export async function newVolume(ctx, t, environment, options = {}) {
         lastActiveAt: now,
         reason: null,
     }, now);
-    await t.environmentEvent(id, "environment.reset", {
+    await t.agentEvent(id, "agent.reset", {
         volumeGeneration: volumeGen,
         ...(options.reason ? { reason: options.reason } : {}),
         ...(options.seed ? { from: { version: options.seed.version } } : {}),
@@ -893,12 +1037,12 @@ export async function newVolume(ctx, t, environment, options = {}) {
     await revokeHost(t, id, epoch);
     return volumeGen;
 }
-/** `GET /v1/environments/{id}/events`: the Environment's lifecycle stream. */
-export async function environmentEventsOf(ctx, id, scope, query = {}) {
-    reachable(environmentGrantsOf(scope), id);
+/** `GET /v1/agents/{id}/events`: the Environment's lifecycle stream. */
+export async function agentEventsOf(ctx, id, scope, query = {}) {
+    reachable(agentGrantsOf(scope), id);
     // One read returns at most the Tenant's Runtime limit `environmentEventItems`; `from` reads on.
     return ctx.store.tx(async (t) => ({
-        events: await t.environmentEvents(id, { ...query, limit: (await readRuntimeLimits(t)).environmentEventItems }),
+        events: await t.agentEvents(id, { ...query, limit: (await readRuntimeLimits(t)).environmentEventItems }),
     }));
 }
 /**
@@ -910,23 +1054,23 @@ function checkOwner(environment, ownerUserId, opaque) {
         return;
     if (opaque)
         notFound();
-    fail(403, `Environment ${environment.id} is for another owner's sessions (its ownerUserId guard).`, { code: "environment_owner_mismatch" });
+    fail(403, `Agent ${environment.id} is for another owner's sessions (its owner guard).`, { code: "agent_owner_mismatch" });
 }
 /**
  * Opens a new session on Environment `id` (`PutSessionRequest.environment`): it must exist, be
  * reachable with `grants` and pass its owner guard. Runs in the session's transaction, after
  * its session row lock; holds the Environment's row lock.
  */
-export async function openEnvironment(t, id, options) {
+export async function openAgent(t, id, options) {
     reachable(options.grants, id);
     const environment = (await liveEnvironment(t, id, { lock: true })) ?? notFound();
     checkOwner(environment, options.ownerUserId, options.opaque);
     return environment;
 }
 /** Records the attachment on the session's log and on the Environment's stream. */
-export async function recordAttachment(t, sessionId, environmentId) {
-    await t.event(sessionId, null, "environment.attached", { environmentId });
-    await t.environmentEvent(environmentId, "environment.attached", { sessionId });
+export async function recordAttachment(t, sessionId, agentId) {
+    await t.event(sessionId, null, "agent.attached", { agentId });
+    await t.agentEvent(agentId, "agent.attached", { sessionId });
 }
 /**
  * Checks a turn start on a session that names an Environment, in the command's transaction
@@ -935,25 +1079,25 @@ export async function recordAttachment(t, sessionId, environmentId) {
  * do not stop it (D66). Holds the Environment row's lock until the transaction ends, so a turn
  * start and disk work on one Environment are decided one after the other.
  *
- * A pod Environment must also be usable: not lost (`environment_lost`), on a Runtime with
- * sandbox pods (`environment_unavailable`). A stopped or failed pod is asked to run again, with
+ * A pod Environment must also be usable: not lost (`agent_lost`), on a Runtime with
+ * sandbox pods (`agent_unavailable`). A stopped or failed pod is asked to run again, with
  * its recipe applied, after the commit.
  */
-export async function checkEnvironmentTurn(t, session, scope, ctx) {
+export async function checkAgentTurn(t, session, scope, ctx) {
     const id = session.environmentId;
     if (id === undefined)
         return;
-    const grants = environmentGrantsOf(scope);
-    if (grants !== undefined && !environmentGranted(grants, id))
-        fail(403, `This token does not reach Environment ${id}.`, { code: "environment_not_granted" });
+    const grants = agentGrantsOf(scope);
+    if (grants !== undefined && !agentGranted(grants, id))
+        fail(403, `This token does not reach Agent ${id}.`, { code: "agent_not_granted" });
     const environment = await liveEnvironment(t, id, { lock: true });
     if (!environment)
-        return fail(409, `Environment ${id} was deleted. Create it again to continue this session.`, {
-            code: "environment_unavailable",
+        return fail(409, `Agent ${id} was deleted. Create it again to continue this session.`, {
+            code: "agent_unavailable",
         });
     if (environment.ownerUserId !== undefined && environment.ownerUserId !== session.ownerUserId)
-        fail(403, `Environment ${id} is for another owner's sessions (its ownerUserId guard).`, {
-            code: "environment_owner_mismatch",
+        fail(403, `Agent ${id} is for another owner's sessions (its owner guard).`, {
+            code: "agent_owner_mismatch",
         });
     // The harness the turn would run on (R4.1, Q9): a pod about to wake runs its recipe's. A
     // session never moves to another harness: its state is that harness's. An Environment's
@@ -963,9 +1107,9 @@ export async function checkEnvironmentTurn(t, session, scope, ctx) {
     const waking = environment.pod !== undefined && (environment.pod.desired !== "running" || environment.pod.observed === "failed");
     const runs = waking ? environment.recipe.harness : environment.applied.harness;
     if (!isWorkflowManifest(session.manifest) && runs !== harnessOf(session))
-        fail(409, `Environment ${id} runs the ${runs} harness, and this session runs ${harnessOf(session)}: open a new session to run on it.`, {
+        fail(409, `Agent ${id} runs the ${runs} harness, and this session runs ${harnessOf(session)}: open a new session to run on it.`, {
             code: "harness_mismatch",
-            details: { harness: harnessOf(session), environmentHarness: runs },
+            details: { harness: harnessOf(session), agentHarness: runs },
         });
     if (environment.kind === "none")
         return;
@@ -975,12 +1119,12 @@ export async function checkEnvironmentTurn(t, session, scope, ctx) {
     if (!pod)
         return;
     if (!ctx?.pods)
-        fail(409, `Environment ${id} is a pod Environment, and this Runtime has no sandbox pods: run \`nylorun local sandbox enable --context <name>\`.`, {
-            code: "environment_unavailable",
+        fail(409, `Agent ${id} runs on a pod, and this Runtime has no sandbox pods: run \`nylorun local sandbox enable --context <name>\`.`, {
+            code: "agent_unavailable",
         });
     if (pod.observed === "lost")
-        fail(409, `Environment ${id} was lost (${pod.reason ?? "its volume is gone"}). Reset it to continue.`, {
-            code: "environment_lost",
+        fail(409, `Agent ${id}'s pod was lost (${pod.reason ?? "its volume is gone"}). Reset it to continue.`, {
+            code: "agent_lost",
         });
     const now = new Date().toISOString();
     if (pod.desired !== "running" || pod.observed === "failed") {
@@ -998,7 +1142,7 @@ export async function detachAllSessions(t) {
             continue;
         await t.environment(environment.id, { lock: true });
         for (const session of sessions)
-            await t.environmentEvent(environment.id, "environment.detached", {
+            await t.agentEvent(environment.id, "agent.detached", {
                 sessionId: session.id,
                 reason: "reset",
             });
@@ -1009,7 +1153,7 @@ export async function detachAllSessions(t) {
  * from here), and for a running pod idle counts from now and the idle timer is armed (D34).
  * Best effort.
  */
-export async function touchEnvironment(ctx, id) {
+export async function touchAgent(ctx, id) {
     try {
         await ctx.store.tx(async (t) => {
             const environment = await liveEnvironment(t, id, { lock: true });
@@ -1021,7 +1165,7 @@ export async function touchEnvironment(ctx, id) {
             if (!environment.pod || environment.pod.desired !== "running")
                 return;
             await t.updateEnvironmentPod(id, { lastActiveAt: iso }, iso);
-            const idleMs = podLifecycleConfig(await readSandboxConfig(t), environment.recipe).idleMs;
+            const idleMs = idleMsOf(await readSandboxConfig(t), environment);
             await t.signalSandbox(id, { kind: "arm", timer: "idle", at: now.getTime() + idleMs });
         });
     }
@@ -1050,7 +1194,7 @@ export async function rearmPodTimers(ctx) {
                 await ctx.sandboxSignal(row.id, {
                     kind: "arm",
                     timer: "idle",
-                    at: Date.parse(row.pod.lastActiveAt ?? row.createdAt) + podLifecycleConfig(config, row.recipe).idleMs,
+                    at: Date.parse(row.pod.lastActiveAt ?? row.createdAt) + idleMsOf(config, row),
                 });
     }
     catch (error) {