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

server/src/__tests__/environment-service.test.ts

@@ -0,0 +1,224 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { eq } from "drizzle-orm";
+import { agents, companies, createDb, environmentLeases, environments, heartbeatRuns } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { environmentService } from "../services/environments.ts";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres environment service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("environmentService leases", () => {
+  let stopDb: (() => Promise<void>) | null = null;
+  let db!: ReturnType<typeof createDb>;
+  let svc!: ReturnType<typeof environmentService>;
+
+  beforeAll(async () => {
+    const started = await startEmbeddedPostgresTestDatabase("environment-service");
+    stopDb = started.stop;
+    db = createDb(started.connectionString);
+    svc = environmentService(db);
+  });
+
+  afterEach(async () => {
+    await db.delete(environmentLeases);
+    await db.delete(heartbeatRuns);
+    await db.delete(agents);
+    await db.delete(environments);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await stopDb?.();
+  });
+
+  async function seedEnvironment() {
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const environmentId = randomUUID();
+    const runId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(environments).values({
+      id: environmentId,
+      companyId,
+      name: "Local",
+      driver: "local",
+      status: "active",
+      config: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId,
+      invocationSource: "manual",
+      status: "running",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    return { companyId, agentId, environmentId, runId };
+  }
+
+  it("acquires and releases a lease for a run", async () => {
+    const { companyId, environmentId, runId } = await seedEnvironment();
+
+    const lease = await svc.acquireLease({
+      companyId,
+      environmentId,
+      heartbeatRunId: runId,
+      metadata: { driver: "local" },
+    });
+
+    expect(lease.status).toBe("active");
+    expect(lease.heartbeatRunId).toBe(runId);
+
+    const released = await svc.releaseLease(lease.id);
+
+    expect(released?.status).toBe("released");
+    expect(released?.releasedAt).not.toBeNull();
+  });
+
+  it("releases all active leases for a run without touching unrelated rows", async () => {
+    const { companyId, agentId, environmentId, runId } = await seedEnvironment();
+    const otherRunId = randomUUID();
+
+    await db.insert(heartbeatRuns).values({
+      id: otherRunId,
+      companyId,
+      agentId,
+      invocationSource: "manual",
+      status: "running",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const targetLease = await svc.acquireLease({
+      companyId,
+      environmentId,
+      heartbeatRunId: runId,
+    });
+    const otherLease = await svc.acquireLease({
+      companyId,
+      environmentId,
+      heartbeatRunId: otherRunId,
+    });
+
+    const released = await svc.releaseLeasesForRun(runId);
+
+    expect(released.map((lease) => lease.id)).toEqual([targetLease.id]);
+
+    const stillActive = await svc.listLeases(environmentId, { status: "active" });
+    expect(stillActive.map((lease) => lease.id)).toEqual([otherLease.id]);
+  });
+
+  it("creates and then reuses the default local environment for a company", async () => {
+    const companyId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const created = await svc.ensureLocalEnvironment(companyId);
+    const reused = await svc.ensureLocalEnvironment(companyId);
+
+    expect(created.driver).toBe("local");
+    expect(reused.id).toBe(created.id);
+
+    const rows = await db.select().from(environments).where(eq(environments.companyId, companyId));
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.name).toBe("Local");
+  });
+
+  it("leaves an existing default local environment untouched", async () => {
+    const companyId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    const archivedAt = new Date("2025-01-01T00:00:00.000Z");
+    const [existing] = await db
+      .insert(environments)
+      .values({
+        companyId,
+        name: "Archived Local",
+        description: "Operator-managed local environment",
+        driver: "local",
+        status: "archived",
+        config: { shell: "zsh" },
+        metadata: { owner: "operator" },
+        createdAt: archivedAt,
+        updatedAt: archivedAt,
+      })
+      .returning();
+
+    const ensured = await svc.ensureLocalEnvironment(companyId);
+
+    expect(ensured.id).toBe(existing?.id);
+    expect(ensured.name).toBe("Archived Local");
+    expect(ensured.status).toBe("archived");
+    expect(ensured.metadata).toEqual({ owner: "operator" });
+
+    const rows = await db.select().from(environments).where(eq(environments.companyId, companyId));
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.updatedAt.toISOString()).toBe(archivedAt.toISOString());
+  });
+
+  it("deduplicates concurrent default local environment creation", async () => {
+    const companyId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const results = await Promise.all(
+      Array.from({ length: 8 }, () => svc.ensureLocalEnvironment(companyId)),
+    );
+
+    expect(new Set(results.map((environment) => environment.id)).size).toBe(1);
+
+    const rows = await db.select().from(environments).where(eq(environments.companyId, companyId));
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.driver).toBe("local");
+    expect(rows[0]?.status).toBe("active");
+  });
+});