@xemahq/agent-session-runtime 0.1.1

package/src/lib/environment-resolver.ts

@@ -0,0 +1,480 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── EnvironmentResolver — single source of truth for execution env ──
+//
+// Wraps the existing `WorkspaceImageComposer` (which produces mount
+// plans) and adds the dimensions the manifest now declares: skills,
+// MCP services, credentials, permissions, persistence paths, preview
+// surface, sub-agents, default model, env vars, plus the resolved
+// agent identity itself. Output is a `ResolvedEnvironment` — the
+// snapshot every entry point (workflow agent.activity, interactive-
+// session bootstrap) hands to `applyWorkerControlSetup`.
+//
+// Precedence chain (top wins):
+//
+//   1. ExplicitOverrides (session/run model override, workflow `with.model`)
+//   2. SurfaceContext.surfaceDefaults (caller-derived surface knobs)
+//   3. Workspace manifest (`spec.*`)
+//   4. Intrinsic agent floor (enforced HERE — never overridable)
+//
+// The TOOL floor (`INTRINSIC_FLOOR_TOOLS`) is materialised on every
+// resolution into `ResolvedEnvironment.intrinsicFloorTools`. The set is
+// fixed and closed; nothing in the request can subtract from it.
+// Sub-agent overrides are ADDITIVE, never destructive: an explicit
+// override appends or refines the model on a slug; it cannot remove
+// a manifest-declared sub-agent (and downstream the agent's intrinsic
+// floor cannot be removed either).
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { createHash } from 'node:crypto';
+
+import {
+  INTRINSIC_FLOOR_TOOLS,
+  IntrinsicFloorTool,
+} from '@xemahq/kernel-contracts/agent-composition';
+import type { WorkspaceMountPlan } from '@xemahq/kernel-contracts/agent-workspace';
+import {
+  ToolProviderKind,
+  type ToolSelectionEntry,
+} from '@xemahq/kernel-contracts/mcp-tool';
+import type { CompiledWorkspaceManifest } from '@xemahq/dsl/workspace-manifest';
+import {
+  ManifestSurface,
+  type AgentRunRole,
+  type Briefcase,
+  type BriefcaseMcpTool,
+  type CompiledManifestCredential,
+  type CompiledManifestDisplay,
+  type CompiledManifestPermissions,
+  type CompiledManifestPersistence,
+  type CompiledManifestOutputSurface,
+  type CompiledManifestSkillRef,
+  type ModelRef,
+  type SubAgentBinding,
+} from '@xemahq/kernel-contracts/workflow';
+
+import { ManifestSurfaceMismatchError } from './errors';
+import type { TemplateResolver, WorkspaceImageComposer } from './types';
+
+/**
+ * Discriminated surface context — declares whether the resolver is
+ * being invoked from a workflow step or an interactive session. The
+ * resolver validates `manifest.metadata.surfaceCompat` against this
+ * value and fails fast on mismatch (per CLAUDE.md, no silent fallback).
+ */
+export type SurfaceContext =
+  | {
+      readonly kind: typeof ManifestSurface.WORKFLOW;
+      readonly orgId: string;
+      readonly projectId: string;
+      readonly runId: string;
+      readonly jobRunId: string;
+    }
+  | {
+      readonly kind: typeof ManifestSurface.AGENT_SESSION;
+      readonly orgId: string;
+      readonly projectId: string;
+      readonly sessionId: string;
+      readonly turnGen?: number;
+    };
+
+/**
+ * Per-call explicit overrides. These layer ON TOP of the manifest's
+ * declarations and the agent's intrinsic floor (which is enforced
+ * downstream — the resolver does not see it). Overrides should only
+ * carry values the caller actually wants to assert; absent fields
+ * inherit from the manifest.
+ */
+export interface ExplicitEnvironmentOverrides {
+  /** Replaces `manifest.agent.defaultModel` for this call. */
+  readonly model?: ModelRef;
+  /**
+   * Additive — appended after manifest-declared sub-agents. Duplicate
+   * slugs collapse with override winning (so a caller can refine the
+   * model on a manifest-declared delegate without removing it).
+   */
+  readonly subAgents?: readonly SubAgentBinding[];
+  /**
+   * Replaces `manifest.agent.role` for this call. Used by surfaces
+   * that legitimately re-role the same manifest (e.g. a reviewer
+   * borrow of a builder manifest).
+   */
+  readonly role?: AgentRunRole;
+  /**
+   * Replaces `manifest.agent.deliverableSpecRef` for this call.
+   */
+  readonly deliverableSpecRef?: string;
+}
+
+export interface EnvironmentResolverRequest {
+  readonly manifest: CompiledWorkspaceManifest;
+  readonly surface: SurfaceContext;
+  readonly overrides?: ExplicitEnvironmentOverrides;
+  /** Free-form context threaded to mount-source extractors. */
+  readonly agentContext: Readonly<Record<string, unknown>>;
+  /** Optional template resolver for seed-file template entries. */
+  readonly templateResolver?: TemplateResolver;
+  /**
+   * Kernel-shipped System-scope skill slugs to PREPEND to the mounted
+   * skill list. The resolver forwards this verbatim to the composer
+   * (see `ComposeWorkspaceImageRequest.systemSkillSlugs`). The caller
+   * is the entry-point service (workflow agent.activity, agent-session
+   * bootstrap) — it fetches the list from `skill-registry-api` once
+   * per dispatch. Omitted / empty = no System layer mounted (e.g.
+   * unit tests).
+   */
+  readonly systemSkillSlugs?: readonly string[];
+  /**
+   * Optional MCP stanza resolver (Phase D1). Translates the manifest's
+   * `toolSelection` into a `mcpServers` map suitable for direct write
+   * into `opencode.jsonc:mcp`. When absent, the resolved environment
+   * carries no MCP stanzas — appropriate for workflow surfaces today
+   * (no MCP support) and tests. Session-api wires its
+   * `SessionToolResolverService` in via this hook so the same
+   * snapshot covers MCP alongside agents + skills + permissions.
+   */
+  readonly mcpResolver?: McpStanzaResolver;
+  /**
+   * Run-scoped Briefcase from `ActionBaseInput.briefcase`. The resolver
+   * unions `briefcase.mcpTools[]` with `manifest.toolSelection` before
+   * calling the mcpResolver and emitting `resolved.toolSelection`,
+   * and threads the briefcase through to the composer for upload /
+   * reference mount entries. Workflow declarations are never
+   * SUBTRACTED — briefcase tools are strictly additive.
+   */
+  readonly briefcase?: Briefcase;
+}
+
+/**
+ * Kernel-tier abstraction for "given a tool selection + tenancy +
+ * session context, return the `mcpServers` stanza opencode.jsonc
+ * expects". Implementations live in Platform packages
+ * (`SessionToolResolverService` in `agent-session-api`) so the
+ * kernel never imports mcp-gateway-api directly.
+ */
+export interface McpStanzaResolver {
+  resolve(
+    selection: readonly ToolSelectionEntry[],
+    context: McpStanzaResolverContext,
+  ): Promise<Record<string, unknown>>;
+}
+
+export interface McpStanzaResolverContext {
+  readonly orgId: string;
+  readonly projectId: string;
+  readonly sessionId?: string;
+  readonly actorSubject?: string;
+}
+
+/**
+ * Fully resolved execution environment — the snapshot every entry
+ * point hands to `applyWorkerControlSetup`. Deterministic in
+ * (manifest, surface, overrides, agentContext): `hash` is a sha256 of
+ * the canonical-form JSON so resume drift detection can compare two
+ * resolutions cheaply.
+ */
+export interface ResolvedEnvironment {
+  readonly surface: ManifestSurface;
+  readonly manifest: {
+    readonly slug: string;
+    readonly version: string;
+  };
+  readonly display: CompiledManifestDisplay;
+  readonly agent: {
+    readonly slug: string;
+    readonly role: AgentRunRole;
+    readonly deliverableSpecRef?: string;
+    readonly model?: ModelRef;
+  };
+  readonly subAgents: readonly SubAgentBinding[];
+  readonly skills: readonly CompiledManifestSkillRef[];
+  readonly toolSelection: readonly ToolSelectionEntry[];
+  /**
+   * Baseline tools every agent receives regardless of manifest — `bash`,
+   * `read`, `write`, `edit`, `grep`, `glob`, `ls`, `task`, `todo_write`,
+   * `memory`. Fixed, closed, and not overridable: the resolver writes
+   * the same set on every resolution. Downstream consumers (worker
+   * activity, session-bundle apply) merge this into the agent's runtime
+   * tool surface before handing to OpenCode. Strings are the wire-shape
+   * tool names (members of the `IntrinsicFloorTool` enum).
+   */
+  readonly intrinsicFloorTools: readonly IntrinsicFloorTool[];
+  readonly credentials: readonly CompiledManifestCredential[];
+  readonly permissions: CompiledManifestPermissions;
+  readonly persistence: CompiledManifestPersistence;
+  readonly outputSurface: CompiledManifestOutputSurface;
+  readonly mountPlan: WorkspaceMountPlan;
+  readonly env: readonly { readonly name: string; readonly value: string }[];
+  /**
+   * Phase D1: resolved `mcpServers` map ready to drop into
+   * `opencode.jsonc:mcp`. Empty `{}` when the manifest declares no
+   * toolSelection or when the request omits an `mcpResolver`. Keeps
+   * the snapshot self-contained so downstream callers (workflow
+   * activity, session-api bundle apply) do not have to re-resolve
+   * MCP independently.
+   */
+  readonly mcpServers: Readonly<Record<string, unknown>>;
+  /**
+   * Deterministic sha256 of the canonical-form JSON of every other
+   * field. Drift detection diffs the structured fields; this hash is
+   * a cheap "are we different at all?" early exit.
+   */
+  readonly hash: string;
+}
+
+export interface EnvironmentResolver {
+  resolve(req: EnvironmentResolverRequest): Promise<ResolvedEnvironment>;
+}
+
+export class DefaultEnvironmentResolver implements EnvironmentResolver {
+  constructor(private readonly composer: WorkspaceImageComposer) {}
+
+  async resolve(req: EnvironmentResolverRequest): Promise<ResolvedEnvironment> {
+    this.assertSurfaceCompat(req.manifest, req.surface);
+
+    const role = req.overrides?.role ?? req.manifest.agent.role;
+    const deliverableSpecRef =
+      req.overrides?.deliverableSpecRef ?? req.manifest.agent.deliverableSpecRef;
+
+    const mountPlan = await this.composer.compose({
+      orgId: req.surface.orgId,
+      projectId: req.surface.projectId,
+      manifest: req.manifest,
+      agentContext: req.agentContext,
+      ...(req.surface.kind === ManifestSurface.WORKFLOW
+        ? {
+            workflowRun: {
+              runId: req.surface.runId,
+              jobRunId: req.surface.jobRunId,
+            },
+          }
+        : {
+            interactive: {
+              sessionId: req.surface.sessionId,
+              ...(req.surface.turnGen !== undefined
+                ? { turnGen: req.surface.turnGen }
+                : {}),
+            },
+          }),
+      agentOverrides: {
+        role,
+        ...(deliverableSpecRef !== undefined ? { deliverableSpecRef } : {}),
+      },
+      ...(req.templateResolver !== undefined
+        ? { templateResolver: req.templateResolver }
+        : {}),
+      ...(req.systemSkillSlugs !== undefined
+        ? { systemSkillSlugs: req.systemSkillSlugs }
+        : {}),
+      ...(req.briefcase !== undefined ? { briefcase: req.briefcase } : {}),
+    });
+
+    const subAgents = mergeSubAgents(
+      req.manifest.agent.subAgents,
+      req.overrides?.subAgents,
+    );
+    const model = req.overrides?.model ?? req.manifest.agent.defaultModel;
+
+    const toolSelection = mergeBriefcaseToolSelection(
+      req.manifest.toolSelection,
+      req.briefcase?.mcpTools,
+    );
+
+    // Phase H.2: capability federation. When an `mcpResolver` is wired
+    // (session-boot, workflow-runtime-worker) the resolver ALWAYS runs —
+    // the returned stanza is the fixed three meta-tool surface
+    // (`xema-capabilities-{list,describe,invoke}`), regardless of
+    // selection. `toolSelection` is still threaded through for snapshot
+    // provenance / audit, but the wire-side resolver ignores it. Empty
+    // `{}` only when no resolver is wired (unit tests + workflow surfaces
+    // that don't talk to mcp-gateway yet).
+    let mcpServers: Readonly<Record<string, unknown>> = Object.freeze({});
+    if (req.mcpResolver) {
+      const ctx: McpStanzaResolverContext =
+        req.surface.kind === ManifestSurface.AGENT_SESSION
+          ? {
+              orgId: req.surface.orgId,
+              projectId: req.surface.projectId,
+              sessionId: req.surface.sessionId,
+            }
+          : {
+              orgId: req.surface.orgId,
+              projectId: req.surface.projectId,
+            };
+      mcpServers = await req.mcpResolver.resolve(toolSelection, ctx);
+    }
+
+    const resolved: Omit<ResolvedEnvironment, 'hash'> = {
+      surface: req.surface.kind,
+      manifest: {
+        slug: req.manifest.slug,
+        version: req.manifest.version,
+      },
+      display: req.manifest.display,
+      agent: {
+        slug: req.manifest.agent.slug,
+        role,
+        ...(deliverableSpecRef !== undefined ? { deliverableSpecRef } : {}),
+        ...(model !== undefined ? { model } : {}),
+      },
+      subAgents,
+      skills: req.manifest.skills,
+      toolSelection,
+      // Floor is a fixed, closed set — emitted on every resolution. The
+      // request cannot subtract from it; the manifest cannot subtract
+      // from it. Downstream consumers MUST merge this set with the
+      // agent's authored permission block before handing to OpenCode.
+      intrinsicFloorTools: INTRINSIC_FLOOR_TOOLS,
+      credentials: req.manifest.credentials,
+      permissions: req.manifest.permissions,
+      persistence: req.manifest.persistence,
+      outputSurface: req.manifest.outputSurface,
+      mountPlan,
+      env: req.manifest.env,
+      mcpServers,
+    };
+
+    return { ...resolved, hash: hashResolved(resolved) };
+  }
+
+  private assertSurfaceCompat(
+    manifest: CompiledWorkspaceManifest,
+    surface: SurfaceContext,
+  ): void {
+    if (!manifest.surfaceCompat.includes(surface.kind)) {
+      throw new ManifestSurfaceMismatchError(
+        `Manifest '${manifest.slug}@${manifest.version}' declares surfaceCompat=[${manifest.surfaceCompat.join(', ')}] but was resolved on '${surface.kind}'.`,
+      );
+    }
+  }
+}
+
+/**
+ * Merge manifest-declared sub-agents with caller-supplied overrides.
+ * Overrides are additive: matching slugs collapse with override
+ * winning (so the caller can refine a manifest-declared delegate's
+ * model without redeclaring its alias). Insertion order is preserved
+ * so downstream `applyWorkerControlSetup` materialises a deterministic
+ * agent list.
+ */
+/**
+ * Exported so callers that materialise a session before holding a full
+ * `ResolvedEnvironment` (the workflow activity's pre-resolve setup
+ * call, the agent-session resume path) can compose the same
+ * authoritative sub-agent list the resolver would produce. Single
+ * source of truth — pickers MUST NOT roll their own merge.
+ */
+export function mergeSubAgents(
+  base: readonly SubAgentBinding[],
+  overrides: readonly SubAgentBinding[] | undefined,
+): readonly SubAgentBinding[] {
+  if (!overrides || overrides.length === 0) {return base;}
+  const overrideBySlug = new Map<string, SubAgentBinding>(
+    overrides.map((s) => [s.slug, s]),
+  );
+  const baseSlugs = new Set<string>();
+  const out: SubAgentBinding[] = [];
+  for (const b of base) {
+    baseSlugs.add(b.slug);
+    out.push(overrideBySlug.get(b.slug) ?? b);
+  }
+  for (const o of overrides) {
+    if (!baseSlugs.has(o.slug)) {out.push(o);}
+  }
+  return out;
+}
+
+/**
+ * Union the manifest's static toolSelection with the run-scoped
+ * briefcase tools. Briefcase entries are appended (manifest order
+ * wins for stable opencode key ordering); duplicates by
+ * `(kind, providerKind, resourceId, toolName?)` collapse.
+ *
+ * `BriefcaseMcpTool.providerKind` is wire-shape `string`; we validate
+ * against `ToolProviderKind` here so an out-of-enum value fails fast
+ * at dispatch instead of silently bypassing the manifest contract.
+ */
+function mergeBriefcaseToolSelection(
+  manifestSelection: readonly ToolSelectionEntry[],
+  briefcaseTools: readonly BriefcaseMcpTool[] | undefined,
+): readonly ToolSelectionEntry[] {
+  if (!briefcaseTools || briefcaseTools.length === 0) return manifestSelection;
+  const out: ToolSelectionEntry[] = [...manifestSelection];
+  const seen = new Set<string>(out.map(toolSelectionKey));
+  for (const t of briefcaseTools) {
+    if (!isToolProviderKind(t.providerKind)) {
+      throw new Error(
+        `briefcase.mcpTools[].providerKind='${t.providerKind}' is not a known ToolProviderKind — dispatch must validate at the engine boundary.`,
+      );
+    }
+    const entry: ToolSelectionEntry =
+      t.kind === 'tool'
+        ? {
+            kind: 'tool',
+            providerKind: t.providerKind,
+            resourceId: t.resourceId,
+            toolName: requireToolName(t),
+          }
+        : {
+            kind: 'provider',
+            providerKind: t.providerKind,
+            resourceId: t.resourceId,
+          };
+    const key = toolSelectionKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(entry);
+  }
+  return out;
+}
+
+function toolSelectionKey(entry: ToolSelectionEntry): string {
+  return entry.kind === 'tool'
+    ? `tool:${entry.providerKind}:${entry.resourceId}:${entry.toolName}`
+    : `provider:${entry.providerKind}:${entry.resourceId}`;
+}
+
+function isToolProviderKind(value: string): value is ToolProviderKind {
+  return (Object.values(ToolProviderKind) as string[]).includes(value);
+}
+
+function requireToolName(t: BriefcaseMcpTool): string {
+  if (t.toolName === undefined || t.toolName.length === 0) {
+    throw new Error(
+      `briefcase.mcpTools[].toolName is required when kind='tool' (providerKind='${t.providerKind}', resourceId='${t.resourceId}').`,
+    );
+  }
+  return t.toolName;
+}
+
+/**
+ * Canonical-form sha256 of the resolved environment minus the hash
+ * itself. Used for cheap drift detection: if two snapshots hash to the
+ * same value the structured diff is guaranteed to be empty.
+ *
+ * Excludes `mountPlan` from the hash because mount-plan composition
+ * embeds caller-supplied lease keys / timestamps that don't actually
+ * change the environment shape — the comparator focuses on what the
+ * manifest declares, not on transient plan-side identifiers. Mount-
+ * level drift surfaces through the structured diff instead.
+ */
+function hashResolved(
+  resolved: Omit<ResolvedEnvironment, 'hash'>,
+): string {
+  const { mountPlan: _mountPlan, ...rest } = resolved;
+  return createHash('sha256').update(canonicalJson(rest)).digest('hex');
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(',')}]`;
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => a.localeCompare(b));
+  return `{${entries
+    .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`)
+    .join(',')}}`;
+}

package/src/lib/errors.ts

@@ -0,0 +1,43 @@
+import { AWP_V1_SPEC } from '@xemahq/kernel-contracts/agent-workspace';
+
+/**
+ * Thrown by the composer when a manifest references an AWP slot key
+ * that is not declared in `AWP_V1_SPEC.slots`. Fail-fast — the
+ * alternative (silent skip) yields an incomplete workspace with no
+ * signal to the operator, masking typos and stale slot names from
+ * older spec versions.
+ */
+/**
+ * Thrown by `DefaultEnvironmentResolver.resolve()` when the resolved
+ * manifest's `metadata.surfaceCompat` does not include the surface
+ * the resolver is being invoked on (e.g. a workflow step pointing at
+ * a manifest declared `surfaceCompat: [agent-session]`). Fail-
+ * fast — the alternative is a silently broken dispatch where the
+ * agent boots on a surface the manifest authoring time never
+ * considered.
+ */
+export class ManifestSurfaceMismatchError extends Error {
+  override readonly name = 'ManifestSurfaceMismatchError';
+}
+
+export class UnknownSlotError extends Error {
+  override readonly name = 'UnknownSlotError';
+
+  constructor(
+    readonly slotKey: string,
+    readonly origin:
+      | 'manifest.mounts'
+      | 'manifest.seedFiles'
+      | 'rendered.mounts'
+      | 'inputArtifacts',
+    readonly manifestSlug: string,
+    readonly manifestVersion: string,
+  ) {
+    super(
+      `Workspace manifest '${manifestSlug}@${manifestVersion}' references slot '${slotKey}' from ${origin}, ` +
+        `but AWP_V1_SPEC declares no such slot. Known slots: [${AWP_V1_SPEC.slots
+          .map((s) => s.key)
+          .join(', ')}].`,
+    );
+  }
+}

package/src/lib/lifecycle-state.ts

@@ -0,0 +1,139 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent-session lifecycle state machine ──
+//
+// Pure enums + transitions. Mirrors the `SessionStatus` enum persisted by
+// the agent-session-api service; the worker imports from here (the
+// service's persistence-layer enums are not importable across the apps
+// boundary).
+//
+// Single source of truth for "can this session be paused right now?".
+// Both interactive-session callers AND the workflow-runtime-worker
+// dispatch activity consult `canTransition()` before issuing the HTTP
+// call so misuse fails fast at compile time rather than as a 409 from
+// the service.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Lifecycle state of an agent-session row. Mirrors the persisted enum on
+ * the agent-session-api service. Closed set.
+ */
+export const SessionLifecycleState = {
+  creating: 'creating',
+  provisioning: 'provisioning',
+  active: 'active',
+  paused: 'paused',
+  recovering: 'recovering',
+  completing: 'completing',
+  completed: 'completed',
+  failed: 'failed',
+  archived: 'archived',
+} as const;
+
+export type SessionLifecycleStateValue =
+  (typeof SessionLifecycleState)[keyof typeof SessionLifecycleState];
+
+/**
+ * Who created the session row. Mirrors the persisted `SessionOwnerKind`.
+ *
+ *   - `interactive_session`  — user-facing chat sessions
+ *   - `pipeline_run`         — workflow-runtime-worker redraft loop spines
+ *   - `chat_thread`          — reserved (no dispatcher today)
+ *
+ * The CI enum-parity check verifies this stays in lockstep with the
+ * persisted enum.
+ */
+export const SessionOwnerKind = {
+  interactive_session: 'interactive_session',
+  pipeline_run: 'pipeline_run',
+  chat_thread: 'chat_thread',
+} as const;
+
+export type SessionOwnerKindValue =
+  (typeof SessionOwnerKind)[keyof typeof SessionOwnerKind];
+
+/**
+ * Per-state transition matrix. `canTransition(from, to)` returns true
+ * iff the transition is valid.
+ *
+ * Notable transitions:
+ *   - `paused → recovering` (resume claim)
+ *   - `recovering → active` (resume success)
+ *   - `recovering → paused` (resume rollback)
+ *   - `active → completing → completed` (terminal success)
+ *   - any-non-terminal → `failed` (terminal failure)
+ *   - `paused | completed | failed → archived` (cleanup sweep)
+ */
+const TRANSITIONS: Readonly<
+  Record<SessionLifecycleStateValue, ReadonlySet<SessionLifecycleStateValue>>
+> = {
+  creating: new Set([
+    SessionLifecycleState.provisioning,
+    SessionLifecycleState.failed,
+  ]),
+  provisioning: new Set([
+    SessionLifecycleState.active,
+    SessionLifecycleState.failed,
+  ]),
+  active: new Set([
+    SessionLifecycleState.paused,
+    SessionLifecycleState.completing,
+    SessionLifecycleState.failed,
+  ]),
+  paused: new Set([
+    SessionLifecycleState.recovering,
+    SessionLifecycleState.archived,
+    SessionLifecycleState.failed,
+  ]),
+  recovering: new Set([
+    SessionLifecycleState.active,
+    SessionLifecycleState.paused,
+    SessionLifecycleState.failed,
+  ]),
+  completing: new Set([
+    SessionLifecycleState.completed,
+    SessionLifecycleState.failed,
+  ]),
+  completed: new Set([SessionLifecycleState.archived]),
+  failed: new Set([SessionLifecycleState.archived]),
+  archived: new Set(),
+};
+
+export function canTransition(
+  from: SessionLifecycleStateValue,
+  to: SessionLifecycleStateValue,
+): boolean {
+  return TRANSITIONS[from].has(to);
+}
+
+/**
+ * Terminal states — no further transitions possible (except the
+ * `completed | failed → archived` cleanup sweep). Callers use this to
+ * short-circuit "is this session done?" checks.
+ */
+export function isTerminal(state: SessionLifecycleStateValue): boolean {
+  return (
+    state === SessionLifecycleState.completed ||
+    state === SessionLifecycleState.failed ||
+    state === SessionLifecycleState.archived
+  );
+}
+
+/**
+ * Pausable states — the session has a live worker that can be told to
+ * snapshot. `provisioning` is intentionally excluded: the worker isn't
+ * ready yet, so a pause request would 409. Callers receiving such a
+ * 409 should retry with backoff once `active` is reached.
+ */
+export function isPausable(state: SessionLifecycleStateValue): boolean {
+  return state === SessionLifecycleState.active;
+}
+
+/**
+ * Resumable states. `paused` is the canonical case. `failed` rows are
+ * NOT resumable from here — they require explicit operator action
+ * (the resume API would 409). `recovering` is a transient state owned
+ * by an in-flight resume; another caller observing it should back off.
+ */
+export function isResumable(state: SessionLifecycleStateValue): boolean {
+  return state === SessionLifecycleState.paused;
+}