@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/tenant/context.d.ts

@@ -5,8 +5,9 @@
  *
  * Business code changes state only inside `ctx.store.tx(async (t) => …)` and follows the
  * seam rules: events through `t.event(...)` (the relay appends them to Durable Streams after
- * commit), and advances through `await t.wake(id, { reason, dedupeKey }, ctx.wake)`, which
- * writes the wake to the outbox in the transaction and delivers it after commit. It never
+ * commit), and advances through `await t.wake(id, { reason, dedupeKey })`, which writes the
+ * wake to the outbox in the transaction; the store delivers it after commit (`ctx.wake`,
+ * wired with `SessionStore.deliverTo`). It never
  * publishes or notifies itself; `runtime.ts` wires the streams with `wireStreams()`. No
  * external I/O runs inside a tx.
  *
@@ -17,8 +18,7 @@ import type { SessionHistory } from "./history.js";
 import type { IssuerScope, SubjectScope, TenantEnvelope } from "@nylorun/core/contracts";
 import type { DurableCheckpoint, FlowCheckpoint } from "@nylorun/harness/run";
 import type { AgentManifest, JsonValue, SandboxManifest } from "@nylorun/core/define";
-import type { CredentialSelection } from "@nylorun/core/contracts";
-import type { SessionStore, Tx } from "../store/types.js";
+import type { OutboxRequest, SessionStore, Tx } from "../store/types.js";
 import type { FlowLimits } from "../core/limits.js";
 import type { ModelProvider } from "../core/provider.js";
 import type { ModelGate } from "../gates/model-gate.js";
@@ -39,6 +39,8 @@ import type { SigningKeys } from "./signing-keys.js";
 import type { BlobStore } from "../blob/index.js";
 import type { WorkspaceReader } from "../artifacts/workspace.js";
 import type { RunGrants } from "./run-grants.js";
+import type { TraceOptions } from "../traces/options.js";
+import type { TraceContext } from "../traces/ids.js";
 export interface Session {
     id: string;
     agentId: string;
@@ -73,26 +75,49 @@ export interface Session {
      * turn it started (`linkedTurnEnd` in `core/flow-host.ts`).
      */
     lastTurnId?: string;
+    /** When the active turn started (R7.1, `turn-timing.ts`); absent on a turn started before. */
+    turnStartedAt?: string;
+    /** How long the active turn has waited paused for a person, in ms (R7.1). */
+    pausedMs?: number;
+    /** Since when the active turn waits paused (R7.1); absent while it runs. */
+    pausedAt?: string;
+    /**
+     * The trace context the active turn's message arrived with (R7.4): its trace is the caller's,
+     * and the context core hands on (to the harness, tools and sandbox commands) is in it.
+     */
+    turnTrace?: TraceContext;
     creation: unknown;
-    vaultIds?: readonly string[];
-    credentialSelections?: readonly CredentialSelection[];
     mcpSnapshot?: McpSnapshot;
     mcpDiagnostics?: readonly McpDiagnostic[];
-    /** Session id that keys the shared sandbox; absent means this session owns it. */
-    sandboxOwnerId?: string;
     /**
-     * The sandbox resource the session is attached to (`sandbox: { id }`): its workspace is the
-     * sandbox's, shared with every session attached to it, and it outlives the session.
+     * The Environment the session names (`environment`, protocol 11): its sandbox is the
+     * session's (the Environment's id keys the workspace) and its vault holds the session's
+     * credentials. It outlives the session.
+     */
+    environmentId?: string;
+    /** The Environment's recipe version when the session opened (shown, never enforced). */
+    environmentVersion?: number;
+    /**
+     * The harness that runs the session's turns (R4.1), pinned when it opened: its Environment's
+     * harness, else `nylorun`. Absent on a session opened before R4: ours (`harnessOf`).
      */
-    sandboxId?: string;
+    harness?: string;
     /**
-     * The sandbox chosen when the session was opened, resolved against the Tenant's limits, or
-     * inherited from the session it shares with. Absent when the session has no sandbox or its
-     * definition declares one (`.sandbox()`).
+     * A flow agent's linked session: the session whose turn opened the flow tree. Its sessions
+     * share the tree's Environment, and their turns nest in the root's, so they do not hold the
+     * Environment against each other (`checkEnvironmentTurn`).
+     */
+    flowRootId?: string;
+    /**
+     * The Environment's sandbox spec when the session opened (kinds `virtual` and `pod`).
+     * Absent without an Environment, or for kind `none`.
      */
     sandbox?: SandboxManifest;
-    /** Where `sandbox` came from: `sandbox` is a sandbox resource's spec. */
-    sandboxSource?: "default" | "inline" | "shared" | "sandbox";
+    /**
+     * Why the session takes no new turn: `protocol_11` for a session opened before protocol 11
+     * (migration 0020). Its history stays readable.
+     */
+    closedReason?: string;
 }
 export type AuthScope = {
     kind: "application";
@@ -109,7 +134,7 @@ export type AuthScope = {
 }
 /**
  * A trusted issuer's token (Host feature `trusted-issuers`, F9-D12): one subject, with the
- * issuer's scopes, agents and sandbox grants, until `expiresAt` (ms). Only its expiry ends it.
+ * issuer's scopes, agents and Environment grants, until `expiresAt` (ms). Only its expiry ends it.
  */
  | {
     kind: "token";
@@ -119,8 +144,8 @@ export type AuthScope = {
     /** The issuer's scopes the token holds, which may add `studio`. */
     scopes: ReadonlySet<IssuerScope>;
     agents: ReadonlySet<string> | "*";
-    /** The sandboxes it reaches: exact ids or `p/*` prefixes. Absent or empty reaches none. */
-    sandboxes?: readonly string[];
+    /** The Environments it reaches: exact ids or `p/*` prefixes. Absent or empty reaches none. */
+    environments?: readonly string[];
     expiresAt: number;
     /** The token's `jti`, or a hash of it. */
     tokenId: string;
@@ -182,6 +207,11 @@ export interface TenantContext {
      * this process's `sandbox` today; over the Harness API's `workspace.read` from F6.2.
      */
     readonly workspaces: WorkspaceReader;
+    /**
+     * How the trace route (R7.5) makes spans: the resource and the content the installation exports
+     * (R7.2). Absent: `service.name` `nylorun`, no content.
+     */
+    readonly traces?: TraceOptions;
     /**
      * The run token of each session an advance of this process owns (F5): the credential the
      * HTTP gate clients present for that session's model and MCP calls (`run-grants.ts`).
@@ -212,13 +242,18 @@ export interface TenantContext {
     /** How long an advance's ownership lease lasts; the heartbeat renews it. */
     readonly ownerLeaseMs: number;
     /**
-     * Seam: hand a wake to `DurableExecution.wake`, outside any tx. Business code passes it to
-     * `t.wake` (the outbox), which calls it after commit; the sweep calls it for outbox rows
-     * left undelivered and for orphaned sessions. Resolves `true` once the execution accepted
-     * the wake, `false` while the Tenant is closing: the wake is not sent, and its outbox row
-     * stays for the next sweep.
+     * Seam: hand a wake to `DurableExecution.wake`, outside any tx: the sweep's orphan scan,
+     * and `send`. Resolves `true` once the execution accepted the wake, `false` while the
+     * Tenant is closing: the wake is not sent.
      */
     wake(sessionId: string, wake: Wake): Promise<boolean>;
+    /**
+     * Seam: hand an outbox request to Durable Session Execution (`wake` or `sandboxSignal`),
+     * outside any tx. The store calls it after commit for what business code wrote with
+     * `t.wake` and `t.signalSandbox` (`SessionStore.deliverTo`); the sweep calls it for rows
+     * left undelivered. `false` (the Tenant is closing) leaves the row for the next sweep.
+     */
+    send(request: OutboxRequest): Promise<boolean>;
     /**
      * Seam: abort the advance of a session running in this process, if any. With `turnId`, only
      * an advance of that turn (a cancel signal names the turn it cancelled).
@@ -226,14 +261,16 @@ export interface TenantContext {
     abortLocal(sessionId: string, turnId?: string): void;
     /**
      * Sandbox pods (F7.2): the sandboxes service and the Runtime image pods copy the engine from.
-     * Absent without a cluster (`nylorun sandbox enable`): kind `pod` is `sandbox_unavailable`.
+     * Absent without a cluster (`nylorun sandbox enable`): kind `pod` is `environment_unavailable`.
      */
     readonly pods?: TenantPods;
     /**
-     * Seam: reconcile a pod sandbox, or arm one of its timers (`DurableExecution.sandbox`). Call
-     * it from `t.afterCommit`. Dropped while the Tenant is closing; the sweep re-sends reconciles.
+     * Seam: reconcile a pod sandbox, or arm one of its timers (`DurableExecution.sandbox`),
+     * outside any tx. What a transaction causes goes through `t.signalSandbox` instead, which
+     * writes it down; a direct call is best effort. `false` while the Tenant is closing (not
+     * sent); `true` without sandbox pods, where there is nothing to send.
      */
-    sandboxSignal(sandboxId: string, signal: SandboxSignal): Promise<void>;
+    sandboxSignal(sandboxId: string, signal: SandboxSignal): Promise<boolean>;
     /** This Tenant's execution invocations that need an operator, for Tenant status. */
     readonly stuckInvocations?: () => Promise<StuckInvocation[]>;
     /** Callbacks the Tenant sweep runs after its own steps (`sweep.ts`). */
@@ -267,14 +304,11 @@ export interface Lease {
 export declare function ownedSession(t: Tx, lease: Lease, id: string): Promise<Session>;
 /** The session read in its own transaction, or a 404. */
 export declare function loadSession(ctx: TenantContext, id: string, access?: SessionAccess): Promise<Session>;
-/**
- * A synchronous lookup over `start` and every session its `sandboxOwnerId` chain names, for
- * the sandbox-sharing helpers, which walk that chain synchronously.
- */
-export declare function sandboxLookup(t: Tx, start: string | undefined): Promise<(id: string) => Session | undefined>;
 /** The sandboxes service a Tenant drives its pod sandboxes with (`TenantContext.pods`). */
 export interface TenantPods {
     readonly client: SandboxesClient;
     /** The Runtime image the pods copy the engine from (`NYLORUN_SANDBOX_HARNESS_IMAGE`). */
     readonly harnessImage: string;
 }
+/** The harness a session runs (R4.1): the one it pinned, else ours. */
+export declare function harnessOf(session: Pick<Session, "harness">): string;

package/dist/tenant/context.js

@@ -1,3 +1,4 @@
+import { DEFAULT_HARNESS } from "@nylorun/core/contracts";
 import { fail } from "./http.js";
 /**
  * `access`, when set, limits the request to the owner's sessions of the allowed agents:
@@ -34,19 +35,7 @@ export async function ownedSession(t, lease, id) {
 export function loadSession(ctx, id, access) {
     return ctx.store.tx((t) => sessionOf(t, id, access));
 }
-/**
- * A synchronous lookup over `start` and every session its `sandboxOwnerId` chain names, for
- * the sandbox-sharing helpers, which walk that chain synchronously.
- */
-export async function sandboxLookup(t, start) {
-    const found = new Map();
-    let id = start;
-    while (id && !found.has(id)) {
-        const session = await t.get("sessions", id);
-        if (!session)
-            break;
-        found.set(id, session);
-        id = session.sandboxOwnerId;
-    }
-    return (sid) => found.get(sid);
+/** The harness a session runs (R4.1): the one it pinned, else ours. */
+export function harnessOf(session) {
+    return session.harness ?? DEFAULT_HARNESS;
 }

package/dist/tenant/control.d.ts

@@ -8,9 +8,16 @@
  * - `sessions.reset` is written by the reset's transaction (`reset.ts`): every process moves
  *   its session streams to the new basin generation and ends those of deleted sessions
  *   (`checkSessionStreams`).
+ * - `host.revoked` is written by the transaction that moves a pod sandbox's host epoch
+ *   (`sandboxes.ts`, `sandbox/join.ts`, `sandbox/pods/reconcile.ts`): every process closes its
+ *   connections hosting that sandbox at an older epoch, wherever the host connected
+ *   (`HarnessApiServer.revokeHost`).
  *
  * A lost signal costs latency, never correctness: the advance checks the Session Store before
- * every effect, and the session streams are checked periodically (`streams.ts`).
+ * every effect, the session streams are checked periodically (`streams.ts`), and a revoked
+ * host's writes are fenced by its runs' lease epochs and its token by the sandbox's row.
+ * Signals are read back from their rows for two minutes, so a process whose listener was
+ * down catches up.
  */
 import type { TenantContext } from "./context.js";
 export interface WireControlOptions {

package/dist/tenant/control.js

@@ -16,6 +16,8 @@ export async function wireControl(ctx, options = {}) {
     const follower = await ctx.store.followSignals((signal) => {
         if (signal.type === "session.cancel")
             ctx.abortLocal(signal.sessionId, signal.turnId);
+        else if (signal.type === "host.revoked")
+            ctx.harness.revokeHost(signal.sandboxId, signal.epoch);
         else
             void checkSessionStreams(ctx).catch(report("session stream check failed"));
     }, {

package/dist/tenant/effects.d.ts

@@ -42,6 +42,6 @@ export declare function recoversModelCalls(ctx: TenantContext): boolean;
 export declare function resolveNewFlowEffect(ctx: TenantContext, request: HostEffect, signal: AbortSignal, lease: Lease): Promise<EffectResolution>;
 /**
  * The credential of an MCP server or HTTP tool request made on behalf of a session: from its
- * attached vaults (`vault/sources.ts`).
+ * Environment's vault (`vault/sources.ts`).
  */
 export declare function authorize(ctx: TenantContext, sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;

package/dist/tenant/effects.js

@@ -4,9 +4,9 @@ import { mayDispatchMore } from "../core/limits.js";
 import { sessionCredentials } from "../vault/sources.js";
 import { isRemoteMcpCall } from "../harness/calls.js";
 import { isHttpToolCall } from "../gates/http-tool.js";
-import { owningSandboxSessionId, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
+import { sandboxSpecOf } from "../sandbox/share.js";
 import { withPlatformTools, withSandboxCapability } from "../sandbox/session-sandbox.js";
-import { loadSession, ownedSession, sandboxLookup, sessionOf, } from "./context.js";
+import { loadSession, ownedSession, sessionOf, } from "./context.js";
 import { fail } from "./http.js";
 import { turnManifestOf } from "./session.js";
 import { command } from "./commands.js";
@@ -85,11 +85,14 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
             }
         }
         const active = await countActiveFlowWork(t, request.sessionId, request.turnId);
+        // When the run journaled the effect (R7.1); a queued effect keeps it once dispatched.
+        const startedAt = existing?.startedAt ?? new Date().toISOString();
         if (!mayDispatchMore(active, ctx.flowLimits)) {
             if (!existing || existing.status !== "queued")
                 await t.put("effects", request.effectId, {
                     request,
                     status: "queued",
+                    startedAt,
                 });
             return resolved({ status: "pending" });
         }
@@ -101,19 +104,32 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                 value: {
                     kind: "failed",
                     code: "tool.unavailable",
-                    message: `The tool stage '${request.key ?? request.path ?? ""}' runs your code, and the Runtime runs no code of yours during a session`,
+                    message: `The tool stage '${request.key ?? request.path ?? ""}' runs your code, but the Runtime runs agents from their manifests alone`,
                 },
             };
-            await t.put("effects", request.effectId, { request, status: "completed", outcome });
-            await t.event(workflow.id, workflow.activeTurnId, "node.started", {
+            await t.put("effects", request.effectId, {
+                request,
+                status: "completed",
+                outcome,
+                startedAt,
+                settledAt: startedAt,
+            });
+            const node = {
                 path: request.path,
                 kind: "tool",
                 key: request.key,
                 ...(request.iterations !== undefined ? { iterations: request.iterations } : {}),
+            };
+            await t.event(workflow.id, workflow.activeTurnId, "node.started", node);
+            // Nothing ran (R7.1): the stage's outcome row says so.
+            await t.event(workflow.id, workflow.activeTurnId, "node.completed", {
+                ...node,
+                effectId: request.effectId,
+                status: "failed",
             });
             return resolved({ status: "completed", outcome });
         }
-        return { kind: "agent", workflow };
+        return { kind: "agent", workflow, startedAt };
     });
     if (step.kind === "resolved")
         return step.resolution;
@@ -130,6 +146,7 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
             request,
             status: "pending",
             agentSessionId,
+            startedAt: step.startedAt,
         });
         await t.put("links", agentSessionId, {
             workflowSessionId: workflow.id,
@@ -145,12 +162,8 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
         if (exists)
             return;
         const definition = leafDefinition(workflow, body, request);
-        const lookup = await sandboxLookup(t, workflow.sandboxOwnerId);
-        const sandboxOwnerId = sessionSandboxSpec(workflow) || workflow.sandboxOwnerId
-            ? owningSandboxSessionId(workflow, lookup)
-            : undefined;
-        // A sandbox chosen when the tree was opened reaches every agent in it, with its tools.
-        const inherited = inheritedSandbox(sandboxOwnerId === undefined ? undefined : lookup(sandboxOwnerId) ?? workflow, definition);
+        // The tree's Environment reaches every agent in it: its sandbox, with its tools, and its vault.
+        const inherited = inheritedSandbox(workflow, definition);
         // Without one, an agent with MCP or HTTP tools still reads its stored results (R2b C11).
         const pinned = inherited?.manifest ? inherited : platformTools(definition.manifest);
         const created = {
@@ -167,14 +180,18 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                 requestId: `flow-put-${request.effectId}`,
                 agentId: body.agentId,
                 ownerUserId: workflow.ownerUserId,
-                ...(sandboxOwnerId ? { sandbox: { session: sandboxOwnerId } } : {}),
+                ...(workflow.environmentId === undefined ? {} : { environment: workflow.environmentId }),
             },
-            vaultIds: workflow.vaultIds,
-            credentialSelections: workflow.credentialSelections,
-            ...(sandboxOwnerId ? { sandboxOwnerId } : {}),
-            ...(inherited
-                ? { sandbox: inherited.spec, sandboxSource: "shared" }
-                : {}),
+            flowRootId: workflow.flowRootId ?? workflow.id,
+            ...(workflow.environmentId === undefined
+                ? {}
+                : {
+                    environmentId: workflow.environmentId,
+                    ...(workflow.environmentVersion === undefined
+                        ? {}
+                        : { environmentVersion: workflow.environmentVersion }),
+                }),
+            ...(inherited ? { sandbox: inherited.spec } : {}),
         };
         await t.put("sessions", agentSessionId, created);
     });
@@ -258,7 +275,7 @@ function platformTools(manifest) {
 }
 /**
  * The credential of an MCP server or HTTP tool request made on behalf of a session: from its
- * attached vaults (`vault/sources.ts`).
+ * Environment's vault (`vault/sources.ts`).
  */
 export async function authorize(ctx, sessionId, request) {
     const s = await loadSession(ctx, sessionId);

package/dist/tenant/environments.d.ts

@@ -0,0 +1,167 @@
+/**
+ * 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.
+ *
+ * - **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.
+ * - **A recipe that changes.** `PUT` on an existing id compares the fields sent: `kind` and
+ *   `storage` are fixed (`409`), labels replace, and any other change writes the recipe and bumps
+ *   `version`. A pod runs `applied`: image and resources reach it when it is next asked to run
+ *   from stopped (`wantRunning`), so nothing swaps them mid-turn; so does `harness`, which picks
+ *   what the pod runs (R4.4). Network and lifecycle apply at once. A virtual or `none`
+ *   Environment applies every change at once.
+ * - **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).
+ * - **Serial turns.** One turn at a time per Environment with a sandbox: a session whose
+ *   Environment another session's turn holds is refused (`409 environment_busy`).
+ * - **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.
+ */
+import { type EnvironmentView, type PutEnvironmentRequest } from "@nylorun/core/contracts";
+import type { Environment, Tx } from "../store/types.js";
+import type { SandboxRouteDeps } from "../core/sandbox-routes.js";
+import { type AuthScope, type Session, type TenantContext } from "./context.js";
+/** The Environment grants that limit `scope`, or undefined when it reaches every Environment. */
+export declare function environmentGrantsOf(scope: AuthScope): readonly string[] | undefined;
+/** Who the vault's audit rows name for a request: the subject, else the application. */
+export declare function actorOf(scope: AuthScope): string;
+/** Refuses (the 404 of a missing one) Environment `id` when the caller's grants miss it. */
+export declare function assertReaches(scope: AuthScope, id: string): void;
+/** An Environment, unless it is gone or being deleted. */
+export declare function liveEnvironment(t: Tx, id: string, options?: {
+    lock?: boolean;
+}): Promise<Environment | undefined>;
+/**
+ * `PUT /v1/environments/{id}`: creates the Environment and its vault (within the Tenant's limit
+ * on their number), or finds the one with this id, so "get or create" is one call. On an
+ * existing one, `kind` and `storage` must match, labels replace, the owner guard is set or
+ * cleared, and a recipe change bumps `version`. Every `PUT` counts as the Environment's use.
+ */
+export declare function putEnvironment(ctx: TenantContext, id: string, body: PutEnvironmentRequest, scope: AuthScope): Promise<EnvironmentView>;
+/** `GET /v1/environments/{id}`. */
+export declare function getEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<EnvironmentView>;
+/** `GET /v1/environments?label=k=v`: every Environment with all the labels, that the caller reaches. */
+export declare function listEnvironments(ctx: TenantContext, labels: Record<string, string>, scope: AuthScope): Promise<{
+    environments: EnvironmentView[];
+}>;
+/**
+ * Asks pod Environment `id` to run when it is stopped or failed (a disk copy needs its engine),
+ * with its recipe applied, as a turn start would.
+ */
+export declare function wakePod(ctx: TenantContext, id: string): Promise<void>;
+/** Whether a disk lease (R2d step 3) holds `environment` now. */
+export declare function diskHeld(environment: Environment, now?: number): boolean;
+/** Refused while a snapshot or restore copies the disk (a pending seed does not count). */
+export declare function refuseDiskCopy(environment: Environment): void;
+/**
+ * `DELETE /v1/environments/{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.
+ */
+export declare function deleteEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<{
+    id: string;
+    deleted: boolean;
+}>;
+/**
+ * Deletes every Environment unused for its `lifecycle.deleteAfter` (Q13): no turn, recipe
+ * change, secret write, stop or reset since. One with a turn running waits for the next sweep.
+ * Run by the Tenant sweep.
+ */
+export declare function sweepUnusedEnvironments(ctx: TenantContext, now?: number): Promise<void>;
+/**
+ * `POST /v1/environments/{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 declare function stopEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<EnvironmentView>;
+/**
+ * `POST /v1/environments/{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 declare function resetEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<EnvironmentView>;
+/**
+ * Gives pod Environment `environment` (locked) a new pod on a new, empty volume, the next volume
+ * generation, with its recipe applied: the old Sandbox and volume are retired. With `seed`, the
+ * new volume starts from that disk version before any turn (R2d step 3): a restore, or the
+ * recovery of a lost volume.
+ */
+export declare function newVolume(ctx: TenantContext, t: Tx, environment: Environment, options?: {
+    seed?: {
+        artifactId: string;
+        version: number;
+    };
+    reason?: "restore" | "lost";
+}): Promise<number>;
+/** How long a pending seed holds the disk before another process may take it over. */
+export declare const SEED_LEASE_MS: number;
+/** `GET /v1/environments/{id}/events`: the Environment's lifecycle stream. */
+export declare function environmentEventsOf(ctx: TenantContext, id: string, scope: AuthScope, fromSeq: number | undefined): Promise<{
+    events: {
+        schema: "nylorun.environment-event/1";
+        eventId: string;
+        tenantId: string;
+        environmentId: string;
+        seq: number;
+        time: string;
+        type: "environment.attached" | "environment.created" | "environment.deleted" | "environment.detached" | "environment.egress" | "environment.failed" | "environment.lost" | "environment.relaunched" | "environment.reset" | "environment.running" | "environment.suspended";
+        payload: Record<string, unknown>;
+    }[];
+}>;
+/**
+ * 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 declare function openEnvironment(t: Tx, id: string, options: {
+    grants?: readonly string[];
+    ownerUserId: string;
+    opaque: boolean;
+}): Promise<Environment>;
+/** Records the attachment on the session's log and on the Environment's stream. */
+export declare function recordAttachment(t: Tx, sessionId: string, environmentId: string): Promise<void>;
+/**
+ * Checks a turn start on a session that names an Environment, in the command's transaction
+ * after the session row lock: the Environment still exists, a token caller's grants reach it,
+ * its owner guard admits the session's owner, and, with a sandbox, no other session's turn
+ * holds it. Holds the Environment row's lock until the transaction ends, so two turn starts 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
+ * its recipe applied, after the commit.
+ */
+export declare function checkEnvironmentTurn(t: Tx, session: Session, scope: AuthScope, ctx?: TenantContext): Promise<void>;
+/** A sessions reset detaches every session from its Environment: each one's stream says so. */
+export declare function detachAllSessions(t: Tx): Promise<void>;
+/**
+ * Marks the end of a turn's segment on Environment `id`: it was used now (`deleteAfter` counts
+ * from here), and for a running pod idle counts from now and the idle timer is armed (D34).
+ * Best effort.
+ */
+export declare function touchEnvironment(ctx: TenantContext, id: string): Promise<void>;
+/**
+ * Re-arms the idle timer of every running pod after the Tenant's settings change, so a shorter
+ * `limits.idle` applies to pods already idle (D36: the settings are read whenever a timer is
+ * set). Best effort.
+ */
+export declare function rearmPodTimers(ctx: TenantContext): Promise<void>;
+/** Session lookups for the sandbox route handlers (`core/sandbox-routes.ts`). */
+export declare function sandboxRouteDeps(ctx: TenantContext): SandboxRouteDeps;