@runuai/host 0.9.150 → 0.9.152

package/lib/runtime-state.ts

@@ -46,14 +46,30 @@ export function activeLoaderHostTasks(): HostTask[] {
     .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): void {
+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")}`,
   );
-  getDb()
+  db
     .delete(schema.hostTasks)
     .where(eq(schema.hostTasks.taskId, taskId))
     .run();
@@ -62,9 +78,10 @@ export function deleteHostTask(taskId: string): void {
 /** 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): void {
+export function purgeHostTaskState(taskId: string, db: Db = getDb()): void {
   console.warn(`[runtime-state] purging all host state for task ${taskId}`);
-  getDb().transaction((tx) => {
+  db.transaction((tx) => {
+    closeCurrentTaskRunAssignmentIn(tx, taskId);
     tx.delete(schema.hostAgentSessions)
       .where(eq(schema.hostAgentSessions.taskId, taskId))
       .run();
@@ -172,8 +189,9 @@ export function recordTaskUpResult(
   result: TaskUpResult,
   environment: TaskEnvironmentLocator,
   envMode: ProjectEnvMode,
+  db: Db = getDb(),
 ): void {
-  upsertHostTask(taskId, {
+  upsertHostTaskIn(db, taskId, {
     codeServerPort: result.codeServerPort ?? null,
     previewPorts: JSON.stringify(result.previewPorts ?? []),
     composeProject: result.composeProject,
@@ -188,15 +206,409 @@ export function recordTaskUpResult(
   });
 }
 
-export function recordTaskStarting(taskId: string): void {
-  upsertHostTask(taskId, {
-    statusMirror: "starting",
-    lockedAt: Date.now(),
-    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`. */
@@ -212,9 +624,13 @@ export function recordTaskEnvironmentPrepared(
   });
 }
 
-export function recordTaskDown(taskId: string, status: string | undefined): void {
-  const db = getDb();
+export function recordTaskDown(
+  taskId: string,
+  status: string | undefined,
+  db: Db = getDb(),
+): void {
   db.transaction((tx) => {
+    closeCurrentTaskRunAssignmentIn(tx, taskId);
     upsertHostTaskIn(tx, taskId, {
       codeServerPort: null,
       previewPorts: "[]",