@xopcai/xopc 0.0.235 → 0.0.239

package/dist/src/execution-environments/local-worktree-manager.d.ts

@@ -0,0 +1,37 @@
+import { ExecutionEnvironmentStore } from './store.js';
+import { type ExecutionEnvironment } from './types.js';
+export interface ProvisionManagedWorktreeInput {
+    projectId: string;
+    repositoryPath: string;
+    baseRef?: string;
+    environmentId?: string;
+}
+export interface LocalWorktreeInspection {
+    healthy: boolean;
+    registered: boolean;
+    rootExists: boolean;
+    dirty: boolean;
+    headSha?: string;
+    branchRef?: string;
+    locked: boolean;
+    problems: string[];
+}
+export interface LocalWorktreeManagerOptions {
+    store?: ExecutionEnvironmentStore;
+    stateDir?: string;
+}
+export declare class LocalWorktreeManager {
+    private readonly store;
+    private readonly stateDir?;
+    constructor(options?: LocalWorktreeManagerOptions);
+    registerLocalCheckout(input: {
+        projectId?: string;
+        workspacePath: string;
+        environmentId?: string;
+    }): Promise<ExecutionEnvironment>;
+    provisionManagedWorktree(input: ProvisionManagedWorktreeInput): Promise<ExecutionEnvironment>;
+    inspect(environmentId: string): Promise<LocalWorktreeInspection>;
+    reconcile(environmentId: string): Promise<ExecutionEnvironment>;
+    remove(environmentId: string): Promise<ExecutionEnvironment>;
+    private cleanupFailedProvision;
+}

package/dist/src/execution-environments/local-worktree-manager.js

@@ -0,0 +1,322 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { ExecutionEnvironmentConflictError } from "./types.js";
+import { ExecutionEnvironmentStore } from "./store.js";
+import { findGitWorktree, inspectGitRepository, resolveGitCommit, runGit } from "./git.js";
+import { resolveExecutionWorktreesRoot, resolveManagedWorktreePath } from "./paths.js";
+import { dirname, relative, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { mkdir, rm, stat } from "node:fs/promises";
+import lockfile from "proper-lockfile";
+//#region src/execution-environments/local-worktree-manager.ts
+init_logger();
+const log = createLogger("ExecutionEnvironment:LocalWorktree");
+async function withRepositoryLock(gitCommonDir, fn) {
+	const lockPath = resolve(gitCommonDir, "xopc-worktree.lock");
+	const release = await lockfile.lock(gitCommonDir, {
+		realpath: false,
+		lockfilePath: lockPath,
+		retries: {
+			retries: 20,
+			factor: 1.2,
+			minTimeout: 25,
+			maxTimeout: 250
+		}
+	});
+	try {
+		return await fn();
+	} finally {
+		await release();
+	}
+}
+function errorMessage(error) {
+	return (error instanceof Error ? error.message : String(error)).slice(0, 2e3);
+}
+async function isDirectory(path) {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function assertManagedPath(rootPath, stateDir) {
+	const managedRoot = resolveExecutionWorktreesRoot(stateDir);
+	const candidate = resolve(rootPath);
+	const child = relative(managedRoot, candidate);
+	if (!child || child.startsWith("..") || resolve(managedRoot, child) !== candidate) throw new Error(`Refusing to manage worktree outside ${managedRoot}`);
+}
+var LocalWorktreeManager = class {
+	store;
+	stateDir;
+	constructor(options = {}) {
+		this.store = options.store ?? new ExecutionEnvironmentStore();
+		this.stateDir = options.stateDir;
+	}
+	async registerLocalCheckout(input) {
+		if (!await isDirectory(input.workspacePath)) throw new Error(`Local checkout does not exist: ${input.workspacePath}`);
+		const repository = await inspectGitRepository(input.workspacePath).catch(() => void 0);
+		const environment = this.store.create({
+			...input.environmentId ? { id: input.environmentId } : {},
+			...input.projectId ? { projectId: input.projectId } : {},
+			kind: "local_checkout",
+			rootPath: input.workspacePath,
+			...repository ? {
+				repositoryRoot: repository.repositoryRoot,
+				gitCommonDir: repository.gitCommonDir,
+				baseRef: repository.branchRef ?? "HEAD",
+				baseSha: repository.headSha,
+				branchRef: repository.branchRef
+			} : {}
+		});
+		const provisioning = this.store.transition({
+			environmentId: environment.id,
+			expectedVersion: environment.version,
+			toStatus: "provisioning",
+			reason: "local checkout validation started"
+		});
+		return this.store.transition({
+			environmentId: environment.id,
+			expectedVersion: provisioning.version,
+			toStatus: "ready",
+			reason: "local checkout validated"
+		});
+	}
+	async provisionManagedWorktree(input) {
+		const repository = await inspectGitRepository(input.repositoryPath);
+		if (repository.dirty) throw new ExecutionEnvironmentConflictError(`Repository has uncommitted changes: ${repository.repositoryRoot}`);
+		const baseRef = input.baseRef?.trim() || "HEAD";
+		const baseSha = await resolveGitCommit(repository.repositoryRoot, baseRef);
+		const environmentId = input.environmentId?.trim() || randomUUID();
+		const rootPath = resolveManagedWorktreePath(input.projectId, environmentId, this.stateDir);
+		assertManagedPath(rootPath, this.stateDir);
+		if (existsSync(rootPath)) throw new ExecutionEnvironmentConflictError(`Worktree path already exists: ${rootPath}`);
+		const environment = this.store.create({
+			id: environmentId,
+			projectId: input.projectId,
+			kind: "managed_worktree",
+			rootPath,
+			repositoryRoot: repository.repositoryRoot,
+			gitCommonDir: repository.gitCommonDir,
+			baseRef,
+			baseSha
+		});
+		const provisioning = this.store.transition({
+			environmentId: environment.id,
+			expectedVersion: environment.version,
+			toStatus: "provisioning",
+			reason: "managed worktree provisioning started"
+		});
+		try {
+			await withRepositoryLock(repository.gitCommonDir, async () => {
+				await mkdir(dirname(rootPath), {
+					recursive: true,
+					mode: 448
+				});
+				await runGit(repository.repositoryRoot, [
+					"worktree",
+					"add",
+					"--detach",
+					"--lock",
+					rootPath,
+					baseSha
+				]);
+				if (!await findGitWorktree(repository.repositoryRoot, rootPath)) throw new Error(`Git did not register worktree ${rootPath}`);
+			});
+			const ready = this.store.transition({
+				environmentId: environment.id,
+				expectedVersion: provisioning.version,
+				toStatus: "ready",
+				reason: "managed worktree provisioned",
+				metadata: { baseSha }
+			});
+			log.info({
+				environmentId: ready.id,
+				projectId: ready.projectId,
+				path: ready.rootPath
+			}, "Managed worktree ready");
+			return ready;
+		} catch (error) {
+			await this.cleanupFailedProvision(repository.repositoryRoot, repository.gitCommonDir, rootPath);
+			const failed = this.store.transition({
+				environmentId: environment.id,
+				expectedVersion: provisioning.version,
+				toStatus: "error",
+				reason: "managed worktree provisioning failed",
+				error: errorMessage(error)
+			});
+			log.error({
+				err: error,
+				environmentId: failed.id,
+				path: rootPath
+			}, `Managed worktree provisioning failed: ${failed.lastError}`);
+			throw error;
+		}
+	}
+	async inspect(environmentId) {
+		const environment = this.store.getRequired(environmentId);
+		if (environment.kind !== "managed_worktree" || !environment.repositoryRoot) throw new Error(`Execution environment ${environmentId} is not a managed worktree`);
+		const rootExists = await isDirectory(environment.rootPath);
+		const registered = await findGitWorktree(environment.repositoryRoot, environment.rootPath).catch(() => void 0);
+		const problems = [];
+		if (!rootExists) problems.push("worktree root is missing");
+		if (!registered) problems.push("worktree is not registered in Git");
+		let dirty = false;
+		if (rootExists && registered) dirty = Boolean(await runGit(environment.rootPath, [
+			"status",
+			"--porcelain=v1",
+			"-z",
+			"--untracked-files=all"
+		]));
+		return {
+			healthy: problems.length === 0,
+			registered: Boolean(registered),
+			rootExists,
+			dirty,
+			...registered?.headSha ? { headSha: registered.headSha } : {},
+			...registered?.branchRef ? { branchRef: registered.branchRef } : {},
+			locked: registered?.locked ?? false,
+			problems
+		};
+	}
+	async reconcile(environmentId) {
+		const environment = this.store.getRequired(environmentId);
+		const inspection = await this.inspect(environmentId);
+		if (inspection.healthy) {
+			if (environment.status !== "degraded" && environment.status !== "provisioning") return environment;
+			const provisioning = environment.status === "provisioning" ? environment : this.store.transition({
+				environmentId,
+				expectedVersion: environment.version,
+				toStatus: "provisioning",
+				reason: "managed worktree reconciliation started"
+			});
+			return this.store.transition({
+				environmentId,
+				expectedVersion: provisioning.version,
+				toStatus: "ready",
+				reason: "managed worktree reconciliation succeeded"
+			});
+		}
+		if (environment.status === "degraded" || environment.status === "error") return environment;
+		if (environment.status !== "ready" && environment.status !== "provisioning") throw new ExecutionEnvironmentConflictError(`Cannot reconcile managed worktree ${environmentId} while ${environment.status}`);
+		return this.store.transition({
+			environmentId,
+			expectedVersion: environment.version,
+			toStatus: "degraded",
+			reason: "managed worktree reconciliation detected drift",
+			error: inspection.problems.join("; ")
+		});
+	}
+	async remove(environmentId) {
+		const environment = this.store.getRequired(environmentId);
+		if (environment.status === "deleted") return environment;
+		if (environment.kind === "local_checkout") {
+			if (this.store.listBindings(environmentId).length > 0) throw new ExecutionEnvironmentConflictError(`Local checkout ${environmentId} still has active bindings`);
+			const deleting = environment.status === "deleting" ? environment : this.store.transition({
+				environmentId,
+				expectedVersion: environment.version,
+				toStatus: "deleting",
+				reason: "local checkout retirement started"
+			});
+			const deleted = this.store.transition({
+				environmentId,
+				expectedVersion: deleting.version,
+				toStatus: "deleted",
+				reason: "local checkout retired"
+			});
+			log.info({
+				environmentId,
+				path: environment.rootPath
+			}, "Local checkout retired");
+			return deleted;
+		}
+		if (environment.kind !== "managed_worktree" || !environment.repositoryRoot || !environment.gitCommonDir) throw new Error(`Execution environment ${environmentId} is not a managed worktree`);
+		assertManagedPath(environment.rootPath, this.stateDir);
+		if (this.store.listBindings(environmentId).length > 0) throw new ExecutionEnvironmentConflictError(`Managed worktree ${environmentId} still has active bindings`);
+		const deleting = environment.status === "deleting" ? environment : this.store.transition({
+			environmentId,
+			expectedVersion: environment.version,
+			toStatus: "deleting",
+			reason: "managed worktree deletion started"
+		});
+		try {
+			await withRepositoryLock(environment.gitCommonDir, async () => {
+				const registered = await findGitWorktree(environment.repositoryRoot, environment.rootPath);
+				if (!registered && existsSync(environment.rootPath)) throw new ExecutionEnvironmentConflictError("Refusing to delete a directory no longer registered as this worktree");
+				if (registered) {
+					if (registered.headSha && registered.headSha !== environment.baseSha) {
+						if (!(await runGit(environment.repositoryRoot, [
+							"for-each-ref",
+							`--contains=${registered.headSha}`,
+							"--format=%(refname)",
+							"refs/heads",
+							"refs/remotes"
+						])).trim()) throw new ExecutionEnvironmentConflictError("Save detached commits on a branch before deleting this worktree");
+					}
+					if (registered.locked) await runGit(environment.repositoryRoot, [
+						"worktree",
+						"unlock",
+						environment.rootPath
+					]);
+					try {
+						await runGit(environment.repositoryRoot, [
+							"worktree",
+							"remove",
+							environment.rootPath
+						]);
+					} catch (error) {
+						if (registered.locked) await runGit(environment.repositoryRoot, [
+							"worktree",
+							"lock",
+							environment.rootPath
+						]).catch(() => "");
+						throw error;
+					}
+				}
+			});
+			const deleted = this.store.transition({
+				environmentId,
+				expectedVersion: deleting.version,
+				toStatus: "deleted",
+				reason: "managed worktree deleted"
+			});
+			log.info({
+				environmentId,
+				path: environment.rootPath
+			}, "Managed worktree deleted");
+			return deleted;
+		} catch (error) {
+			this.store.transition({
+				environmentId,
+				expectedVersion: deleting.version,
+				toStatus: "error",
+				reason: "managed worktree deletion failed",
+				error: errorMessage(error)
+			});
+			throw error;
+		}
+	}
+	async cleanupFailedProvision(repositoryRoot, gitCommonDir, rootPath) {
+		await withRepositoryLock(gitCommonDir, async () => {
+			if (await findGitWorktree(repositoryRoot, rootPath).catch(() => void 0)) {
+				await runGit(repositoryRoot, [
+					"worktree",
+					"unlock",
+					rootPath
+				]).catch(() => "");
+				await runGit(repositoryRoot, [
+					"worktree",
+					"remove",
+					"--force",
+					rootPath
+				]).catch(() => "");
+			}
+			if (existsSync(rootPath)) await rm(rootPath, {
+				recursive: true,
+				force: true
+			});
+		}).catch(() => void 0);
+	}
+};
+//#endregion
+export { LocalWorktreeManager };

package/dist/src/execution-environments/paths.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveExecutionWorktreesRoot(stateDir?: string): string;
+export declare function resolveManagedWorktreePath(projectId: string, environmentId: string, stateDir?: string): string;

package/dist/src/execution-environments/paths.js

@@ -0,0 +1,18 @@
+import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
+import { join, resolve } from "node:path";
+//#region src/execution-environments/paths.ts
+init_paths_state();
+const SAFE_PATH_SEGMENT = /^[a-zA-Z0-9._-]+$/;
+function safePathSegment(value, label) {
+	const normalized = value.trim();
+	if (!normalized || !SAFE_PATH_SEGMENT.test(normalized) || normalized === "." || normalized === "..") throw new Error(`${label} contains unsupported path characters`);
+	return normalized;
+}
+function resolveExecutionWorktreesRoot(stateDir = resolveStateDir()) {
+	return resolve(stateDir, "worktrees");
+}
+function resolveManagedWorktreePath(projectId, environmentId, stateDir = resolveStateDir()) {
+	return join(resolveExecutionWorktreesRoot(stateDir), safePathSegment(projectId, "projectId"), safePathSegment(environmentId, "environmentId"));
+}
+//#endregion
+export { resolveExecutionWorktreesRoot, resolveManagedWorktreePath };

package/dist/src/execution-environments/session-environment-service.d.ts

@@ -0,0 +1,22 @@
+import type { Project, ProjectExecutionMode } from '../projects/types.js';
+import { LocalWorktreeManager } from './local-worktree-manager.js';
+import { ExecutionEnvironmentStore } from './store.js';
+import { type ExecutionEnvironment } from './types.js';
+export interface SessionEnvironmentServiceOptions {
+    store?: ExecutionEnvironmentStore;
+    worktrees?: LocalWorktreeManager;
+}
+export declare class SessionEnvironmentService {
+    private readonly store;
+    private readonly worktrees;
+    constructor(options?: SessionEnvironmentServiceOptions);
+    get(sessionKey: string): ExecutionEnvironment | undefined;
+    attach(input: {
+        sessionKey: string;
+        project: Project;
+        mode?: ProjectExecutionMode;
+        baseRef?: string;
+    }): Promise<ExecutionEnvironment>;
+    release(sessionKey: string, removeManaged?: boolean): Promise<ExecutionEnvironment | undefined>;
+    private resolveLocalCheckout;
+}

package/dist/src/execution-environments/session-environment-service.js

@@ -0,0 +1,73 @@
+import { ExecutionEnvironmentConflictError } from "./types.js";
+import { ExecutionEnvironmentStore } from "./store.js";
+import { LocalWorktreeManager } from "./local-worktree-manager.js";
+import { resolve } from "node:path";
+//#region src/execution-environments/session-environment-service.ts
+var SessionEnvironmentService = class {
+	store;
+	worktrees;
+	constructor(options = {}) {
+		this.store = options.store ?? new ExecutionEnvironmentStore();
+		this.worktrees = options.worktrees ?? new LocalWorktreeManager({ store: this.store });
+	}
+	get(sessionKey) {
+		const binding = this.store.resolveBinding(sessionKey);
+		return binding ? this.store.get(binding.environmentId) : void 0;
+	}
+	async attach(input) {
+		const existing = this.get(input.sessionKey);
+		if (existing) {
+			if (existing.projectId !== input.project.id) throw new ExecutionEnvironmentConflictError(`Session ${input.sessionKey} is already bound to a different project's execution environment`);
+			if (input.mode && existing.kind !== input.mode) throw new ExecutionEnvironmentConflictError(`Session ${input.sessionKey} is already using ${existing.kind}; release it before switching to ${input.mode}`);
+			return existing;
+		}
+		const workspaceRoot = input.project.workspaceRoot?.trim();
+		if (!workspaceRoot) throw new ExecutionEnvironmentConflictError(`Project ${input.project.id} needs a fixed workspace before an execution environment can be created`);
+		const environment = (input.mode ?? input.project.executionMode) === "managed_worktree" ? await this.worktrees.provisionManagedWorktree({
+			projectId: input.project.id,
+			repositoryPath: workspaceRoot,
+			baseRef: input.baseRef
+		}) : await this.resolveLocalCheckout(input.project.id, workspaceRoot);
+		try {
+			this.store.bind({
+				sessionKey: input.sessionKey,
+				environmentId: environment.id
+			});
+			return environment;
+		} catch (error) {
+			if (environment.kind === "managed_worktree") await this.worktrees.remove(environment.id).catch(() => void 0);
+			throw error;
+		}
+	}
+	async release(sessionKey, removeManaged = true) {
+		const binding = this.store.resolveBinding(sessionKey);
+		if (!binding) return void 0;
+		const environment = this.store.get(binding.environmentId);
+		this.store.releaseBinding(sessionKey, binding.environmentId);
+		if (removeManaged && environment?.kind === "managed_worktree") await this.worktrees.remove(environment.id);
+		return environment;
+	}
+	async resolveLocalCheckout(projectId, workspaceRoot) {
+		const rootPath = resolve(workspaceRoot);
+		const existing = this.store.list({
+			projectId,
+			limit: 500
+		}).find((environment) => environment.kind === "local_checkout" && environment.rootPath === rootPath && environment.status === "ready");
+		if (existing) return existing;
+		try {
+			return await this.worktrees.registerLocalCheckout({
+				projectId,
+				workspacePath: rootPath
+			});
+		} catch (error) {
+			const raced = this.store.list({
+				projectId,
+				limit: 500
+			}).find((environment) => environment.kind === "local_checkout" && environment.rootPath === rootPath && environment.status === "ready");
+			if (raced) return raced;
+			throw error;
+		}
+	}
+};
+//#endregion
+export { SessionEnvironmentService };

package/dist/src/execution-environments/store.d.ts

@@ -0,0 +1,13 @@
+import { type BindExecutionEnvironmentInput, type CreateExecutionEnvironmentInput, type ExecutionEnvironment, type ExecutionEnvironmentBinding, type ExecutionEnvironmentEvent, type ExecutionEnvironmentListQuery, type TransitionExecutionEnvironmentInput } from './types.js';
+export declare class ExecutionEnvironmentStore {
+    create(input: CreateExecutionEnvironmentInput): ExecutionEnvironment;
+    get(environmentId: string): ExecutionEnvironment | undefined;
+    getRequired(environmentId: string): ExecutionEnvironment;
+    list(query?: ExecutionEnvironmentListQuery): ExecutionEnvironment[];
+    transition(input: TransitionExecutionEnvironmentInput): ExecutionEnvironment;
+    bind(input: BindExecutionEnvironmentInput): ExecutionEnvironmentBinding;
+    resolveBinding(sessionKey: string): ExecutionEnvironmentBinding | undefined;
+    listBindings(environmentId: string, includeReleased?: boolean): ExecutionEnvironmentBinding[];
+    releaseBinding(sessionKey: string, expectedEnvironmentId?: string): ExecutionEnvironmentBinding | undefined;
+    listEvents(environmentId: string): ExecutionEnvironmentEvent[];
+}

package/dist/src/execution-environments/store.js

@@ -0,0 +1,183 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { ExecutionEnvironmentConflictError, ExecutionEnvironmentNotFoundError, canTransitionExecutionEnvironment } from "./types.js";
+import { resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/execution-environments/store.ts
+function optionalText(value) {
+	return value?.trim() || void 0;
+}
+function requiredText(value, label) {
+	const normalized = value.trim();
+	if (!normalized) throw new Error(`${label} is required`);
+	return normalized;
+}
+function environmentFromRow(row) {
+	return {
+		id: row.environment_id,
+		...row.project_id ? { projectId: row.project_id } : {},
+		kind: row.kind,
+		status: row.status,
+		rootPath: row.root_path,
+		...row.repository_root ? { repositoryRoot: row.repository_root } : {},
+		...row.git_common_dir ? { gitCommonDir: row.git_common_dir } : {},
+		...row.base_ref ? { baseRef: row.base_ref } : {},
+		...row.base_sha ? { baseSha: row.base_sha } : {},
+		...row.branch_ref ? { branchRef: row.branch_ref } : {},
+		version: row.version,
+		...row.last_error ? { lastError: row.last_error } : {},
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+		...row.last_used_at == null ? {} : { lastUsedAt: row.last_used_at },
+		...row.deleted_at == null ? {} : { deletedAt: row.deleted_at }
+	};
+}
+function bindingFromRow(row) {
+	return {
+		id: row.binding_id,
+		sessionKey: row.session_key,
+		environmentId: row.environment_id,
+		createdAt: row.created_at,
+		...row.released_at == null ? {} : { releasedAt: row.released_at }
+	};
+}
+function eventFromRow(row) {
+	return {
+		id: row.event_id,
+		environmentId: row.environment_id,
+		...row.from_status ? { fromStatus: row.from_status } : {},
+		toStatus: row.to_status,
+		reason: row.reason,
+		metadata: JSON.parse(row.metadata_json),
+		createdAt: row.created_at
+	};
+}
+function getEnvironmentRow(environmentId) {
+	return getSqliteDatabase().prepare(`SELECT * FROM execution_environments WHERE environment_id = ?`).get(environmentId);
+}
+var ExecutionEnvironmentStore = class {
+	create(input) {
+		const id = input.id?.trim() || randomUUID();
+		const rootPath = resolve(requiredText(input.rootPath, "rootPath"));
+		const projectId = optionalText(input.projectId);
+		const repositoryRoot = optionalText(input.repositoryRoot);
+		const gitCommonDir = optionalText(input.gitCommonDir);
+		if (input.kind === "managed_worktree" && (!repositoryRoot || !gitCommonDir)) throw new Error("managed_worktree requires repositoryRoot and gitCommonDir");
+		const now = Date.now();
+		runSqliteWriteTransaction((db) => {
+			db.prepare(`INSERT INTO execution_environments (
+          environment_id, project_id, kind, status, root_path,
+          repository_root, git_common_dir, base_ref, base_sha, branch_ref,
+          version, created_at, updated_at
+        ) VALUES (?, ?, ?, 'requested', ?, ?, ?, ?, ?, ?, 1, ?, ?)`).run(id, projectId ?? null, input.kind, rootPath, repositoryRoot ? resolve(repositoryRoot) : null, gitCommonDir ? resolve(gitCommonDir) : null, optionalText(input.baseRef) ?? null, optionalText(input.baseSha) ?? null, optionalText(input.branchRef) ?? null, now, now);
+			db.prepare(`INSERT INTO execution_environment_events (
+          event_id, environment_id, from_status, to_status, reason, metadata_json, created_at
+        ) VALUES (?, ?, NULL, 'requested', 'created', '{}', ?)`).run(randomUUID(), id, now);
+		});
+		return this.getRequired(id);
+	}
+	get(environmentId) {
+		const row = getEnvironmentRow(environmentId);
+		return row ? environmentFromRow(row) : void 0;
+	}
+	getRequired(environmentId) {
+		const environment = this.get(environmentId);
+		if (!environment) throw new ExecutionEnvironmentNotFoundError(environmentId);
+		return environment;
+	}
+	list(query = {}) {
+		const clauses = [];
+		const params = [];
+		if (query.projectId) {
+			clauses.push("project_id = ?");
+			params.push(query.projectId);
+		}
+		if (query.status) {
+			clauses.push("status = ?");
+			params.push(query.status);
+		}
+		if (!query.includeDeleted) clauses.push("deleted_at IS NULL");
+		const limit = Math.min(500, Math.max(1, Math.floor(query.limit ?? 100)));
+		params.push(limit);
+		const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+		return getSqliteDatabase().prepare(`SELECT * FROM execution_environments ${where} ORDER BY updated_at DESC LIMIT ?`).all(...params).map(environmentFromRow);
+	}
+	transition(input) {
+		const reason = requiredText(input.reason, "reason");
+		const now = Date.now();
+		runSqliteWriteTransaction((db) => {
+			const row = getEnvironmentRow(input.environmentId);
+			if (!row) throw new ExecutionEnvironmentNotFoundError(input.environmentId);
+			if (row.version !== input.expectedVersion) throw new ExecutionEnvironmentConflictError(`Execution environment ${input.environmentId} changed from version ${input.expectedVersion} to ${row.version}`);
+			if (!canTransitionExecutionEnvironment(row.status, input.toStatus)) throw new ExecutionEnvironmentConflictError(`Cannot transition execution environment ${input.environmentId} from ${row.status} to ${input.toStatus}`);
+			const error = optionalText(input.error);
+			const lastError = input.toStatus === "error" || input.toStatus === "degraded" ? error ?? row.last_error : null;
+			if (db.prepare(`UPDATE execution_environments
+         SET status = ?, version = version + 1, updated_at = ?, last_error = ?,
+             deleted_at = CASE WHEN ? = 'deleted' THEN ? ELSE deleted_at END
+         WHERE environment_id = ? AND version = ?`).run(input.toStatus, now, lastError, input.toStatus, now, input.environmentId, input.expectedVersion).changes !== 1) throw new ExecutionEnvironmentConflictError(`Execution environment ${input.environmentId} changed concurrently`);
+			db.prepare(`INSERT INTO execution_environment_events (
+          event_id, environment_id, from_status, to_status, reason, metadata_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), input.environmentId, row.status, input.toStatus, reason, JSON.stringify(input.metadata ?? {}), now);
+		});
+		return this.getRequired(input.environmentId);
+	}
+	bind(input) {
+		const sessionKey = requiredText(input.sessionKey, "sessionKey");
+		return runSqliteWriteTransaction((db) => {
+			const environment = getEnvironmentRow(input.environmentId);
+			if (!environment) throw new ExecutionEnvironmentNotFoundError(input.environmentId);
+			if (environment.status !== "ready") throw new ExecutionEnvironmentConflictError(`Execution environment ${input.environmentId} is not bindable while ${environment.status}`);
+			const active = db.prepare(`SELECT * FROM execution_environment_bindings
+         WHERE session_key = ? AND released_at IS NULL`).get(sessionKey);
+			if (active) {
+				if (active.environment_id === input.environmentId) return bindingFromRow(active);
+				throw new ExecutionEnvironmentConflictError(`Session ${sessionKey} is already bound to ${active.environment_id}`);
+			}
+			if (environment.kind === "managed_worktree") {
+				const owner = db.prepare(`SELECT * FROM execution_environment_bindings
+           WHERE environment_id = ? AND released_at IS NULL LIMIT 1`).get(input.environmentId);
+				if (owner) throw new ExecutionEnvironmentConflictError(`Managed worktree ${input.environmentId} is already bound to session ${owner.session_key}`);
+			}
+			const binding = {
+				id: randomUUID(),
+				sessionKey,
+				environmentId: input.environmentId,
+				createdAt: Date.now()
+			};
+			db.prepare(`INSERT INTO execution_environment_bindings (
+          binding_id, session_key, environment_id, created_at
+        ) VALUES (?, ?, ?, ?)`).run(binding.id, binding.sessionKey, binding.environmentId, binding.createdAt);
+			db.prepare(`UPDATE execution_environments SET last_used_at = ?, updated_at = ? WHERE environment_id = ?`).run(binding.createdAt, binding.createdAt, binding.environmentId);
+			return binding;
+		});
+	}
+	resolveBinding(sessionKey) {
+		const row = getSqliteDatabase().prepare(`SELECT * FROM execution_environment_bindings
+       WHERE session_key = ? AND released_at IS NULL`).get(sessionKey);
+		return row ? bindingFromRow(row) : void 0;
+	}
+	listBindings(environmentId, includeReleased = false) {
+		return getSqliteDatabase().prepare(`SELECT * FROM execution_environment_bindings
+       WHERE environment_id = ? ${includeReleased ? "" : "AND released_at IS NULL"}
+       ORDER BY created_at, rowid`).all(environmentId).map(bindingFromRow);
+	}
+	releaseBinding(sessionKey, expectedEnvironmentId) {
+		return runSqliteWriteTransaction((db) => {
+			const active = db.prepare(`SELECT * FROM execution_environment_bindings
+         WHERE session_key = ? AND released_at IS NULL`).get(sessionKey);
+			if (!active) return void 0;
+			if (expectedEnvironmentId && active.environment_id !== expectedEnvironmentId) throw new ExecutionEnvironmentConflictError(`Session ${sessionKey} is bound to ${active.environment_id}, not ${expectedEnvironmentId}`);
+			const releasedAt = Date.now();
+			db.prepare(`UPDATE execution_environment_bindings SET released_at = ? WHERE binding_id = ? AND released_at IS NULL`).run(releasedAt, active.binding_id);
+			return bindingFromRow({
+				...active,
+				released_at: releasedAt
+			});
+		});
+	}
+	listEvents(environmentId) {
+		return getSqliteDatabase().prepare(`SELECT * FROM execution_environment_events WHERE environment_id = ? ORDER BY created_at, rowid`).all(environmentId).map(eventFromRow);
+	}
+};
+//#endregion
+export { ExecutionEnvironmentStore };

package/dist/src/execution-environments/subject.d.ts

@@ -0,0 +1,2 @@
+import type { ExecutionEnvironment } from './types.js';
+export declare function getExecutionEnvironmentForSession(sessionKey: string): ExecutionEnvironment | undefined;