pi-webdesk 0.1.0

package/dist/apps/daemon/src/task-runtime.js

@@ -0,0 +1,1124 @@
+// apps/daemon/src/task-runtime.ts
+import { randomUUID } from "node:crypto";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import {
+  isPiBridgeError
+} from "../../../packages/pi-bridge/src/index.js";
+import {
+  PROTOCOL_VERSION,
+  createDaemonEventFactory,
+  taskRuntimeSnapshotSchema,
+  taskRuntimeStatusSchema,
+  taskSessionTreeSchema
+} from "../../../packages/protocol/src/index.js";
+import { buildSessionTree, buildTranscript } from "./session-projection.js";
+var TaskRuntimeOperationError = class extends Error {
+  name = "TaskRuntimeOperationError";
+  code;
+  status;
+  constructor(code, message, status, options) {
+    super(message, options);
+    this.code = code;
+    this.status = status;
+  }
+};
+var DETAIL_LIMIT = 1e3;
+function clip(text) {
+  return text.length > DETAIL_LIMIT ? `${text.slice(0, DETAIL_LIMIT - 1)}\u2026` : text;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var MAX_APPROVAL_TIMEOUT_MS = 10 * 6e4;
+var MAX_APPROVAL_TIMEOUT_MARGIN_MS = 5e3;
+function createTaskRuntimeCoordinator(options) {
+  const now = options.now ?? Date.now;
+  const entries = /* @__PURE__ */ new Map();
+  const startsInFlight = /* @__PURE__ */ new Map();
+  const runtimeCleanups = /* @__PURE__ */ new Map();
+  const uncertainRuntimeCleanups = /* @__PURE__ */ new Set();
+  const activeRuntimeRequests = /* @__PURE__ */ new Map();
+  const exclusiveRuntimeRequests = /* @__PURE__ */ new Set();
+  const archiveStops = /* @__PURE__ */ new Set();
+  const lastStatuses = /* @__PURE__ */ new Map();
+  let disposed = false;
+  function statusOf(entry) {
+    return taskRuntimeStatusSchema.parse({
+      protocol: PROTOCOL_VERSION,
+      type: "task-runtime",
+      taskId: entry.taskId,
+      runtimeGeneration: entry.generation,
+      lastSequence: entry.lastSequence,
+      state: entry.state,
+      working: entry.working,
+      approval: entry.pendingApproval?.approval ?? null,
+      model: entry.model,
+      ...entry.detail === null ? {} : { detail: clip(entry.detail) }
+    });
+  }
+  function publishStatus(entry) {
+    const event = entry.emit("runtime-status", {
+      state: entry.state,
+      model: entry.model,
+      ...entry.detail === null ? {} : { detail: clip(entry.detail) }
+    });
+    lastStatuses.set(entry.taskId, statusOf(entry));
+    options.publish(event);
+  }
+  function publishApprovalResolved(entry, pending, resolution) {
+    const event = entry.emit("approval-resolved", {
+      approvalId: pending.approval.approvalId,
+      resolution
+    });
+    lastStatuses.set(entry.taskId, statusOf(entry));
+    options.publish(event);
+  }
+  function detachPendingApproval(entry) {
+    const pending = entry.pendingApproval;
+    if (pending === null) return null;
+    entry.pendingApproval = null;
+    if (pending.timer !== null) clearTimeout(pending.timer);
+    pending.timer = null;
+    return pending;
+  }
+  function expirePendingApproval(entry, pending) {
+    if (entry.removed || entry.pendingApproval !== pending) return;
+    detachPendingApproval(entry);
+    try {
+      entry.runtime.respondToDialog({
+        requestId: pending.requestId,
+        kind: "confirm",
+        confirmed: false
+      });
+    } catch (error) {
+      options.publish(
+        entry.emit("log", {
+          level: "error",
+          message: `Failed to deliver approval timeout ${pending.approval.approvalId}: ${errorMessage(error)}`
+        })
+      );
+    }
+    publishApprovalResolved(entry, pending, "timeout");
+  }
+  function supersedePendingApproval(entry, respond) {
+    const pending = detachPendingApproval(entry);
+    if (pending === null) return;
+    if (respond) {
+      try {
+        entry.runtime.respondToDialog({
+          requestId: pending.requestId,
+          kind: "confirm",
+          confirmed: false
+        });
+      } catch (error) {
+        options.publish(
+          entry.emit("log", {
+            level: "error",
+            message: `Failed to deny superseded approval ${pending.approval.approvalId}: ${errorMessage(error)}`
+          })
+        );
+      }
+    }
+    publishApprovalResolved(entry, pending, "superseded");
+  }
+  function removeEntry(entry, respondToApproval = true) {
+    supersedePendingApproval(entry, respondToApproval);
+    entry.removed = true;
+    entry.unsubscribe();
+    if (entries.get(entry.taskId) === entry) {
+      entries.delete(entry.taskId);
+    }
+  }
+  function trackRuntimeCleanup(entry) {
+    const existing = runtimeCleanups.get(entry);
+    if (existing !== void 0) return existing;
+    const cleanup = (async () => {
+      try {
+        await entry.runtime.dispose();
+      } catch (error) {
+        options.publish(
+          entry.emit("log", {
+            level: "error",
+            message: clip(
+              `Pi runtime cleanup failed; durable recovery ownership was retained: ${errorMessage(error)}`
+            )
+          })
+        );
+        return false;
+      }
+      if (entry.processRecording !== null) {
+        try {
+          await entry.processRecording;
+        } catch (error) {
+          options.publish(
+            entry.emit("log", {
+              level: "error",
+              message: clip(
+                `Pi runtime ownership recording did not settle cleanly; the lease was retained: ${errorMessage(error)}`
+              )
+            })
+          );
+          return false;
+        }
+      }
+      if (entry.processPid !== null && options.clearRuntimeProcess !== void 0) {
+        try {
+          await options.clearRuntimeProcess(entry.taskId, entry.generation, entry.processPid);
+        } catch (error) {
+          options.publish(
+            entry.emit("log", {
+              level: "error",
+              message: clip(
+                `Pi stopped, but its durable recovery lease could not be cleared: ${errorMessage(error)}`
+              )
+            })
+          );
+          return false;
+        }
+      }
+      return true;
+    })();
+    runtimeCleanups.set(entry, cleanup);
+    void cleanup.then((clean) => {
+      if (!clean) uncertainRuntimeCleanups.add(entry);
+      if (runtimeCleanups.get(entry) === cleanup) {
+        runtimeCleanups.delete(entry);
+      }
+    });
+    return cleanup;
+  }
+  async function waitForTaskCleanups(taskId) {
+    const results = await Promise.all(
+      [...runtimeCleanups].filter(([entry]) => entry.taskId === taskId).map(([, cleanup]) => cleanup)
+    );
+    return results.every(Boolean) && ![...uncertainRuntimeCleanups].some((entry) => entry.taskId === taskId);
+  }
+  function publishCleanupUncertain(taskId, preferred) {
+    const entry = preferred ?? [...uncertainRuntimeCleanups].find((candidate) => candidate.taskId === taskId);
+    if (entry === void 0) return;
+    entry.state = "failed";
+    entry.working = false;
+    entry.detail = "Pi runtime cleanup could not be proven. Restart Webdesk to run durable process recovery before starting or archiving this task.";
+    publishStatus(entry);
+  }
+  function requireCleanupProven(taskId, clean, entry) {
+    if (!clean) {
+      publishCleanupUncertain(taskId, entry);
+      throw new TaskRuntimeOperationError(
+        "runtime-recovery-required",
+        "A previous Pi runtime cleanup could not be proven. Restart Webdesk to run durable process recovery before starting this task again.",
+        409
+      );
+    }
+  }
+  function assertTaskNotArchiving(taskId) {
+    if (options.isTaskArchiving?.(taskId) === true || archiveStops.has(taskId)) {
+      throw new TaskRuntimeOperationError(
+        "runtime-busy",
+        "This task is being archived or restored. Wait for that operation to finish.",
+        409
+      );
+    }
+  }
+  async function trackRuntimeRequest(taskId, operation, exclusive = true) {
+    assertTaskNotArchiving(taskId);
+    if (exclusive && activeRuntimeRequests.has(taskId)) {
+      throw new TaskRuntimeOperationError(
+        "runtime-busy",
+        "Another Pi runtime request is already in progress for this task.",
+        409
+      );
+    }
+    if (exclusive) exclusiveRuntimeRequests.add(taskId);
+    activeRuntimeRequests.set(taskId, (activeRuntimeRequests.get(taskId) ?? 0) + 1);
+    try {
+      return await operation();
+    } finally {
+      if (exclusive) exclusiveRuntimeRequests.delete(taskId);
+      const remaining = (activeRuntimeRequests.get(taskId) ?? 1) - 1;
+      if (remaining === 0) activeRuntimeRequests.delete(taskId);
+      else activeRuntimeRequests.set(taskId, remaining);
+    }
+  }
+  function cleanUpFailedRuntime(entry) {
+    if (entry.removed) return;
+    removeEntry(entry);
+    void trackRuntimeCleanup(entry);
+  }
+  function handleDialogRequest(entry, request) {
+    if (request.kind === "approval") {
+      if (entry.pendingApproval !== null) {
+        try {
+          entry.runtime.respondToDialog({
+            requestId: request.requestId,
+            kind: "confirm",
+            confirmed: false
+          });
+        } catch {
+        }
+        options.publish(
+          entry.emit("log", {
+            level: "error",
+            message: `Refused overlapping ${request.toolName} approval for tool call ${request.toolCallId}; only one decision may be pending per task runtime.`
+          })
+        );
+        return;
+      }
+      const receivedAtMs = now();
+      const requestedAtMs = Math.min(request.requestedAtMs, receivedAtMs);
+      const upstreamTimeoutMs = Math.min(request.timeoutMs, MAX_APPROVAL_TIMEOUT_MS);
+      const timeoutMarginMs = Math.min(
+        MAX_APPROVAL_TIMEOUT_MARGIN_MS,
+        Math.max(1, Math.floor(upstreamTimeoutMs * 0.05))
+      );
+      const expiresAtMs = requestedAtMs + Math.max(1, upstreamTimeoutMs - timeoutMarginMs);
+      const timeoutMs = expiresAtMs - receivedAtMs;
+      if (timeoutMs <= 0) {
+        try {
+          entry.runtime.respondToDialog({
+            requestId: request.requestId,
+            kind: "confirm",
+            confirmed: false
+          });
+        } catch {
+        }
+        options.publish(
+          entry.emit("log", {
+            level: "warning",
+            message: `Refused expired ${request.toolName} approval for tool call ${request.toolCallId}; the action remains blocked.`
+          })
+        );
+        return;
+      }
+      const pending = {
+        approval: {
+          approvalId: randomUUID(),
+          toolCallId: request.toolCallId,
+          toolName: request.toolName,
+          summary: request.summary,
+          requestedAtMs,
+          expiresAtMs
+        },
+        requestId: request.requestId,
+        timer: null
+      };
+      entry.pendingApproval = pending;
+      options.publish(entry.emit("approval-requested", pending.approval));
+      pending.timer = setTimeout(() => {
+        expirePendingApproval(entry, pending);
+      }, timeoutMs);
+      pending.timer.unref?.();
+      return;
+    }
+    try {
+      entry.runtime.respondToDialog({
+        requestId: request.requestId,
+        kind: "cancel"
+      });
+      options.publish(
+        entry.emit("log", {
+          level: "warning",
+          message: `Cancelled unsupported Pi ${request.kind} dialog ("${request.title}"): only versioned Webdesk policy approvals may reach the browser.`
+        })
+      );
+    } catch (error) {
+      options.publish(
+        entry.emit("log", {
+          level: "error",
+          message: `Failed to cancel Pi dialog ${request.requestId}: ${errorMessage(error)}`
+        })
+      );
+    }
+  }
+  function handleRuntimeEvent(entry, event) {
+    if (entry.removed) return;
+    switch (event.kind) {
+      case "lifecycle":
+        if (event.state === "failed" && entry.state === "ready" && !entry.removed) {
+          entry.state = "failed";
+          entry.working = false;
+          entry.detail = "Pi reported a fatal runtime failure.";
+          publishStatus(entry);
+          queueMicrotask(() => cleanUpFailedRuntime(entry));
+        }
+        return;
+      case "assistant-delta":
+        options.publish(entry.emit("assistant-delta", { text: event.text }));
+        return;
+      case "tool-activity":
+        options.publish(entry.emit("tool-activity", event.tool));
+        return;
+      case "agent-activity":
+        entry.activityRevision++;
+        if (event.phase === "agent-start" || event.phase === "turn-start") {
+          entry.working = true;
+        } else if (event.phase === "agent-end" || event.phase === "agent-settled") {
+          entry.working = false;
+        }
+        options.publish(entry.emit("agent-activity", { phase: event.phase }));
+        return;
+      case "notification":
+        options.publish(entry.emit("log", { level: event.level, message: event.message }));
+        return;
+      case "extension-error":
+        options.publish(
+          entry.emit("log", {
+            level: "error",
+            message: `Pi extension error: ${event.message}`
+          })
+        );
+        return;
+      case "protocol-issue":
+        options.publish(
+          entry.emit("log", {
+            level: event.fatal ? "error" : "warning",
+            message: `Pi protocol issue: ${event.message}`
+          })
+        );
+        if (event.fatal && entry.state === "failed") {
+          entry.detail = `Pi protocol failure: ${event.message}`;
+          publishStatus(entry);
+          cleanUpFailedRuntime(entry);
+        }
+        return;
+      case "policy-status":
+        return;
+      case "dialog-requested":
+        handleDialogRequest(entry, event.request);
+        return;
+      case "exited": {
+        const interrupted = entry.working || entry.pendingApproval !== null;
+        entry.working = false;
+        entry.detail = `Pi exited (code ${event.code}, signal ${event.signal ?? "null"})`;
+        if (entry.state === "starting") {
+          entry.startupExit = entry.detail;
+          return;
+        }
+        if (entry.state !== "failed") entry.state = interrupted ? "failed" : "exited";
+        publishStatus(entry);
+        removeEntry(entry, false);
+        void trackRuntimeCleanup(entry);
+        return;
+      }
+    }
+  }
+  async function verifyRuntimeWorktree(task) {
+    try {
+      if (options.validateWorktree !== void 0) return await options.validateWorktree(task);
+      const worktree = await stat(task.worktreePath);
+      if (!worktree.isDirectory()) throw new Error("not a directory");
+      return task.worktreePath;
+    } catch (error) {
+      throw new TaskRuntimeOperationError(
+        "task-not-ready",
+        `The task worktree is unavailable at ${task.worktreePath}. Recover the worktree before starting Pi.`,
+        409,
+        { cause: error }
+      );
+    }
+  }
+  async function startRuntime(taskId) {
+    const task = await options.getTask(taskId);
+    if (disposed) {
+      throw new TaskRuntimeOperationError(
+        "runtime-unavailable",
+        "The daemon is shutting down.",
+        503
+      );
+    }
+    if (task === null) {
+      throw new TaskRuntimeOperationError(
+        "task-not-found",
+        "The selected task no longer exists.",
+        404
+      );
+    }
+    if (task.status !== "ready") {
+      throw new TaskRuntimeOperationError(
+        "task-not-ready",
+        `Only a ready task can start a runtime; this task is ${task.status}.`,
+        409
+      );
+    }
+    let verifiedWorktreePath = await verifyRuntimeWorktree(task);
+    if (disposed) {
+      throw new TaskRuntimeOperationError(
+        "runtime-unavailable",
+        "The daemon is shutting down.",
+        503
+      );
+    }
+    if (options.reconcileRuntimeProcess !== void 0) {
+      try {
+        await options.reconcileRuntimeProcess(taskId);
+      } catch (error) {
+        throw new TaskRuntimeOperationError(
+          "runtime-recovery-required",
+          `Webdesk could not safely reconcile the previous Pi runtime: ${errorMessage(error)} Stop any remaining task processes, then choose Start Pi to retry.`,
+          409,
+          { cause: error }
+        );
+      }
+    }
+    let generation;
+    try {
+      generation = await options.claimRuntimeGeneration(taskId);
+    } catch (error) {
+      throw new TaskRuntimeOperationError(
+        "runtime-unavailable",
+        `Webdesk could not reserve a runtime generation: ${errorMessage(error)}`,
+        503,
+        { cause: error }
+      );
+    }
+    if (disposed) {
+      throw new TaskRuntimeOperationError(
+        "runtime-unavailable",
+        "The daemon is shutting down.",
+        503
+      );
+    }
+    verifiedWorktreePath = await verifyRuntimeWorktree(task);
+    if (disposed) {
+      throw new TaskRuntimeOperationError(
+        "runtime-unavailable",
+        "The daemon is shutting down.",
+        503
+      );
+    }
+    let runtime;
+    try {
+      runtime = options.createRuntime({
+        taskId,
+        worktreePath: verifiedWorktreePath,
+        sessionFile: task.piSessionFile ?? null
+      });
+    } catch (error) {
+      throw new TaskRuntimeOperationError(
+        "runtime-start-failed",
+        `The Pi runtime could not be created: ${errorMessage(error)}`,
+        502,
+        { cause: error }
+      );
+    }
+    const rawEmit = createDaemonEventFactory({
+      taskId,
+      runtimeGeneration: generation,
+      ...options.now === void 0 ? {} : { now: options.now }
+    });
+    let entry;
+    entry = {
+      taskId,
+      generation,
+      runtime,
+      state: "starting",
+      working: false,
+      activityRevision: 0,
+      startupExit: null,
+      detail: null,
+      model: null,
+      lastSequence: null,
+      pendingApproval: null,
+      processPid: null,
+      processRecording: null,
+      removed: false,
+      unsubscribe: () => {
+      },
+      emit(type, payload) {
+        const event = rawEmit(type, payload);
+        entry.lastSequence = event.sequence;
+        return event;
+      }
+    };
+    const competingEntry = entries.get(taskId);
+    if (competingEntry !== void 0 && !competingEntry.removed) {
+      await runtime.dispose().catch(() => void 0);
+      throw new TaskRuntimeOperationError(
+        "runtime-busy",
+        "Another Pi runtime became active while this task was starting.",
+        409
+      );
+    }
+    entry.unsubscribe = runtime.subscribe((event) => handleRuntimeEvent(entry, event));
+    entries.set(taskId, entry);
+    publishStatus(entry);
+    try {
+      const handshake = await runtime.start({
+        onProcessStarted: async (pid) => {
+          entry.processPid = pid;
+          const recording = options.recordRuntimeProcess?.(taskId, generation, pid) ?? Promise.resolve();
+          entry.processRecording = recording;
+          await recording;
+        }
+      });
+      assertRuntimeInitializing(entry);
+      const piState = await runtime.getState();
+      assertRuntimeInitializing(entry);
+      if (piState.sessionFile === null || !path.isAbsolute(piState.sessionFile)) {
+        throw new Error("Pi did not report an absolute persistent session file for this task.");
+      }
+      const sessionFile = path.normalize(piState.sessionFile);
+      if (task.piSessionFile !== void 0 && path.normalize(task.piSessionFile) !== sessionFile) {
+        throw new Error(
+          "Pi resumed a different session file than the one associated with this task."
+        );
+      }
+      if (task.piSessionFile === void 0) {
+        await options.recordTaskSession(taskId, sessionFile);
+        assertRuntimeInitializing(entry);
+      }
+      assertRuntimeInitializing(entry);
+      entry.model = normalizeModel(piState.model);
+      const authenticated = entry.model === null || options.isProviderAuthenticated === void 0 ? true : await options.isProviderAuthenticated(entry.model.provider);
+      assertRuntimeInitializing(entry);
+      entry.state = authenticated ? "ready" : "needs_auth";
+      entry.detail = authenticated ? `pita-policy v${handshake.version}, ${handshake.mode} mode` : `Sign in to ${entry.model?.provider ?? "the selected Pi provider"} before sending a prompt.`;
+      publishStatus(entry);
+      return statusOf(entry);
+    } catch (error) {
+      const message = errorMessage(error);
+      const removedBeforeFailure = entry.removed;
+      if (!entry.removed) {
+        entry.state = "failed";
+        entry.detail = message;
+        publishStatus(entry);
+        removeEntry(entry);
+      }
+      if (!removedBeforeFailure) await trackRuntimeCleanup(entry);
+      if (error instanceof TaskRuntimeOperationError) throw error;
+      throw new TaskRuntimeOperationError(
+        "runtime-start-failed",
+        `The Pi runtime did not become ready: ${message}`,
+        502,
+        { cause: error }
+      );
+    }
+  }
+  function assertRuntimeInitializing(entry) {
+    if (disposed || entry.removed) {
+      throw new TaskRuntimeOperationError(
+        "runtime-unavailable",
+        "The daemon is shutting down.",
+        503
+      );
+    }
+    if (entry.startupExit !== null) {
+      throw new Error(entry.startupExit);
+    }
+  }
+  async function inspectRuntime(taskId) {
+    const task = await options.getTask(taskId);
+    requireNotDisposed();
+    if (task === null) {
+      throw new TaskRuntimeOperationError(
+        "task-not-found",
+        "The selected task no longer exists.",
+        404
+      );
+    }
+    if (task.status !== "ready") {
+      throw new TaskRuntimeOperationError(
+        "task-not-ready",
+        `Only a ready task can own a runtime; this task is ${task.status}.`,
+        409
+      );
+    }
+    const entry = entries.get(taskId);
+    if (entry !== void 0) return statusOf(entry);
+    const previous = lastStatuses.get(taskId);
+    if (previous !== void 0) return previous;
+    return taskRuntimeStatusSchema.parse({
+      protocol: PROTOCOL_VERSION,
+      type: "task-runtime",
+      taskId,
+      runtimeGeneration: task.runtimeGeneration ?? 0,
+      lastSequence: null,
+      state: "idle",
+      working: false,
+      model: null
+    });
+  }
+  async function offlineSnapshot(taskId) {
+    const status = await inspectRuntime(taskId);
+    return taskRuntimeSnapshotSchema.parse({
+      protocol: PROTOCOL_VERSION,
+      type: "task-runtime-snapshot",
+      taskId,
+      runtimeGeneration: status.runtimeGeneration,
+      lastSequence: status.lastSequence,
+      state: status.state,
+      working: status.working,
+      approval: status.approval,
+      model: status.model ?? null,
+      ...status.detail === void 0 ? {} : { detail: status.detail },
+      transcript: null,
+      transcriptUnavailableReason: "runtime-not-live",
+      omittedTranscriptItems: 0,
+      sessionTree: null,
+      inFlightGap: status.working
+    });
+  }
+  async function captureSnapshot(taskId) {
+    const entry = entries.get(taskId);
+    if (entry === void 0 || entry.removed) return offlineSnapshot(taskId);
+    let piEntries = null;
+    let piTree = null;
+    let unavailableReason;
+    let captureStable = false;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const cursorBefore = entry.lastSequence;
+      try {
+        piEntries = await entry.runtime.getEntries();
+        unavailableReason = void 0;
+      } catch (error) {
+        piEntries = null;
+        unavailableReason = isPiBridgeError(error, "PI_RUNTIME_NOT_READY") ? "runtime-not-live" : "pi-request-failed";
+        break;
+      }
+      try {
+        piTree = await entry.runtime.getTree();
+      } catch {
+        piTree = null;
+      }
+      if (entry.removed) break;
+      if (entry.lastSequence === cursorBefore) {
+        captureStable = true;
+        break;
+      }
+    }
+    if (entry.removed) return offlineSnapshot(taskId);
+    const status = statusOf(entry);
+    const transcript = piEntries === null ? null : buildTranscript(piEntries);
+    return taskRuntimeSnapshotSchema.parse({
+      protocol: PROTOCOL_VERSION,
+      type: "task-runtime-snapshot",
+      taskId,
+      runtimeGeneration: status.runtimeGeneration,
+      lastSequence: status.lastSequence,
+      state: status.state,
+      working: status.working,
+      approval: status.approval,
+      model: status.model ?? null,
+      ...status.detail === void 0 ? {} : { detail: status.detail },
+      transcript: transcript?.items ?? null,
+      ...unavailableReason === void 0 ? {} : { transcriptUnavailableReason: unavailableReason },
+      omittedTranscriptItems: transcript?.omittedItems ?? 0,
+      sessionTree: piTree === null ? null : buildSessionTree(piTree),
+      // A working runtime is streaming non-canonical output. Likewise, if all
+      // bounded attempts observed cursor movement, the transcript and cursor
+      // were not captured atomically even if the turn just settled.
+      inFlightGap: status.working || piEntries !== null && !captureStable
+    });
+  }
+  function requireLiveRuntime(taskId) {
+    const entry = entries.get(taskId);
+    if (entry === void 0 || entry.state !== "ready") {
+      throw new TaskRuntimeOperationError(
+        "runtime-not-ready",
+        "Start the task runtime and wait for it to become ready first.",
+        409
+      );
+    }
+    return entry;
+  }
+  function requireModelRuntime(taskId) {
+    const entry = entries.get(taskId);
+    if (entry === void 0 || entry.state !== "ready" && entry.state !== "needs_auth") {
+      throw new TaskRuntimeOperationError(
+        "runtime-not-ready",
+        "Start the task runtime and wait for Pi setup before selecting a model.",
+        409
+      );
+    }
+    return entry;
+  }
+  function requireNotDisposed() {
+    if (disposed) {
+      throw new TaskRuntimeOperationError(
+        "runtime-unavailable",
+        "The daemon is shutting down.",
+        503
+      );
+    }
+  }
+  return {
+    async ensure(taskId) {
+      requireNotDisposed();
+      assertTaskNotArchiving(taskId);
+      const inFlight = startsInFlight.get(taskId);
+      if (inFlight !== void 0) return inFlight;
+      const entry = entries.get(taskId);
+      if (entry !== void 0 && entry.state !== "failed") return statusOf(entry);
+      if (entry?.state === "failed") cleanUpFailedRuntime(entry);
+      const start = waitForTaskCleanups(taskId).then((clean) => {
+        requireCleanupProven(taskId, clean);
+        return startRuntime(taskId);
+      }).finally(() => {
+        startsInFlight.delete(taskId);
+      });
+      startsInFlight.set(taskId, start);
+      return start;
+    },
+    status: inspectRuntime,
+    async snapshot(taskId) {
+      requireNotDisposed();
+      return captureSnapshot(taskId);
+    },
+    async sessionTree(taskId) {
+      requireNotDisposed();
+      const entry = entries.get(taskId);
+      if (entry === void 0 || entry.removed || entry.state !== "ready" && entry.state !== "needs_auth") {
+        throw new TaskRuntimeOperationError(
+          "runtime-not-ready",
+          "Start the task runtime to view its Pi session tree.",
+          409
+        );
+      }
+      try {
+        const tree = await entry.runtime.getTree();
+        return taskSessionTreeSchema.parse({
+          protocol: PROTOCOL_VERSION,
+          type: "task-session-tree",
+          taskId,
+          runtimeGeneration: entry.generation,
+          sessionTree: buildSessionTree(tree)
+        });
+      } catch (error) {
+        throw new TaskRuntimeOperationError(
+          "runtime-request-failed",
+          "Pi could not provide the session tree. Retry after the runtime settles.",
+          502,
+          { cause: error }
+        );
+      }
+    },
+    steer(taskId, message) {
+      return trackRuntimeRequest(taskId, async () => {
+        requireNotDisposed();
+        const entry = requireLiveRuntime(taskId);
+        if (entry.pendingApproval !== null) {
+          throw new TaskRuntimeOperationError(
+            "runtime-busy",
+            "Resolve the pending tool approval before steering Pi.",
+            409
+          );
+        }
+        if (!entry.working) {
+          throw new TaskRuntimeOperationError(
+            "runtime-not-working",
+            "Pi is not working on a turn; send a prompt instead.",
+            409
+          );
+        }
+        try {
+          await entry.runtime.steer(message);
+        } catch (error) {
+          throw new TaskRuntimeOperationError(
+            "runtime-request-failed",
+            `Pi did not accept the steering message: ${errorMessage(error)}`,
+            502,
+            { cause: error }
+          );
+        }
+        return statusOf(entry);
+      });
+    },
+    prompt(taskId, message) {
+      return trackRuntimeRequest(taskId, async () => {
+        requireNotDisposed();
+        if (options.isTaskLifecycleBusy?.(taskId) === true) {
+          throw new TaskRuntimeOperationError(
+            "runtime-busy",
+            "A validation, commit, or merge operation is active for this task. Wait for it to finish before prompting Pi.",
+            409
+          );
+        }
+        const candidate = entries.get(taskId);
+        if (candidate?.state === "needs_auth") {
+          throw new TaskRuntimeOperationError(
+            "runtime-auth-required",
+            `Sign in to ${candidate.model?.provider ?? "the selected Pi provider"}, then restart Pi before resending the prompt.`,
+            409
+          );
+        }
+        const entry = requireLiveRuntime(taskId);
+        if (entry.working) {
+          throw new TaskRuntimeOperationError(
+            "runtime-busy",
+            "Pi is already working. Abort the active turn or wait for it to finish.",
+            409
+          );
+        }
+        const activityBeforePrompt = entry.activityRevision;
+        entry.working = true;
+        try {
+          await entry.runtime.prompt(message);
+        } catch (error) {
+          if (entry.activityRevision === activityBeforePrompt) entry.working = false;
+          if (isAuthRequiredError(error)) {
+            entry.state = "needs_auth";
+            entry.detail = `Sign in to ${entry.model?.provider ?? "the selected Pi provider"}, then restart Pi.`;
+            publishStatus(entry);
+            throw new TaskRuntimeOperationError("runtime-auth-required", entry.detail, 409, {
+              cause: error
+            });
+          }
+          throw new TaskRuntimeOperationError(
+            "runtime-request-failed",
+            `Pi did not accept the prompt: ${errorMessage(error)}`,
+            502,
+            { cause: error }
+          );
+        }
+        return statusOf(entry);
+      });
+    },
+    async restart(taskId) {
+      requireNotDisposed();
+      assertTaskNotArchiving(taskId);
+      if (startsInFlight.has(taskId)) {
+        throw new TaskRuntimeOperationError(
+          "runtime-busy",
+          "Wait for the current Pi startup to finish before restarting it.",
+          409
+        );
+      }
+      if (activeRuntimeRequests.has(taskId)) {
+        throw new TaskRuntimeOperationError(
+          "runtime-busy",
+          "Wait for the active Pi runtime request to finish before restarting it.",
+          409
+        );
+      }
+      const entry = entries.get(taskId);
+      if (entry?.working === true) {
+        throw new TaskRuntimeOperationError(
+          "runtime-busy",
+          "Abort the active Pi turn before restarting the runtime.",
+          409
+        );
+      }
+      const restart = (async () => {
+        let clean;
+        if (entry !== void 0) {
+          removeEntry(entry);
+          clean = await trackRuntimeCleanup(entry);
+        } else {
+          clean = await waitForTaskCleanups(taskId);
+        }
+        requireCleanupProven(taskId, clean, entry);
+        return startRuntime(taskId);
+      })().finally(() => {
+        if (startsInFlight.get(taskId) === restart) {
+          startsInFlight.delete(taskId);
+        }
+      });
+      startsInFlight.set(taskId, restart);
+      return restart;
+    },
+    setModel(taskId, provider, modelId) {
+      return trackRuntimeRequest(taskId, async () => {
+        requireNotDisposed();
+        const entry = requireModelRuntime(taskId);
+        if (entry.working) {
+          throw new TaskRuntimeOperationError(
+            "runtime-busy",
+            "Wait for Pi to finish before changing the model.",
+            409
+          );
+        }
+        try {
+          const selected = await entry.runtime.setModel(provider, modelId);
+          if (selected.provider !== provider || selected.id !== modelId) {
+            throw new Error("Pi selected a different model than requested.");
+          }
+          entry.model = normalizeModel(selected);
+          const authenticated = options.isProviderAuthenticated === void 0 ? true : await options.isProviderAuthenticated(provider);
+          entry.state = authenticated ? "ready" : "needs_auth";
+          entry.detail = authenticated ? `Using ${entry.model?.name ?? modelId} via ${provider}.` : `Sign in to ${provider} before sending a prompt.`;
+          publishStatus(entry);
+          return statusOf(entry);
+        } catch (error) {
+          const authRequired = isAuthRequiredError(error);
+          if (authRequired) {
+            entry.state = "needs_auth";
+            entry.detail = `Sign in to ${provider}, then select the model again.`;
+            publishStatus(entry);
+          }
+          throw new TaskRuntimeOperationError(
+            authRequired ? "runtime-auth-required" : "runtime-request-failed",
+            `Pi could not select ${provider}/${modelId}: ${errorMessage(error)}`,
+            authRequired ? 409 : 502,
+            { cause: error }
+          );
+        }
+      });
+    },
+    async resolveApproval(taskId, approvalId, decision) {
+      requireNotDisposed();
+      assertTaskNotArchiving(taskId);
+      const entry = entries.get(taskId);
+      const pending = entry?.pendingApproval ?? null;
+      if (entry === void 0 || pending === null) {
+        throw new TaskRuntimeOperationError(
+          "approval-not-pending",
+          "This task has no approval waiting for a decision.",
+          409
+        );
+      }
+      if (pending.approval.approvalId !== approvalId) {
+        throw new TaskRuntimeOperationError(
+          "approval-not-pending",
+          "That approval is stale or belongs to a different runtime request.",
+          409
+        );
+      }
+      if (now() >= pending.approval.expiresAtMs) {
+        expirePendingApproval(entry, pending);
+        throw new TaskRuntimeOperationError(
+          "approval-not-pending",
+          "That approval expired; the action remains blocked.",
+          409
+        );
+      }
+      detachPendingApproval(entry);
+      try {
+        entry.runtime.respondToDialog({
+          requestId: pending.requestId,
+          kind: "confirm",
+          confirmed: decision === "approve"
+        });
+      } catch (error) {
+        publishApprovalResolved(entry, pending, "superseded");
+        options.publish(
+          entry.emit("log", {
+            level: "error",
+            message: `Failed to deliver approval decision ${approvalId}: ${errorMessage(error)}`
+          })
+        );
+        throw new TaskRuntimeOperationError(
+          "runtime-request-failed",
+          "Pi could not accept the approval decision; the action remains blocked.",
+          502,
+          { cause: error }
+        );
+      }
+      publishApprovalResolved(entry, pending, decision === "approve" ? "approved" : "denied");
+      return statusOf(entry);
+    },
+    abort(taskId) {
+      return trackRuntimeRequest(taskId, async () => {
+        requireNotDisposed();
+        const entry = requireLiveRuntime(taskId);
+        if (exclusiveRuntimeRequests.has(taskId) && !entry.working && entry.pendingApproval === null) {
+          throw new TaskRuntimeOperationError(
+            "runtime-busy",
+            "Another Pi runtime request is already in progress for this task.",
+            409
+          );
+        }
+        supersedePendingApproval(entry, true);
+        try {
+          await entry.runtime.abort();
+        } catch (error) {
+          throw new TaskRuntimeOperationError(
+            "runtime-request-failed",
+            `Pi did not accept the abort: ${errorMessage(error)}`,
+            502,
+            { cause: error }
+          );
+        }
+        return statusOf(entry);
+      }, false);
+    },
+    isMutating(taskId) {
+      const entry = entries.get(taskId);
+      return startsInFlight.has(taskId) || activeRuntimeRequests.has(taskId) || archiveStops.has(taskId) || entry?.working === true || entry?.pendingApproval != null;
+    },
+    async stopForArchive(taskId) {
+      requireNotDisposed();
+      if (archiveStops.has(taskId)) {
+        throw new TaskRuntimeOperationError(
+          "runtime-busy",
+          "Runtime cleanup is already active for this task.",
+          409
+        );
+      }
+      const entry = entries.get(taskId);
+      if (startsInFlight.has(taskId) || activeRuntimeRequests.has(taskId) || entry?.working === true || entry?.pendingApproval != null) {
+        throw new TaskRuntimeOperationError(
+          "runtime-busy",
+          "Wait for Pi startup, the active turn, or its pending approval to settle before archiving.",
+          409
+        );
+      }
+      archiveStops.add(taskId);
+      try {
+        let clean = await waitForTaskCleanups(taskId);
+        if (entry !== void 0 && !entry.removed) {
+          removeEntry(entry);
+          clean = await trackRuntimeCleanup(entry) && clean;
+        }
+        clean = await waitForTaskCleanups(taskId) && clean;
+        if (options.reconcileRuntimeProcess !== void 0) {
+          try {
+            await options.reconcileRuntimeProcess(taskId);
+          } catch (error) {
+            throw new TaskRuntimeOperationError(
+              "runtime-recovery-required",
+              `Webdesk could not safely reconcile the previous Pi runtime: ${errorMessage(error)}`,
+              409,
+              { cause: error }
+            );
+          }
+        }
+        if (!clean) {
+          publishCleanupUncertain(taskId, entry);
+          throw new TaskRuntimeOperationError(
+            "runtime-recovery-required",
+            "Pi runtime cleanup could not be proven; Webdesk kept its recovery lease and did not archive the task.",
+            409
+          );
+        }
+        lastStatuses.delete(taskId);
+      } finally {
+        archiveStops.delete(taskId);
+      }
+    },
+    async disposeAll() {
+      if (disposed) return;
+      disposed = true;
+      const live = [...entries.values()];
+      entries.clear();
+      await Promise.all([
+        ...runtimeCleanups.values(),
+        ...live.map(async (entry) => {
+          supersedePendingApproval(entry, true);
+          entry.removed = true;
+          entry.unsubscribe();
+          await trackRuntimeCleanup(entry);
+        })
+      ]);
+      runtimeCleanups.clear();
+      uncertainRuntimeCleanups.clear();
+    }
+  };
+}
+function normalizeModel(model) {
+  if (model === null || model.provider === void 0) return null;
+  return {
+    provider: model.provider,
+    id: model.id,
+    name: model.name ?? model.id
+  };
+}
+function isAuthRequiredError(error) {
+  if (!isPiBridgeError(error, "PI_REQUEST_FAILED")) return false;
+  const detail = error.details["error"];
+  return typeof detail === "string" && /(?:no api key found|use \/login|not authenticated|authentication required)/i.test(detail);
+}
+export {
+  TaskRuntimeOperationError,
+  createTaskRuntimeCoordinator
+};