@opengeni/db 0.2.0

package/drizzle/0021_sandbox_pty_sessions.sql

@@ -0,0 +1,70 @@
+-- Channel-A interactive PTY sessions — the ONLY new persistent state the
+-- structured-services surface needs (P4.4; design-of-record
+-- modules/08-channel-a.md §3.1).
+--
+-- FS list/read/write/search and Git status/diff/log/show are STATELESS point
+-- queries against the live box (resume-by-id, run, drop) — they persist nothing;
+-- their notifications (fs.changed/git.changed) ride the existing session_events
+-- log. An interactive PTY, by contrast, is a live in-box process: we map our
+-- UUID ptyId <-> the SDK's numeric exec-session id (writeStdin({ sessionId })),
+-- the owning workspace/session, the lease_epoch that fences the PTY to the box
+-- it was opened on, and a last_input_at heartbeat so the one global reaper can
+-- kill idle PTYs (TTL) and PTYs stranded by a box re-key (epoch mismatch ->
+-- terminal.pty.exited{reason:"owner_gone"}).
+--
+-- DDL is INERT until the API wires the PTY routes (gated behind
+-- sandboxOwnershipEnabled). Forward-only, behavior-preserving: no existing row
+-- references it.
+
+CREATE TABLE IF NOT EXISTS "sandbox_pty_sessions" (
+  "id"              uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL, -- == ptyId on the wire
+  "account_id"      uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"    uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+  "session_id"      uuid NOT NULL REFERENCES "sessions"("id")         ON DELETE CASCADE,
+  -- The SDK numeric exec-session id used by writeStdin({ sessionId }). NULL until
+  -- the open exec yields a still-running process (a fast-exiting shell has none).
+  "exec_session_id" integer,
+  "lease_epoch"     integer NOT NULL, -- fenced to the box that opened it
+  "cols"            integer NOT NULL,
+  "rows"            integer NOT NULL,
+  "shell"           text NOT NULL,
+  "cwd"             text NOT NULL,
+  "status"          text NOT NULL DEFAULT 'open', -- 'open' | 'closed'
+  -- The viewer grant/subject that opened it (free-text — access subjects are not
+  -- always UUIDs, so a text column, never a uuid NOT NULL).
+  "opened_by"       text NOT NULL,
+  "last_input_at"   timestamptz NOT NULL DEFAULT now(),
+  "created_at"      timestamptz NOT NULL DEFAULT now(),
+  "closed_at"       timestamptz,
+
+  CONSTRAINT "sandbox_pty_sessions_status_chk" CHECK ("status" IN ('open','closed'))
+);
+
+-- List a session's OPEN PTYs (for reattach + reap) without scanning closed rows.
+CREATE INDEX IF NOT EXISTS "sandbox_pty_sessions_session_idx"
+  ON "sandbox_pty_sessions" ("workspace_id", "session_id")
+  WHERE "status" = 'open';
+
+-- ============== RLS + grants (verbatim 0017/0019/0020 boilerplate) ===========
+ALTER TABLE "sandbox_pty_sessions" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "sandbox_pty_sessions" FORCE  ROW LEVEL SECURITY;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = current_schema() AND tablename = 'sandbox_pty_sessions' AND policyname = 'workspace_isolation'
+  ) THEN
+    DROP POLICY workspace_isolation ON "sandbox_pty_sessions";
+  END IF;
+END $$;
+CREATE POLICY workspace_isolation ON "sandbox_pty_sessions"
+  USING (opengeni_private.workspace_rls_visible(account_id, workspace_id))
+  WITH CHECK (opengeni_private.workspace_rls_visible(account_id, workspace_id));
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON "sandbox_pty_sessions" TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0022_sandbox_lease_terminal_url.sql

@@ -0,0 +1,32 @@
+-- The REAL PTY terminal (ttyd pty-ws) data-plane URL cache (P5.t).
+--
+-- The interactive terminal is now a REAL PTY streamed over the SAME Modal raw-TLS
+-- tunnel the desktop noVNC uses (symmetric with Channel-B), replacing the broken
+-- stateless ptyWrite-over-HTTP path (Modal kept the live PTY process handle in an
+-- in-memory per-call activeProcesses Map; a fresh session per HTTP call hit
+-- "session not found"). ttyd listens on 7681 in-box and is exposed over a SEPARATE
+-- provider tunnel from the 6080 desktop noVNC — a DIFFERENT URL.
+--
+-- The lease already caches the single desktop tunnel URL (data_plane_url, the 6080
+-- noVNC plane). The terminal tunnel (7681) resolves to its own URL, so it needs
+-- its own cache column. mintTerminalStream records it here under the epoch fence
+-- (recordLeaseTerminalDataPlaneUrl); the fast-path then re-mints only a fresh
+-- scoped token against the cached URL (no box touch). It is reset to NULL on every
+-- box re-key (commitWarmingToWarm / failWarmingToCold / drain-cold / warming-death
+-- reset) exactly like data_plane_url, so a stale URL never survives a rollover.
+--
+-- Forward-only, behavior-preserving: NULLable, no backfill needed (a warm lease
+-- re-resolves + records it on the next terminal attach; a cold/legacy row reads
+-- NULL = "not yet minted").
+
+ALTER TABLE "sandbox_leases"
+  ADD COLUMN IF NOT EXISTS "terminal_data_plane_url" text;
+
+-- Re-grant on the new column (idempotent; mirrors the boilerplate in 0018 so a
+-- fresh opengeni_app role can read/write the added column).
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0023_session_title.sql

@@ -0,0 +1,19 @@
+-- Agent-generated session display title.
+--
+-- A session gets a short title generated by the agent itself (via the
+-- set_session_title first-party tool) — not a separate LLM call. `title` is
+-- NULL until set, in which case the UI keeps falling back to the
+-- initialMessage-derived label. `title_source` records who set it ('agent' for
+-- auto/agent writes, 'user' for a manual rename); a user-set title is permanent
+-- and the clobber guard (title_source IS DISTINCT FROM 'user') protects it from
+-- later agent writes. Both nullable, no backfill.
+ALTER TABLE "sessions"
+  ADD COLUMN IF NOT EXISTS "title" text,
+  ADD COLUMN IF NOT EXISTS "title_source" text;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0024_codex_subscription_credentials.sql

@@ -0,0 +1,51 @@
+-- Per-workspace ChatGPT/Codex subscription credentials.
+--
+-- One row per workspace. The secrets (access/refresh/id token) live INSIDE
+-- credential_encrypted using the v1 AES-256-GCM envelope (environment-crypto.ts),
+-- key = OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY — the same envelope used for
+-- workspace environment variables. chatgpt_account_id / plan_type / scopes /
+-- status are plaintext (request header + UI, non-secret). RLS enforces strict
+-- per-workspace isolation, identical to workspace_environment_variables.
+
+CREATE TABLE IF NOT EXISTS "codex_subscription_credentials" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id" uuid NOT NULL REFERENCES "workspaces"("id") ON DELETE CASCADE,
+  "credential_encrypted" text NOT NULL,
+  "chatgpt_account_id" text,
+  "scopes" text,
+  "plan_type" text,
+  "is_fedramp" boolean NOT NULL DEFAULT false,
+  "expires_at" timestamptz,
+  "last_refresh_at" timestamptz,
+  "status" text NOT NULL DEFAULT 'active',
+  "last_error" text,
+  "version" integer NOT NULL DEFAULT 1,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  "updated_at" timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "codex_subscription_credentials_workspace_idx"
+  ON "codex_subscription_credentials" ("workspace_id");
+
+ALTER TABLE "codex_subscription_credentials" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "codex_subscription_credentials" FORCE ROW LEVEL SECURITY;
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = current_schema() AND tablename = 'codex_subscription_credentials' AND policyname = 'workspace_isolation'
+  ) THEN
+    DROP POLICY workspace_isolation ON "codex_subscription_credentials";
+  END IF;
+END $$;
+CREATE POLICY workspace_isolation ON "codex_subscription_credentials"
+  USING (opengeni_private.workspace_rls_visible(account_id, workspace_id))
+  WITH CHECK (opengeni_private.workspace_rls_visible(account_id, workspace_id));
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0024_sandboxes_enrollments_metrics.sql

@@ -0,0 +1,262 @@
+-- First-class swappable sandboxes + enrollment records + per-machine metrics, and
+-- the per-session mutable, epoch-fenced active-sandbox POINTER (M2 of the
+-- bring-your-own-compute mega-PR; design-of-record .agent/implementation-dossier.md
+-- §10.3 routing proxy + §10.7 metrics + §23 enrollment).
+--
+-- WHY these four tables land together:
+--   * enrollments       — a user's own machine, registered once (the agent's
+--                          ed25519 pubkey IS its identity; whole-machine consent +
+--                          display/screen-control capture; active|revoked).
+--   * sandboxes          — the first-class NAMED sandbox a session's active pointer
+--                          points AT (kind modal|selfhosted; a selfhosted sandbox
+--                          carries enrollment_id → the machine it lives on).
+--   * sessions.active_sandbox_id / active_epoch — the mutable, epoch-fenced pointer
+--                          (the second epoch ABOVE lease_epoch) the routing proxy
+--                          re-reads PER TOOL CALL to make hot-swap seamless.
+--   * machine_metrics_{latest,series} — last-sample upsert + ~1/min downsampled
+--                          series per enrollment (NOT Prometheus; §10.7).
+--
+-- INTEGER epoch (NOT bigint): the lease-epoch spike proved postgres-js returns int8
+-- from a raw query as a JS STRING, which breaks a strict epoch-fence compare. The
+-- active_epoch fence shares that discipline — int4 returns a JS number. Epochs never
+-- approach 2^31, so the narrower type loses nothing (same rationale as
+-- sandbox_leases.lease_epoch in 0017).
+--
+-- DDL is INERT until the M3+ provider/routing/enrollment code wires it (gated behind
+-- sandboxSelfhostedEnabled). Forward-only + behavior-preserving: active_sandbox_id
+-- defaults to NULL (a NULL pointer resolves to the session's own group sandbox — the
+-- backward-compat default of §10.3), active_epoch defaults to 0; no backfill needed.
+--
+-- ROLLBACK (forward-only repo, but each statement is cleanly reversible): the down
+-- order is the FK-reverse of the up order —
+--   DROP TABLE machine_metrics_series;
+--   DROP TABLE machine_metrics_latest;
+--   ALTER TABLE sessions DROP COLUMN active_epoch, DROP COLUMN active_sandbox_id;
+--   DROP TABLE sandboxes;
+--   DROP TABLE enrollments;
+-- (the migration up/down/up gate exercises exactly this.)
+
+-- ============== enrollments (one row per registered machine) =================
+-- The agent's ed25519 PUBLIC key is the machine's identity (the control-plane
+-- subject the agent subscribes to maps to it). exposure is the loudly-consented
+-- access mode ('whole-machine' today; the column is text+CHECK so a future
+-- narrower mode is a CHECK widening, not a re-key). has_display/allow_screen_control
+-- are the desktop/computer-use consent bits (default FALSE — consent is opt-in).
+-- status is the lifecycle: 'active' until the user revokes (uninstall --purge /
+-- dashboard revoke), then 'revoked' (revoked_at stamped). last_seen_at is the
+-- heartbeat-driven liveness cursor surfaced in the Machines dashboard.
+CREATE TABLE IF NOT EXISTS "enrollments" (
+  "id"                   uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "account_id"           uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"         uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+
+  -- The agent's ed25519 public key (the machine identity). Unique per workspace —
+  -- one machine enrolls once per workspace (a re-enroll of the same key is an
+  -- idempotent UPDATE, not a second row).
+  "pubkey"               text NOT NULL,
+
+  -- The loudly-consented access mode. 'whole-machine' is the only mode today.
+  "exposure"             text NOT NULL DEFAULT 'whole-machine'
+                           CHECK ("exposure" IN ('whole-machine')),
+
+  -- Desktop / computer-use consent bits (default FALSE — opt-in per §3/§18).
+  "has_display"          boolean NOT NULL DEFAULT false,
+  "allow_screen_control" boolean NOT NULL DEFAULT false,
+
+  -- Lifecycle. 'active' until revoked; the reaper / Machines list filter on it.
+  "status"               text NOT NULL DEFAULT 'active'
+                           CHECK ("status" IN ('active','revoked')),
+
+  -- The machine's OS/arch (linux|macos|windows + the cargo arch). Reported at
+  -- enroll; informs the asset/desktop-capability decisions.
+  "os"                   text NOT NULL DEFAULT 'linux'
+                           CHECK ("os" IN ('linux','macos','windows')),
+  "arch"                 text NOT NULL DEFAULT 'x86_64',
+
+  -- Heartbeat liveness cursor (online/reconnecting/offline derive from this +
+  -- the §10.6 thresholds). NULL until the first connect.
+  "last_seen_at"         timestamptz,
+
+  "created_at"           timestamptz NOT NULL DEFAULT now(),
+  "revoked_at"           timestamptz,
+  "updated_at"           timestamptz NOT NULL DEFAULT now()
+);
+
+-- One enrollment per (workspace, pubkey): a re-enroll of the same machine is an
+-- idempotent upsert, never a duplicate machine row.
+CREATE UNIQUE INDEX IF NOT EXISTS "enrollments_workspace_pubkey_idx"
+  ON "enrollments" ("workspace_id", "pubkey");
+
+-- List a workspace's ACTIVE machines for the Machines dashboard without scanning
+-- revoked rows.
+CREATE INDEX IF NOT EXISTS "enrollments_workspace_status_idx"
+  ON "enrollments" ("workspace_id", "status");
+
+-- ============== sandboxes (the first-class named sandbox pointer target) ======
+-- The row a session's active_sandbox_id points AT. kind discriminates the backend
+-- the routing proxy resolves to: 'modal' (a cloud box) or 'selfhosted' (a user's
+-- machine, carrying enrollment_id → the enrollment it lives on). A modal sandbox
+-- has NULL enrollment_id; a selfhosted sandbox MUST carry one (enforced by the
+-- partial CHECK below). enrollment_id is ON DELETE SET NULL so deleting an
+-- enrollment never cascade-kills a sandbox row a session might still point at —
+-- the routing layer surfaces agent_offline instead.
+CREATE TABLE IF NOT EXISTS "sandboxes" (
+  "id"            uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "account_id"    uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"  uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+
+  -- The backend this sandbox resolves to.
+  "kind"          text NOT NULL CHECK ("kind" IN ('modal','selfhosted')),
+
+  -- A human-facing name (the Machines/sandbox-list label).
+  "name"          text NOT NULL,
+
+  -- The enrollment a selfhosted sandbox lives on. NULL for a modal sandbox; SET
+  -- NULL (not CASCADE) on enrollment delete so a pointed-at sandbox row is never
+  -- swept out from under a session.
+  "enrollment_id" uuid REFERENCES "enrollments"("id") ON DELETE SET NULL,
+
+  "created_at"    timestamptz NOT NULL DEFAULT now(),
+  "updated_at"    timestamptz NOT NULL DEFAULT now(),
+
+  -- A selfhosted sandbox is meaningless without its machine; a modal sandbox has
+  -- no enrollment. Pin the invariant at the DB edge.
+  CONSTRAINT "sandboxes_selfhosted_enrollment_chk"
+    CHECK (("kind" = 'selfhosted' AND "enrollment_id" IS NOT NULL)
+        OR ("kind" <> 'selfhosted' AND "enrollment_id" IS NULL))
+);
+
+-- List a workspace's sandboxes (the sandboxes_list tool / Machines surface).
+CREATE INDEX IF NOT EXISTS "sandboxes_workspace_created_idx"
+  ON "sandboxes" ("workspace_id", "created_at");
+
+-- Enumerate the sandboxes living on one enrollment (a machine's sandbox; a
+-- selfhosted enrollment is maxSandboxes:1, but the index is general).
+CREATE INDEX IF NOT EXISTS "sandboxes_enrollment_idx"
+  ON "sandboxes" ("enrollment_id")
+  WHERE "enrollment_id" IS NOT NULL;
+
+-- ============== sessions.active_sandbox_id + active_epoch (the pointer) =======
+-- The mutable, epoch-fenced pointer the routing proxy re-reads PER TOOL CALL.
+-- active_sandbox_id NULL == "use the session's own group sandbox" (the §10.3
+-- backward-compat default — no backfill flips existing rows). ON DELETE SET NULL
+-- so deleting a sandbox a session points at degrades to the group default, never
+-- a dangling FK. active_epoch is the SECOND epoch ABOVE lease_epoch, bumped on
+-- every swap; an in-flight op fenced by a stale active_epoch retries against the
+-- new active sandbox. integer (NOT bigint) — see header.
+ALTER TABLE "sessions"
+  ADD COLUMN IF NOT EXISTS "active_sandbox_id" uuid
+    REFERENCES "sandboxes"("id") ON DELETE SET NULL,
+  ADD COLUMN IF NOT EXISTS "active_epoch" integer NOT NULL DEFAULT 0;
+
+-- ============== machine_metrics_latest (one row per enrollment) ===============
+-- Last-sample upsert: ONE row per enrollment, overwritten on every sample. The
+-- PRIMARY KEY on enrollment_id is the upsert conflict target (ON CONFLICT
+-- (enrollment_id) DO UPDATE). ON DELETE CASCADE — metrics die with the machine.
+-- The sampled signals (§10.7): CPU%, load1/5/15, RAM/disk used+total, optional
+-- GPU util/mem, and a contention signal (run-queue length / pressure). Nullable
+-- where a platform/sample may not provide it (no GPU, headless).
+CREATE TABLE IF NOT EXISTS "machine_metrics_latest" (
+  "enrollment_id"  uuid PRIMARY KEY REFERENCES "enrollments"("id") ON DELETE CASCADE,
+  "account_id"     uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"   uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+
+  "cpu_percent"    numeric,
+  "load1"          numeric,
+  "load5"          numeric,
+  "load15"         numeric,
+  "mem_used_bytes"   bigint,
+  "mem_total_bytes"  bigint,
+  "disk_used_bytes"  bigint,
+  "disk_total_bytes" bigint,
+  "gpu_util_percent" numeric,
+  "gpu_mem_used_bytes"  bigint,
+  "gpu_mem_total_bytes" bigint,
+  "contention"     numeric,
+
+  -- When the agent took the sample (the agent's clock) vs when we stored it.
+  "sampled_at"     timestamptz NOT NULL,
+  "updated_at"     timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS "machine_metrics_latest_workspace_idx"
+  ON "machine_metrics_latest" ("workspace_id");
+
+-- ============== machine_metrics_series (downsampled ~1/min, retained N days) ===
+-- Append-only downsampled history (one row ~per minute per enrollment). Retention
+-- (delete rows older than N days) is a later concern; the table shape lands here.
+-- Same signal columns as _latest. The (enrollment_id, sampled_at) index serves the
+-- dashboard time-range read AND the retention sweep.
+CREATE TABLE IF NOT EXISTS "machine_metrics_series" (
+  "id"             uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "enrollment_id"  uuid NOT NULL REFERENCES "enrollments"("id") ON DELETE CASCADE,
+  "account_id"     uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"   uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+
+  "cpu_percent"    numeric,
+  "load1"          numeric,
+  "load5"          numeric,
+  "load15"         numeric,
+  "mem_used_bytes"   bigint,
+  "mem_total_bytes"  bigint,
+  "disk_used_bytes"  bigint,
+  "disk_total_bytes" bigint,
+  "gpu_util_percent" numeric,
+  "gpu_mem_used_bytes"  bigint,
+  "gpu_mem_total_bytes" bigint,
+  "contention"     numeric,
+
+  "sampled_at"     timestamptz NOT NULL,
+  "created_at"     timestamptz NOT NULL DEFAULT now()
+);
+
+-- Dashboard time-range read (newest-first per machine) + the retention sweep.
+CREATE INDEX IF NOT EXISTS "machine_metrics_series_enrollment_sampled_idx"
+  ON "machine_metrics_series" ("enrollment_id", "sampled_at");
+
+-- The retention sweep scans by age across all machines.
+CREATE INDEX IF NOT EXISTS "machine_metrics_series_sampled_idx"
+  ON "machine_metrics_series" ("sampled_at");
+
+-- ============== RLS + grants (verbatim 0017/0021 boilerplate) ================
+-- Every new table is workspace-scoped behind the SAME workspace_rls_visible policy
+-- the lease/pty tables use, so a scoped opengeni_app connection only ever sees its
+-- own workspace's machines/sandboxes/metrics.
+ALTER TABLE "enrollments"            ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "enrollments"            FORCE  ROW LEVEL SECURITY;
+ALTER TABLE "sandboxes"              ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "sandboxes"              FORCE  ROW LEVEL SECURITY;
+ALTER TABLE "machine_metrics_latest" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "machine_metrics_latest" FORCE  ROW LEVEL SECURITY;
+ALTER TABLE "machine_metrics_series" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "machine_metrics_series" FORCE  ROW LEVEL SECURITY;
+
+DO $$
+DECLARE
+  t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['enrollments','sandboxes','machine_metrics_latest','machine_metrics_series']
+  LOOP
+    IF EXISTS (
+      SELECT 1 FROM pg_policies
+      WHERE schemaname = current_schema() AND tablename = t AND policyname = 'workspace_isolation'
+    ) THEN
+      EXECUTE format('DROP POLICY workspace_isolation ON %I', t);
+    END IF;
+    EXECUTE format(
+      'CREATE POLICY workspace_isolation ON %I '
+      'USING (opengeni_private.workspace_rls_visible(account_id, workspace_id)) '
+      'WITH CHECK (opengeni_private.workspace_rls_visible(account_id, workspace_id))',
+      t);
+  END LOOP;
+END $$;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON "enrollments"            TO opengeni_app;
+    GRANT SELECT, INSERT, UPDATE, DELETE ON "sandboxes"              TO opengeni_app;
+    GRANT SELECT, INSERT, UPDATE, DELETE ON "machine_metrics_latest" TO opengeni_app;
+    GRANT SELECT, INSERT, UPDATE, DELETE ON "machine_metrics_series" TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0025_device_enrollment_requests.sql

@@ -0,0 +1,142 @@
+-- The OAuth 2.0 device-authorization (RFC 8628) PENDING request store (M5 of the
+-- bring-your-own-compute mega-PR; design-of-record .agent/implementation-dossier.md
+-- §10.2 enrollment device-flow + §18 LOUD consent). One short-TTL, SINGLE-USE row
+-- per in-flight enrollment, keyed by an opaque device_code (the agent polls with) +
+-- a short user_code (the user types at the approve page).
+--
+-- WHY a table (not in-memory / a signed stateless code): the agent polling and the
+-- user approving can hit DIFFERENT api replicas, and the consent record (WHO
+-- approved WHEN to WHAT) must be durable + auditable. An in-memory map would break
+-- across replicas and lose the consent trail. Postgres is the consistent,
+-- multi-replica-safe store the rest of the control plane already uses (no KV/Redis
+-- in the API). Mirrors the M2 0024 conventions verbatim (RLS + grants boilerplate).
+--
+-- STATE MACHINE: pending → approved | denied. A pending row past expires_at is
+-- EXPIRED on poll (no separate state — the expiry is read at poll time). Once the
+-- agent polls an approved row's credentials, the row flips to 'consumed' (so the
+-- credentials are single-use). The DURABLE identity the approve produced is the
+-- `enrollments` row (+ a `sandboxes` row, acceptance #2); this request row is
+-- transient and a retention sweep prunes terminal rows.
+--
+-- ROLLBACK (forward-only repo, but cleanly reversible):
+--   DROP TABLE device_enrollment_requests;
+-- (the migration up/down/up gate exercises exactly this.)
+
+-- The lifecycle domain (text + CHECK so a future state is a CHECK widening, not a
+-- re-key — same discipline as enrollments.status / sandboxes.kind in 0024).
+CREATE TABLE IF NOT EXISTS "device_enrollment_requests" (
+  "id"                        uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  -- The opaque code the agent polls with (unguessable, single-use). Globally unique.
+  "device_code"               text NOT NULL,
+  -- The short human-typed code (e.g. 'WDJB-MJHT'). Unique among LIVE (pending) rows.
+  "user_code"                 text NOT NULL,
+  "account_id"                uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"              uuid NOT NULL REFERENCES "workspaces"("id") ON DELETE CASCADE,
+  -- The agent's ed25519 public key (the machine identity the enrollment binds to).
+  "pubkey"                    text NOT NULL,
+  "os"                        text NOT NULL DEFAULT 'linux',
+  "arch"                      text NOT NULL DEFAULT 'x86_64',
+  "machine_name"              text,
+  -- The exposure the agent REQUESTED (whole-machine in v1; loudly consented at approve).
+  "requested_exposure"        text NOT NULL DEFAULT 'whole-machine',
+  -- The agent CAN offer a display (a real screen / Xvfb is available).
+  "can_offer_display"         boolean NOT NULL DEFAULT false,
+  -- The agent REQUESTS screen control (computer-use); the user's allow_screen_control
+  -- at approve is the AUTHORITATIVE consent.
+  "requests_screen_control"   boolean NOT NULL DEFAULT false,
+  "status"                    text NOT NULL DEFAULT 'pending',
+  -- ── LOUD CONSENT capture (who/when/what), stamped at approve ────────────────
+  "approved_by_subject_id"    text,
+  "approved_by_subject_label" text,
+  -- The user's screen-control consent decision (whole-machine is mandatory at approve).
+  "allow_screen_control"      boolean NOT NULL DEFAULT false,
+  "approved_at"               timestamptz,
+  -- The enrollment + sandbox the approve produced (acceptance #2). Null until approved.
+  -- ON DELETE SET NULL so deleting an enrollment never cascade-kills this audit row.
+  "enrollment_id"             uuid REFERENCES "enrollments"("id") ON DELETE SET NULL,
+  "sandbox_id"                uuid REFERENCES "sandboxes"("id") ON DELETE SET NULL,
+  "expires_at"                timestamptz NOT NULL,
+  "created_at"                timestamptz NOT NULL DEFAULT now(),
+  "updated_at"                timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "device_enrollment_requests_status_chk"
+    CHECK ("status" IN ('pending', 'approved', 'denied', 'consumed')),
+  CONSTRAINT "device_enrollment_requests_exposure_chk"
+    CHECK ("requested_exposure" IN ('whole-machine')),
+  CONSTRAINT "device_enrollment_requests_os_chk"
+    CHECK ("os" IN ('linux', 'macos', 'windows'))
+);
+
+-- The device_code is the agent's poll key — globally unique + indexed.
+CREATE UNIQUE INDEX IF NOT EXISTS "device_enrollment_requests_device_code_idx"
+  ON "device_enrollment_requests" ("device_code");
+
+-- The user_code must be unique among LIVE (pending) rows so the approve lookup is
+-- unambiguous; a terminal row's code may be recycled (partial unique index).
+CREATE UNIQUE INDEX IF NOT EXISTS "device_enrollment_requests_user_code_pending_idx"
+  ON "device_enrollment_requests" ("user_code")
+  WHERE "status" = 'pending';
+
+CREATE INDEX IF NOT EXISTS "device_enrollment_requests_workspace_created_idx"
+  ON "device_enrollment_requests" ("workspace_id", "created_at");
+
+CREATE INDEX IF NOT EXISTS "device_enrollment_requests_expires_idx"
+  ON "device_enrollment_requests" ("expires_at");
+
+-- ============== RLS + grants (verbatim 0017/0021/0024 boilerplate) ===========
+-- Workspace-scoped behind the SAME workspace_rls_visible policy the lease/pty/
+-- enrollment tables use, so a scoped opengeni_app connection only ever sees its own
+-- workspace's pending device-auth requests.
+ALTER TABLE "device_enrollment_requests" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "device_enrollment_requests" FORCE  ROW LEVEL SECURITY;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = current_schema() AND tablename = 'device_enrollment_requests' AND policyname = 'workspace_isolation'
+  ) THEN
+    DROP POLICY workspace_isolation ON "device_enrollment_requests";
+  END IF;
+  CREATE POLICY workspace_isolation ON "device_enrollment_requests"
+    USING (opengeni_private.workspace_rls_visible(account_id, workspace_id))
+    WITH CHECK (opengeni_private.workspace_rls_visible(account_id, workspace_id));
+END $$;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON "device_enrollment_requests" TO opengeni_app;
+  END IF;
+END $$;
+
+-- ============== device_code → (account_id, workspace_id) resolver ============
+-- The agent's POST /poll presents ONLY the opaque device_code — it has NO
+-- workspace context yet (it isn't enrolled). FORCE RLS would block a scoped
+-- connection from reading the row to discover which workspace it belongs to. So,
+-- exactly like the global reaper's cross-workspace sweep (0017
+-- opengeni_private.reap_sandbox_leases), the lookup is a SECURITY DEFINER read fn
+-- that returns ONLY the (account_id, workspace_id) for an UNEXPIRED-or-recent row.
+-- The DAO then re-reads the FULL row under the resolved workspace's RLS scope, so
+-- the device_code is the capability (unguessable + unique) and no broad table read
+-- ever escapes RLS. Returns no rows for an unknown code.
+CREATE OR REPLACE FUNCTION opengeni_private.resolve_device_enrollment_request(
+  p_device_code text
+)
+RETURNS TABLE (account_id uuid, workspace_id uuid)
+LANGUAGE sql
+SECURITY DEFINER
+-- EMBED-SAFE (see 0017): no pinned 'public' search_path -- inherit the caller's path so
+-- device_enrollment_requests resolves in public (standalone) OR the dedicated schema (embed).
+AS $$
+  SELECT d.account_id, d.workspace_id
+  FROM device_enrollment_requests d
+  WHERE d.device_code = p_device_code
+  LIMIT 1
+$$;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT EXECUTE ON FUNCTION opengeni_private.resolve_device_enrollment_request(text) TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0026_device_enrollment_user_code_resolver.sql

@@ -0,0 +1,47 @@
+-- The user_code → (account_id, workspace_id) resolver for the click-Grant approve
+-- page lookup (self-hosted enrollment UX, design 11 §B.1). Companion to the
+-- device_code resolver in 0025 (resolve_device_enrollment_request).
+--
+-- WHY a SECURITY DEFINER resolver: POST /v1/enrollments/device/lookup is the
+-- approve page reading machine details for a user_code WITHOUT a workspace in the
+-- path — the user_code is globally unique among LIVE (status='pending') rows (the
+-- 0025 partial unique index device_enrollment_requests_user_code_pending_idx). A
+-- scoped opengeni_app connection is under FORCE RLS and cannot read a row to learn
+-- which workspace it belongs to, so — exactly like 0025's device_code resolver —
+-- this returns ONLY the (account_id, workspace_id) for the PENDING row matching the
+-- code. The DAO then re-reads the FULL row under the resolved workspace's RLS scope
+-- and the ROUTE re-checks the caller holds an enrollments:read grant in THAT
+-- workspace, so the user_code is the capability and no broad read escapes RLS.
+--
+-- PENDING-ONLY: the partial unique index guarantees AT MOST ONE pending row per
+-- user_code, so the resolver is unambiguous; a terminal (approved/denied/consumed)
+-- row's recycled code is intentionally invisible here (lookup is for the live
+-- approve decision only).
+--
+-- ROLLBACK (forward-only repo, but cleanly reversible):
+--   DROP FUNCTION IF EXISTS opengeni_private.resolve_pending_device_enrollment_by_user_code(text);
+
+CREATE OR REPLACE FUNCTION opengeni_private.resolve_pending_device_enrollment_by_user_code(
+  p_user_code text
+)
+RETURNS TABLE (account_id uuid, workspace_id uuid)
+LANGUAGE sql
+SECURITY DEFINER
+-- EMBED-SAFE (see 0017/0025): no pinned 'public' search_path -- inherit the caller's path so
+-- device_enrollment_requests resolves in public (standalone) OR the dedicated schema (embed).
+-- A pinned `public` path also fails CREATE-time body validation (check_function_bodies) under
+-- the dedicated-schema migrate, since device_enrollment_requests lives in <schema>, not public.
+AS $$
+  SELECT d.account_id, d.workspace_id
+  FROM device_enrollment_requests d
+  WHERE d.user_code = p_user_code
+    AND d.status = 'pending'
+  LIMIT 1
+$$;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT EXECUTE ON FUNCTION opengeni_private.resolve_pending_device_enrollment_by_user_code(text) TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0027_session_working_dir.sql

@@ -0,0 +1,24 @@
+-- Per-session working directory (Stage A: backend slice).
+--
+-- sessions.working_dir is the path/cwd BASE the session's (selfhosted) box
+-- operates under — its agent exec, terminal pty, and structural file dock. The
+-- value is a launch-workspace_root-relative subdir (resolved under workspace_root
+-- by the agent's resolve_cwd) or an absolute machine path.
+--
+-- NULL (the default) ⇒ today's behavior EXACTLY: the agent substitutes its launch
+-- workspace_root for an empty cwd, so an unset working_dir is a byte-identical
+-- no-op (every existing + new row is NULL, no backfill). It is surfaced alongside
+-- the active-sandbox pointer (readActiveSandbox) and written through the
+-- epoch-fenced setActiveSandbox CAS, never the row INSERT — so it is seeded
+-- create-time when a machine target is named, per-session.
+ALTER TABLE "sessions"
+  ADD COLUMN IF NOT EXISTS "working_dir" text;
+
+-- Re-grant on the new column (idempotent; mirrors the boilerplate in earlier
+-- migrations so a fresh opengeni_app role can read/write the added column).
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO opengeni_app;
+  END IF;
+END $$;