@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/agent/process/sessions-teardown.ts

@@ -0,0 +1,281 @@
+/**
+ * Terminate / cancel / dispose phases for managed process sessions.
+ */
+import { killProcessTree } from "../shell.js";
+import { acquireRecordLease, loadProcessRecoveryRecords, releaseRecordLease } from "./recovery.js";
+import {
+  assertNotDisposed,
+  durableSeams,
+  emit,
+  isTerminalState,
+  nowIso,
+  type SessionRecord,
+  type SessionsHost,
+  settleWaiters,
+} from "./sessions-host.js";
+import { persistRecoveryUnknown, persistTransition } from "./sessions-monitor.js";
+import { ProcessSessionError, type ProcessSessionState } from "./types.js";
+
+export function reconcileAllUnknown(host: SessionsHost): number {
+  let n = 0;
+  for (const record of [...host.sessions.values()]) {
+    if (record.state !== "running" && record.state !== "starting") continue;
+    terminateRecord(host, record, "unknown", null);
+    n += 1;
+  }
+  return n;
+}
+
+export async function checkSandboxAlive(host: SessionsHost): Promise<void> {
+  if (!host.sandbox?.status || host.sandboxLost) return;
+  try {
+    const status = await host.sandbox.status();
+    if (status.state !== "running") {
+      host.sandboxLost = true;
+      reconcileAllUnknown(host);
+    }
+  } catch {
+    host.sandboxLost = true;
+    reconcileAllUnknown(host);
+  }
+}
+
+export function sweepExpired(host: SessionsHost): void {
+  const now = Date.now();
+  for (const record of host.sessions.values()) {
+    if (record.state !== "running" && record.state !== "starting") continue;
+    if (now < record.expiresAt) continue;
+    terminateRecord(host, record, "expired", null);
+  }
+}
+
+export function terminateRecord(host: SessionsHost, record: SessionRecord, state: ProcessSessionState, exitCode: number | null): void {
+  if (
+    record.state === "exited" ||
+    record.state === "killed" ||
+    record.state === "released" ||
+    record.state === "expired" ||
+    record.state === "unknown"
+  ) {
+    return;
+  }
+  const child = record.child;
+  const backend = record.backend;
+  const pty = record.pty;
+  record.child = undefined;
+  record.backend = undefined;
+  record.pty = undefined;
+  if (state === "released") {
+    try {
+      child?.stdout.removeAllListeners();
+      child?.stderr.removeAllListeners();
+      child?.stdout.destroy();
+      child?.stderr.destroy();
+      child?.stdin.destroy();
+      child?.unref();
+    } catch {
+      // best effort
+    }
+    void backend?.release().catch(() => undefined);
+    void pty?.release().catch(() => undefined);
+  } else if (state === "killed" || state === "expired" || state === "unknown") {
+    if (child?.pid) {
+      try {
+        killProcessTree(child.pid);
+      } catch {
+        // best effort
+      }
+    }
+    if (backend) {
+      void backend.kill().catch(() => undefined);
+    }
+    if (pty) {
+      void pty.kill().catch(() => undefined);
+    }
+  } else if (state === "exited" && child) {
+    try {
+      child.stdout.destroy();
+      child.stderr.destroy();
+      child.stdin.destroy();
+    } catch {
+      // best effort
+    }
+  }
+  record.state = state;
+  record.exitCode = state === "unknown" || state === "released" ? null : exitCode;
+  record.exitedAt = nowIso();
+  record.stdinClosed = true;
+  try {
+    record.accumulator.finish();
+  } catch {
+    // ignore
+  }
+  persistTransition(host, record);
+  settleWaiters(record);
+  const type =
+    state === "exited"
+      ? "process_exited"
+      : state === "killed"
+        ? "process_killed"
+        : state === "released"
+          ? "process_released"
+          : state === "expired"
+            ? "process_expired"
+            : "process_unknown";
+  emit(host, {
+    type,
+    sessionId: record.id,
+    processId: record.pid !== undefined ? String(record.pid) : record.id,
+    owner: record.owner,
+    exitCode: record.exitCode,
+    at: record.exitedAt,
+  });
+}
+
+export function requireRecord(host: SessionsHost, sessionId: string, owner?: string): SessionRecord {
+  assertNotDisposed(host);
+  sweepExpired(host);
+  const record = host.sessions.get(sessionId);
+  if (!record) throw new ProcessSessionError("ERR_PRISM_PROCESS_STATE", `unknown session: ${sessionId}`);
+  if (owner !== undefined && owner !== record.owner) {
+    throw new ProcessSessionError("ERR_PRISM_PROCESS_OWNERSHIP", "session owner mismatch");
+  }
+  return record;
+}
+
+export async function cancelOwned(host: SessionsHost, owner: string, cancelOptions?: { release?: boolean }): Promise<void> {
+  assertNotDisposed(host);
+  sweepExpired(host);
+  await checkSandboxAlive(host);
+  const release = cancelOptions?.release === true;
+  for (const record of [...host.sessions.values()]) {
+    if (record.owner !== owner) continue;
+    if (record.state !== "running" && record.state !== "starting") continue;
+    const cancelPty = record.pty;
+    const cancelBackend = record.backend;
+    if (release || record.releaseOnCancel) {
+      if (cancelPty || cancelBackend) {
+        terminateRecord(host, record, "released", null);
+        if (cancelPty) {
+          try {
+            await cancelPty.release();
+          } catch {
+            // continue
+          }
+        } else if (cancelBackend) {
+          try {
+            await cancelBackend.release();
+          } catch {
+            // continue
+          }
+        }
+      } else {
+        terminateRecord(host, record, "released", null);
+      }
+    } else {
+      if (cancelPty || cancelBackend) {
+        terminateRecord(host, record, "killed", null);
+        if (cancelPty) {
+          try {
+            await cancelPty.kill();
+          } catch {
+            // continue
+          }
+        } else if (cancelBackend) {
+          try {
+            await cancelBackend.kill();
+          } catch {
+            // continue
+          }
+        }
+      } else {
+        terminateRecord(host, record, "killed", null);
+      }
+    }
+  }
+  // Durable pass (plan 026 Task 5): cancellation of a recovered/unattached
+  // process either reaches the attached backend (above) or records unknown —
+  // never a fabricated exit. Lease + CAS guard every mutation so two replicas
+  // cannot cancel the same record into different outcomes.
+  if (host.durable) {
+    const seams = durableSeams(host);
+    const { records } = await loadProcessRecoveryRecords({
+      checkpoints: seams.checkpoints,
+      limits: host.recoveryLimits,
+      ownership: host.ownership,
+    });
+    for (const { record, version } of records) {
+      if (record.owner !== owner) continue;
+      if (isTerminalState(record.state)) continue;
+      if (host.sessions.has(record.id)) continue; // handled by the live pass above
+      const lease = await acquireRecordLease({
+        leases: seams.leases,
+        id: record.id,
+        ownerId: seams.ownerId,
+        ttlMs: host.recoveryLimits.leaseTtlMs,
+        ownership: host.ownership,
+      });
+      if (!lease) continue; // another replica owns or is recovering it
+      try {
+        await persistRecoveryUnknown(host, record, version);
+      } finally {
+        await releaseRecordLease({
+          leases: seams.leases,
+          id: record.id,
+          ownerId: seams.ownerId,
+          token: lease.token,
+          ownership: host.ownership,
+        });
+      }
+    }
+  }
+}
+
+export async function disposeSessions(host: SessionsHost): Promise<void> {
+  if (host.disposed) return;
+  host.disposed = true;
+  for (const record of [...host.sessions.values()]) {
+    if (record.state === "running" || record.state === "starting") {
+      if (record.pty) {
+        try {
+          await record.pty.kill();
+        } catch {
+          // best effort
+        }
+      }
+      if (record.backend) {
+        try {
+          await record.backend.kill();
+        } catch {
+          // best effort
+        }
+      }
+      terminateRecord(host, record, "killed", null);
+    } else if (record.state === "released" && record.pid) {
+      try {
+        killProcessTree(record.pid);
+      } catch {
+        // best effort
+      }
+      record.pid = undefined;
+    }
+    try {
+      await record.accumulator.cleanupTempFile();
+    } catch {
+      // best effort
+    }
+    if (record.recoveryLeaseToken) {
+      // A lease token only exists on durable hosts (createSessionsHost validates the seams).
+      const seams = durableSeams(host);
+      void releaseRecordLease({
+        leases: seams.leases,
+        id: record.id,
+        ownerId: seams.ownerId,
+        token: record.recoveryLeaseToken,
+        ownership: host.ownership,
+      });
+      record.recoveryLeaseToken = undefined;
+    }
+  }
+  host.sessions.clear();
+}

package/coding/src/agent/process/sessions.ts

@@ -0,0 +1,30 @@
+/**
+ * Managed ProcessSession registry — native spawn or optional sandbox startProcess.
+ */
+import { assertNotDisposed, createSessionsHost } from "./sessions-host.js";
+import { recoverSessions } from "./sessions-recovery.js";
+import { startSession } from "./sessions-spawn.js";
+import { cancelOwned, disposeSessions, reconcileAllUnknown, requireRecord, terminateRecord } from "./sessions-teardown.js";
+import { type CreateProcessSessionsOptions, ProcessSessionError, type ProcessSessions } from "./types.js";
+
+export function createProcessSessions(options: CreateProcessSessionsOptions): ProcessSessions {
+  const host = createSessionsHost(options);
+  return {
+    start: (request) => startSession(host, request),
+    get: (sessionId, owner) => requireRecord(host, sessionId, owner).handle,
+    cancelOwned: (owner, cancelOptions) => cancelOwned(host, owner, cancelOptions),
+    markUnknown: async (sessionId, owner) => {
+      const record = requireRecord(host, sessionId, owner);
+      if (record.state !== "running" && record.state !== "starting") {
+        throw new ProcessSessionError("ERR_PRISM_PROCESS_STATE", `cannot mark unknown in state ${record.state}`);
+      }
+      terminateRecord(host, record, "unknown", null);
+    },
+    reconcile: async () => {
+      assertNotDisposed(host);
+      return { markedUnknown: reconcileAllUnknown(host) };
+    },
+    recover: (recoverOptions) => recoverSessions(host, recoverOptions),
+    dispose: () => disposeSessions(host),
+  };
+}

package/coding/src/agent/process/types.ts

@@ -0,0 +1,358 @@
+import { OwnershipScope } from "@arnilo/prism";
+import type { CheckpointStore, LeaseStore } from "@arnilo/prism-extensions/workflows";
+/** Duck-typed long-running sandbox handle (mirrors coding-security SandboxProcessHandle). */
+import type { ExecutionPolicy } from "../execution-policy.js";
+import { AgentIdentity } from "../identity.js";
+import {
+  DEFAULT_MAX_PROCESS_INPUT_BYTES,
+  DEFAULT_MAX_PROCESS_LIFETIME_MS,
+  DEFAULT_MAX_PROCESS_OUTPUT_CHUNK_BYTES,
+  DEFAULT_MAX_PROCESS_SESSIONS,
+  DEFAULT_MAX_PROCESS_TOTAL_OUTPUT_BYTES,
+  DEFAULT_MAX_PTY_ATTACH_TIMEOUT_MS,
+  DEFAULT_MAX_PTY_BACKEND_METADATA_BYTES,
+  DEFAULT_MAX_TERMINAL_COLUMNS,
+  DEFAULT_MAX_TERMINAL_RESIZES_PER_MINUTE,
+  DEFAULT_MAX_TERMINAL_ROWS,
+  DEFAULT_MAX_TERMINAL_TERM_BYTES,
+  HARD_MAX_PROCESS_INPUT_BYTES,
+  HARD_MAX_PROCESS_LIFETIME_MS,
+  HARD_MAX_PROCESS_OUTPUT_CHUNK_BYTES,
+  HARD_MAX_PROCESS_SESSIONS,
+  HARD_MAX_PROCESS_TOTAL_OUTPUT_BYTES,
+  HARD_MAX_PTY_ATTACH_TIMEOUT_MS,
+  HARD_MAX_PTY_BACKEND_METADATA_BYTES,
+  HARD_MAX_TERMINAL_COLUMNS,
+  HARD_MAX_TERMINAL_RESIZES_PER_MINUTE,
+  HARD_MAX_TERMINAL_ROWS,
+  HARD_MAX_TERMINAL_TERM_BYTES,
+  validateCodingLimit,
+} from "../limits.js";
+export interface ProcessSandboxHandle {
+  write(data: Uint8Array): Promise<void>;
+  signal(name: string): Promise<void>;
+  kill(): Promise<void>;
+  release(): Promise<void>;
+  wait(options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<{ exitCode: number | null }>;
+  /** Opaque non-secret reattachment ref for durable process recovery (plan 026 Task 5). */
+  readonly ref?: string;
+}
+
+export interface ProcessSandboxStartRequest {
+  readonly file: string;
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly onData?: (data: Buffer) => void;
+  readonly signal?: AbortSignal;
+  readonly timeout?: number;
+}
+
+/** Optional sandbox backend for ProcessSessions.
+ * Presence of `startProcess` = long-running capable; absence fails closed.
+ */
+export interface ProcessSandboxBackend {
+  startProcess?(request: ProcessSandboxStartRequest): Promise<ProcessSandboxHandle>;
+  attachProcess?(ref: string): Promise<ProcessSandboxHandle | null>;
+  status?(): Promise<{ readonly state: string }>;
+}
+
+/** Bounded terminal geometry + TERM for interactive PTY sessions (frozen caps in limits.ts). */
+export interface ProcessTerminalRequest {
+  /** 1..maxTerminalColumns (default 120; host-configured max wins when smaller). */
+  readonly columns?: number;
+  /** 1..maxTerminalRows (default 40; host-configured max wins when smaller). */
+  readonly rows?: number;
+  /** TERM string, UTF-8 bytes <= maxTerminalTermBytes (default "xterm-256color"). */
+  readonly term?: string;
+}
+
+/** Bounded resize dimensions for an interactive PTY session. */
+export interface ProcessTerminalResize {
+  readonly columns: number;
+  readonly rows: number;
+}
+
+/**
+ * Host PTY handle (mirrors ProcessSandboxHandle) plus optional bounded resize
+ * and backend metadata. Capability is explicit: the session handle exposes
+ * `resize` only when the backend declared `capabilities.resize`.
+ */
+export interface ProcessPtyHandle {
+  write(data: Uint8Array): Promise<void>;
+  signal(name: string): Promise<void>;
+  kill(): Promise<void>;
+  release(): Promise<void>;
+  resize?(dimensions: ProcessTerminalResize): Promise<void>;
+  /** Bounded host metadata (UTF-8 JSON bytes <= maxPtyBackendMetadataBytes), surfaced via session metadata(). */
+  readonly metadata?: Readonly<Record<string, string>>;
+  /** Opaque non-secret reattachment ref for durable process recovery (plan 026 Task 5). */
+  readonly ref?: string;
+  wait(options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<{ exitCode: number | null }>;
+}
+
+export interface ProcessPtyStartRequest {
+  readonly file: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly columns: number;
+  readonly rows: number;
+  readonly term: string;
+  readonly onData?: (data: Buffer) => void;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Host-selected PTY backend. Capability and metadata are explicit, never
+ * duck-typed: `pty: true` requires a backend whose `startPty` is present
+ * (otherwise `ERR_PRISM_PROCESS_PTY_UNSUPPORTED` before process creation) and
+ * `capabilities.resize` must be true for the session handle to expose resize.
+ */
+export interface ProcessPtyBackend {
+  startPty?(request: ProcessPtyStartRequest): Promise<ProcessPtyHandle>;
+  readonly capabilities?: { readonly resize: boolean };
+}
+
+export type ProcessSessionState = "starting" | "running" | "exited" | "killed" | "released" | "expired" | "unknown";
+
+export type ProcessSessionErrorCode =
+  | "ERR_PRISM_PROCESS_POLICY"
+  | "ERR_PRISM_PROCESS_OWNERSHIP"
+  | "ERR_PRISM_PROCESS_STATE"
+  | "ERR_PRISM_PROCESS_LIMIT"
+  | "ERR_PRISM_PROCESS_PTY_UNSUPPORTED"
+  | "ERR_PRISM_PROCESS_PTY_BACKEND"
+  | "ERR_PRISM_PROCESS_PTY_LIMIT"
+  | "ERR_PRISM_PROCESS_UNSUPPORTED";
+
+export class ProcessSessionError extends Error {
+  readonly code: ProcessSessionErrorCode;
+  constructor(code: ProcessSessionErrorCode, message: string) {
+    super(message);
+    this.name = "ProcessSessionError";
+    this.code = code;
+  }
+}
+
+export interface ProcessSessionLimits {
+  readonly maxSessions?: number;
+  readonly maxInputBytes?: number;
+  readonly maxLifetimeMs?: number;
+  readonly maxOutputChunkBytes?: number;
+  readonly maxTotalOutputBytes?: number;
+  /** Phase 26: PTY terminal bounds (defaults/hard caps frozen in limits.ts). */
+  readonly maxTerminalColumns?: number;
+  readonly maxTerminalRows?: number;
+  readonly maxTerminalTermBytes?: number;
+  readonly maxTerminalResizesPerMinute?: number;
+  readonly maxPtyAttachTimeoutMs?: number;
+  readonly maxPtyBackendMetadataBytes?: number;
+}
+
+export interface ResolvedProcessSessionLimits {
+  readonly maxSessions: number;
+  readonly maxInputBytes: number;
+  readonly maxLifetimeMs: number;
+  readonly maxOutputChunkBytes: number;
+  readonly maxTotalOutputBytes: number;
+  readonly maxTerminalColumns: number;
+  readonly maxTerminalRows: number;
+  readonly maxTerminalTermBytes: number;
+  readonly maxTerminalResizesPerMinute: number;
+  readonly maxPtyAttachTimeoutMs: number;
+  readonly maxPtyBackendMetadataBytes: number;
+}
+
+export function resolveProcessSessionLimits(limits?: ProcessSessionLimits): ResolvedProcessSessionLimits {
+  return {
+    maxSessions: validateCodingLimit("maxSessions", limits?.maxSessions ?? DEFAULT_MAX_PROCESS_SESSIONS, HARD_MAX_PROCESS_SESSIONS),
+    maxInputBytes: validateCodingLimit(
+      "maxInputBytes",
+      limits?.maxInputBytes ?? DEFAULT_MAX_PROCESS_INPUT_BYTES,
+      HARD_MAX_PROCESS_INPUT_BYTES,
+    ),
+    maxLifetimeMs: validateCodingLimit(
+      "maxLifetimeMs",
+      limits?.maxLifetimeMs ?? DEFAULT_MAX_PROCESS_LIFETIME_MS,
+      HARD_MAX_PROCESS_LIFETIME_MS,
+    ),
+    maxOutputChunkBytes: validateCodingLimit(
+      "maxOutputChunkBytes",
+      limits?.maxOutputChunkBytes ?? DEFAULT_MAX_PROCESS_OUTPUT_CHUNK_BYTES,
+      HARD_MAX_PROCESS_OUTPUT_CHUNK_BYTES,
+    ),
+    maxTotalOutputBytes: validateCodingLimit(
+      "maxTotalOutputBytes",
+      limits?.maxTotalOutputBytes ?? DEFAULT_MAX_PROCESS_TOTAL_OUTPUT_BYTES,
+      HARD_MAX_PROCESS_TOTAL_OUTPUT_BYTES,
+    ),
+    maxTerminalColumns: validateCodingLimit(
+      "maxTerminalColumns",
+      limits?.maxTerminalColumns ?? DEFAULT_MAX_TERMINAL_COLUMNS,
+      HARD_MAX_TERMINAL_COLUMNS,
+    ),
+    maxTerminalRows: validateCodingLimit("maxTerminalRows", limits?.maxTerminalRows ?? DEFAULT_MAX_TERMINAL_ROWS, HARD_MAX_TERMINAL_ROWS),
+    maxTerminalTermBytes: validateCodingLimit(
+      "maxTerminalTermBytes",
+      limits?.maxTerminalTermBytes ?? DEFAULT_MAX_TERMINAL_TERM_BYTES,
+      HARD_MAX_TERMINAL_TERM_BYTES,
+    ),
+    maxTerminalResizesPerMinute: validateCodingLimit(
+      "maxTerminalResizesPerMinute",
+      limits?.maxTerminalResizesPerMinute ?? DEFAULT_MAX_TERMINAL_RESIZES_PER_MINUTE,
+      HARD_MAX_TERMINAL_RESIZES_PER_MINUTE,
+    ),
+    maxPtyAttachTimeoutMs: validateCodingLimit(
+      "maxPtyAttachTimeoutMs",
+      limits?.maxPtyAttachTimeoutMs ?? DEFAULT_MAX_PTY_ATTACH_TIMEOUT_MS,
+      HARD_MAX_PTY_ATTACH_TIMEOUT_MS,
+    ),
+    maxPtyBackendMetadataBytes: validateCodingLimit(
+      "maxPtyBackendMetadataBytes",
+      limits?.maxPtyBackendMetadataBytes ?? DEFAULT_MAX_PTY_BACKEND_METADATA_BYTES,
+      HARD_MAX_PTY_BACKEND_METADATA_BYTES,
+    ),
+  };
+}
+
+export interface ProcessStartRequest {
+  readonly command: string;
+  readonly args?: readonly string[];
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * Default false. true without a host ptyBackend.startPty →
+   * ERR_PRISM_PROCESS_PTY_UNSUPPORTED before process creation; backend
+   * failures → ERR_PRISM_PROCESS_PTY_BACKEND; terminal/resize/attach bounds →
+   * ERR_PRISM_PROCESS_PTY_LIMIT.
+   */
+  readonly pty?: boolean;
+  /** Bounded terminal geometry + TERM for pty: true sessions. */
+  readonly terminal?: ProcessTerminalRequest;
+  readonly lifetimeMs?: number;
+  /** Owner string for this session; defaults to registry ownership key. */
+  readonly owner?: string;
+  /** When true, run cancel releases instead of killing (default kill). */
+  readonly releaseOnCancel?: boolean;
+  /** Abortable start: an aborted signal fails the start before spawn persists. */
+  readonly signal?: AbortSignal;
+}
+
+export interface ProcessOutputChunk {
+  readonly data: string;
+  /** Next byte cursor for paging. */
+  readonly cursor: number;
+  readonly eof: boolean;
+}
+
+export interface ProcessExitResult {
+  readonly exitCode: number | null;
+  readonly state: ProcessSessionState;
+}
+
+export interface ProcessSessionMetadata {
+  readonly id: string;
+  readonly commandFingerprint: string;
+  readonly owner: string;
+  readonly workspace: string;
+  readonly policyDecision: string;
+  readonly startedAt: string;
+  readonly exitedAt?: string;
+  readonly state: ProcessSessionState;
+  readonly releaseOnCancel: boolean;
+  /** True when the session runs through the host ptyBackend. */
+  readonly pty: boolean;
+  /** Resolved terminal geometry + TERM for PTY sessions (bounded at start). */
+  readonly terminal?: { readonly columns: number; readonly rows: number; readonly term: string };
+  /** Bounded backend metadata (validated <= maxPtyBackendMetadataBytes at start). */
+  readonly ptyBackendMetadata?: Readonly<Record<string, string>>;
+}
+
+export interface ProcessSession {
+  readonly id: string;
+  readonly state: ProcessSessionState;
+  readonly owner: string;
+  metadata(): ProcessSessionMetadata;
+  output(request?: { cursor?: number; maxBytes?: number }): Promise<ProcessOutputChunk>;
+  /**
+   * Fires when new output is published (a chunk was appended) or the session reached a terminal
+   * state, so a reader waits instead of polling. The returned function unsubscribes; a listener that
+   * throws never fails the process that produced the output.
+   */
+  onOutput(listener: () => void): () => void;
+  input(data: string | Uint8Array): Promise<void>;
+  wait(options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<ProcessExitResult>;
+  signal(name: "SIGTERM" | "SIGINT" | "SIGHUP"): Promise<void>;
+  kill(): Promise<void>;
+  release(): Promise<void>;
+  /** Present only when the host backend declared `capabilities.resize` (PTY sessions). */
+  resize?(dimensions: ProcessTerminalResize): Promise<void>;
+}
+
+export type CodingProcessEvent = {
+  readonly type: "process_started" | "process_exited" | "process_killed" | "process_released" | "process_expired" | "process_unknown";
+  readonly sessionId: string;
+  readonly processId: string;
+  readonly owner: string;
+  readonly exitCode?: number | null;
+  readonly at: string;
+};
+
+export interface ProcessSessions {
+  start(request: ProcessStartRequest): Promise<ProcessSession>;
+  get(sessionId: string, owner?: string): ProcessSession;
+  /** Kill (default) or release all sessions for `owner`. */
+  cancelOwned(owner: string, options?: { release?: boolean }): Promise<void>;
+  /** Mark a running session unknown (backend loss); never fabricates exitCode. */
+  markUnknown(sessionId: string, owner?: string): Promise<void>;
+  /**
+   * Host resume / sandbox-loss reconciliation: mark every running/starting session unknown.
+   * Never fabricates exitCode. O(owned sessions).
+   */
+  reconcile(): Promise<{ readonly markedUnknown: number }>;
+  /**
+   * Durable process recovery (plan 026 Task 5): reconcile durable recovery
+   * records against the live registry — attach-if-attested via the host
+   * recovery backend, otherwise `starting|running` records atomically become
+   * `unknown`. Never fabricates an exit code and never probes PIDs. Requires
+   * `checkpoints` + `leases` + `ownerId` at construction, else
+   * ERR_PRISM_RECOVERY_UNSUPPORTED. O(owned records).
+   */
+  recover(options?: { signal?: AbortSignal }): Promise<import("./recovery.js").ProcessRecoveryReport>;
+  dispose(): Promise<void>;
+}
+
+export interface CreateProcessSessionsOptions {
+  readonly cwd: string;
+  readonly policy?: ExecutionPolicy;
+  readonly limits?: ProcessSessionLimits;
+  readonly onEvent?: (event: CodingProcessEvent) => void;
+  readonly ownership?: OwnershipScope;
+  /** Host-verified identity; projects onto default owner when ownership omitted. */
+  readonly identity?: AgentIdentity;
+  /**
+   * When set: use `startProcess` if present; otherwise start() fails closed
+   * (`ERR_PRISM_PROCESS_UNSUPPORTED`). Native spawn only when sandbox omitted.
+   */
+  readonly sandbox?: ProcessSandboxBackend;
+  /**
+   * Phase 26: optional host-selected PTY backend. `pty: true` delegates only
+   * to this backend; absent backend or missing startPty fails closed with
+   * `ERR_PRISM_PROCESS_PTY_UNSUPPORTED` before process creation.
+   */
+  readonly ptyBackend?: ProcessPtyBackend;
+  /**
+   * Phase 26 durable process recovery: intent is persisted before spawn and
+   * lifecycle transitions are CAS-written under LeaseStore fencing. All three
+   * of `checkpoints`, `leases`, and `ownerId` must be present together — a
+   * partial recovery configuration fails closed at construction. `recover()`
+   * is attach-if-attested via `recoveryBackend`; otherwise starting/running
+   * records atomically become unknown (no fabricated exit, no PID probing).
+   */
+  readonly checkpoints?: CheckpointStore;
+  readonly leases?: LeaseStore;
+  readonly ownerId?: string;
+  readonly recoveryBackend?: import("./recovery.js").ProcessRecoveryBackend;
+  readonly recoveryLimits?: import("./recovery.js").ProcessRecoveryLimits;
+}