Add local environment lifecycle (#4297)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Every heartbeat run needs a concrete place where the agent's adapter
process executes.
> - Today that execution location is implicitly the local machine, which
makes it hard to track, audit, and manage as a first-class runtime
concern.
> - The first step is to represent the current local execution path
explicitly without changing how users experience agent runs.
> - This pull request adds core Environment and Environment Lease
records, then routes existing local heartbeat execution through a
default `Local` environment.
> - The benefit is that local runs remain behavior-preserving while the
system now has durable environment identity, lease lifecycle tracking,
and activity records for execution placement.

## What Changed

- Added `environments` and `environment_leases` database tables, schema
exports, and migration `0065_environments.sql`.
- Added shared environment constants, TypeScript types, and validators
for environment drivers, statuses, lease policies, lease statuses, and
cleanup states.
- Added `environmentService` for listing, reading, creating, updating,
and ensuring company-scoped environments.
- Added environment lease lifecycle operations for acquire, metadata
update, single-lease release, and run-wide release.
- Updated heartbeat execution to lazily ensure a company-scoped default
`Local` environment before adapter execution.
- Updated heartbeat execution to acquire an ephemeral local environment
lease, write `paperclipEnvironment` into the run context snapshot, and
release active leases during run finalization.
- Added activity log events for environment lease acquisition and
release.
- Added tests for environment service behavior and the local heartbeat
environment lifecycle.
- Added a CI-follow-up heartbeat guard so deferred issue comment wakes
are promoted before automatic missing-comment retries, with focused
batching test coverage.

## Verification

Local verification run for this branch:

- `pnpm -r typecheck`
- `pnpm build`
- `pnpm exec vitest run server/src/__tests__/environment-service.test.ts
server/src/__tests__/heartbeat-local-environment.test.ts --pool=forks`

Additional reviewer/CI verification:

- Confirm `pnpm-lock.yaml` is not modified.
- Confirm `pnpm test:run` passes in CI.
- Confirm `PAPERCLIP_E2E_SKIP_LLM=true pnpm run test:e2e` passes in CI.
- Confirm a local heartbeat run creates one active `Local` environment
when needed, records one lease for the run, releases the lease when the
run finishes, and includes `paperclipEnvironment` in the run context
snapshot.

Screenshots: not applicable; this PR has no UI changes.

## Risks

- Migration risk: introduces two new tables and a new migration journal
entry. Review should verify company scoping, indexes, foreign keys, and
enum defaults are correct.
- Lifecycle risk: heartbeat finalization now releases environment leases
in addition to existing runtime cleanup. A finalization bug could leave
stale active leases or mark a failed run's lease incorrectly.
- Behavior-preservation risk: local adapter execution should remain
unchanged apart from environment bookkeeping. Review should pay
attention to the heartbeat path around context snapshot updates and
final cleanup ordering.
- Activity volume risk: each heartbeat run now logs lease acquisition
and release events, increasing activity log volume by two records per
run.

## Model Used

OpenAI GPT-5.4 via Codex CLI. Capabilities used: repository inspection,
TypeScript implementation review, local test/build execution, and
PR-description drafting.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots (N/A: no UI changes)
- [x] I have updated relevant documentation to reflect my changes (N/A:
no user-facing docs or commands changed)
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

packages/db/src/migrations/0065_environments.sql

@@ -0,0 +1,50 @@
+CREATE TABLE "environments" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"driver" text DEFAULT 'local' NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"config" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"metadata" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "environment_leases" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"environment_id" uuid NOT NULL,
+	"execution_workspace_id" uuid,
+	"issue_id" uuid,
+	"heartbeat_run_id" uuid,
+	"status" text DEFAULT 'active' NOT NULL,
+	"lease_policy" text DEFAULT 'ephemeral' NOT NULL,
+	"provider" text,
+	"provider_lease_id" text,
+	"acquired_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"last_used_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"expires_at" timestamp with time zone,
+	"released_at" timestamp with time zone,
+	"failure_reason" text,
+	"cleanup_status" text,
+	"metadata" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "environments" ADD CONSTRAINT "environments_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "environment_leases" ADD CONSTRAINT "environment_leases_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "environment_leases" ADD CONSTRAINT "environment_leases_environment_id_environments_id_fk" FOREIGN KEY ("environment_id") REFERENCES "public"."environments"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "environment_leases" ADD CONSTRAINT "environment_leases_execution_workspace_id_execution_workspaces_id_fk" FOREIGN KEY ("execution_workspace_id") REFERENCES "public"."execution_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "environment_leases" ADD CONSTRAINT "environment_leases_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "environment_leases" ADD CONSTRAINT "environment_leases_heartbeat_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("heartbeat_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "environments_company_status_idx" ON "environments" USING btree ("company_id","status");--> statement-breakpoint
+CREATE UNIQUE INDEX "environments_company_driver_idx" ON "environments" USING btree ("company_id","driver");--> statement-breakpoint
+CREATE INDEX "environments_company_name_idx" ON "environments" USING btree ("company_id","name");--> statement-breakpoint
+CREATE INDEX "environment_leases_company_environment_status_idx" ON "environment_leases" USING btree ("company_id","environment_id","status");--> statement-breakpoint
+CREATE INDEX "environment_leases_company_execution_workspace_idx" ON "environment_leases" USING btree ("company_id","execution_workspace_id");--> statement-breakpoint
+CREATE INDEX "environment_leases_company_issue_idx" ON "environment_leases" USING btree ("company_id","issue_id");--> statement-breakpoint
+CREATE INDEX "environment_leases_heartbeat_run_idx" ON "environment_leases" USING btree ("heartbeat_run_id");--> statement-breakpoint
+CREATE INDEX "environment_leases_company_last_used_idx" ON "environment_leases" USING btree ("company_id","last_used_at");--> statement-breakpoint
+CREATE INDEX "environment_leases_provider_lease_idx" ON "environment_leases" USING btree ("provider_lease_id");

packages/db/src/migrations/meta/_journal.json

@@ -456,6 +456,13 @@
       "when": 1776780002000,
       "tag": "0064_issue_thread_interaction_idempotency",
       "breakpoints": true
+    },
+    {
+      "idx": 65,
+      "version": "7",
+      "when": 1776903900000,
+      "tag": "0065_environments",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/environment_leases.ts

@@ -0,0 +1,46 @@
+import { index, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { environments } from "./environments.js";
+import { executionWorkspaces } from "./execution_workspaces.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+import { issues } from "./issues.js";
+
+export const environmentLeases = pgTable(
+  "environment_leases",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    environmentId: uuid("environment_id").notNull().references(() => environments.id, { onDelete: "cascade" }),
+    executionWorkspaceId: uuid("execution_workspace_id").references(() => executionWorkspaces.id, { onDelete: "set null" }),
+    issueId: uuid("issue_id").references(() => issues.id, { onDelete: "set null" }),
+    heartbeatRunId: uuid("heartbeat_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    status: text("status").notNull().default("active"),
+    leasePolicy: text("lease_policy").notNull().default("ephemeral"),
+    provider: text("provider"),
+    providerLeaseId: text("provider_lease_id"),
+    acquiredAt: timestamp("acquired_at", { withTimezone: true }).notNull().defaultNow(),
+    lastUsedAt: timestamp("last_used_at", { withTimezone: true }).notNull().defaultNow(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    releasedAt: timestamp("released_at", { withTimezone: true }),
+    failureReason: text("failure_reason"),
+    cleanupStatus: text("cleanup_status"),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyEnvironmentStatusIdx: index("environment_leases_company_environment_status_idx").on(
+      table.companyId,
+      table.environmentId,
+      table.status,
+    ),
+    companyExecutionWorkspaceIdx: index("environment_leases_company_execution_workspace_idx").on(
+      table.companyId,
+      table.executionWorkspaceId,
+    ),
+    companyIssueIdx: index("environment_leases_company_issue_idx").on(table.companyId, table.issueId),
+    heartbeatRunIdx: index("environment_leases_heartbeat_run_idx").on(table.heartbeatRunId),
+    companyLastUsedIdx: index("environment_leases_company_last_used_idx").on(table.companyId, table.lastUsedAt),
+    providerLeaseIdx: index("environment_leases_provider_lease_idx").on(table.providerLeaseId),
+  }),
+);

packages/db/src/schema/environments.ts

@@ -0,0 +1,23 @@
+import { index, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+
+export const environments = pgTable(
+  "environments",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    name: text("name").notNull(),
+    description: text("description"),
+    driver: text("driver").notNull().default("local"),
+    status: text("status").notNull().default("active"),
+    config: jsonb("config").$type<Record<string, unknown>>().notNull().default({}),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyStatusIdx: index("environments_company_status_idx").on(table.companyId, table.status),
+    companyDriverIdx: uniqueIndex("environments_company_driver_idx").on(table.companyId, table.driver),
+    companyNameIdx: index("environments_company_name_idx").on(table.companyId, table.name),
+  }),
+);

packages/db/src/schema/index.ts

@@ -22,6 +22,8 @@ export { agentWakeupRequests } from "./agent_wakeup_requests.js";
 export { projects } from "./projects.js";
 export { projectWorkspaces } from "./project_workspaces.js";
 export { executionWorkspaces } from "./execution_workspaces.js";
+export { environments } from "./environments.js";
+export { environmentLeases } from "./environment_leases.js";
 export { workspaceOperations } from "./workspace_operations.js";
 export { workspaceRuntimeServices } from "./workspace_runtime_services.js";
 export { projectGoals } from "./project_goals.js";

packages/shared/src/constants.ts

@@ -209,6 +209,21 @@ export const PROJECT_STATUSES = [
 ] as const;
 export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
 
+export const ENVIRONMENT_DRIVERS = ["local"] as const;
+export type EnvironmentDriver = (typeof ENVIRONMENT_DRIVERS)[number];
+
+export const ENVIRONMENT_STATUSES = ["active", "archived"] as const;
+export type EnvironmentStatus = (typeof ENVIRONMENT_STATUSES)[number];
+
+export const ENVIRONMENT_LEASE_STATUSES = ["active", "released", "expired", "failed"] as const;
+export type EnvironmentLeaseStatus = (typeof ENVIRONMENT_LEASE_STATUSES)[number];
+
+export const ENVIRONMENT_LEASE_POLICIES = ["ephemeral"] as const;
+export type EnvironmentLeasePolicy = (typeof ENVIRONMENT_LEASE_POLICIES)[number];
+
+export const ENVIRONMENT_LEASE_CLEANUP_STATUSES = ["pending", "success", "failed"] as const;
+export type EnvironmentLeaseCleanupStatus = (typeof ENVIRONMENT_LEASE_CLEANUP_STATUSES)[number];
+
 export const ROUTINE_STATUSES = ["active", "paused", "archived"] as const;
 export type RoutineStatus = (typeof ROUTINE_STATUSES)[number];
 

packages/shared/src/index.ts

@@ -32,6 +32,11 @@ export {
   GOAL_LEVELS,
   GOAL_STATUSES,
   PROJECT_STATUSES,
+  ENVIRONMENT_DRIVERS,
+  ENVIRONMENT_STATUSES,
+  ENVIRONMENT_LEASE_STATUSES,
+  ENVIRONMENT_LEASE_POLICIES,
+  ENVIRONMENT_LEASE_CLEANUP_STATUSES,
   ROUTINE_STATUSES,
   ROUTINE_CONCURRENCY_POLICIES,
   ROUTINE_CATCH_UP_POLICIES,
@@ -124,6 +129,11 @@ export {
   type GoalLevel,
   type GoalStatus,
   type ProjectStatus,
+  type EnvironmentDriver,
+  type EnvironmentStatus,
+  type EnvironmentLeaseStatus,
+  type EnvironmentLeasePolicy,
+  type EnvironmentLeaseCleanupStatus,
   type RoutineStatus,
   type RoutineConcurrencyPolicy,
   type RoutineCatchUpPolicy,
@@ -200,6 +210,9 @@ export {
 
 export type {
   Company,
+  Environment,
+  EnvironmentLease,
+  LocalEnvironmentConfig,
   FeedbackVote,
   FeedbackDataSharingPreference,
   FeedbackTargetType,
@@ -533,6 +546,14 @@ export {
   type UpdateCompany,
   type UpdateCompanyBranding,
   type UpsertIssueFeedbackVote,
+  environmentDriverSchema,
+  environmentStatusSchema,
+  environmentLeaseStatusSchema,
+  environmentLeaseCleanupStatusSchema,
+  createEnvironmentSchema,
+  updateEnvironmentSchema,
+  type CreateEnvironment,
+  type UpdateEnvironment,
   agentSkillStateSchema,
   agentSkillSyncModeSchema,
   agentSkillEntrySchema,

packages/shared/src/types/environment.ts

@@ -0,0 +1,46 @@
+import type {
+  EnvironmentDriver,
+  EnvironmentLeaseCleanupStatus,
+  EnvironmentLeasePolicy,
+  EnvironmentLeaseStatus,
+  EnvironmentStatus,
+} from "../constants.js";
+
+export interface LocalEnvironmentConfig {
+  [key: string]: unknown;
+}
+
+export interface Environment {
+  id: string;
+  companyId: string;
+  name: string;
+  description: string | null;
+  driver: EnvironmentDriver;
+  status: EnvironmentStatus;
+  config: LocalEnvironmentConfig;
+  metadata: Record<string, unknown> | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface EnvironmentLease {
+  id: string;
+  companyId: string;
+  environmentId: string;
+  executionWorkspaceId: string | null;
+  issueId: string | null;
+  heartbeatRunId: string | null;
+  status: EnvironmentLeaseStatus;
+  leasePolicy: EnvironmentLeasePolicy;
+  provider: string | null;
+  providerLeaseId: string | null;
+  acquiredAt: Date;
+  lastUsedAt: Date;
+  expiresAt: Date | null;
+  releasedAt: Date | null;
+  failureReason: string | null;
+  cleanupStatus: EnvironmentLeaseCleanupStatus | null;
+  metadata: Record<string, unknown> | null;
+  createdAt: Date;
+  updatedAt: Date;
+}

packages/shared/src/types/index.ts

@@ -1,4 +1,5 @@
 export type { Company } from "./company.js";
+export type { Environment, EnvironmentLease, LocalEnvironmentConfig } from "./environment.js";
 export type {
   FeedbackVote,
   FeedbackDataSharingPreference,

packages/shared/src/validators/environment.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import {
+  ENVIRONMENT_DRIVERS,
+  ENVIRONMENT_LEASE_CLEANUP_STATUSES,
+  ENVIRONMENT_LEASE_STATUSES,
+  ENVIRONMENT_STATUSES,
+} from "../constants.js";
+
+export const environmentDriverSchema = z.enum(ENVIRONMENT_DRIVERS);
+export const environmentStatusSchema = z.enum(ENVIRONMENT_STATUSES);
+export const environmentLeaseStatusSchema = z.enum(ENVIRONMENT_LEASE_STATUSES);
+export const environmentLeaseCleanupStatusSchema = z.enum(ENVIRONMENT_LEASE_CLEANUP_STATUSES);
+
+const environmentFields = {
+  name: z.string().min(1),
+  description: z.string().optional().nullable(),
+  driver: environmentDriverSchema,
+  status: environmentStatusSchema.optional().default("active"),
+  config: z.record(z.unknown()).optional().default({}),
+  metadata: z.record(z.unknown()).optional().nullable(),
+};
+
+export const createEnvironmentSchema = z.object(environmentFields).strict();
+export type CreateEnvironment = z.infer<typeof createEnvironmentSchema>;
+
+export const updateEnvironmentSchema = z.object({
+  name: z.string().min(1).optional(),
+  description: z.string().optional().nullable(),
+  driver: environmentDriverSchema.optional(),
+  status: environmentStatusSchema.optional(),
+  config: z.record(z.unknown()).optional(),
+  metadata: z.record(z.unknown()).optional().nullable(),
+}).strict();
+export type UpdateEnvironment = z.infer<typeof updateEnvironmentSchema>;

packages/shared/src/validators/index.ts

@@ -24,6 +24,16 @@ export {
   type UpdateCompany,
   type UpdateCompanyBranding,
 } from "./company.js";
+export {
+  environmentDriverSchema,
+  environmentStatusSchema,
+  environmentLeaseStatusSchema,
+  environmentLeaseCleanupStatusSchema,
+  createEnvironmentSchema,
+  updateEnvironmentSchema,
+  type CreateEnvironment,
+  type UpdateEnvironment,
+} from "./environment.js";
 export {
   feedbackDataSharingPreferenceSchema,
   feedbackTargetTypeSchema,