@moondeck/station 0.0.1 → 1.0.1

package/lib/runtime-state.ts

@@ -0,0 +1,1033 @@
+import { and, eq, inArray, isNull, notInArray, or } from "drizzle-orm";
+
+import { getDb, schema, type Db } from "./db";
+import { isTerminal, TERMINAL_STATUSES } from "./task-status";
+import { newId } from "./ulid";
+import type { HostTask } from "../db/schema";
+import type { TaskLaunchInput, TaskUpResult } from "../src/protocol";
+import {
+  parseTaskEnvironmentLocator,
+  serializeTaskEnvironmentLocator,
+  type ProjectEnvMode,
+  type TaskEnvironmentLocator,
+} from "./task-environment/types";
+
+type DbExecutor = Pick<Db, "select" | "insert" | "update" | "delete">;
+
+/** Lifecycle event kinds recorded for the local UI's `/api/events` (ADR-028). */
+export type HostEventKind =
+  | "task.created"
+  | "task.started"
+  | "task.ended"
+  | "task.ship";
+
+export function getHostTask(taskId: string): HostTask | null {
+  return (
+    getDb()
+      .select()
+      .from(schema.hostTasks)
+      .where(eq(schema.hostTasks.taskId, taskId))
+      .get() ?? null
+  );
+}
+
+/** Loader tasks whose authenticated gateway generation may still have a live
+ * runtime after this host process restarts. Terminal/stopped rows are never
+ * reactivated merely because an old credential file survived. */
+export function activeLoaderHostTasks(): HostTask[] {
+  return getDb()
+    .select()
+    .from(schema.hostTasks)
+    .where(
+      and(
+        eq(schema.hostTasks.envMode, "loader"),
+        inArray(schema.hostTasks.statusMirror, ["starting", "running"]),
+      ),
+    )
+    .all();
+}
+
+/** ADR-154: the runs whose runtime survives this process's start running:
+ *  each task marked running whose admitted run is open and established. */
+export function runningTaskRuns(db: Db = getDb()): Array<{ taskId: string; runEpoch: number }> {
+  const rows = db
+    .select({ taskId: schema.hostTasks.taskId })
+    .from(schema.hostTasks)
+    .where(eq(schema.hostTasks.statusMirror, "running"))
+    .all();
+  return rows.flatMap(({ taskId }) => {
+    const run = readTaskRunEpochState(taskId, db);
+    return run !== null && run.assignmentOpen && run.runtimeEstablishedEpoch === run.highestRunEpoch && run.highestRunEpoch > 0
+      ? [{ taskId, runEpoch: run.highestRunEpoch }]
+      : [];
+  });
+}
+
+/** Remove a provisional first-seen row when admission loses a lifecycle gate. */
+export function deleteHostTask(taskId: string, db: Db = getDb()): void {
+  // Row deletions are rare and load-bearing; a silent one cost a live
+  // machine-task forensic session (2026-08-27). Name the caller.
+  console.warn(
+    `[runtime-state] deleting host task row ${taskId}\n${(new Error().stack ?? "").split("\n").slice(2, 5).join("\n")}`,
+  );
+  db
+    .delete(schema.hostTasks)
+    .where(eq(schema.hostTasks.taskId, taskId))
+    .run();
+}
+
+/** Final orphan-GC metadata purge. Runtime/filesystem and credential proofs
+ * happen before this transaction; a SQLite failure leaves every task-owned
+ * row intact rather than acknowledging a partial metadata deletion. */
+export function purgeHostTaskState(taskId: string, db: Db = getDb()): void {
+  console.warn(`[runtime-state] purging all host state for task ${taskId}`);
+  db.transaction((tx) => {
+    closeCurrentTaskRunAssignmentIn(tx, taskId);
+    tx.delete(schema.hostAgentSessions)
+      .where(eq(schema.hostAgentSessions.taskId, taskId))
+      .run();
+    tx.delete(schema.hostEvents)
+      .where(eq(schema.hostEvents.taskId, taskId))
+      .run();
+    tx.delete(schema.hostTasks)
+      .where(eq(schema.hostTasks.taskId, taskId))
+      .run();
+  });
+}
+
+/** A managed runtime may restart only when no task lifecycle is active. */
+export function hasActiveHostTasks(): boolean {
+  return Boolean(
+    getDb()
+      .select({ taskId: schema.hostTasks.taskId })
+      .from(schema.hostTasks)
+      .where(inArray(schema.hostTasks.statusMirror, ["starting", "running"]))
+      .limit(1)
+      .get(),
+  );
+}
+
+/**
+ * A task lifecycle mutation is mid-flight: a taskUp between admission and its
+ * recorded result. Steady-state RUNNING tasks are deliberately not counted —
+ * durable sessions survive a managed service restart, so a version update
+ * needs only the mutations drained. The strict all-tasks predicate above
+ * remains for legacy conversion (which takes over a different service's live
+ * workload) and rollback. Live 2026-08-17: using the strict predicate for
+ * plain updates made every update fail while any task merely existed.
+ */
+export function hasInFlightHostTaskLifecycle(): boolean {
+  return Boolean(
+    getDb()
+      .select({ taskId: schema.hostTasks.taskId })
+      .from(schema.hostTasks)
+      .where(eq(schema.hostTasks.statusMirror, "starting"))
+      .limit(1)
+      .get(),
+  );
+}
+
+/**
+ * Whether a persisted workload makes destructive host maintenance unsafe.
+ * Only the closed set of cloud terminal states is removable. Null and future /
+ * malformed values fail closed so a newer or partially-written lifecycle row
+ * cannot be destroyed by an older CLI that does not understand it.
+ */
+export function hostTaskBlocksMaintenance(status: string | null): boolean {
+  return status === null || !isTerminal(status);
+}
+
+/** Uninstall must preserve every local workload that is not provably terminal. */
+export function hasNonTerminalHostTasks(): boolean {
+  return Boolean(
+    getDb()
+      .select({ taskId: schema.hostTasks.taskId })
+      .from(schema.hostTasks)
+      .where(
+        or(
+          isNull(schema.hostTasks.statusMirror),
+          notInArray(schema.hostTasks.statusMirror, [...TERMINAL_STATUSES]),
+        ),
+      )
+      .limit(1)
+      .get(),
+  );
+}
+
+export function upsertHostTask(
+  taskId: string,
+  values: Partial<Omit<HostTask, "taskId" | "updatedAt">>,
+): void {
+  upsertHostTaskIn(getDb(), taskId, values);
+}
+
+function upsertHostTaskIn(
+  db: DbExecutor,
+  taskId: string,
+  values: Partial<Omit<HostTask, "taskId" | "updatedAt">>,
+): void {
+  const now = Date.now();
+  db
+    .insert(schema.hostTasks)
+    .values({
+      taskId,
+      previewPorts: "[]",
+      ...values,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: schema.hostTasks.taskId,
+      set: {
+        ...values,
+        updatedAt: now,
+      },
+    })
+    .run();
+}
+
+export function recordTaskUpResult(
+  taskId: string,
+  result: TaskUpResult,
+  environment: TaskEnvironmentLocator,
+  envMode: ProjectEnvMode,
+  db: Db = getDb(),
+): void {
+  upsertHostTaskIn(db, taskId, {
+    codeServerPort: result.codeServerPort ?? null,
+    previewPorts: JSON.stringify(result.previewPorts ?? []),
+    composeProject: result.composeProject,
+    worktreePath: result.worktreePath,
+    environmentProvider: environment.provider,
+    environmentLocator: serializeTaskEnvironmentLocator(environment),
+    envMode,
+    statusMirror: "running",
+    lockedAt: null,
+    startedAt: Date.now(),
+    endedAt: null,
+  });
+}
+
+export type TaskRunEpochAdmission =
+  | { kind: "legacy" }
+  | {
+      kind: "accepted";
+      relation: "advanced" | "retry";
+      previousRunEpoch: number;
+      hadTask: boolean;
+    }
+  | {
+      kind: "stale";
+      currentRunEpoch: number;
+      reason: "older" | "closed";
+    };
+
+export interface TaskRunEpochState {
+  /** Highest v1 dispatch this runner has ever admitted for the task. */
+  highestRunEpoch: number;
+  /** False after Stop/teardown; only a strictly higher epoch may reopen it. */
+  assignmentOpen: boolean;
+  /** Zero until a runtime has successfully completed task-up for this epoch. */
+  runtimeEstablishedEpoch: number;
+}
+
+export type CloseTaskRunAssignmentResult =
+  | { kind: "missing" }
+  | { kind: "mismatch"; currentRunEpoch: number }
+  | { kind: "already_closed"; runEpoch: number }
+  | { kind: "closed"; runEpoch: number };
+
+export type StoppedTaskRunAssignment =
+  | { kind: "legacy" }
+  | { kind: "closed"; runEpoch: number };
+
+function persistedRunEpoch(value: number): number {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error("persisted assignment run epoch is invalid");
+  }
+  return value;
+}
+
+function taskRunEpochStateIn(
+  db: DbExecutor,
+  taskId: string,
+): TaskRunEpochState | null {
+  const assignment = db
+    .select()
+    .from(schema.hostTaskRunAssignments)
+    .where(eq(schema.hostTaskRunAssignments.taskId, taskId))
+    .get();
+  if (!assignment) return null;
+  const task = db
+    .select({ runEpoch: schema.hostTasks.runEpoch })
+    .from(schema.hostTasks)
+    .where(eq(schema.hostTasks.taskId, taskId))
+    .get();
+  return {
+    highestRunEpoch: persistedRunEpoch(assignment.highestRunEpoch),
+    assignmentOpen: assignment.assignmentOpen,
+    runtimeEstablishedEpoch: hostTaskRunEpoch(task ?? {}),
+  };
+}
+
+/** Read all three durable assignment facts from one SQLite snapshot. */
+export function readTaskRunEpochState(
+  taskId: string,
+  db: Db = getDb(),
+): TaskRunEpochState | null {
+  return db.transaction((tx) => taskRunEpochStateIn(tx, taskId));
+}
+
+/**
+ * A runtime may be reused only when both authorities name this exact run:
+ * the assignment is still open at its monotonic floor, and task-up recorded
+ * the runtime as fully established. Legacy reuse remains available only on a
+ * task that has never crossed the v1 floor.
+ */
+export function canReuseTaskRuntimeForRun(
+  taskId: string,
+  runEpoch: number | undefined,
+  db: Db = getDb(),
+): boolean {
+  if (
+    runEpoch !== undefined &&
+    (!Number.isSafeInteger(runEpoch) || runEpoch < 1)
+  ) {
+    throw new Error("task run epoch must be a positive safe integer");
+  }
+  return db.transaction((tx) => {
+    const state = taskRunEpochStateIn(tx, taskId);
+    const task = tx
+      .select({
+        runEpoch: schema.hostTasks.runEpoch,
+        statusMirror: schema.hostTasks.statusMirror,
+      })
+      .from(schema.hostTasks)
+      .where(eq(schema.hostTasks.taskId, taskId))
+      .get();
+    if (runEpoch === undefined) {
+      return (
+        state === null &&
+        task !== undefined &&
+        hostTaskRunEpoch(task) === 0 &&
+        task.statusMirror === "running"
+      );
+    }
+    return (
+      state !== null &&
+      state.assignmentOpen &&
+      state.highestRunEpoch === runEpoch &&
+      state.runtimeEstablishedEpoch === runEpoch &&
+      task?.statusMirror === "running"
+    );
+  });
+}
+
+/**
+ * Persist the assignment fence as soon as a v1 task-up reaches the runner.
+ * The floor is deliberately independent of the removable runtime row. A
+ * same-epoch retry is admitted only while the assignment remains open; a
+ * higher epoch atomically reopens it, and nothing can lower it.
+ */
+export function admitTaskRunEpoch(
+  taskId: string,
+  runEpoch: number | undefined,
+  db: Db = getDb(),
+): TaskRunEpochAdmission {
+  if (
+    runEpoch !== undefined &&
+    (!Number.isSafeInteger(runEpoch) || runEpoch < 1)
+  ) {
+    throw new Error("task run epoch must be a positive safe integer");
+  }
+  return db.transaction((tx) => {
+    const existingTask = tx
+      .select({ taskId: schema.hostTasks.taskId })
+      .from(schema.hostTasks)
+      .where(eq(schema.hostTasks.taskId, taskId))
+      .get();
+    const assignment = tx
+      .select()
+      .from(schema.hostTaskRunAssignments)
+      .where(eq(schema.hostTaskRunAssignments.taskId, taskId))
+      .get();
+    if (runEpoch === undefined) {
+      if (assignment !== undefined) {
+        throw new Error(
+          `legacy task-up is refused after run ${String(assignment.highestRunEpoch)} was admitted`,
+        );
+      }
+      return { kind: "legacy" } as const;
+    }
+    if (assignment === undefined) {
+      tx.insert(schema.hostTaskRunAssignments)
+        .values({
+          taskId,
+          highestRunEpoch: runEpoch,
+          assignmentOpen: true,
+          updatedAt: Date.now(),
+        })
+        .run();
+      return {
+        kind: "accepted",
+        relation: "advanced",
+        previousRunEpoch: 0,
+        hadTask: existingTask !== undefined,
+      } as const;
+    }
+    const currentRunEpoch = persistedRunEpoch(assignment.highestRunEpoch);
+    if (runEpoch < currentRunEpoch) {
+      return { kind: "stale", currentRunEpoch, reason: "older" } as const;
+    }
+    if (runEpoch === currentRunEpoch) {
+      if (!assignment.assignmentOpen) {
+        return { kind: "stale", currentRunEpoch, reason: "closed" } as const;
+      }
+      return {
+        kind: "accepted",
+        relation: "retry",
+        previousRunEpoch: currentRunEpoch,
+        hadTask: existingTask !== undefined,
+      } as const;
+    }
+    tx.update(schema.hostTaskRunAssignments)
+      .set({
+        highestRunEpoch: runEpoch,
+        assignmentOpen: true,
+        updatedAt: Date.now(),
+      })
+      .where(eq(schema.hostTaskRunAssignments.taskId, taskId))
+      .run();
+    return {
+      kind: "accepted",
+      relation: "advanced",
+      previousRunEpoch: currentRunEpoch,
+      hadTask: existingTask !== undefined,
+    } as const;
+  });
+}
+
+/**
+ * Close one exact assignment. A delayed Stop for an older run is harmless.
+ * The established-runtime epoch remains available for exact cleanup and
+ * forensics; the independent closed bit is what makes reuse impossible.
+ */
+export function closeTaskRunAssignment(
+  taskId: string,
+  runEpoch: number,
+  db: Db = getDb(),
+): CloseTaskRunAssignmentResult {
+  if (!Number.isSafeInteger(runEpoch) || runEpoch < 1) {
+    throw new Error("task run epoch must be a positive safe integer");
+  }
+  return db.transaction((tx) => {
+    const assignment = tx
+      .select()
+      .from(schema.hostTaskRunAssignments)
+      .where(eq(schema.hostTaskRunAssignments.taskId, taskId))
+      .get();
+    if (!assignment) return { kind: "missing" } as const;
+    const currentRunEpoch = persistedRunEpoch(assignment.highestRunEpoch);
+    if (currentRunEpoch !== runEpoch) {
+      return { kind: "mismatch", currentRunEpoch } as const;
+    }
+    if (!assignment.assignmentOpen) {
+      return { kind: "already_closed", runEpoch } as const;
+    }
+    closeCurrentTaskRunAssignmentIn(tx, taskId);
+    return { kind: "closed", runEpoch } as const;
+  });
+}
+
+/**
+ * Close the exact assignment named by Stop. While the caller holds the task
+ * lifecycle slot, this may also adopt a pre-v1 runtime whose durable task row
+ * still has epoch zero. Persisting that adopted epoch closed prevents a
+ * delayed same-epoch task-up from reviving the runtime after Stop.
+ */
+export function closeTaskRunAssignmentForStop(
+  taskId: string,
+  runEpoch: number,
+  db: Db = getDb(),
+): CloseTaskRunAssignmentResult {
+  if (!Number.isSafeInteger(runEpoch) || runEpoch < 1) {
+    throw new Error("task run epoch must be a positive safe integer");
+  }
+  return db.transaction((tx) => {
+    const assignment = tx
+      .select()
+      .from(schema.hostTaskRunAssignments)
+      .where(eq(schema.hostTaskRunAssignments.taskId, taskId))
+      .get();
+    if (assignment) {
+      const currentRunEpoch = persistedRunEpoch(assignment.highestRunEpoch);
+      if (currentRunEpoch !== runEpoch) {
+        return { kind: "mismatch", currentRunEpoch } as const;
+      }
+      if (!assignment.assignmentOpen) {
+        return { kind: "already_closed", runEpoch } as const;
+      }
+      closeCurrentTaskRunAssignmentIn(tx, taskId);
+      return { kind: "closed", runEpoch } as const;
+    }
+
+    const task = tx
+      .select({ runEpoch: schema.hostTasks.runEpoch })
+      .from(schema.hostTasks)
+      .where(eq(schema.hostTasks.taskId, taskId))
+      .get();
+    if (task === undefined || hostTaskRunEpoch(task) !== 0) {
+      return { kind: "missing" } as const;
+    }
+
+    const now = Date.now();
+    tx.insert(schema.hostTaskRunAssignments)
+      .values({
+        taskId,
+        highestRunEpoch: runEpoch,
+        assignmentOpen: false,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .run();
+    return { kind: "closed", runEpoch } as const;
+  });
+}
+
+/**
+ * Close and identify the assignment whose runtime was just proven stopped.
+ * The caller MUST hold the task lifecycle slot: that is what makes "current"
+ * the exact run associated with the physical stop, rather than whichever run
+ * happens to be current when a later status publisher wakes up.
+ */
+export function closeCurrentTaskRunAssignmentForStoppedRuntime(
+  taskId: string,
+  db: Db = getDb(),
+): StoppedTaskRunAssignment {
+  return db.transaction((tx) => {
+    const assignment = tx
+      .select()
+      .from(schema.hostTaskRunAssignments)
+      .where(eq(schema.hostTaskRunAssignments.taskId, taskId))
+      .get();
+    if (!assignment) return { kind: "legacy" } as const;
+    const runEpoch = persistedRunEpoch(assignment.highestRunEpoch);
+    if (assignment.assignmentOpen) {
+      closeCurrentTaskRunAssignmentIn(tx, taskId);
+    }
+    return { kind: "closed", runEpoch } as const;
+  });
+}
+
+function closeCurrentTaskRunAssignmentIn(
+  db: DbExecutor,
+  taskId: string,
+): void {
+  const now = Date.now();
+  db.update(schema.hostTaskRunAssignments)
+    .set({ assignmentOpen: false, updatedAt: now })
+    .where(eq(schema.hostTaskRunAssignments.taskId, taskId))
+    .run();
+}
+
+/** Record successful task-up only for the exact still-open assignment. */
+export function recordTaskRuntimeEstablished(
+  taskId: string,
+  runEpoch: number,
+  db: Db = getDb(),
+): void {
+  if (!Number.isSafeInteger(runEpoch) || runEpoch < 1) {
+    throw new Error("task run epoch must be a positive safe integer");
+  }
+  db.transaction((tx) => {
+    const state = taskRunEpochStateIn(tx, taskId);
+    if (
+      state === null ||
+      !state.assignmentOpen ||
+      state.highestRunEpoch !== runEpoch
+    ) {
+      throw new Error("task runtime does not match the open assignment");
+    }
+    const task = tx
+      .select({ statusMirror: schema.hostTasks.statusMirror })
+      .from(schema.hostTasks)
+      .where(eq(schema.hostTasks.taskId, taskId))
+      .get();
+    if (task?.statusMirror !== "running") {
+      throw new Error("task runtime has not completed task-up");
+    }
+    tx.update(schema.hostTasks)
+      .set({ runEpoch, updatedAt: Date.now() })
+      .where(eq(schema.hostTasks.taskId, taskId))
+      .run();
+  });
+}
+
+export function recordTaskStarting(
+  taskId: string,
+  runEpoch?: number,
+  db: Db = getDb(),
+): void {
+  if (
+    runEpoch !== undefined &&
+    (!Number.isSafeInteger(runEpoch) || runEpoch < 1)
+  ) {
+    throw new Error("task run epoch must be a positive safe integer");
+  }
+  db.transaction((tx) => {
+    const assignment = taskRunEpochStateIn(tx, taskId);
+    if (runEpoch === undefined) {
+      if (assignment !== null) {
+        throw new Error("legacy task start is refused after v1 admission");
+      }
+    } else if (
+      assignment === null ||
+      !assignment.assignmentOpen ||
+      assignment.highestRunEpoch !== runEpoch
+    ) {
+      throw new Error("task run epoch does not match the open assignment");
+    }
+    upsertHostTaskIn(tx, taskId, {
+      statusMirror: "starting",
+      lockedAt: Date.now(),
+      startedAt: Date.now(),
+      endedAt: null,
+      // A starting row is not proof that provisioning completed. The exact
+      // epoch is installed only by recordTaskRuntimeEstablished.
+      ...(runEpoch === undefined ? {} : { runEpoch: 0 }),
+    });
+  });
+}
+
+/** The successfully established runtime epoch; zero includes legacy rows and
+ * v1 rows still provisioning. Anything malformed fails closed. */
+export function hostTaskRunEpoch(task: {
+  runEpoch?: number | null;
+}): number {
+  const value = task.runEpoch ?? 0;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error("persisted task run epoch is invalid");
+  }
+  return value;
+}
+
+/** Persist the provider-owned crash-recovery identity before provisioning may
+ * create worktrees, containers, networks, or volumes. Status remains
+ * `starting`; the enriched locator is written by `recordTaskUpResult`. */
+export function recordTaskEnvironmentPrepared(
+  taskId: string,
+  environment: TaskEnvironmentLocator,
+  envMode: ProjectEnvMode,
+): void {
+  upsertHostTask(taskId, {
+    environmentProvider: environment.provider,
+    environmentLocator: serializeTaskEnvironmentLocator(environment),
+    envMode,
+  });
+}
+
+export function recordTaskDown(
+  taskId: string,
+  status: string | undefined,
+  db: Db = getDb(),
+): void {
+  db.transaction((tx) => {
+    closeCurrentTaskRunAssignmentIn(tx, taskId);
+    upsertHostTaskIn(tx, taskId, {
+      codeServerPort: null,
+      previewPorts: "[]",
+      composeProject: null,
+      worktreePath: null,
+      environmentProvider: null,
+      environmentLocator: null,
+      envMode: null,
+      projectEnvSpec: null,
+      statusMirror: status ?? "killed",
+      lockedAt: null,
+      endedAt: Date.now(),
+    });
+    applyTaskTerminalHistoryRetentionInTransaction(tx, taskId);
+  });
+}
+
+export function recordTaskError(taskId: string): void {
+  upsertHostTask(taskId, {
+    statusMirror: "error",
+    lockedAt: null,
+    endedAt: Date.now(),
+  });
+}
+
+/**
+ * Persist the owner + project slugs the host received in TaskLaunchInput, so
+ * the local UI can show "who/what" for active tasks (ADR-028). The cloud
+ * remains the audit authority; this is a local read-convenience mirror.
+ */
+export function recordTaskOwner(
+  taskId: string,
+  ownerUserId: string,
+  ownerEmail: string | null,
+  ownerName: string | null,
+  projectSlugs: string[],
+  engineAccountScope: string | null = null,
+  /** Lead project first — the order project env merges in. */
+  projectIds: string[] = [],
+): void {
+  upsertHostTask(taskId, {
+    ownerUserId,
+    ownerEmail,
+    ownerName,
+    projectSlugs: JSON.stringify(projectSlugs),
+    projectIds: JSON.stringify(projectIds),
+    engineAccountScope,
+  });
+}
+
+/** Legacy baked-machine project ids, lead first; `[]` for rows that predate
+ *  the column or carry an unreadable value. Loader resolution uses projectEnvSpec. */
+export function hostTaskProjectIds(task: { projectIds?: string | null }): string[] {
+  try {
+    const parsed: unknown = JSON.parse(task.projectIds ?? "[]");
+    return Array.isArray(parsed)
+      ? parsed.filter((id): id is string => typeof id === "string" && id.length > 0)
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Null is the durable meaning of a task created before ADR-153 PR2. */
+export function hostTaskEnvMode(task: {
+  envMode?: string | null;
+}): ProjectEnvMode {
+  if (task.envMode === null || task.envMode === undefined) return "baked";
+  if (task.envMode === "baked" || task.envMode === "loader") {
+    return task.envMode;
+  }
+  throw new Error(`unsupported task project env mode: ${task.envMode}`);
+}
+
+export type TaskSharedFilesMode = "off" | "ro" | "rw";
+
+/**
+ * Normalize the trusted task-launch setting before it is persisted. The wire
+ * default has always been read-only; recovery records that decision rather
+ * than consulting the task-writable `.uai/files-mounted` marker.
+ */
+export function normalizeTaskSharedFilesMode(
+  value: string | undefined,
+): TaskSharedFilesMode {
+  if (value === undefined) return "ro";
+  if (value === "off" || value === "ro" || value === "rw") return value;
+  throw new Error(`unsupported task shared-files mode: ${value}`);
+}
+
+/** Persist the normalized mode while the authoritative task launch exists. */
+export function recordTaskSharedFilesMode(
+  taskId: string,
+  task: { sharedFiles?: string },
+  db: Db = getDb(),
+): TaskSharedFilesMode {
+  const mode = normalizeTaskSharedFilesMode(task.sharedFiles);
+  upsertHostTaskIn(db, taskId, { sharedFilesMode: mode });
+  return mode;
+}
+
+/**
+ * Read the trusted recovery authority. Null identifies a pre-Files-v1 row;
+ * malformed or newer values fail closed instead of becoming read-only.
+ */
+export function hostTaskSharedFilesMode(task: {
+  sharedFilesMode?: string | null;
+}): TaskSharedFilesMode | null {
+  const mode = task.sharedFilesMode;
+  if (mode === null || mode === undefined) return null;
+  if (mode === "off" || mode === "ro" || mode === "rw") return mode;
+  throw new Error(`unsupported persisted task shared-files mode: ${mode}`);
+}
+
+export interface TaskFilesRecoveryBinding {
+  locator: TaskEnvironmentLocator;
+  workspacePath: string;
+  mode: TaskSharedFilesMode;
+}
+
+/** Files may be staged before a recovered grant opens only from an exact,
+ * established v1 runtime row. A fresh/starting/different run has no binding;
+ * an exact running row with incomplete or non-self metadata is corruption and
+ * fails closed instead of letting root operate on a guessed workspace. */
+export function taskFilesRecoveryBinding(
+  task: Pick<
+    HostTask,
+    | "statusMirror"
+    | "runEpoch"
+    | "environmentLocator"
+    | "worktreePath"
+    | "sharedFilesMode"
+  > | null,
+  assignment: { taskId: string; runEpoch: number },
+): TaskFilesRecoveryBinding | null {
+  if (
+    task === null ||
+    task.statusMirror !== "running" ||
+    hostTaskRunEpoch(task) !== assignment.runEpoch
+  ) {
+    return null;
+  }
+  if (task.environmentLocator === null || task.worktreePath === null) {
+    throw new Error("the recovered task has no complete runtime locator");
+  }
+  const mode = hostTaskSharedFilesMode(task);
+  if (mode === null) throw new Error("the recovered task predates Files v1");
+  const locator = parseTaskEnvironmentLocator(task.environmentLocator);
+  const value = locator.value;
+  if (
+    locator.provider !== "self" ||
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    (value as Record<string, unknown>).workspacePath !== "/workspace" ||
+    (value as Record<string, unknown>).taskId !== assignment.taskId
+  ) {
+    throw new Error("the recovered task does not have the canonical Files-v1 runtime");
+  }
+  return { locator, workspacePath: "/workspace", mode };
+}
+
+export interface TaskProjectEnvSpec {
+  schemaVersion: 1;
+  projects: Array<{
+    projectId: string;
+    position: number;
+    declaredNames: string[];
+  }>;
+  /** Cloud-computed, explicitly non-secret task literals (preview/theme). */
+  previewEnv: Record<string, string>;
+}
+
+const PROJECT_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Build the value-free resolver input while the authoritative launch frame is present. */
+export function taskProjectEnvSpec(
+  input: Pick<TaskLaunchInput, "projects" | "task">,
+): TaskProjectEnvSpec {
+  const projects = input.projects
+    .map((project) => {
+      let parsed: unknown = [];
+      try {
+        parsed = JSON.parse(project.env);
+      } catch {
+        // Match task-up's established malformed-env behavior: no declarations.
+      }
+      const names: string[] = [];
+      const seen = new Set<string>();
+      if (Array.isArray(parsed)) {
+        for (const declaration of parsed) {
+          if (
+            !declaration ||
+            typeof declaration !== "object" ||
+            Array.isArray(declaration)
+          ) {
+            continue;
+          }
+          const name = (declaration as { key?: unknown }).key;
+          if (
+            typeof name === "string" &&
+            PROJECT_ENV_NAME.test(name) &&
+            !seen.has(name)
+          ) {
+            seen.add(name);
+            names.push(name);
+          }
+        }
+      }
+      return {
+        projectId: project.id,
+        position: project.position,
+        declaredNames: names,
+      };
+    })
+    .sort(
+      (left, right) =>
+        left.position - right.position ||
+        left.projectId.localeCompare(right.projectId),
+    );
+  const previewEnv = Object.fromEntries(
+    Object.entries(input.task.previewEnv ?? {}).sort(([left], [right]) =>
+      left.localeCompare(right),
+    ),
+  );
+  return { schemaVersion: 1, projects, previewEnv };
+}
+
+/** Persist resolver metadata before environment provisioning starts. */
+export function recordTaskProjectEnvSpec(
+  taskId: string,
+  input: Pick<TaskLaunchInput, "projects" | "task">,
+): void {
+  upsertHostTask(taskId, {
+    projectEnvSpec: JSON.stringify(taskProjectEnvSpec(input)),
+  });
+}
+
+/** Null is a pre-feature row; malformed/newer persisted state fails closed. */
+export function hostTaskProjectEnvSpec(task: {
+  projectEnvSpec?: string | null;
+}): TaskProjectEnvSpec | null {
+  if (task.projectEnvSpec === null || task.projectEnvSpec === undefined) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(task.projectEnvSpec);
+  } catch {
+    throw new Error("persisted task project env spec is malformed");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("persisted task project env spec is malformed");
+  }
+  const record = parsed as Record<string, unknown>;
+  if (
+    record.schemaVersion !== 1 ||
+    !Array.isArray(record.projects) ||
+    !record.previewEnv ||
+    typeof record.previewEnv !== "object" ||
+    Array.isArray(record.previewEnv)
+  ) {
+    throw new Error("unsupported persisted task project env spec");
+  }
+  const projects = record.projects.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error("persisted task project env spec has a malformed project");
+    }
+    const project = entry as Record<string, unknown>;
+    if (
+      typeof project.projectId !== "string" ||
+      project.projectId.length === 0 ||
+      !Number.isSafeInteger(project.position) ||
+      !Array.isArray(project.declaredNames) ||
+      project.declaredNames.some(
+        (name) => typeof name !== "string" || !PROJECT_ENV_NAME.test(name),
+      )
+    ) {
+      throw new Error("persisted task project env spec has a malformed project");
+    }
+    return {
+      projectId: project.projectId,
+      position: project.position as number,
+      declaredNames: [...new Set(project.declaredNames as string[])],
+    };
+  });
+  const previewEnv: Record<string, string> = {};
+  for (const [name, value] of Object.entries(record.previewEnv)) {
+    if (!PROJECT_ENV_NAME.test(name) || typeof value !== "string") {
+      throw new Error("persisted task project env spec has malformed preview env");
+    }
+    previewEnv[name] = value;
+  }
+  return { schemaVersion: 1, projects, previewEnv };
+}
+
+/** Append a task lifecycle event to the host event log (local `/api/events`). */
+export function recordHostEvent(
+  taskId: string,
+  kind: HostEventKind,
+  detail?: string | null,
+): void {
+  // `recordTaskDown` prunes the earlier lifecycle history before this terminal
+  // event is appended. Do not immediately recreate that owner-facing history
+  // when retention is disabled; the correctness tombstone remains in
+  // `uai_host_tasks` either way.
+  if (kind === "task.ended" && !retainsTerminalHistory()) return;
+  getDb()
+    .insert(schema.hostEvents)
+    .values({ id: newId(), taskId, kind, detail: detail ?? null })
+    .run();
+}
+
+function retainsTerminalHistory(db: DbExecutor = getDb()): boolean {
+  return (
+    db
+      .select({
+        retainTerminalHistory: schema.hostSettings.retainTerminalHistory,
+      })
+      .from(schema.hostSettings)
+      .where(eq(schema.hostSettings.id, "host"))
+      .get()?.retainTerminalHistory ?? true
+  );
+}
+
+/**
+ * Apply the owner-facing terminal-history policy without deleting the durable
+ * lifecycle tombstone used by idempotence, maintenance admission, and orphan
+ * GC. Active/stopped/error rows and their history are deliberately untouched.
+ *
+ * Returns whether terminal history remains enabled. The optional DB keeps the
+ * operation testable and lets the config manager apply a newly-disabled policy
+ * to the same host database immediately.
+ */
+export function applyTerminalHistoryRetention(db: Db = getDb()): boolean {
+  let retained = true;
+  db.transaction((tx) => {
+    retained = applyTerminalHistoryRetentionInTransaction(tx);
+  });
+  return retained;
+}
+
+/** Same policy, for callers that already own the crash-consistency boundary. */
+export function applyTerminalHistoryRetentionInTransaction(
+  db: DbExecutor,
+): boolean {
+  if (retainsTerminalHistory(db)) return true;
+
+  const terminalTasks = db
+    .select({ taskId: schema.hostTasks.taskId })
+    .from(schema.hostTasks)
+    .where(inArray(schema.hostTasks.statusMirror, [...TERMINAL_STATUSES]))
+    .all();
+
+  for (const { taskId } of terminalTasks) {
+    scrubTerminalTaskHistory(db, taskId);
+  }
+
+  return false;
+}
+
+/**
+ * Apply disabled retention to the task that is transitioning terminal.
+ *
+ * The full sweep above is reserved for boot reconciliation and the one-time
+ * config transition. Re-scanning every permanent tombstone on each task-down
+ * would make teardown cost grow with all historical tasks.
+ */
+export function applyTaskTerminalHistoryRetentionInTransaction(
+  db: DbExecutor,
+  taskId: string,
+): boolean {
+  if (retainsTerminalHistory(db)) return true;
+  const status = db
+    .select({ statusMirror: schema.hostTasks.statusMirror })
+    .from(schema.hostTasks)
+    .where(eq(schema.hostTasks.taskId, taskId))
+    .get()?.statusMirror;
+  if (status && isTerminal(status)) scrubTerminalTaskHistory(db, taskId);
+  return false;
+}
+
+function scrubTerminalTaskHistory(db: DbExecutor, taskId: string): void {
+  db.delete(schema.hostAgentSessions)
+    .where(eq(schema.hostAgentSessions.taskId, taskId))
+    .run();
+  db.delete(schema.hostEvents)
+    .where(eq(schema.hostEvents.taskId, taskId))
+    .run();
+  db.update(schema.hostTasks)
+    .set({
+      ownerUserId: null,
+      ownerEmail: null,
+      ownerName: null,
+      projectSlugs: "[]",
+      startedAt: null,
+    })
+    .where(eq(schema.hostTasks.taskId, taskId))
+    .run();
+}