@a-t-h-i/bot-lobby 0.6.26 → 0.6.28

package/src/lobby/planner.ts

@@ -522,6 +522,49 @@ export function memberPrompt(member: PanelMember, instructions?: string): string
   return [base, loadPrompt("panel.md"), `## Your seat\n\n${MEMBER_SEATS[member]}`].join("\n\n---\n\n");
 }
 
+/** A planning session as JSON: what `PlanningSession.snapshot` writes and `restore` reads. */
+export interface PlanningSnapshot {
+  version: 1;
+  /** Absent on snapshots kept before sessions had ids: a restore gives them one. */
+  id?: string;
+  createdAt?: number;
+  messages: PlannerMessage[];
+  seed?: PlannerSeed;
+  reply?: PlannerReply;
+  questions: PanelQuestion[];
+  notes: PanelNote[];
+  members: MemberState[];
+  seats: PanelMember[];
+  pins: PanelMember[];
+  satOut: Array<[PanelMember, number]>;
+  lastStatus: Array<[PanelMember, "ready" | "open"]>;
+  sat: PanelMember[];
+  memberNotes: Array<[PanelMember, string[]]>;
+  turns: number;
+  mode: RoundMode;
+  answered: AskResult[];
+  lineComments: LineComment[];
+  saved?: PlannedTask;
+  savedParts: PlannedTask[];
+  error?: string;
+  autoContinued: boolean;
+  attempts: number;
+  /** A round was running when it was taken. */
+  running: boolean;
+}
+
+/** What a seat that was thinking when pi stopped shows until its round runs again. */
+export const STOPPED_WITH_PI = "pi stopped during the round";
+
+/** Whether a parsed file is a snapshot this version reads; a torn or foreign file is not. */
+export function isPlanningSnapshot(value: unknown): value is PlanningSnapshot {
+  const snapshot = value as PlanningSnapshot;
+  return Boolean(snapshot) && snapshot.version === 1 && Array.isArray(snapshot.messages) && Array.isArray(snapshot.questions) && Array.isArray(snapshot.seats)
+    && Array.isArray(snapshot.members) && Array.isArray(snapshot.pins) && Array.isArray(snapshot.satOut) && Array.isArray(snapshot.lastStatus)
+    && Array.isArray(snapshot.sat) && Array.isArray(snapshot.memberNotes) && Array.isArray(snapshot.answered) && Array.isArray(snapshot.lineComments)
+    && Array.isArray(snapshot.savedParts) && Array.isArray(snapshot.notes) && typeof snapshot.turns === "number";
+}
+
 interface RunOutcome {
   status: MetricRecord["status"];
   output: string;
@@ -530,7 +573,15 @@ interface RunOutcome {
   usage: { input: number; output: number; cost: number; turns: number };
 }
 
+/** A new planning session's id: `PS-` and the time, so ids sort by when they began. */
+export function planningId(now = Date.now()): string {
+  return `PS-${now.toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+}
+
 export class PlanningSession {
+  /** Names the session among the project's plans (src/state/plan-history.ts). */
+  id = planningId();
+  createdAt = Date.now();
   messages: PlannerMessage[] = [];
   seed?: PlannerSeed;
   /** The oracle's latest reply; its plan is the current draft. */
@@ -563,6 +614,8 @@ export class PlanningSession {
   satOut = new Map<PanelMember, number>();
   /** How each seat left the last round it sat. */
   private readonly lastStatus = new Map<PanelMember, "ready" | "open">();
+  /** Seats that answered in at least one round: who took part in the plan. */
+  private readonly sat = new Set<PanelMember>();
   /** The last round was started by the classifier settling every question; the next one waits for the user. */
   private autoContinued = false;
   private controller?: AbortController;
@@ -707,6 +760,95 @@ export class PlanningSession {
     this.controller?.abort();
   }
 
+  /**
+   * The seats that took part in the plan: each answered in a round and is
+   * still on the panel. One the classifier always left out, or the user
+   * unseated, sat the plan out, and the task it becomes runs without it.
+   */
+  get panel(): PanelMember[] {
+    return PANEL_MEMBERS.filter((member) => this.sat.has(member) && this.seats.has(member));
+  }
+
+  /** Everything the session needs to carry on in another pi process, as JSON. */
+  snapshot(): PlanningSnapshot {
+    return {
+      version: 1,
+      id: this.id,
+      createdAt: this.createdAt,
+      messages: this.messages,
+      ...(this.seed ? { seed: this.seed } : {}),
+      ...(this.reply ? { reply: this.reply } : {}),
+      questions: this.questions,
+      notes: this.notes,
+      members: this.members,
+      seats: [...this.seats],
+      pins: [...this.pins],
+      satOut: [...this.satOut],
+      lastStatus: [...this.lastStatus],
+      sat: [...this.sat],
+      memberNotes: [...this.memberNotes],
+      turns: this.turns,
+      mode: this.mode,
+      answered: this.answered,
+      lineComments: this.lineComments,
+      ...(this.saved ? { saved: this.saved } : {}),
+      savedParts: this.savedParts,
+      ...(this.error ? { error: this.error } : {}),
+      autoContinued: this.autoContinued,
+      attempts: this.attempts,
+      running: this.busy,
+    };
+  }
+
+  /**
+   * A session as a snapshot left it. A round that was running when pi
+   * stopped is marked interrupted: `resume` runs it again.
+   */
+  static restore(deps: PlannerDeps, snapshot: PlanningSnapshot): PlanningSession {
+    const session = new PlanningSession({ ...deps, panel: snapshot.seats }, snapshot.seed);
+    if (snapshot.id) session.id = snapshot.id;
+    if (typeof snapshot.createdAt === "number") session.createdAt = snapshot.createdAt;
+    session.messages = snapshot.messages;
+    if (snapshot.reply) session.reply = snapshot.reply;
+    session.questions = snapshot.questions;
+    session.notes = snapshot.notes;
+    session.members = snapshot.members.map((member) => member.status === "thinking" ? { ...member, status: "failed", error: STOPPED_WITH_PI, step: undefined } : member);
+    for (const member of snapshot.pins) session.pins.add(member);
+    session.satOut = new Map(snapshot.satOut);
+    for (const [member, status] of snapshot.lastStatus) session.lastStatus.set(member, status);
+    for (const member of snapshot.sat) session.sat.add(member);
+    for (const [member, notes] of snapshot.memberNotes) session.memberNotes.set(member, notes);
+    session.turns = snapshot.turns;
+    session.mode = snapshot.mode;
+    session.answered = snapshot.answered;
+    session.lineComments = snapshot.lineComments;
+    if (snapshot.saved) session.saved = snapshot.saved;
+    session.savedParts = snapshot.savedParts;
+    if (snapshot.error) session.error = snapshot.error;
+    session.autoContinued = snapshot.autoContinued;
+    session.attempts = snapshot.attempts;
+    session.interrupted = snapshot.running;
+    return session;
+  }
+
+  /** A round was running when pi stopped, and has not run again yet. */
+  interrupted = false;
+
+  /** Run again the round pi stopped in the middle of; nothing when none was. */
+  async resume(): Promise<void> {
+    if (!this.interrupted || this.busy) return;
+    this.interrupted = false;
+    const last = this.messages.at(-1);
+    if (last?.role === "you") return this.retry();
+    // The seed alone had started the first round.
+    if (this.messages.length === 0 && this.seed) {
+      this.turns = Math.max(0, this.turns - 1);
+      return this.open();
+    }
+    // The round had already written its reply: only its last checks were cut off.
+    this.deps.onChange?.();
+  }
+
   /** Save the latest draft as a pending task. */
   save(now = new Date()): PlannedTask {
     const plan = this.reply?.plan;
@@ -715,6 +857,7 @@ export class PlanningSession {
       title: this.title ?? this.messages[0]?.text.split("\n")[0] ?? "planned task",
       brief: plan,
       ...(this.seed ? { issue: this.seed.issue } : {}),
+      panel: this.panel,
     }, now);
     this.deps.feed?.log(ORACLE_LABEL, `saved ${this.saved.id} to pending tasks`, "success");
     this.deps.onChange?.();
@@ -733,6 +876,7 @@ export class PlanningSession {
       brief: partBrief({ plan, steps, proposal, index }),
       ...(this.seed ? { issue: this.seed.issue } : {}),
       split: partInfo(proposal, index, group),
+      panel: this.panel,
     }, new Date(now.getTime() + (proposal.tasks.length - index))));
     this.savedParts = parts;
     this.saved = parts[0];
@@ -966,6 +1110,7 @@ export class PlanningSession {
       const transcript = [plannerTranscript(this.messages, this.seed, this.reply?.plan, ""), likely].filter(Boolean).join("\n\n");
       const outcomes = await Promise.all(this.members.map((state) => this.runMember(state, transcript, controller.signal, effort)));
       if (controller.signal.aborted) throw new Error("stopped");
+      for (const outcome of outcomes) if (outcome.reply) this.sat.add(outcome.member);
       this.notes = PANEL_MEMBERS.flatMap((member) => (this.memberNotes.get(member) ?? []).map((text) => ({ from: MEMBER_LABELS[member], text })));
       this.step = "writing the plan";
       this.deps.onChange?.();

package/src/lobby/quickfix.ts

@@ -65,6 +65,8 @@ export interface QuickFixJob {
   profile?: QuickFixProfile;
   /** The oracle sent it here from a request typed to the lobby. */
   routed?: boolean;
+  /** An earlier run was cut off when pi stopped: some of its edits may already be in the tree. */
+  interrupted?: boolean;
 }
 
 /** How a job enters the queue besides its prompt. */
@@ -111,6 +113,10 @@ export interface QuickFixDeps {
 
 export const MAX_JOBS = 30;
 export const MAX_STEPS = 200;
+/** Steps a snapshot keeps per job: enough to read what it did. */
+const MAX_KEPT_STEPS = 40;
+/** What a job pi stopped in the middle of is told when it runs again. */
+export const INTERRUPTED_NOTE = "An earlier run of this request was cut off when pi stopped, so some of its edits may already be in the tree: look at the files before you change them, and finish the request.";
 
 function isActive(job: QuickFixJob): boolean {
   return job.status === "queued" || job.status === "running";
@@ -202,6 +208,39 @@ export class QuickFixQueue {
     return true;
   }
 
+  /** The queue as JSON, for the next pi process to carry on from. */
+  snapshot(): QuickFixJob[] {
+    return this.jobs.map((job) => ({ ...job, steps: job.steps.slice(-MAX_KEPT_STEPS) }));
+  }
+
+  /**
+   * Take up a queue an earlier pi process left: finished jobs stay as they
+   * ended, and the one that was running when pi stopped goes back to the front
+   * of the queue, told that it was cut off. Returns the jobs that will run.
+   */
+  restore(jobs: readonly QuickFixJob[]): QuickFixJob[] {
+    const kept = jobs.map((job): QuickFixJob => job.status !== "running" ? { ...job } : {
+      ...job,
+      status: "queued",
+      interrupted: true,
+      note: "pi stopped while this ran; it runs again from where the tree is",
+      steps: job.steps.map((step) => ({ ...step, pending: false })),
+    });
+    // Queues from more than one stopped window may share ids: a repeated one is numbered on.
+    const number = (job: QuickFixJob) => Number(/^QF-(\d+)$/.exec(job.id)?.[1] ?? 0);
+    this.counter = Math.max(this.counter, ...this.jobs.map(number), ...kept.map(number));
+    const taken = new Set(this.jobs.map((job) => job.id));
+    for (const job of kept) {
+      if (taken.has(job.id)) job.id = `QF-${++this.counter}`;
+      taken.add(job.id);
+    }
+    const resumed = kept.filter((job) => job.interrupted && job.status === "queued");
+    this.jobs = [...resumed, ...kept.filter((job) => !resumed.includes(job)), ...this.jobs];
+    this.changed();
+    this.pump();
+    return this.jobs.filter(isActive);
+  }
+
   /** Abort everything (session shutdown). */
   cancelAll(): void {
     for (const job of this.jobs) if (job.status === "queued") job.status = "cancelled";
@@ -259,7 +298,7 @@ export class QuickFixQueue {
       const attempt = (model: string | undefined, thinking: string) => runPiAgent(
         {
           cwd: this.deps.cwd,
-          task: likely ? `${job.prompt}\n\n${likely}` : job.prompt,
+          task: [job.prompt, job.interrupted ? INTERRUPTED_NOTE : "", likely].filter(Boolean).join("\n\n"),
           systemPrompt: quickFixPrompt(profile.instructions),
           tools: [...QUICK_FIX_TOOLS, ...(this.deps.hints?.tools() ?? [])],
           ...grantOption("quickfix"),

package/src/lobby/recovery.ts

@@ -0,0 +1,415 @@
+/**
+ * Carrying on after pi stops unexpectedly. A window running the lobby keeps
+ * what it is doing on disk as it changes: its planning panel and quick-fix
+ * queue (by session), and a record of the sessions it drives and whether each
+ * was mid-turn (src/state/recovery.ts). Quitting on purpose removes the
+ * record; a crash, a kill or a closed terminal leaves it.
+ *
+ * The next window to start the lobby in the project takes the stopped
+ * windows over: the planning panel comes back where it was (a round that was
+ * cut off runs again), queued quick fixes run (the one cut off runs again),
+ * and every session that drove a task still under way is started again from
+ * its saved file, its oracle told to pick up where it stopped when it was
+ * mid-turn. A window that is that same session again (`pi -c`) carries its
+ * own task on itself. Nothing here runs in a subagent or a background session.
+ */
+import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
+import { loadTask, ownedTask, saveTask } from "../state/persistence.ts";
+import { resolvePhaseTiming } from "../state/phase-timing.ts";
+import { updateBudget } from "../state/budget.ts";
+import { clearStaleRuns } from "../state/work-time.ts";
+import { livePresence } from "../state/presence.ts";
+import {
+  claimStoppedWindows,
+  moveSessionState,
+  readSessionState,
+  removeSessionState,
+  removeWindow,
+  stoppedWindows,
+  writeSessionState,
+  writeWindow,
+  type BackgroundRecord,
+  type WindowRecord,
+} from "../state/recovery.ts";
+import { isPlanningSnapshot, type PlanningSession, type PlanningSnapshot } from "./planner.ts";
+import { keepPlan } from "../state/plan-history.ts";
+import type { QuickFixJob } from "./quickfix.ts";
+import type { BackgroundSession } from "./sessions.ts";
+
+/** Writes after a change wait this long, so a burst of changes is one write. */
+export const SAVE_DELAY_MS = 300;
+/** How long after the lobby starts this window's own interrupted turn is picked back up. */
+export const NUDGE_DELAY_MS = 1500;
+
+/** What the oracle is told when the session it was working in stopped mid-turn. */
+export function resumeMessage(task: Task): string {
+  return [
+    `bot-lobby: pi stopped unexpectedly while you were working on ${task.id} (${task.state}${task.paused ? ", paused" : ""}).`,
+    "Pick up where you left off: read where the task stands with the orchestrate tool (action=status), run again any step that was cut off (its agent stopped with pi, and its edits may be half done), ask again any question that was not answered, and carry on.",
+  ].join(" ");
+}
+
+/** A task a stopped session drove that is still under way, or undefined. */
+function liveTask(root: string, configDir: string, sessionId: string): Task | undefined {
+  const task = ownedTask(root, configDir, sessionId);
+  return task && !TERMINAL_STATES.includes(task.state) ? task : undefined;
+}
+
+const INTERRUPTED_DECISION = "pi stopped unexpectedly; the task carried on in the next session (steps that were running stopped with it)";
+
+/**
+ * Clear what the stopped process left marked as under way on a task: the
+ * questions it was waiting on (they no longer wait), the time given to the
+ * steps it was running, and the runs it noted as active. A decision records
+ * the stop, so the task's history says what happened.
+ */
+export function settleInterrupted(root: string, configDir: string, taskId: string, now = new Date(), note = INTERRUPTED_DECISION): void {
+  const task = loadTask(root, configDir, taskId);
+  if (!task) return;
+  const at = now.toISOString();
+  for (const id of [...(task.blockingRequestIds ?? task.phaseTiming?.blockingRequestIds ?? [])]) resolvePhaseTiming(task, id, at);
+  task.decisions.push({ domain: "master", text: note, createdAt: at });
+  task.updatedAt = at;
+  saveTask(root, configDir, task);
+  updateBudget(root, configDir, taskId, (budget) => {
+    for (const allotment of budget.allotments) {
+      if (allotment.endedAt) continue;
+      allotment.endedAt = at;
+      allotment.outcome = "stopped";
+    }
+  });
+  clearStaleRuns(root, configDir, taskId);
+}
+
+/** A session to start again from its saved file. */
+export interface Relaunch {
+  name: string;
+  sessionFile: string;
+  taskId: string;
+  /** The nudge it gets once up, when it was mid-turn. */
+  message?: string;
+}
+
+/** What the window starting the lobby can carry on from the windows that stopped. */
+export interface RecoveryPlan {
+  windows: WindowRecord[];
+  /** Kept state to hand to this session, from the newest stopped window that has it. */
+  planner?: { from: string };
+  quickfix: string[];
+  relaunch: Relaunch[];
+  /** This window is the stopped one's session again, and its task is under way. */
+  own?: { taskId: string; message?: string };
+}
+
+/**
+ * Decide what carries on: pure but for reads, so a test can check it. The
+ * stopped windows are claimed first (`claimStoppedWindows`), so only one
+ * window acts on each.
+ */
+export function planRecovery(input: {
+  root: string;
+  configDir: string;
+  sessionId: string;
+  windows: readonly WindowRecord[];
+  /** Sessions running now in some terminal: never started a second time. */
+  running: ReadonlySet<string>;
+}): RecoveryPlan {
+  const { root, configDir, sessionId } = input;
+  const plan: RecoveryPlan = { windows: [...input.windows], quickfix: [], relaunch: [] };
+  const hasOwnPlanner = isPlanningSnapshot(readSessionState(root, configDir, "planner", sessionId));
+  const seen = new Set<string>();
+  const consider = (session: { sessionId: string; sessionFile?: string; name?: string; working: boolean }) => {
+    if (seen.has(session.sessionId) || input.running.has(session.sessionId)) return;
+    seen.add(session.sessionId);
+    const task = liveTask(root, configDir, session.sessionId);
+    if (!task) return;
+    const message = session.working && !task.paused ? resumeMessage(task) : undefined;
+    if (session.sessionId === sessionId) {
+      plan.own = { taskId: task.id, ...(message ? { message } : {}) };
+      return;
+    }
+    if (!session.sessionFile) return;
+    plan.relaunch.push({ name: session.name ?? task.title, sessionFile: session.sessionFile, taskId: task.id, ...(message ? { message } : {}) });
+  };
+  for (const window of input.windows) {
+    if (!hasOwnPlanner && !plan.planner && window.sessionId !== sessionId && isPlanningSnapshot(readSessionState(root, configDir, "planner", window.sessionId))) {
+      plan.planner = { from: window.sessionId };
+    }
+    if (window.sessionId !== sessionId && Array.isArray(readSessionState(root, configDir, "quickfix", window.sessionId))) plan.quickfix.push(window.sessionId);
+    consider({ sessionId: window.sessionId, ...(window.sessionFile ? { sessionFile: window.sessionFile } : {}), working: window.working });
+    for (const background of window.background) consider(background);
+  }
+  return plan;
+}
+
+/** What `recover` needs of the lobby: its paths and session, and how to act. */
+export interface RecoveryHost {
+  root: string;
+  configDir: string;
+  sessionId: string;
+  /** Start a stopped session again in the background from its saved file. */
+  relaunch(start: Relaunch): BackgroundSession | string;
+  /** Restore the planning panel from a snapshot (and run again a round it cut off). */
+  restorePlanner(snapshot: PlanningSnapshot): void;
+  /** Take up quick-fix jobs a stopped process left; returns how many will run. */
+  restoreQuickFixes(jobs: readonly QuickFixJob[]): number;
+  /** Send this window's oracle the nudge, once it is idle. */
+  nudge(message: string): void;
+}
+
+/** What carried on, in words, or undefined when nothing did. */
+export function recoverySummary(parts: { planner: boolean; quickfixes: number; tasks: string[] }): string | undefined {
+  const done = [
+    parts.planner ? "the planning session" : "",
+    parts.quickfixes > 0 ? `${parts.quickfixes} quick fix${parts.quickfixes === 1 ? "" : "es"}` : "",
+    parts.tasks.length > 0 ? `${parts.tasks.length === 1 ? "task" : "tasks"} ${parts.tasks.join(", ")}` : "",
+  ].filter(Boolean);
+  if (done.length === 0) return undefined;
+  const list = done.length === 1 ? done[0]! : `${done.slice(0, -1).join(", ")} and ${done.at(-1)}`;
+  return `pi stopped unexpectedly — carried on with ${list}`;
+}
+
+/**
+ * Carry on what the stopped windows were doing, and this session's own kept
+ * planning panel and quick-fix queue. Returns the summary to show, if any.
+ */
+export function recover(host: RecoveryHost): string | undefined {
+  const { root, configDir, sessionId } = host;
+  const windows = claimStoppedWindows(root, configDir);
+  let running = new Set<string>();
+  try {
+    running = new Set(livePresence(root, configDir).map((presence) => presence.sessionId));
+  } catch {
+    // Unreadable heartbeats only mean nothing is ruled out.
+  }
+  running.delete(sessionId);
+  const plan = planRecovery({ root, configDir, sessionId, windows, running });
+
+  if (plan.planner) moveSessionState(root, configDir, "planner", plan.planner.from, sessionId);
+  const snapshot = readSessionState(root, configDir, "planner", sessionId);
+  const planner = isPlanningSnapshot(snapshot);
+  if (planner) host.restorePlanner(snapshot);
+
+  const jobs: QuickFixJob[] = [];
+  for (const from of [sessionId, ...plan.quickfix]) {
+    const kept = readSessionState(root, configDir, "quickfix", from);
+    if (Array.isArray(kept)) jobs.push(...(kept as QuickFixJob[]));
+    if (from !== sessionId) removeSessionState(root, configDir, "quickfix", from);
+  }
+  const quickfixes = jobs.length > 0 ? host.restoreQuickFixes(jobs) : 0;
+
+  const tasks: string[] = [];
+  for (const start of plan.relaunch) {
+    settleInterrupted(root, configDir, start.taskId);
+    const session = host.relaunch(start);
+    if (typeof session !== "string") tasks.push(start.taskId);
+  }
+  if (plan.own) {
+    settleInterrupted(root, configDir, plan.own.taskId);
+    if (plan.own.message) host.nudge(plan.own.message);
+    tasks.push(plan.own.taskId);
+  }
+  // A restart after a quit restores the panel quietly; only carrying on after a stop is announced.
+  return windows.length > 0 ? recoverySummary({ planner, quickfixes, tasks }) : undefined;
+}
+
+/** Whether a window in this project stopped without quitting: the lobby then starts on, to carry its work on. */
+export function workToCarryOn(root: string, configDir: string): boolean {
+  try {
+    return stoppedWindows(root, configDir).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** A write that waits a moment, so a burst of changes is one write; `flush` writes now. */
+export class Debounced {
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private closed = false;
+  private readonly write: () => void;
+  private readonly delayMs: number;
+  constructor(write: () => void, delayMs = SAVE_DELAY_MS) {
+    this.write = write;
+    this.delayMs = delayMs;
+  }
+
+  schedule(): void {
+    if (this.closed || this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      this.run();
+    }, this.delayMs);
+    this.timer.unref?.();
+  }
+
+  flush(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    if (!this.closed) this.run();
+  }
+
+  /** Write once more, then never again (the lobby is stopping). */
+  close(): void {
+    this.flush();
+    this.closed = true;
+  }
+
+  /** Never write again, not even what is waiting. */
+  cancel(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    this.closed = true;
+  }
+
+  private run(): void {
+    try {
+      this.write();
+    } catch {
+      // A read-only project only means the work does not carry on after a crash.
+    }
+  }
+}
+
+/** What a window keeps on disk while the lobby runs, so the next window can carry it on. */
+export interface KeeperSource {
+  root: string;
+  configDir: string;
+  sessionId: () => string;
+  sessionFile: () => string | undefined;
+  /** This window's oracle is mid-turn. */
+  working: () => boolean;
+  planner: () => PlanningSession | undefined;
+  quickfix: () => readonly QuickFixJob[];
+  background: () => readonly BackgroundSession[];
+}
+
+/**
+ * Keeps this window's record, planning panel and quick-fix queue on disk as
+ * they change, for the next window to carry on after a stop.
+ */
+export class WindowKeeper {
+  private readonly startedAt = new Date().toISOString();
+  readonly window: Debounced;
+  readonly planner: Debounced;
+  readonly quickfix: Debounced;
+  /** pi going down on an uncaught error skips the shutdown: what is waiting is written as the process exits. */
+  private readonly onExit = () => {
+    for (const writer of [this.planner, this.quickfix, this.window]) writer.close();
+  };
+  private readonly source: KeeperSource;
+  constructor(source: KeeperSource) {
+    this.source = source;
+    process.once("exit", this.onExit);
+    this.window = new Debounced(() => writeWindow(source.root, source.configDir, this.record()));
+    this.planner = new Debounced(() => {
+      const session = source.planner();
+      if (session) this.keepPlanner(session, session.snapshot());
+    });
+    this.quickfix = new Debounced(() => {
+      const jobs = source.quickfix();
+      if (jobs.length > 0) writeSessionState(source.root, source.configDir, "quickfix", source.sessionId(), jobs);
+      else removeSessionState(source.root, source.configDir, "quickfix", source.sessionId());
+    });
+  }
+
+  /** The panel as this window's (to carry on) and among the project's plans (to read again later). */
+  private keepPlanner(session: PlanningSession, snapshot: PlanningSnapshot): void {
+    writeSessionState(this.source.root, this.source.configDir, "planner", this.source.sessionId(), snapshot);
+    keepPlan(this.source.root, this.source.configDir, session.id, session.createdAt, snapshot);
+  }
+
+  private record(): Omit<WindowRecord, "pid" | "token" | "updatedAt"> {
+    const file = this.source.sessionFile();
+    return {
+      sessionId: this.source.sessionId(),
+      ...(file ? { sessionFile: file } : {}),
+      working: this.source.working(),
+      background: backgroundRecords(this.source.background(), this.source.root),
+      startedAt: this.startedAt,
+    };
+  }
+
+  /**
+   * The lobby is stopping. `carryOn` (pi stopped on a signal, or is going
+   * down unexpectedly) keeps everything as it stands for the next window; a
+   * stop on purpose (quit, switching sessions, turning bot-lobby off) records
+   * what was running as stopped and removes the window's record.
+   */
+  stop(carryOn: boolean): void {
+    process.off("exit", this.onExit);
+    if (carryOn) {
+      this.planner.close();
+      this.quickfix.close();
+      this.window.close();
+      return;
+    }
+    const { root, configDir } = this.source;
+    const sessionId = this.source.sessionId();
+    try {
+      const session = this.source.planner();
+      if (session) this.keepPlanner(session, stoppedSnapshot(session.snapshot()));
+      const jobs = this.source.quickfix().map(stoppedJob);
+      if (jobs.length > 0) writeSessionState(root, configDir, "quickfix", sessionId, jobs);
+      else removeSessionState(root, configDir, "quickfix", sessionId);
+      removeWindow(root, configDir);
+    } catch {
+      // A read-only project keeps nothing.
+    }
+    for (const writer of [this.planner, this.quickfix, this.window]) writer.cancel();
+  }
+}
+
+/** What a stop on purpose leaves of a planning round: stopped, and retryable. */
+export function stoppedSnapshot(snapshot: PlanningSnapshot): PlanningSnapshot {
+  if (!snapshot.running) return snapshot;
+  return { ...snapshot, running: false, members: snapshot.members.map((member) => member.status === "thinking" ? { ...member, status: "failed", error: "stopped" } : member), error: STOPPED_ROUND };
+}
+
+/** What a stop on purpose leaves of a quick fix that was queued or running: cancelled. */
+export function stoppedJob(job: QuickFixJob): QuickFixJob {
+  if (job.status !== "queued" && job.status !== "running") return job;
+  return { ...job, status: "cancelled", note: "stopped when the lobby stopped", ...(job.finishedAt ? {} : { finishedAt: Date.now() }) };
+}
+
+/** A round stopped by a quit, as the Plan tab shows it. */
+export const STOPPED_ROUND = "stopped when the lobby stopped — retry runs the round again";
+
+/** The background sessions worth carrying on: running, saved to a file, in this project. */
+export function backgroundRecords(sessions: readonly BackgroundSession[], root: string): BackgroundRecord[] {
+  return sessions
+    .filter((session) => session.alive && session.sessionId && session.sessionFile && (!session.projectRoot || session.projectRoot === root))
+    .map((session) => ({ sessionId: session.sessionId!, sessionFile: session.sessionFile!, name: session.name, working: session.busy || session.dialogs.length > 0 }));
+}
+
+/**
+ * Whether pi is stopping on a signal (a closed terminal, a kill) rather than a
+ * quit the user asked for: such a stop carries on in the next window. pi turns
+ * both into the same `quit` shutdown, so the signal is heard here first. When
+ * pi's own handlers are gone, the signal is passed on, so it still stops pi.
+ */
+let signalled = false;
+let listening = false;
+
+export function stoppingOnSignal(): boolean {
+  return signalled;
+}
+
+export function listenForSignals(): void {
+  if (listening) return;
+  listening = true;
+  const signals: NodeJS.Signals[] = process.platform === "win32" ? ["SIGTERM"] : ["SIGTERM", "SIGHUP"];
+  for (const signal of signals) {
+    const handler = () => {
+      signalled = true;
+      if (process.listenerCount(signal) > 1) return;
+      process.off(signal, handler);
+      process.kill(process.pid, signal);
+    };
+    process.on(signal, handler);
+  }
+}
+
+/** Forget a heard signal (tests). */
+export function resetSignals(): void {
+  signalled = false;
+}