@polderlabs/bizar 6.2.4 → 6.3.0

package/plugins/bizar/src/background.ts

@@ -1,1806 +0,0 @@
-/**
- * background.ts
- *
- * InstanceManager — owns the in-memory map of background instances and
- * orchestrates the per-instance event handlers (v0.4.2 spec §2.2, §4, §5.4, §6.2).
- *
- * Responsibilities:
- *   - `add()` is the single entry point for inserting a new instance. The
- *     cap check and the map insertion happen inside one async mutex, so
- *     concurrent `add()` calls can never exceed the cap (HIGH-10 / HIGH-12 /
- *     HIGH-21 / HIGH-38).
- *   - `update()` patches the in-memory state and persists to disk. The
- *     per-instance mutex from {@link BackgroundStateStore} serializes
- *     concurrent updates to the same instance.
- *   - `kill()` and `collect()` operate on the in-memory state; the HTTP
- *     calls go through {@link HttpClient}.
- *   - `rebuildInMemoryMap()` is called on init (spec §5.4). Any in-flight
- *     `running` or `pending` instance is marked `failed` because the
- *     serve child is new and the cline sessions are gone.
- *   - `shutdownAll()` is called on `dispose` / SIGTERM. Marks all in-memory
- *     instances `failed` with `error: "plugin shutting down"`, aborts
- *     each via `POST /session/{id}/abort` (best-effort, 5s timeout per
- *     call), then waits for the serve child to exit.
- *
- * Per-instance event handler (spec §4.1, §4.3, §6.2):
- *   - For every `EventMessagePartUpdated` of `type: "tool"`, increment
- *     `toolCallCount`. If the count reaches the per-instance cap, abort
- *     the session and mark the instance `failed` with
- *     `error: "Tool-call cap reached (N). Aborted to prevent cost runaway."`.
- *   - If the tool part's error matches the loop-guard regex
- *     `Loop protection: 12 identical calls to (\S+)`, capture the tool
- *     name into `loopGuardTool`, set `error` to the canonical string,
- *     and mark the instance `failed`.
- *   - For every `EventMessagePartUpdated` of `type: "text"` on an
- *     assistant message, refresh `resultPreview` (last 200 chars).
- *   - On `EventSessionIdle`, mark the instance `done`.
- *   - On `EventSessionError`, mark the instance `failed` with the error.
- *
- * v0.3.0 — stall and thinking-loop protection:
- *   - Every event handler updates `lastEventAt` (the "heartbeat"). The
- *     stall checker fires every `STALL_CHECK_INTERVAL_MS`; if a non-terminal
- *     instance has `now - lastEventAt > backgroundStallTimeoutMs`, the
- *     session is aborted and the instance marked `failed`.
- *   - `tool` and `text` parts advance `lastToolOrTextAt`. `thinking`
- *     parts do NOT advance it; that is the loop indicator.
- *   - The thinking-loop checker fires every `STALL_CHECK_INTERVAL_MS`. For
- *     a `running` instance with `now - lastToolOrTextAt >
- *     backgroundThinkingLoopTimeoutMs`:
- *       - If `interventionCount < backgroundMaxInterventions`: send a
- *         research-intervention prompt (fire-and-forget) and increment the
- *         counter.
- *       - Otherwise: abort the session and mark `failed`.
- *   - When a `tool` or `text` part arrives after one or more interventions,
- *     the counter is reset to 0 (sign of progress). The intervention
- *     metadata is cleared so a later status check does not show stale
- *     intervention info.
- *
- * "Track BEFORE HTTP" invariant (spec §2.2 / HIGH-21):
- *   - The instance is added to the map (status `pending`) BEFORE any HTTP
- *     call. If the HTTP call fails, the instance is marked `failed`. The
- *     map is never left in a half-state.
- */
-
-import type {
-  BackgroundState,
-  BackgroundStateStore,
-  Logger,
-  ToolCallEntry,
-} from "./background-state.js";
-import {
-  MAX_TOOL_CALL_HISTORY,
-  MAX_TOOL_ARG_CHARS,
-  TERMINAL_STATUSES,
-} from "./background-state.js";
-import type { HttpClient } from "./http-client.js";
-import type { EventStream, StreamEvent, SessionEventHandler } from "./event-stream.js";
-import type { ServeLifecycle } from "./serve.js";
-import { researchInterventionPrompt } from "./research-prompt.js";
-
-import * as clineRunner from "./cline-runner.js";
-
-// --- v5.5.1 — dashboard HTTP helpers -------------------------------------
-//
-// Background agents run as cline serve SDK sessions managed by the
-// dashboard. The plugin's `pause`/`resume` (and the tool layer's
-// `kill`/`send-message`) therefore talk to the dashboard over HTTP
-// instead of touching the OS or the cline SDK directly.
-//
-// These helpers are intentionally tiny — they only need to do POSTs
-// for `pause`/`resume`. The token + URL resolution matches what
-// `bg-spawn.ts` and `bg-send-message.ts` do.
-
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-function resolveDashboardUrl(): string {
-  const fromEnv = process.env.BIZAR_DASHBOARD_URL;
-  if (fromEnv && fromEnv.trim()) return fromEnv.trim().replace(/\/+$/, "");
-  const port = process.env.BIZAR_DASHBOARD_PORT;
-  if (port && /^\d+$/.test(port)) return `http://127.0.0.1:${port}`;
-  return "http://127.0.0.1:4098";
-}
-
-const DEFAULT_DASHBOARD_AUTH_PATHS = [
-  join(homedir(), ".config", "bizar", "dashboard-secret"),
-  join(homedir(), ".cache", "bizarharness", "dash-auth.json"),
-  join(homedir(), ".cache", "bizar", "dash-auth.json"),
-];
-
-function readDashboardToken(): string {
-  for (const candidate of DEFAULT_DASHBOARD_AUTH_PATHS) {
-    try {
-      if (!existsSync(candidate)) continue;
-      const text = readFileSync(candidate, "utf-8").trim();
-      if (text && text.length >= 16) return text;
-    } catch {
-      /* ignore */
-    }
-  }
-  for (const candidate of DEFAULT_DASHBOARD_AUTH_PATHS) {
-    try {
-      if (!existsSync(candidate)) continue;
-      const parsed = JSON.parse(readFileSync(candidate, "utf-8")) as { password?: unknown };
-      if (typeof parsed.password === "string" && parsed.password.length >= 16) {
-        return parsed.password;
-      }
-    } catch {
-      /* ignore */
-    }
-  }
-  return "";
-}
-
-/**
- * POST to the dashboard with a JSON `{}` body. Used for pause/resume —
- * no payload, just the URL. Returns `{ ok: true }` on 2xx, `{ ok: false,
- * error }` on transport failure or non-2xx (so the caller can surface
- * a structured error without catching exceptions).
- */
-async function postDashboardControl(
-  path: string,
-  logger: Logger,
-): Promise<{ ok: boolean; error?: string }> {
-  const url = `${resolveDashboardUrl()}${path}`;
-  const token = readDashboardToken();
-  const headers: Record<string, string> = {
-    "content-type": "application/json",
-    accept: "application/json",
-  };
-  if (token) headers.authorization = `Bearer ${token}`;
-  const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort(), 5_000);
-  try {
-    const res = await fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({}),
-      signal: ac.signal,
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      logger.warn(`bizar: dashboard ${path} returned ${res.status}: ${text.slice(0, 200)}`);
-      return { ok: false, error: `dashboard_http_${res.status}` };
-    }
-    return { ok: true };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    logger.warn(`bizar: dashboard ${path} failed: ${msg}`);
-    return { ok: false, error: msg };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-// --- Public surface -------------------------------------------------------
-
-/** A snapshot of an instance for the `bizar_status` tool. */
-export interface InstanceView {
-  instanceId: string;
-  agent: string;
-  status: BackgroundState["status"];
-  startedAt: number;
-  completedAt?: number;
-  toolCallCount: number;
-  promptPreview: string;
-  resultPreview?: string;
-  error?: string;
-  parentAgent: string;
-  parentInstanceId?: string;
-  sessionId: string;
-  // v0.3.0 — stall and thinking-loop protection
-  lastEventAt?: number;
-  interventionCount?: number;
-  interventionAt?: number;
-  interventionReason?: string;
-  // v5.x — extended surface for dashboard integration
-  /** Tool call history (cap 100). Each entry has name, args, status, timing. */
-  toolCalls?: ToolCallEntry[];
-  /** Progress percentage (0..100; -1 = indeterminate). */
-  progress?: number;
-  /** Progress message (free-form). */
-  progressMessage?: string;
-  /** PID of the cline run subprocess, if known. */
-  processId?: number;
-  /** Current runner state (one of "starting"|"running"|"done"|"failed"|"killed"). */
-  runnerState?: string;
-  /** Tags from spawn (free-form). */
-  tags?: string[];
-  /** When the instance was paused (epoch ms), if paused. */
-  pausedAt?: number;
-}
-
-/** The return shape of `bizar_collect`. */
-export interface CollectResult {
-  status: BackgroundState["status"];
-  result: string;
-  toolCallCount: number;
-  durationMs: number;
-  error?: string;
-}
-
-/** Filter shape for `list()`. */
-export interface InstanceListFilter {
-  agent?: string;
-  status?: BackgroundState["status"];
-}
-
-/** Shape passed to `add()`. The status is forced to `pending` and the
- *  startedAt is stamped by the manager. */
-export type AddDraft = Omit<BackgroundState, "status" | "startedAt">;
-
-/** Return type of `add()`. `"cap_reached"` is a sentinel for the
- *  overshoot path; the populated state is the success path. */
-export type AddResult = BackgroundState | "cap_reached";
-
-// --- Constants ------------------------------------------------------------
-
-/** Maximum length of `resultPreview` per spec §3.2. */
-const RESULT_PREVIEW_MAX = 200;
-/** Maximum length of `promptPreview` stored in the JSON. */
-const PROMPT_PREVIEW_MAX = 200;
-/** Tool-call cap regex (spec §4.1, NEW-H8 pin). */
-const LOOP_GUARD_RE = /Loop protection: 12 identical calls to (\S+)/;
-
-/**
- * How often the stall + thinking-loop checker fires. 15 seconds is short
- * enough to detect stalls within one tick of the default 3-min stall
- * timeout, and long enough that the per-instance mutex is not constantly
- * contested. Spec §v0.3.0.
- */
-const STALL_CHECK_INTERVAL_MS = 15_000;
-
-// --- Class ---------------------------------------------------------------
-
-/**
- * Manages the in-memory map of background instances. Created once at
- * plugin init; lives for the life of the plugin process.
- */
-export class InstanceManager {
-  private instances = new Map<string, BackgroundState>();
-  private eventUnsubscribers = new Map<string, () => void>();
-  private addLock: Promise<unknown> = Promise.resolve();
-  private stateStore: BackgroundStateStore;
-  private maxConcurrent: number;
-  private toolCallCap: number;
-  private logger: Logger;
-  // v0.8.0 — `serve`, `http`, `stream` are nullable to support the
-  // bg-only mode used when the cline serve child is unavailable
-  // (BIZAR_SERVE_DISABLE=1, startup failure) or when this process IS a
-  // bg-spawned `cline run` subprocess. In bg-only mode, every method
-  // that would otherwise call `this.http.X` or `this.stream.X` is a
-  // no-op; state transitions still happen via the runner's `onExit`
-  // callback (see src/tools/bg-spawn.ts).
-  private serve: ServeLifecycle | null;
-  private http: HttpClient | null;
-  private stream: EventStream | null;
-  private worktree: string;
-  // v0.3.0 — stall and thinking-loop protection
-  private stallTimeoutMs: number;
-  private thinkingLoopTimeoutMs: number;
-  private maxInterventions: number;
-  /** Interval handle for the periodic stall + thinking-loop checker. */
-  private stallCheckerTimer: ReturnType<typeof setInterval> | null = null;
-  /** Guard so tests can disable the interval without monkey-patching. */
-  private stallCheckerDisabled = false;
-
-  constructor(opts: {
-    stateStore: BackgroundStateStore;
-    maxConcurrent: number;
-    toolCallCap: number;
-    logger: Logger;
-    // v0.8.0 — `worktree` is now an explicit param (was previously
-    // derived from `opts.serve.worktree`, which is impossible when
-    // `serve` is null in bg-only mode).
-    worktree: string;
-    serve: ServeLifecycle | null;
-    http: HttpClient | null;
-    stream: EventStream | null;
-    // v0.3.0
-    stallTimeoutMs?: number;
-    thinkingLoopTimeoutMs?: number;
-    maxInterventions?: number;
-  }) {
-    this.stateStore = opts.stateStore;
-    this.maxConcurrent = Math.max(1, Math.floor(opts.maxConcurrent));
-    this.toolCallCap = Math.max(1, Math.floor(opts.toolCallCap));
-    this.logger = opts.logger;
-    this.serve = opts.serve;
-    this.http = opts.http;
-    this.stream = opts.stream;
-    this.worktree = opts.worktree;
-    this.stallTimeoutMs = Math.max(
-      1_000,
-      Math.floor(opts.stallTimeoutMs ?? 180_000),
-    );
-    this.thinkingLoopTimeoutMs = Math.max(
-      1_000,
-      Math.floor(opts.thinkingLoopTimeoutMs ?? 300_000),
-    );
-    this.maxInterventions = Math.max(1, Math.floor(opts.maxInterventions ?? 1));
-    // Schedule the periodic stall + thinking-loop checker ONLY when we
-    // have a working HTTP client. In bg-only mode the runner owns the
-    // subprocess lifecycle, so the checker has nothing to do.
-    if (this.http !== null) {
-      this.stallCheckerTimer = setInterval(
-        () => void this.runStallAndLoopChecks(),
-        STALL_CHECK_INTERVAL_MS,
-      );
-      this.stallCheckerTimer.unref?.();
-    }
-  }
-
-  /** True iff the manager was constructed without an HTTP client (no
-   *  cline serve child reachable). HTTP-dependent operations are
-   *  no-ops in this mode. */
-  get isBgOnly(): boolean {
-    return this.http === null;
-  }
-
-  // --- Getters ------------------------------------------------------------
-
-  get size(): number {
-    return this.instances.size;
-  }
-
-  /** Current stall timeout (ms). Exposed for tests. */
-  get stallTimeoutMsValue(): number {
-    return this.stallTimeoutMs;
-  }
-
-  /** Current thinking-loop timeout (ms). Exposed for tests. */
-  get thinkingLoopTimeoutMsValue(): number {
-    return this.thinkingLoopTimeoutMs;
-  }
-
-  /** Current max interventions. Exposed for tests. */
-  get maxInterventionsValue(): number {
-    return this.maxInterventions;
-  }
-
-  /**
-   * Disable the periodic stall + thinking-loop checker. Used by tests
-   * that want to call `runStallAndLoopChecks()` directly without racing
-   * the interval. Idempotent.
-   */
-  disablePeriodicChecks(): void {
-    this.stallCheckerDisabled = true;
-    if (this.stallCheckerTimer !== null) {
-      clearInterval(this.stallCheckerTimer);
-      this.stallCheckerTimer = null;
-    }
-  }
-
-  /**
-   * Run one iteration of the stall + thinking-loop checker. Public so
-   * tests can invoke it deterministically. Production code drives this
-   * via the `setInterval` registered in the constructor.
-   */
-  async runStallAndLoopChecks(): Promise<void> {
-    if (this.stallCheckerDisabled) return;
-    // v0.8.0 — bg-only mode has no HTTP client, so stall and
-    // intervention are no-ops. The constructor also skips registering
-    // the interval in this mode, but a stray call from a test or future
-    // caller must still be safe.
-    if (this.http === null) return;
-    // Snapshot the instance ids so we do not iterate while the map mutates.
-    const ids: string[] = [];
-    for (const inst of this.instances.values()) {
-      if (TERMINAL_STATUSES.has(inst.status)) continue;
-      ids.push(inst.instanceId);
-    }
-    for (const id of ids) {
-      const inst = this.instances.get(id);
-      if (!inst || TERMINAL_STATUSES.has(inst.status)) continue;
-      const now = Date.now();
-      // `lastEventAt` / `lastToolOrTextAt` are seeded by `add()` and
-      // backfilled in `readState`, so they are guaranteed to be set on
-      // any instance that ever reached this method. We coalesce with
-      // `?? 0` because TS strict mode treats the schema field as
-      // optional — the value is informational in the rare case where
-      // it is missing (an old or corrupt state file).
-      const lastEventAt = inst.lastEventAt ?? 0;
-      const lastToolOrTextAt = inst.lastToolOrTextAt ?? 0;
-      // Stall check fires first; it is the more severe failure.
-      if (now - lastEventAt > this.stallTimeoutMs) {
-        await this._abortAsStalled(inst);
-        continue;
-      }
-      // Thinking-loop check applies to `running` instances only. A
-      // `pending` instance has not yet started generating, so it is not
-      // a candidate for the loop detector.
-      if (inst.status === "running") {
-        const since = now - lastToolOrTextAt;
-        if (since > this.thinkingLoopTimeoutMs) {
-          const currentCount = inst.interventionCount ?? 0;
-          if (currentCount < this.maxInterventions) {
-            await this._sendIntervention(inst, since);
-          } else {
-            await this._abortAsThinkingLoop(inst, since);
-          }
-        }
-      }
-    }
-  }
-
-  // --- Internal dispatch (shared by add() and restart()) ------------------
-
-  /**
-   * Insert a fully-constructed BackgroundState into the in-memory map
-   * and persist to disk asynchronously. Does NOT check the concurrency
-   * cap — the caller handles that.
-   *
-   * This is extracted from `add()` so `restart()` can reuse the same
-   * insert-and-persist path without duplicating the logic.
-   */
-  private dispatchInternal(full: BackgroundState): BackgroundState {
-    this.instances.set(full.instanceId, full);
-    // Persist asynchronously; failure is logged but does not roll back
-    // the in-memory insert (the instance is "tracked" either way).
-    this.stateStore.save(full).catch((err: unknown) => {
-      this.logger.warn(
-        `bizar: failed to persist new instance ${full.instanceId}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    });
-    return full;
-  }
-
-  // --- Atomic add (spec §2.2) ---------------------------------------------
-
-  /**
-   * Add a new instance. The cap check and the map insertion are inside
-   * one async mutex — no half-state on overshoot. Returns `"cap_reached"`
-   * on overshoot; the full `BackgroundState` on success.
-   */
-  async add(draft: AddDraft): Promise<AddResult> {
-    return (await (this.addLock = this.addLock.then(async () => {
-      // Count "live" instances: anything not yet terminal.
-      let live = 0;
-      for (const inst of this.instances.values()) {
-        if (!TERMINAL_STATUSES.has(inst.status)) live += 1;
-      }
-      if (live >= this.maxConcurrent) {
-        this.logger.warn(
-          `bizar: max concurrent instances reached (${this.maxConcurrent}); rejecting add`,
-        );
-        return "cap_reached" as const;
-      }
-      const now = Date.now();
-      const full: BackgroundState = {
-        ...draft,
-        status: "pending",
-        startedAt: now,
-        toolCallCount: draft.toolCallCount ?? 0,
-        // Trim the prompt preview so the JSON stays small.
-        promptPreview: (draft.promptPreview ?? "").slice(0, PROMPT_PREVIEW_MAX),
-        // v0.3.0 — seed the liveness timestamps so the stall and
-        // thinking-loop checkers have a baseline. We seed BOTH from
-        // `startedAt` so a freshly-spawned instance is not immediately
-        // flagged as stalled while the session is still being created
-        // (the first event typically arrives within seconds).
-        lastEventAt: now,
-        lastToolOrTextAt: now,
-        interventionCount: 0,
-      };
-      this.dispatchInternal(full);
-      // BUGFIX (v0.5.1): Do NOT call attachEventHandler() here. The
-      // instance was just added with sessionId="" (filled in later by
-      // POST /session). EventStream.onSessionEvent rejects empty strings,
-      // so attaching here threw and the spawn failed before the HTTP
-      // call could run. Callers must call attachEventHandler() explicitly
-      // after the real sessionId is known. See test in
-      // tests/background.test.ts "add() does not attach event handler
-      // (empty sessionId)".
-      return full;
-    }))) as AddResult;
-  }
-
-  // --- Read access --------------------------------------------------------
-
-  /**
-   * Look up an instance by id. Returns null if not found.
-   */
-  async get(instanceId: string): Promise<BackgroundState | null> {
-    return this.instances.get(instanceId) ?? null;
-  }
-
-  /**
-   * Snapshot of in-memory instances, filtered. Used by `bizar_status`.
-   */
-  async list(filter?: InstanceListFilter): Promise<InstanceView[]> {
-    const out: InstanceView[] = [];
-    for (const inst of this.instances.values()) {
-      if (filter?.agent && inst.agent !== filter.agent) continue;
-      if (filter?.status && inst.status !== filter.status) continue;
-      out.push(toView(inst));
-    }
-    // Sort by startedAt ascending so callers see the oldest first.
-    out.sort((a, b) => a.startedAt - b.startedAt);
-    return out;
-  }
-
-  // --- Update -------------------------------------------------------------
-
-  /**
-   * Patch an instance in-memory and persist. Returns silently if the
-   * instance is not found. Mutations that would set a terminal state
-   * stamp `completedAt` automatically.
-   */
-  async update(instanceId: string, patch: Partial<BackgroundState>): Promise<void> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) return;
-    await this.stateStore.withLock(instanceId, async () => {
-      const current = this.instances.get(instanceId);
-      if (!current) return;
-      Object.assign(current, patch);
-      if (TERMINAL_STATUSES.has(patch.status ?? current.status) && !current.completedAt) {
-        current.completedAt = Date.now();
-      }
-      if (TERMINAL_STATUSES.has(current.status)) {
-        this.detachEventHandler(instanceId);
-      }
-      try {
-        await this.stateStore.saveUnlocked(current);
-      } catch (err: unknown) {
-        this.logger.warn(
-          `bizar: failed to persist update for ${instanceId}: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-      }
-    });
-  }
-
-  // --- Kill ---------------------------------------------------------------
-
-  /**
-   * Abort the cline session and mark the instance `killed`. If the
-   * instance is already in a terminal state, this is a no-op (spec §1.5,
-   * MEDIUM-40).
-   *
-   * v5.5.1 — SDK-backed instances are killed via `DELETE /api/background/:id`
-   * on the dashboard (which calls `sdk.sessions.abort`). Pre-v5.5.1
-   * fallback: bg-only mode marks the instance killed in-memory and lets
-   * the runner notice; full mode (with HTTP client) calls
-   * `http.abortSession` directly. The two paths are now functionally
-   * equivalent — the dashboard IS the SDK client in v5.5.1.
-   */
-  async kill(instanceId: string): Promise<void> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) return;
-    if (TERMINAL_STATUSES.has(inst.status)) {
-      this.logger.debug(
-        `bizar: kill(${instanceId}) is a no-op (status=${inst.status})`,
-      );
-      return;
-    }
-    // v5.5.1 — SDK-backed: ask the dashboard to abort.
-    if (inst.liveSession) {
-      const url = `${resolveDashboardUrl()}/api/background/${encodeURIComponent(instanceId)}`;
-      const token = readDashboardToken();
-      const headers: Record<string, string> = { accept: "application/json" };
-      if (token) headers.authorization = `Bearer ${token}`;
-      const ac = new AbortController();
-      const timer = setTimeout(() => ac.abort(), 5_000);
-      try {
-        await fetch(url, { method: "DELETE", headers, signal: ac.signal });
-      } catch (err) {
-        this.logger.warn(
-          `bizar: kill(${instanceId}) dashboard DELETE failed: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-      } finally {
-        clearTimeout(timer);
-      }
-      await this.update(instanceId, {
-        status: "killed",
-        completedAt: Date.now(),
-      });
-      this.logger.info(
-        `bizar: killed background instance ${instanceId} (sdk-backed, dashboard DELETE)`,
-      );
-      return;
-    }
-    // v0.8.0 — bg-only mode has no HTTP client. The subprocess is
-    // already owned by cline-runner.ts (see src/tools/bg-spawn.ts);
-    // mark the instance killed in-memory and let the runner notice the
-    // status change when the process eventually exits. We do NOT try
-    // to kill the OS process from here — that's the runner's job and
-    // we don't have a clean processId reference in bg-only mode
-    // (the runner does, but it lives in a separate module).
-    if (this.http === null) {
-      this.logger.warn(
-        `bizar: kill(${instanceId}) in bg-only mode: marking killed; subprocess will be reaped by cline-runner.ts on exit`,
-      );
-      await this.update(instanceId, {
-        status: "killed",
-        completedAt: Date.now(),
-      });
-      return;
-    }
-    // Pre-v5.5.1 fallback — direct abort on the legacy serve child.
-    const abort = await this.http.abortSession(inst.sessionId, this.worktree);
-    if (!abort.ok) {
-      this.logger.warn(
-        `bizar: kill(${instanceId}): abort failed: ${abort.error}`,
-      );
-    }
-    await this.update(instanceId, {
-      status: "killed",
-      completedAt: Date.now(),
-    });
-    this.logger.info(`bizar: killed background instance ${instanceId}`);
-  }
-
-  // --- Restart (v0.5.5 — persistent auto-restart) ------------------------
-
-  /**
-   * Re-spawn a failed persistent instance with the same prompt, agent,
-   * and model config. The new instance gets a fresh `instanceId` and is
-   * linked to the original via `parentInstanceId`.
-   *
-   * Returns `{ ok: true, newInstanceId }` on success, or
-   * `{ ok: false, error: "..." }` on failure. Does NOT check the
-   * concurrency cap — the original instance is terminal, so its slot
-   * is already freed.
-   */
-  async restart(instanceId: string): Promise<{
-    ok: boolean;
-    newInstanceId?: string;
-    error?: string;
-  }> {
-    const existing = this.instances.get(instanceId);
-    if (!existing) return { ok: false, error: "instance_not_found" };
-    const totalRestarts = this.getTotalRestartCount(instanceId);
-    if (totalRestarts >= (existing.maxRestarts ?? 3)) {
-      return { ok: false, error: "max_restarts_reached" };
-    }
-
-    const now = Date.now();
-    const newInstanceId = generateInstanceId();
-    const full: BackgroundState = {
-      instanceId: newInstanceId,
-      sessionId: "",
-      agent: existing.agent,
-      model: existing.model,
-      promptPreview: (existing.prompt ?? existing.promptPreview ?? "").slice(0, PROMPT_PREVIEW_MAX),
-      prompt: existing.prompt,
-      parentAgent: existing.parentAgent,
-      parentInstanceId: instanceId,
-      logPath: `${this.worktree}/.cline/log/${newInstanceId}.log`,
-      timeoutMs: existing.timeoutMs,
-      toolCallCount: 0,
-      // v0.5.5 — persist the auto-restart fields
-      persistent: existing.persistent,
-      maxRestarts: existing.maxRestarts,
-      restartCount: (existing.restartCount ?? 0) + 1,
-      status: "pending",
-      startedAt: now,
-      lastEventAt: now,
-      lastToolOrTextAt: now,
-      interventionCount: 0,
-    };
-
-    this.dispatchInternal(full);
-    this.logger.info(
-      `bizar: restarted instance ${instanceId} as ${newInstanceId} (restart #${full.restartCount})`,
-    );
-    return { ok: true, newInstanceId };
-  }
-
-  /**
-   * Walk the parent chain to compute the true restart count for this
-   * instance (Forseti C4). `restartCount` alone only reflects the child's
-   * own counter, so a chain of restarts can exceed `maxRestarts`. This
-   * helper sums the counters across the entire chain (parent + all
-   * descendants) and returns the total.
-   */
-  private getTotalRestartCount(instanceId: string): number {
-    let current = this.instances.get(instanceId);
-    if (!current) return 0;
-    let count = current.restartCount ?? 0;
-    let parentId = current.parentInstanceId;
-    const visited = new Set<string>([instanceId]);
-    while (parentId && !visited.has(parentId)) {
-      visited.add(parentId);
-      const parent = this.instances.get(parentId);
-      if (!parent) break;
-      count += parent.restartCount ?? 0;
-      parentId = parent.parentInstanceId;
-    }
-    return count;
-  }
-
-  // --- Collect ------------------------------------------------------------
-
-  /**
-   * Wait for an instance to reach a terminal status, or until `deadline`
-   * (ms epoch) is reached. Returns `true` on terminal, `false` on
-   * timeout.
-   *
-   * Two implementations:
-   *   - **With HTTP+stream** (full mode): subscribe to the SSE session
-   *     event stream AND poll the in-memory map. SSE gives sub-second
-   *     resolution; the in-memory check covers terminal states we set
-   *     ourselves (tool-call cap, loop guard, intervention abort).
-   *   - **Bg-only mode** (no HTTP, no SSE): poll the in-memory map
-   *     every 500 ms. Terminal transitions come from the runner's
-   *     `onExit` callback (see src/tools/bg-spawn.ts) which updates
-   *     the instance state directly.
-   */
-  private async waitForTerminal(
-    instanceId: string,
-    deadline: number,
-  ): Promise<boolean> {
-    // Already terminal?
-    const initial = this.instances.get(instanceId);
-    if (initial && TERMINAL_STATUSES.has(initial.status)) return true;
-
-    if (this.stream === null || initial === undefined) {
-      // Bg-only path: poll the in-memory map.
-      const POLL_MS = 500;
-      while (Date.now() < deadline) {
-        await new Promise<void>((resolve) => setTimeout(resolve, POLL_MS));
-        const cur = this.instances.get(instanceId);
-        if (!cur) return false;
-        if (TERMINAL_STATUSES.has(cur.status)) return true;
-      }
-      return false;
-    }
-
-    // Full path: subscribe to the session event stream AND observe our
-    // own in-memory state changes for terminal transitions we set
-    // ourselves (tool-cap, loop guard, intervention abort).
-    return await new Promise<boolean>((resolve) => {
-      const remaining = Math.max(0, deadline - Date.now());
-      if (remaining === 0) {
-        resolve(false);
-        return;
-      }
-      const timer = setTimeout(() => {
-        unsubscribe();
-        resolve(false);
-      }, remaining);
-      const unsubscribe = this.stream!.onSessionEvent(
-        initial.sessionId,
-        (ev) => {
-          if (ev.type === "session.idle" || ev.type === "session.error") {
-            clearTimeout(timer);
-            unsubscribe();
-            resolve(true);
-            return;
-          }
-          const cur = this.instances.get(instanceId);
-          if (cur && TERMINAL_STATUSES.has(cur.status)) {
-            clearTimeout(timer);
-            unsubscribe();
-            resolve(true);
-          }
-        },
-      );
-      const cur = this.instances.get(instanceId);
-      if (cur && TERMINAL_STATUSES.has(cur.status)) {
-        clearTimeout(timer);
-        unsubscribe();
-        resolve(true);
-      }
-    });
-  }
-
-  /**
-   * Wait for the instance to reach a terminal state (or until
-   * `timeoutMs` elapses), then build the result string per spec §4.4.
-   *
-   * If the instance is already terminal on entry, we skip the wait and
-   * go straight to result construction.
-   */
-  async collect(instanceId: string, timeoutMs: number): Promise<CollectResult> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) {
-      throw new Error(`collect: instance ${instanceId} not found`);
-    }
-    const startedAt = inst.startedAt;
-    const deadline = Date.now() + Math.max(0, timeoutMs);
-
-    // 1. Wait for terminal state.
-    if (!TERMINAL_STATUSES.has(inst.status)) {
-      const reachedTerminal = await this.waitForTerminal(instanceId, deadline);
-      if (!reachedTerminal) {
-        // Timed out. Return what we have.
-        const final = this.instances.get(instanceId);
-        if (final && !TERMINAL_STATUSES.has(final.status)) {
-          await this.update(instanceId, {
-            status: "timed_out",
-            completedAt: Date.now(),
-          });
-        }
-        const dur = Date.now() - startedAt;
-        const final2 = this.instances.get(instanceId);
-        const out: CollectResult = {
-          status: final2?.status ?? "timed_out",
-          result: final2?.resultPreview ?? "",
-          toolCallCount: final2?.toolCallCount ?? 0,
-          durationMs: dur,
-          error: `collect timed out after ${timeoutMs}ms`,
-        };
-        return out;
-      }
-    }
-
-    // 2. Build the result. Fetch messages from the cline server and
-    //    concatenate the assistant text parts. In bg-only mode there is
-    //    no HTTP client to ask, so we fall back to whatever
-    //    `resultPreview` was captured during the run (often empty
-    //    because there is no SSE stream in bg-only mode — the runner
-    //    writes the raw output to the log file instead).
-    const final = this.instances.get(instanceId);
-    if (!final) {
-      throw new Error(`collect: instance ${instanceId} disappeared`);
-    }
-    const resultText = await this.buildResultText(final);
-    const dur = (final.completedAt ?? Date.now()) - startedAt;
-    const out: CollectResult = {
-      status: final.status,
-      result: resultText,
-      toolCallCount: final.toolCallCount,
-      durationMs: dur,
-    };
-    if (final.error !== undefined) out.error = final.error;
-    return out;
-  }
-
-  // --- Rebuild on init (spec §5.4) ----------------------------------------
-
-  /**
-   * Scan the bg directory, load every instance, and rebuild the in-memory
-   * map. Any `running` or `pending` instance is checked for liveness:
-   *
-   *   - v5.5.1: bg instances no longer have OS subprocesses — they live
-   *     as cline serve SDK sessions on the dashboard. `clineRunner.
-   *     isAlive(pid)` always returns `false`, so the adoption branch is
-   *     effectively dead code; we keep it for the rare case a state file
-   *     from v5.5.0 (with a real pid) survives an upgrade. We mark the
-   *     instance `failed` with reason `"v5.5.1 session reconciliation
-   *     pending"` so the operator knows to look at the dashboard; the
-   *     dashboard's own SSE bridge will reconcile.
-   *   - v5.5.0 and earlier: a still-alive PID re-adopts as before.
-   *
-   * Historical terminal records (done, failed, killed, timed_out, steered)
-   * are preserved as-is.
-   */
-  async rebuildInMemoryMap(): Promise<void> {
-    let all: BackgroundState[];
-    try {
-      all = await this.stateStore.list();
-    } catch (err: unknown) {
-      this.logger.warn(
-        `bizar: rebuildInMemoryMap: list() failed: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-      return;
-    }
-    let rebuilt = 0;
-    let failed = 0;
-    let adopted = 0;
-    for (const inst of all) {
-      this.instances.set(inst.instanceId, inst);
-      rebuilt += 1;
-      if (inst.status === "running" || inst.status === "pending") {
-        // v5.5.1 — prefer the liveSession flag (the SDK-session marker)
-        // when present. If the dashboard still tracks the session, we
-        // re-adopt; otherwise we mark failed with a reconcilable message.
-        if (inst.liveSession) {
-          // SDK-backed: we trust the state file. The dashboard's SSE
-          // bridge will deliver the next event. Mark `running` and
-          // `runnerState: "adopted"` so the operator sees the plugin
-          // has caught up.
-          await this.update(inst.instanceId, {
-            status: "running",
-            completedAt: undefined,
-            runnerState: "adopted",
-          });
-          adopted += 1;
-          this.logger.info(
-            `bizar: re-adopted SDK-backed bg instance ${inst.instanceId}`,
-          );
-          continue;
-        }
-        // Pre-v5.5.1 subprocess fallback (rare; the runner is stubbed).
-        const pid = inst.processId;
-        const alive = typeof pid === "number" && clineRunner.isAlive(pid);
-        if (alive) {
-          await this.update(inst.instanceId, {
-            status: "running",
-            completedAt: undefined,
-            runnerState: "adopted",
-          });
-          adopted += 1;
-          this.logger.info(
-            `bizar: adopted still-alive subprocess for instance ${inst.instanceId} (pid=${pid})`,
-          );
-          continue;
-        }
-        const message = "subprocess died during restart";
-        await this.update(inst.instanceId, {
-          status: "failed",
-          error: message,
-          completedAt: Date.now(),
-        });
-        failed += 1;
-      }
-    }
-    if (rebuilt > 0) {
-      this.logger.info(
-        `bizar: rebuilt in-memory map (${rebuilt} instances, ${adopted} adopted, ${failed} marked failed)`,
-      );
-    }
-  }
-
-  // --- Shutdown (spec §5.3) ----------------------------------------------
-
-  /**
-   * Mark all in-memory instances as failed with `error: "plugin shutting down"`,
-   * abort all running sessions best-effort (5s timeout per call, in
-   * parallel), then return. The serve child termination is the
-   * caller's responsibility.
-   *
-   * Also clears the v0.3.0 stall-checker interval. After `shutdownAll`,
-   * the manager is effectively inert — no more periodic checks will
-   * fire even though the InstanceManager object itself is still alive.
-   */
-  async shutdownAll(): Promise<void> {
-    // v0.3.0 — clear the periodic checker first so it does not race
-    // the in-flight updates below.
-    if (this.stallCheckerTimer !== null) {
-      clearInterval(this.stallCheckerTimer);
-      this.stallCheckerTimer = null;
-    }
-    this.stallCheckerDisabled = true;
-    const live: BackgroundState[] = [];
-    for (const inst of this.instances.values()) {
-      if (!TERMINAL_STATUSES.has(inst.status)) {
-        live.push(inst);
-      }
-    }
-    // Phase 1: mark failed first (spec §5.3 step 1).
-    for (const inst of live) {
-      await this.update(inst.instanceId, {
-        status: "failed",
-        error: "plugin shutting down",
-        completedAt: Date.now(),
-      });
-    }
-    // Phase 2: best-effort aborts in parallel, 5s per call. In bg-only
-    // mode there is no HTTP client to ask — the runner owns the
-    // subprocess lifecycle, so the in-memory status flip is the only
-    // signal we can emit. Skipped cleanly when http is null.
-    if (this.http !== null) {
-      const abortPromises = live.map((inst) =>
-        withTimeout(
-          this.http!.abortSession(inst.sessionId, this.worktree),
-          5_000,
-        ).catch(() => undefined),
-      );
-      await Promise.allSettled(abortPromises);
-    }
-    this.logger.info(`bizar: shutdownAll complete (${live.length} instances aborted)`);
-  }
-
-  // --- v0.3.0 stall and thinking-loop helpers ----------------------------
-
-  /**
-   * Mark an instance `failed` with the canonical stall message and
-   * fire-and-forget the cline abort call. The stall timeout is
-   * intentionally short enough that an abort that fails gracefully
-   * (the serve child is dead, etc.) does not leave the user waiting.
-   */
-  private async _abortAsStalled(inst: BackgroundState): Promise<void> {
-    const lastEventAt = inst.lastEventAt ?? 0;
-    const sinceMs = Date.now() - lastEventAt;
-    this.logger.warn(
-      `bizar: instance ${inst.instanceId} stalled (no event for ${sinceMs}ms); aborting`,
-    );
-    // Fire-and-forget. If the serve child is dead, this returns a
-    // failure result but we still mark the instance failed in-memory.
-    // v0.8.0 — bg-only mode has no HTTP client; the abort is a no-op
-    // there (the runner owns the subprocess).
-    if (this.http !== null) {
-      this.http
-        .abortSession(inst.sessionId, this.worktree)
-        .catch(() => undefined);
-    }
-    await this.update(inst.instanceId, {
-      status: "failed",
-      error: `No activity for ${this.stallTimeoutMs}ms — LLM appears stalled`,
-      completedAt: Date.now(),
-    });
-    // v0.5.5 — persistent auto-restart on stall
-    await this._maybeAutoRestart(inst.instanceId);
-  }
-
-  /**
-   * Send the research-intervention prompt to the running session. The
-   * message interrupts the current generation and starts a new turn
-   * with the prompt as the next user message. This is fire-and-forget:
-   * we do not wait for the prompt to complete, only for the HTTP call
-   * to return.
-   */
-  private async _sendIntervention(
-    inst: BackgroundState,
-    sinceMs: number,
-  ): Promise<void> {
-    const messageID = generateMessageId();
-    const prompt = researchInterventionPrompt(sinceMs);
-    const currentCount = inst.interventionCount ?? 0;
-    this.logger.warn(
-      `bizar: instance ${inst.instanceId} thinking loop (${sinceMs}ms without tool/text); sending intervention #${currentCount + 1}/${this.maxInterventions}`,
-    );
-    try {
-      // v0.8.0 — bg-only mode has no HTTP client; interventions are a
-      // no-op there (the runner doesn't expose a "send a user message
-      // mid-run" hook). Logged as a debug so the operator can see why
-      // no intervention went out.
-      if (this.http === null) {
-        this.logger.debug(
-          `bizar: skipping intervention for ${inst.sessionId} (bg-only mode; no HTTP client)`,
-        );
-      } else {
-        await this.http.sendPrompt(
-          {
-            sessionId: inst.sessionId,
-            messageID,
-            agent: inst.agent,
-            parts: [{ type: "text", text: prompt }],
-          },
-          this.worktree,
-        );
-      }
-    } catch (err: unknown) {
-      // We swallow the error: the periodic checker will try again next
-      // tick. The intervention counter is still incremented below so
-      // we eventually escalate to an abort if the prompt keeps failing.
-      this.logger.warn(
-        `bizar: intervention prompt send failed for ${inst.instanceId}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    }
-    const reason = `thinking loop (${formatDuration(sinceMs)} without tool/text)`;
-    await this.update(inst.instanceId, {
-      interventionCount: currentCount + 1,
-      interventionAt: Date.now(),
-      interventionReason: reason,
-      // Bumping lastEventAt here is intentional: the intervention call
-      // counted as an HTTP-driven activity, so the stall checker does
-      // not fire immediately after.
-      lastEventAt: Date.now(),
-    });
-  }
-
-  /**
-   * Mark an instance `failed` with the canonical thinking-loop message
-   * and fire-and-forget the abort call.
-   */
-  private async _abortAsThinkingLoop(
-    inst: BackgroundState,
-    sinceMs: number,
-  ): Promise<void> {
-    this.logger.warn(
-      `bizar: instance ${inst.instanceId} thinking loop exhausted ${this.maxInterventions} intervention(s) over ${sinceMs}ms; aborting`,
-    );
-    // v0.8.0 — bg-only mode has no HTTP client; the abort is a no-op
-    // there (the runner owns the subprocess).
-    if (this.http !== null) {
-      this.http
-        .abortSession(inst.sessionId, this.worktree)
-        .catch(() => undefined);
-    }
-    await this.update(inst.instanceId, {
-      status: "failed",
-      error: `Thinking loop detected: ${formatDuration(sinceMs)} of thinking without tool calls or output. Spawn a Mimir agent for research.`,
-      completedAt: Date.now(),
-    });
-    // v0.5.5 — persistent auto-restart on thinking-loop exhaustion
-    await this._maybeAutoRestart(inst.instanceId);
-  }
-
-  // --- Internal: per-session event handler -------------------------------
-
-  public attachEventHandler(inst: BackgroundState): () => void {
-    this.detachEventHandler(inst.instanceId);
-    // v0.8.0 — bg-only mode has no EventStream; return a no-op unsubscriber.
-    if (!this.stream) return () => {};
-    const handler: SessionEventHandler = (ev: StreamEvent) => {
-      void this.handleInstanceEvent(inst.instanceId, ev);
-    };
-    const unsubscribe = this.stream.onSessionEvent(inst.sessionId, handler);
-    this.eventUnsubscribers.set(inst.instanceId, unsubscribe);
-    return unsubscribe;
-  }
-
-  private detachEventHandler(instanceId: string): void {
-    const unsubscribe = this.eventUnsubscribers.get(instanceId);
-    if (!unsubscribe) return;
-    try {
-      unsubscribe();
-    } catch {
-      // ignore
-    }
-    this.eventUnsubscribers.delete(instanceId);
-  }
-
-  private async handleInstanceEvent(
-    instanceId: string,
-    ev: StreamEvent,
-  ): Promise<void> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) return;
-    // Already terminal — ignore further events (e.g., after kill, an
-    // EventSessionError may still arrive).
-    if (TERMINAL_STATUSES.has(inst.status)) return;
-
-    // v0.3.0 — every event advances the heartbeat. We do this BEFORE
-    // any further work (or inside the per-instance mutex in update())
-    // so the stall checker sees the freshest timestamp regardless of
-    // how the rest of the handler proceeds.
-    inst.lastEventAt = Date.now();
-
-    if (ev.type === "message.part.updated") {
-      await this.onPartUpdated(instanceId, ev);
-    } else if (ev.type === "session.idle") {
-      await this.update(instanceId, {
-        status: "done",
-        completedAt: Date.now(),
-      });
-    } else if (ev.type === "session.error") {
-      const errMsg = ev.error ?? "session error";
-      await this.update(instanceId, {
-        status: "failed",
-        error: errMsg,
-        completedAt: Date.now(),
-      });
-      // v0.5.5 — persistent auto-restart. If the instance is persistent
-      // and was not explicitly killed, try to restart.
-      if (inst.persistent && inst.status !== "killed") {
-        await this._maybeAutoRestart(instanceId);
-      }
-    }
-  }
-
-  /**
-   * v0.8.0 — Public version of `_maybeAutoRestart`. The cline-runner
-   * (see src/cline-runner.ts) calls this from its onExit callback
-   * when a `bizar_spawn_background` subprocess exits. Without this,
-   * persistent instances would never auto-restart under the new
-   * subprocess-based path (the SSE event handler that previously
-   * triggered auto-restart is no longer wired up because we don't
-   * subscribe to per-session events anymore).
-   */
-  async maybeAutoRestart(instanceId: string): Promise<void> {
-    await this._maybeAutoRestart(instanceId);
-  }
-
-  // --- v5.x — pause / resume / progress / tool-call instrumentation -------
-
-  /**
-   * Pause a running instance. In v5.5.1 (SDK-backed) this delegates to
-   * the dashboard's `POST /api/background/:id/pause`, which performs an
-   * OUTPUT pause (stops forwarding events to the WS bus; the underlying
-   * cline serve session keeps running). For pre-v5.5.1 instances
-   * that still carry a `processId`, fall back to the old SIGSTOP path
-   * via the (now stubbed) runner — best-effort, returns ok:false if the
-   * runner reports the OS no longer supports it.
-   *
-   * On success, the in-memory status flips to `"paused"` and `pausedAt`
-   * is stamped.
-   *
-   * Already-terminal instances return `{ ok: false, error: "already_terminal" }`.
-   * Already-paused instances return `{ ok: true }` (no-op).
-   */
-  async pause(instanceId: string): Promise<{ ok: boolean; error?: string }> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) return { ok: false, error: "instance_not_found" };
-    if (TERMINAL_STATUSES.has(inst.status)) {
-      return { ok: false, error: "already_terminal" };
-    }
-    if (inst.status === "paused") return { ok: true };
-
-    // v5.5.1 — SDK-backed: delegate to the dashboard.
-    if (inst.liveSession) {
-      const res = await postDashboardControl(`/api/background/${encodeURIComponent(instanceId)}/pause`, this.logger);
-      if (!res.ok) {
-        return { ok: false, error: res.error || "pause_failed" };
-      }
-      await this.update(instanceId, {
-        status: "paused",
-        pausedAt: Date.now(),
-      });
-      this.logger.info(`bizar: paused background instance ${instanceId} (sdk-backed)`);
-      return { ok: true };
-    }
-
-    // Pre-v5.5.1 fallback: subprocess SIGSTOP. The runner is a stub now,
-    // but if a state file from v5.5.0 is still around we try the old
-    // path for compatibility.
-    if (inst.processId === undefined) {
-      return { ok: false, error: "no_subprocess" };
-    }
-    const pid = inst.processId;
-    const res = clineRunner.pauseAgent(pid);
-    if (!res.ok) return { ok: false, error: res.error || "pause_failed" };
-    await this.update(instanceId, {
-      status: "paused",
-      pausedAt: Date.now(),
-    });
-    this.logger.info(
-      `bizar: paused background instance ${instanceId} (pid=${pid}, legacy)`,
-    );
-    return { ok: true };
-  }
-
-  /**
-   * Resume a paused instance. In v5.5.1 (SDK-backed) delegates to the
-   * dashboard's `POST /api/background/:id/resume`, which drains the
-   * buffered events back to the WS bus. For pre-v5.5.1 instances with
-   * a `processId`, falls back to the old SIGCONT path via the runner.
-   *
-   * Idempotent: resuming a non-paused instance is a no-op that returns
-   * `{ ok: true }`.
-   */
-  async resume(instanceId: string): Promise<{ ok: boolean; error?: string }> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) return { ok: false, error: "instance_not_found" };
-    if (inst.status !== "paused") return { ok: true };
-
-    // v5.5.1 — SDK-backed: delegate to the dashboard.
-    if (inst.liveSession) {
-      const res = await postDashboardControl(`/api/background/${encodeURIComponent(instanceId)}/resume`, this.logger);
-      if (!res.ok) {
-        return { ok: false, error: res.error || "resume_failed" };
-      }
-      await this.update(instanceId, {
-        status: "running",
-        pausedAt: undefined,
-      });
-      this.logger.info(`bizar: resumed background instance ${instanceId} (sdk-backed)`);
-      return { ok: true };
-    }
-
-    // Pre-v5.5.1 fallback: subprocess SIGCONT.
-    if (inst.processId === undefined) {
-      return { ok: false, error: "no_subprocess" };
-    }
-    const res = clineRunner.resumeAgent(inst.processId);
-    if (!res.ok) return { ok: false, error: res.error || "resume_failed" };
-    await this.update(instanceId, {
-      status: "running",
-      pausedAt: undefined,
-    });
-    this.logger.info(
-      `bizar: resumed background instance ${instanceId} (pid=${inst.processId}, legacy)`,
-    );
-    return { ok: true };
-  }
-
-  /**
-   * Update progress (and optional message) for an instance. Called by the
-   * `bizar_report_progress` tool. Pinned to [0, 100] unless `indeterminate`
-   * is true, in which case we set progress to -1.
-   */
-  async updateProgress(
-    instanceId: string,
-    step: number,
-    total: number,
-    message?: string,
-    indeterminate = false,
-  ): Promise<{ ok: boolean; progress?: number; error?: string }> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) return { ok: false, error: "instance_not_found" };
-    if (TERMINAL_STATUSES.has(inst.status)) {
-      return { ok: false, error: "already_terminal" };
-    }
-    let pct: number;
-    if (indeterminate) {
-      pct = -1;
-    } else {
-      const safeTotal = Math.max(1, Math.floor(total));
-      const safeStep = Math.max(0, Math.floor(step));
-      pct = Math.max(0, Math.min(100, Math.round((safeStep / safeTotal) * 100)));
-    }
-    const patch: Partial<BackgroundState> = {
-      progress: pct,
-      progressAt: Date.now(),
-    };
-    if (message !== undefined) patch.progressMessage = message.slice(0, 500);
-    await this.update(instanceId, patch);
-    return { ok: true, progress: pct };
-  }
-
-  /**
-   * Record a tool-call start. Returns the generated id so callers can
-   * pass it to `completeToolCall()` later. Caps the history at
-   * `MAX_TOOL_CALL_HISTORY` entries.
-   */
-  async recordToolCallStart(
-    instanceId: string,
-    name: string,
-    args: unknown,
-  ): Promise<string> {
-    const id = `tc_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
-    const inst = this.instances.get(instanceId);
-    if (!inst) return id;
-    const entry: ToolCallEntry = {
-      id,
-      name: String(name ?? "").slice(0, 200),
-      args: truncateForToolHistory(args),
-      status: "running",
-      startedAt: Date.now(),
-    };
-    const existing = (inst.toolCalls ?? []).slice(-MAX_TOOL_CALL_HISTORY + 1);
-    const next = [...existing, entry].slice(-MAX_TOOL_CALL_HISTORY);
-    await this.update(instanceId, { toolCalls: next });
-    return id;
-  }
-
-  /**
-   * Mark a tool-call complete. `result` and `error` are both truncated.
-   * A no-op if no matching entry is found (the cap may have rolled it off).
-   */
-  async completeToolCall(
-    instanceId: string,
-    id: string,
-    result?: string,
-    error?: string,
-  ): Promise<void> {
-    const inst = this.instances.get(instanceId);
-    if (!inst || !Array.isArray(inst.toolCalls)) return;
-    const idx = inst.toolCalls.findIndex((t) => t.id === id);
-    if (idx < 0) return;
-    const cur = inst.toolCalls[idx];
-    if (!cur) return;
-    const next = inst.toolCalls.slice();
-    const updated: ToolCallEntry = {
-      ...cur,
-      status: error ? "error" : "ok",
-      endedAt: Date.now(),
-    };
-    if (error !== undefined) {
-      updated.error = String(error).slice(0, MAX_TOOL_ARG_CHARS);
-    } else if (result !== undefined) {
-      updated.result = String(result).slice(0, MAX_TOOL_ARG_CHARS);
-    }
-    next[idx] = updated;
-    await this.update(instanceId, { toolCalls: next });
-  }
-
-  /**
-   * Public accessor used by the cline-runner when it wants to surface
-   * the recorded tool-call list (read-only). Returns a copy.
-   */
-  listToolCalls(instanceId: string): ToolCallEntry[] {
-    const inst = this.instances.get(instanceId);
-    if (!inst || !Array.isArray(inst.toolCalls)) return [];
-    return inst.toolCalls.slice();
-  }
-
-  /**
-   * Public: mark an instance as "adopted" — used by `rebuildInMemoryMap`
-   * when a previously running instance's subprocess is still alive. The
-   * status flips back to "running" and the runner is resumed.
-   */
-  async adoptInstance(instanceId: string): Promise<void> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) return;
-    if (!TERMINAL_STATUSES.has(inst.status)) {
-      // Already alive in our map; nothing to adopt.
-      return;
-    }
-    await this.update(instanceId, {
-      status: "running",
-      completedAt: undefined,
-      runnerState: "adopted",
-    });
-  }
-
-  /** v0.5.5 — Attempt an auto-restart for a persistent failed instance. */
-  private async _maybeAutoRestart(instanceId: string): Promise<void> {
-    const inst = this.instances.get(instanceId);
-    if (!inst || !inst.persistent) return;
-    if (inst.status === "killed") return; // user killed it — do not restart
-    this.logger.info(
-      `bizar: persistent instance ${instanceId} failed; auto-restarting`,
-    );
-    const result = await this.restart(instanceId);
-    if (result.ok) {
-      // Clear any previous restartError on the parent so the operator
-      // sees a clean state.
-      await this.update(instanceId, { restartError: undefined });
-      this.logger.info(
-        `bizar: auto-restart complete: ${instanceId} -> ${result.newInstanceId}`,
-      );
-    } else {
-      // Persist a human-readable error so the operator can see why the
-      // restart was rejected (e.g. max_restarts_reached).
-      await this.update(instanceId, { restartError: result.error || "unknown" });
-      this.logger.warn(
-        `bizar: auto-restart failed for ${instanceId}: ${result.error}`,
-      );
-    }
-  }
-
-  private async onPartUpdated(
-    instanceId: string,
-    ev: Extract<StreamEvent, { type: "message.part.updated" }>,
-  ): Promise<void> {
-    const inst = this.instances.get(instanceId);
-    if (!inst) return;
-    const part = ev.part;
-
-    // v0.3.0 — tool and text parts advance the "progress" timestamp.
-    // `thinking` parts do NOT, because that is the loop indicator.
-    if (part.type === "tool" || part.type === "text") {
-      inst.lastToolOrTextAt = Date.now();
-      // The agent has shown concrete progress after one or more
-      // interventions — reset the intervention counter so the next
-      // thinking loop has a fresh budget. Clear the intervention
-      // metadata so a later status check does not show stale info.
-      if ((inst.interventionCount ?? 0) > 0) {
-        inst.interventionCount = 0;
-        delete inst.interventionAt;
-        delete inst.interventionReason;
-      }
-    }
-
-    // --- Tool-call cap (spec §6.2) ---
-    if (part.type === "tool") {
-      const nextCount = inst.toolCallCount + 1;
-      const patch: Partial<BackgroundState> = { toolCallCount: nextCount };
-      if (nextCount >= this.toolCallCap) {
-        // Abort and mark failed. Use a fire-and-forget abort because we
-        // do not want to block the handler on a network call.
-        // v0.8.0 — bg-only mode has no HTTP client; the abort is a
-        // no-op there (the runner owns the subprocess).
-        if (this.http !== null) {
-          this.http
-            .abortSession(inst.sessionId, this.worktree)
-            .catch(() => undefined);
-        }
-        patch.status = "failed";
-        patch.error = `Tool-call cap reached (${nextCount}). Aborted to prevent cost runaway.`;
-        patch.completedAt = Date.now();
-      }
-      await this.update(instanceId, patch);
-      // v0.5.5 — persistent auto-restart on tool-call cap
-      if (patch.status === "failed") {
-        await this._maybeAutoRestart(instanceId);
-        return;
-      }
-    }
-
-    // --- v5.x — Tool call history recording -----------------------------
-    // The tool part re-fires on every state transition (pending ->
-    // running -> completed). We key the history entry by `partID` so
-    // the same call's "running" and "completed" messages converge to
-    // one row. When a part has no entry yet, we record a fresh "running"
-    // entry; when it already exists, we update status/result/error.
-    if (part.type === "tool") {
-      const toolName = readToolName(part);
-      const existing = Array.isArray(inst.toolCalls)
-        ? inst.toolCalls.find((t) => t.id === ev.partID)
-        : undefined;
-      if (existing === undefined) {
-        // Fresh tool call — record start.
-        const tcId = ev.partID;
-        const entry: ToolCallEntry = {
-          id: tcId,
-          name: toolName,
-          args: readToolArgs(part),
-          status: readToolStatus(part),
-          startedAt: Date.now(),
-        };
-        const merged = [...(inst.toolCalls ?? []), entry].slice(
-          -MAX_TOOL_CALL_HISTORY,
-        );
-        await this.update(instanceId, { toolCalls: merged });
-      } else {
-        // Existing entry — update status/result/error.
-        const next = (inst.toolCalls ?? []).slice();
-        const idx = next.findIndex((t) => t.id === ev.partID);
-        if (idx >= 0) {
-          const cur = next[idx];
-          if (cur) {
-            const status = readToolStatus(part);
-            const updated: ToolCallEntry = {
-              ...cur,
-              status,
-              endedAt: status === "ok" || status === "error" ? Date.now() : cur.endedAt,
-            };
-            const errText = readToolError(part);
-            if (errText) updated.error = errText.slice(0, MAX_TOOL_ARG_CHARS);
-            // If the part carries a result string in `state.output` or
-            // a result-shaped field, surface it. The cline schema
-            // is loose here — we accept either `state.output` or raw
-            // `output`.
-            const output = readToolOutput(part);
-            if (output) updated.result = output.slice(0, MAX_TOOL_ARG_CHARS);
-            next[idx] = updated;
-            await this.update(instanceId, { toolCalls: next });
-          }
-        }
-      }
-    }
-
-    // --- Loop-guard threshold-12 detection (spec §4.1) ---
-    if (part.type === "tool" && !inst.loopGuardTool) {
-      const errorText = readToolError(part);
-      if (errorText) {
-        const m = errorText.match(LOOP_GUARD_RE);
-        if (m && m[1]) {
-          const tool = m[1];
-          await this.update(instanceId, {
-            status: "failed",
-            error: `Loop protection: 12 identical calls to ${tool}`,
-            loopGuardTool: tool,
-            completedAt: Date.now(),
-          });
-          // v0.5.5 — persistent auto-restart on loop-guard
-          await this._maybeAutoRestart(instanceId);
-          return;
-        }
-      }
-    }
-
-    // --- Text-part result preview refresh (spec §3.2) ---
-    if (part.type === "text" && typeof part.text === "string") {
-      const preview = part.text.slice(-RESULT_PREVIEW_MAX);
-      const newIds = [...(inst.resultMessageIds ?? []), ev.messageID];
-      // Deduplicate messageIDs.
-      const seen = new Set<string>();
-      const uniq = newIds.filter((id) => {
-        if (seen.has(id)) return false;
-        seen.add(id);
-        return true;
-      });
-      await this.update(instanceId, {
-        resultPreview: preview,
-        resultMessageIds: uniq,
-      });
-    }
-  }
-
-  /**
-   * Build the result text for `collect` per spec §4.4:
-   *   - Fetch assistant messages via `GET /session/{id}/message`.
-   *   - Concatenate `TextPart.text` in order; skip everything else.
-   *   - If `loopGuardTool` is set, prepend the marker.
-   */
-  private async buildResultText(inst: BackgroundState): Promise<string> {
-    // v0.8.0 — bg-only mode has no HTTP client; fall back to whatever
-    // text-part preview we've already accumulated.
-    if (!this.http) return inst.resultPreview ?? "";
-    const res = await this.http.listMessages(inst.sessionId, this.worktree);
-    if (!res.ok) {
-      this.logger.warn(`bizar: collect: listMessages failed: ${res.error}`);
-      return inst.resultPreview ?? "";
-    }
-    const textParts: string[] = [];
-    for (const msg of res.value) {
-      if (msg.role !== "assistant") continue;
-      for (const p of msg.parts) {
-        if (p.type !== "text") continue;
-        if (typeof p.text === "string" && p.text.length > 0) {
-          textParts.push(p.text);
-        }
-      }
-    }
-    const body = textParts.join("");
-    if (inst.loopGuardTool) {
-      return `[loop guard: 12 identical calls to ${inst.loopGuardTool}]\n${body}`;
-    }
-    return body;
-  }
-}
-
-// --- Helpers --------------------------------------------------------------
-
-/**
- * Format a millisecond duration as `Xm Ys` (or just `Ys` if under a minute).
- * Used in stall and thinking-loop error messages.
- */
-function formatDuration(ms: number): string {
-  const safeMs = Math.max(0, Math.floor(ms));
-  const minutes = Math.floor(safeMs / 60_000);
-  const seconds = Math.floor((safeMs % 60_000) / 1000);
-  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
-}
-
-/**
- * Generate a unique instance id: `bgr_<22-char base32>` (ULID-like).
- * We use 16 random bytes encoded as 22 base32 characters. The prefix
- * `bgr_` makes the file naming scheme obvious.
- */
-export function generateInstanceId(): string {
-  const bytes = new Uint8Array(16);
-  globalThis.crypto.getRandomValues(bytes);
-  return `bgr_${base32(bytes)}`;
-}
-
-/**
- * Crockford base32 (no I, L, O, U) encoder for 16 bytes → 26 chars.
- * We use 16 bytes (128 bits) to give plenty of entropy; only the first
- * 22 chars are used for the actual id and the last 4 are dropped.
- */
-function base32(bytes: Uint8Array): string {
-  const ALPH = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-  // Encode 5 bytes → 8 chars; pad the last group with zeros.
-  let bits = 0;
-  let value = 0;
-  let out = "";
-  for (let i = 0; i < bytes.length; i++) {
-    value = (value << 8) | (bytes[i] ?? 0);
-    bits += 8;
-    while (bits >= 5) {
-      out += ALPH[(value >>> (bits - 5)) & 0x1f];
-      bits -= 5;
-    }
-  }
-  if (bits > 0) out += ALPH[(value << (5 - bits)) & 0x1f];
-  return out.slice(0, 22);
-}
-
-/**
- * Generate a unique message id: `msg_<22-char base32>`. Same encoding
- * as `generateInstanceId`. Used for `POST /session/{id}/prompt_async`.
- */
-export function generateMessageId(): string {
-  const bytes = new Uint8Array(16);
-  globalThis.crypto.getRandomValues(bytes);
-  return `msg_${base32(bytes)}`;
-}
-
-function toView(inst: BackgroundState): InstanceView {
-  const v: InstanceView = {
-    instanceId: inst.instanceId,
-    agent: inst.agent,
-    status: inst.status,
-    startedAt: inst.startedAt,
-    toolCallCount: inst.toolCallCount,
-    promptPreview: inst.promptPreview,
-    parentAgent: inst.parentAgent,
-    sessionId: inst.sessionId,
-    // v0.3.0 — stall and thinking-loop protection. Always include
-    // lastEventAt so a status caller can see how fresh the activity is.
-    lastEventAt: inst.lastEventAt,
-  };
-  if (inst.completedAt !== undefined) v.completedAt = inst.completedAt;
-  if (inst.resultPreview !== undefined) v.resultPreview = inst.resultPreview;
-  if (inst.error !== undefined) v.error = inst.error;
-  if (inst.parentInstanceId !== undefined) v.parentInstanceId = inst.parentInstanceId;
-  // Only surface intervention metadata when we have actually intervened.
-  // `interventionCount > 0` is the canonical signal; absent fields mean
-  // "no intervention has been sent yet", which is the common case.
-  const interventionCount = inst.interventionCount ?? 0;
-  if (interventionCount > 0) {
-    v.interventionCount = interventionCount;
-    if (inst.interventionAt !== undefined) v.interventionAt = inst.interventionAt;
-    if (inst.interventionReason !== undefined) v.interventionReason = inst.interventionReason;
-  }
-  // v5.x — extended dashboard surface.
-  if (Array.isArray(inst.toolCalls) && inst.toolCalls.length > 0) {
-    v.toolCalls = inst.toolCalls.slice();
-  }
-  if (typeof inst.progress === "number") v.progress = inst.progress;
-  if (inst.progressMessage !== undefined) v.progressMessage = inst.progressMessage;
-  if (inst.processId !== undefined) v.processId = inst.processId;
-  if (inst.runnerState !== undefined) v.runnerState = inst.runnerState;
-  if (Array.isArray(inst.tags) && inst.tags.length > 0) v.tags = inst.tags.slice();
-  if (inst.pausedAt !== undefined) v.pausedAt = inst.pausedAt;
-  return v;
-}
-
-/**
- * Extract the canonical loop-guard error string from a tool part. The
- * part may carry the error either on `part.error` or on
- * `part.state.error` (per spec §4.1).
- */
-function readToolError(part: { error?: string; state?: { error?: string } }): string | null {
-  if (typeof part.error === "string" && part.error.length > 0) return part.error;
-  if (part.state && typeof part.state.error === "string" && part.state.error.length > 0) {
-    return part.state.error;
-  }
-  return null;
-}
-
-/**
- * v5.x — Read the tool name from a tool part. cline's wire format
- * is loose: the tool name may live on `part.tool`, `part.name`, or as
- * the value of the first entries. Returns "unknown" when nothing
- * matches.
- */
-function readToolName(part: { tool?: unknown; name?: unknown; [k: string]: unknown }): string {
-  const candidates = [part.tool, part.name];
-  for (const c of candidates) {
-    if (typeof c === "string" && c.length > 0) return c.slice(0, 200);
-  }
-  return "unknown";
-}
-
-/**
- * v5.x — Read the tool args from a tool part. cline may carry
- * `args`, `input`, or a JSON-stringified `arguments`. Returns "" when
- * nothing useful is found.
- */
-function readToolArgs(part: { args?: unknown; input?: unknown; arguments?: unknown; [k: string]: unknown }): string {
-  const candidates = [part.args, part.input, part.arguments];
-  for (const c of candidates) {
-    if (c === undefined || c === null) continue;
-    if (typeof c === "string") return c.slice(0, MAX_TOOL_ARG_CHARS);
-    try {
-      return JSON.stringify(c).slice(0, MAX_TOOL_ARG_CHARS);
-    } catch {
-      // fall through
-    }
-  }
-  return "";
-}
-
-/**
- * v5.x — Map the part's state.status (or top-level status) to our
- * ToolCallEntry status enum.
- */
-function readToolStatus(part: { state?: { status?: unknown }; status?: unknown }): "running" | "ok" | "error" {
-  const s = part.state?.status ?? part.status;
-  if (typeof s !== "string") return "running";
-  const lower = s.toLowerCase();
-  if (lower === "ok" || lower === "success" || lower === "completed" || lower === "done") return "ok";
-  if (lower === "error" || lower === "failed") return "error";
-  return "running";
-}
-
-function readToolOutput(part: { state?: { output?: unknown; result?: unknown; status?: unknown; error?: unknown }; output?: unknown; result?: unknown }): string {
-  const candidates = [part.state?.output, part.state?.result, part.output, part.result];
-  for (const c of candidates) {
-    if (c === undefined || c === null) continue;
-    if (typeof c === "string") return c;
-    try {
-      return JSON.stringify(c);
-    } catch {
-      // fall through
-    }
-  }
-  return "";
-}
-
-async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | null = null;
-  const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
-  });
-  try {
-    return await Promise.race([promise, timeout]);
-  } finally {
-    if (timer !== null) clearTimeout(timer);
-  }
-}
-
-/**
- * Serialize an unknown tool-args value into a string suitable for the
- * `toolCalls` history. JSON-serializes objects, truncates to
- * {@link MAX_TOOL_ARG_CHARS}. Returns `""` for empty/undefined.
- */
-function truncateForToolHistory(value: unknown): string {
-  if (value === undefined || value === null) return "";
-  let s: string;
-  try {
-    s = typeof value === "string" ? value : JSON.stringify(value);
-  } catch {
-    s = String(value);
-  }
-  if (s.length > MAX_TOOL_ARG_CHARS) s = s.slice(0, MAX_TOOL_ARG_CHARS) + "…";
-  return s;
-}