thursday-agent 0.1.2 → 0.3.0

package/features/bot/bot.runner.ts

@@ -1,8 +1,15 @@
 import type { ModelMessage } from "ai";
-import { after } from "next/server";
-import { appEventStream, appEvents } from "@/app/api/events/app-event.server";
-import { PATHS } from "@/config";
-import { modelErrorToString } from "@/features/ai/model";
+import {
+  appEventStream,
+  appEvents,
+  presence,
+} from "@/app/api/events/app-event.server";
+import { BOT_RUN, PATHS, WORKSPACE_KEEP } from "@/config";
+import {
+  type ModelFailure,
+  modelErrorToString,
+  modelFailureOf,
+} from "@/features/ai/model";
 import {
   buildTaskOpening,
   OPENING_TURNS,
@@ -13,21 +20,34 @@ import {
   listCallTurns,
 } from "@/features/thursday/thursday.query";
 import { pathsIn } from "@/features/workspace/file-kind";
-import { closeJobShell } from "@/features/workspace/workspace";
+import {
+  closeHiddenBrowser,
+  closeJobShell,
+  jobScratch,
+  listScratchFolders,
+  pruneJobFiles,
+  removeJobScratch,
+  removeUnchangedFolders,
+} from "@/features/workspace/workspace";
 import { desktopNotify } from "@/lib/desktop-notify";
 import { logger } from "@/lib/logger";
 import { publicError } from "@/lib/public-error";
 import { createKeyedLock } from "@/lib/queue";
-import { condenseThread, runBot, type TaskEvent } from "./bot.run";
-import { TASK_CONTINUE, type TaskStatus } from "./bot.schema";
+import { resumeThread, runBot, type TaskEvent } from "./bot.run";
+import { TASK_CONTINUE, type TaskPending, type TaskStatus } from "./bot.schema";
 import {
   addTaskUsage,
+  countStopsSinceSpoken,
+  deleteFinishedTasks,
   deleteMessages,
   deleteTask,
   findTask,
   insertTask,
   lastSeq,
+  listAutoStoppedTasks,
+  listBorrowedTails,
   listRunningTaskIds,
+  listTaskFolders,
   listThread,
   type TaskMessageInput,
   updateTask,
@@ -35,9 +55,10 @@ import {
 } from "./task.query";
 
 /**
- * Runs a job under `after()` so it outlives the request, writing every event
- * to the task's thread (task_message). A run always starts from the thread;
- * `answerTask` is the one way to add to it, serialized per job by `taskLock`.
+ * Runs a job so it outlives the request, writing every event to the task's
+ * thread (task_message). A run always starts from the thread. `answerTask` is
+ * the one way a person adds to it, serialized per job by `taskLock`, and
+ * `resumeTask` the one way the app picks a job back up by itself.
  */
 
 type Run = {
@@ -54,6 +75,8 @@ type Run = {
 type Pinned = {
   __botRuns?: Map<string, Run>;
   __botTaskLock?: ReturnType<typeof createKeyedLock>;
+  __botResumes?: Map<string, ReturnType<typeof setTimeout>>;
+  __botPausing?: { current: Promise<void> };
 };
 
 /** Pinned to globalThis: next dev reloads this module under a running run, and the abort controller and lock must be the originals. */
@@ -66,7 +89,17 @@ const running: Map<string, Run> = ((globalThis as Pinned).__botRuns ??=
  */
 const taskLock = ((globalThis as Pinned).__botTaskLock ??= createKeyedLock());
 
-/** Opens a job. The opening message is the request plus the last turns of the call (bot.prompt buildTaskOpening) and is the thread's first row. */
+/** When each parked job picks itself back up (scheduleResume); one timer per job. */
+const resumes: Map<string, ReturnType<typeof setTimeout>> = ((
+  globalThis as Pinned
+).__botResumes ??= new Map());
+
+/** The pause under way, if any; a returning browser waits for it (resumeStoppedTasks). */
+const pausing = ((globalThis as Pinned).__botPausing ??= {
+  current: Promise.resolve(),
+});
+
+/** Opens a job. The opening message — who is who, the job, the call it came from (bot.prompt buildTaskOpening) — is the thread's first row. */
 export async function startTask(input: {
   bot: string;
   request: string;
@@ -76,7 +109,11 @@ export async function startTask(input: {
   const conversation = input.callId
     ? await listCallTurns(input.callId, OPENING_TURNS)
     : [];
-  const opening = buildTaskOpening({ request: input.request, conversation });
+  const opening = buildTaskOpening({
+    bot: input.bot,
+    request: input.request,
+    conversation,
+  });
   const task = await insertTask({ ...input, opening });
   launch(task.id, {
     bot: input.bot,
@@ -106,11 +143,13 @@ export async function answerTask(id: string, answer: string) {
       live.stop.abort();
       await live.done;
     }
+    // A person picked it up; whatever the app meant to do by itself is moot
+    forgetResume(id);
 
-    const { reply, as } = joinThread(task, answer);
+    const thread = await listThread(id);
+    const { reply, as } = joinThread(task, answer, thread);
     logger.debug(`task ${id}: ${as}`);
 
-    const thread = await listThread(id);
     await upsertMessage(id, (await lastSeq(id)) + 1, {
       bot: null,
       parent: null,
@@ -121,14 +160,53 @@ export async function answerTask(id: string, answer: string) {
       status: "running",
       outcome: null,
       pending: null,
-      reported: false,
+      seen: false,
       endedAt: null,
     });
-    // Stored whole, read back folded (bot.run condenseThread)
-    launch(id, { bot: task.bot, messages: condenseThread([...thread, reply]) });
+    // Resumed on the rows as they were stored (bot.run resumeThread)
+    launch(id, {
+      bot: task.bot,
+      messages: resumeThread([...thread, reply], await listBorrowedTails(id)),
+    });
   });
 }
 
+/**
+ * The `ask_thursday` calls still open in the step a job stopped on: a model can
+ * ask twice at once, and the one answer goes to each rather than leaving the
+ * second to read as a call cut off (bot.run resumeThread). A call that already
+ * has a result — arguments the tool refused — is not open, and the words go in
+ * as a turn instead: a second result for one call is refused outright.
+ */
+function openAsks(thread: ModelMessage[], stoppedOn: string): string[] {
+  const answered = new Set(
+    thread.flatMap((message) =>
+      message.role === "tool"
+        ? message.content.flatMap((part) =>
+            part.type === "tool-result" ? [part.toolCallId] : [],
+          )
+        : [],
+    ),
+  );
+  const step = thread.findLast(
+    (message) =>
+      message.role === "assistant" &&
+      typeof message.content !== "string" &&
+      message.content.some(
+        (part) => part.type === "tool-call" && part.toolCallId === stoppedOn,
+      ),
+  );
+  const asks =
+    step?.role === "assistant" && typeof step.content !== "string"
+      ? step.content.flatMap((part) =>
+          part.type === "tool-call" && part.toolName === TOOL_NAMES.ask_thursday
+            ? [part.toolCallId]
+            : [],
+        )
+      : [stoppedOn];
+  return asks.filter((toolCallId) => !answered.has(toolCallId));
+}
+
 /**
  * How a person's words enter the thread. A job stopped on `ask_thursday` gets
  * them as that call's tool result (a call with no result would break the
@@ -136,23 +214,23 @@ export async function answerTask(id: string, answer: string) {
  * continue has no call to answer, so it is a turn as well.
  */
 function joinThread(
-  task: { status: TaskStatus; pending: { toolCallId: string | null } | null },
+  task: { status: TaskStatus; pending: TaskPending | null },
   answer: string,
+  thread: ModelMessage[],
 ): { reply: ModelMessage; as: "answer" | "interruption" | "follow-up" } {
   const pending = task.status === "waiting" ? task.pending : null;
-  if (pending?.toolCallId) {
+  const asks = pending?.toolCallId ? openAsks(thread, pending.toolCallId) : [];
+  if (asks.length) {
     return {
       as: "answer",
       reply: {
         role: "tool",
-        content: [
-          {
-            type: "tool-result",
-            toolCallId: pending.toolCallId,
-            toolName: TOOL_NAMES.ask_thursday,
-            output: { type: "text", value: answer },
-          },
-        ],
+        content: asks.map((toolCallId) => ({
+          type: "tool-result" as const,
+          toolCallId,
+          toolName: TOOL_NAMES.ask_thursday,
+          output: { type: "text" as const, value: answer },
+        })),
       },
     };
   }
@@ -171,13 +249,17 @@ export async function cancelTask(id: string) {
   return taskLock(id, async () => {
     const task = await findTask(id);
     if (!task) publicError("No such job.");
+    // A job that already ended has an answer in `outcome`; cancelling would
+    // write "Cancelled." over the thing it was run for.
+    if (task.endedAt) publicError("That job has already ended.");
+    forgetResume(id);
     running.get(id)?.stop.abort();
     await updateTask(id, {
       status: "failed",
       outcome: "Cancelled.",
       pending: null,
       // Nobody needs to be told what they just did themselves
-      reported: true,
+      seen: true,
       endedAt: new Date(),
     });
     // Cancel is a real end, so the browser session closes here; the abort in
@@ -189,53 +271,259 @@ export async function cancelTask(id: string) {
 /** Deletes the job, stopping it first if it is still running. */
 export async function removeTask(id: string) {
   return taskLock(id, async () => {
+    const task = await findTask(id);
+    forgetResume(id);
     running.get(id)?.stop.abort();
     running.delete(id);
     void closeJobShell(id);
-    return deleteTask(id);
+    const gone = await deleteTask(id);
+    // The working folder's lifetime is the row's: with the job gone, what it was
+    // working with is nobody's (workspace.ts jobScratch).
+    if (gone && task) await removeJobScratch(id, task.label);
+    return gone;
   });
 }
 
 /**
- * At boot (instrumentation): rows the last process left as running become
- * `waiting` with the one continue option, not failed. The answer resumes the
- * stored thread (answerTask).
+ * Clearing finished jobs from the screen, and their working folders with them.
+ * Lives here rather than in the query because a row and a folder go together
+ * and only one of the two is the database's.
+ */
+export async function removeFinishedTasks(): Promise<number> {
+  const removed = await deleteFinishedTasks();
+  for (const task of removed) await removeJobScratch(task.id, task.label);
+  return removed.length;
+}
+
+/**
+ * Clears what jobs left behind by age (config WORKSPACE_KEEP), at boot and on a
+ * timer (instrumentation): a job's folder once the job ended that long ago — a job
+ * running or waiting keeps its own however old — a scratch folder no job owns once
+ * it has not changed that long, and spilled output and browser snapshots that old
+ * (pruneJobFiles). A job's folder goes under the job's lock, so a word that picks
+ * the job back up in that moment never finds its material gone. Returns the
+ * folders that went.
+ */
+export async function sweepJobFiles(): Promise<string[]> {
+  const cutoff = Date.now() - WORKSPACE_KEEP.forMs;
+  const stale = (task: {
+    status: TaskStatus;
+    endedAt: Date | null;
+    updatedAt: Date;
+  }) =>
+    (task.status === "done" || task.status === "failed") &&
+    (task.endedAt ?? task.updatedAt).getTime() < cutoff;
+
+  // Folders on disk; each one a job owns is taken out as its job is read
+  const unowned = new Set(await listScratchFolders());
+  const removed: string[] = [];
+  for (const task of await listTaskFolders()) {
+    const folder = jobScratch(task.id, task.label);
+    if (!unowned.delete(folder) || !stale(task)) continue;
+    await taskLock(task.id, async () => {
+      const now = await findTask(task.id);
+      if (!now || !stale(now)) return;
+      await removeJobScratch(task.id, task.label);
+      removed.push(folder);
+    });
+  }
+  removed.push(...(await removeUnchangedFolders([...unowned])));
+  await pruneJobFiles();
+  if (removed.length) {
+    logger.info(
+      `cleared ${removed.length} old job folder(s): ${removed.join(", ")}`,
+    );
+  }
+  return removed;
+}
+
+/**
+ * At boot (instrumentation): rows the last process left as running are not
+ * running now. Each is parked the way every stop the app causes is (parkTask),
+ * so it picks itself back up once a browser is on the app. Nothing else needs
+ * to reconcile — a run that ends badly records it itself (drive), and the write
+ * that does so is durable (database/db.ts oneAtATime).
  */
 export async function sweepTasks() {
   for (const id of await listRunningTaskIds()) {
-    if (running.has(id)) continue;
-    await updateTask(id, {
-      status: "waiting",
-      outcome:
-        "The server restarted while this was running. Everything it had done is still here. Pick it back up?",
-      pending: { toolCallId: null, options: [TASK_CONTINUE] },
-      reported: false,
-      endedAt: null,
-    });
+    if (!running.has(id)) {
+      await parkTask(id, {
+        why: "The server restarted while this was running.",
+      });
+    }
   }
 }
 
 /**
- * The browser closed (app-event.server presence): every run stops where it is
- * and waits with the one continue option, the way a restart leaves it
- * (sweepTasks). The thread stays; answering resumes it.
+ * The browser closed, or the server is going down (instrumentation): every run
+ * stops where it is and is parked (parkTask). All at once — a run slow to let go
+ * must not keep the others running. The thread stays, and so does the window: a
+ * resume carries on in the page it left off at, including a sign-in the user is
+ * mid-way through, which only that window can finish.
  */
 export async function pauseTasks(reason: string) {
-  for (const [id, run] of [...running]) {
-    await taskLock(id, async () => {
-      run.stop.abort();
-      await run.done;
-      const task = await findTask(id);
-      if (!task || task.status !== "running") return;
-      await updateTask(id, {
-        status: "waiting",
-        outcome: `${reason} Everything it had done is still here. Pick it back up?`,
-        pending: { toolCallId: null, options: [TASK_CONTINUE] },
-        reported: false,
-        endedAt: null,
-      });
-      void closeJobShell(id);
+  const work = Promise.all(
+    [...running].map(([id, run]) =>
+      taskLock(id, async () => {
+        run.stop.abort();
+        await run.done;
+        const task = await findTask(id);
+        if (!task || task.status !== "running") return;
+        await parkTask(id, { why: reason });
+      }).catch((cause) => logger.error(`task ${id}: pause`, cause)),
+    ),
+  ).then(() => {});
+  pausing.current = work;
+  await work;
+}
+
+/**
+ * A browser is on the app again (instrumentation `presence.onBack`): every job
+ * the app parked picks itself back up — now, or when the wait a failed model
+ * call set runs out. A pause still under way is waited for first, so a quick
+ * reload does not miss what it parks.
+ */
+export async function resumeStoppedTasks() {
+  await pausing.current;
+  for (const task of await listAutoStoppedTasks()) {
+    scheduleResume(task.id, task.retryAt - Date.now());
+  }
+}
+
+/** One timer per job: a newer stop replaces what an older one set. */
+function scheduleResume(id: string, inMs: number) {
+  forgetResume(id);
+  resumes.set(
+    id,
+    setTimeout(
+      () => {
+        resumes.delete(id);
+        void resumeTask(id).catch((cause) =>
+          logger.error(`task ${id}: resume`, cause),
+        );
+      },
+      Math.max(0, inMs),
+    ),
+  );
+}
+
+function forgetResume(id: string) {
+  clearTimeout(resumes.get(id));
+  resumes.delete(id);
+}
+
+/**
+ * Picks a parked job back up. Only with a browser on the app — nothing runs
+ * without one, and its return tries again — and only if it is still parked: a
+ * person may have answered, cancelled or deleted it since. No turn is added,
+ * because nobody said anything; the note parkTask left is what the run reads last.
+ */
+async function resumeTask(id: string) {
+  if (!presence.watching) return;
+  await taskLock(id, async () => {
+    const task = await findTask(id);
+    if (!task || task.status !== "waiting" || !task.pending?.auto) return;
+    if (running.has(id)) return;
+    logger.debug(`task ${id}: picking back up`);
+    const thread = await listThread(id);
+    await updateTask(id, {
+      status: "running",
+      outcome: null,
+      pending: null,
+      seen: false,
+      endedAt: null,
     });
+    launch(id, {
+      bot: task.bot,
+      messages: resumeThread(thread, await listBorrowedTails(id)),
+    });
+  });
+}
+
+/**
+ * Stops a job the app stopped, rather than the bot or a person: a restart, a
+ * closed browser, a model call a retry or a compaction can fix. It waits with
+ * the one continue option like any stop, with a line in its thread saying why —
+ * the resumed run reads it — and picks itself back up (scheduleResume). Unless
+ * the app has already stopped it `BOT_RUN.autoResumes` times since a person last
+ * spoke to it: that is what a job that keeps taking the server down looks like,
+ * and it waits for a person instead.
+ */
+async function parkTask(
+  id: string,
+  stop: {
+    why: string;
+    /** A failed model call: wait before trying again (config BOT_RUN.retryAfterMs). */
+    retry?: boolean;
+    /** Where the job compacts from now on (bot.run `budget`). */
+    budget?: number;
+  },
+) {
+  const stops = await countStopsSinceSpoken(id);
+  const auto = stops < BOT_RUN.autoResumes;
+  const waits = BOT_RUN.retryAfterMs;
+  const inMs =
+    auto && stop.retry ? waits[Math.min(stops, waits.length - 1)] : 0;
+
+  await writeNote(id, `${stop.why} ${IN_FLIGHT}`).catch((cause) =>
+    logger.warn(`task ${id}: stop not written`, cause),
+  );
+  await writeEnding(id, {
+    status: "waiting",
+    outcome: auto
+      ? `${stop.why} ${inMs ? `It tries again in ${spell(inMs)}.` : "It picks back up by itself."}`
+      : `${stop.why} It has stopped ${stops + 1} times in a row, so it waits for you. Everything it had done is still here.`,
+    pending: {
+      toolCallId: null,
+      options: [TASK_CONTINUE],
+      ...(auto ? { auto: true, retryAt: Date.now() + inMs } : {}),
+    },
+    ...(stop.budget ? { contextBudget: stop.budget } : {}),
+    seen: false,
+    endedAt: null,
+  });
+  if (auto) scheduleResume(id, inMs);
+}
+
+/** Said to a resumed run after why it stopped. */
+const IN_FLIGHT =
+  "Anything that was under way — a command, a page loading, a download — may not have finished: check before relying on it, then carry on.";
+
+const spell = (ms: number) =>
+  ms < 60_000
+    ? `${Math.round(ms / 1000)} seconds`
+    : `${Math.round(ms / 60_000)} minutes`;
+
+/** A line from the app in a thread no run is writing (ThreadWriter.note is the one for a run that is). */
+async function writeNote(id: string, text: string) {
+  await upsertMessage(id, (await lastSeq(id)) + 1, {
+    bot: null,
+    parent: null,
+    role: "user",
+    content: text,
+    note: true,
+  });
+}
+
+/**
+ * The write that tells anyone a run ended at all. Tried again: everything else
+ * in the run has happened, and a miss leaves the row `running` until the next
+ * boot. Writes are serialised, so what is left is a database that briefly
+ * cannot be written to (database/db.ts).
+ */
+async function writeEnding(
+  id: string,
+  patch: Parameters<typeof updateTask>[1],
+) {
+  for (const wait of [1_000, 3_000, null]) {
+    try {
+      await updateTask(id, patch);
+      return;
+    } catch (cause) {
+      if (wait === null) throw cause;
+      logger.warn(`task ${id}: ending not written, trying again`, cause);
+      await new Promise((resolve) => setTimeout(resolve, wait));
+    }
   }
 }
 
@@ -258,14 +546,14 @@ function launch(id: string, input: { bot: string; messages: ModelMessage[] }) {
     },
   };
   running.set(id, run);
-  // The response goes out first, and the run carries on behind it
-  after(() =>
-    drive(id, input, stop.signal, notes)
-      .catch((cause) => {
-        logger.error(`task ${id}`, cause);
-      })
-      .finally(finish),
-  );
+  // Held by the server, not by a request: a run also starts from a returning
+  // browser and a retry timer, where `after()` throws (no request) or waits for
+  // the event stream to close
+  void drive(id, input, stop.signal, notes)
+    .catch((cause) => {
+      logger.error(`task ${id}`, cause);
+    })
+    .finally(finish);
 }
 
 /**
@@ -282,6 +570,9 @@ class ThreadWriter {
     { assistant: number | null; tool: number | null; parts: StepParts }
   >();
 
+  /** Set once the run is over: a borrowed run still unwinding must not write into a thread a resume has taken. */
+  private closed = false;
+
   constructor(
     private taskId: string,
     seq: number,
@@ -289,6 +580,25 @@ class ThreadWriter {
     this.seq = seq;
   }
 
+  close() {
+    this.closed = true;
+  }
+
+  /**
+   * A line from the app rather than from anyone in the room. A user row so a
+   * resumed run reads it as something it was told, and `note` so the screen
+   * draws it as a note and `rosterOf` does not take it for a person speaking.
+   */
+  async note(text: string) {
+    await upsertMessage(this.taskId, ++this.seq, {
+      bot: null,
+      parent: null,
+      role: "user",
+      content: text,
+      note: true,
+    });
+  }
+
   private step(event: TaskEvent) {
     const key = `${event.bot} ${event.parent ?? ""}`;
     let step = this.steps.get(key);
@@ -307,7 +617,7 @@ class ThreadWriter {
     seq: number,
     event: TaskEvent,
     message: ModelMessage,
-    extra: { compact?: boolean } = {},
+    extra: { compact?: boolean; note?: boolean } = {},
   ) {
     const input: TaskMessageInput = {
       bot: event.bot,
@@ -315,11 +625,13 @@ class ThreadWriter {
       role: message.role,
       content: message.content,
       compact: extra.compact ?? false,
+      note: extra.note ?? false,
     };
     return upsertMessage(this.taskId, seq, input);
   }
 
   async on(event: TaskEvent) {
+    if (this.closed) return;
     const step = this.step(event);
     switch (event.type) {
       case "text":
@@ -350,8 +662,9 @@ class ThreadWriter {
           type: "tool-result",
           toolCallId: event.id,
           toolName: event.name,
-          output:
-            typeof event.output === "string"
+          output: event.error
+            ? { type: "error-text", value: String(event.output) }
+            : typeof event.output === "string"
               ? { type: "text", value: event.output }
               : { type: "json", value: event.output as never },
         });
@@ -387,7 +700,7 @@ class ThreadWriter {
           ++this.seq,
           event,
           { role: "user", content: event.text },
-          { compact: true },
+          { compact: true, note: true },
         );
 
       case "interjection":
@@ -420,7 +733,16 @@ async function drive(
   let ending: {
     status: TaskStatus;
     outcome: string;
-    pending: { toolCallId: string | null; options: string[] } | null;
+    pending: TaskPending | null;
+  } | null = null;
+  /**
+   * What broke, as the provider said it — the thread carries it too (below) —
+   * and whose it is to fix (model.ts modelFailureOf).
+   */
+  let broken: {
+    message: string;
+    failure: ModelFailure;
+    budget?: number;
   } | null = null;
 
   try {
@@ -453,18 +775,23 @@ async function drive(
             outcome: event.question,
             pending: { toolCallId: event.id, options: event.options },
           };
-        } else if (event.type === "report") {
-          // An incomplete report goes back to waiting with the continue option.
-          // The outcome is the report text verbatim; the same text is the
-          // thread line (bot.query linesOf).
-          ending = {
-            status: event.complete ? "done" : "waiting",
-            outcome: event.text,
-            pending: event.complete
-              ? null
-              : { toolCallId: null, options: [TASK_CONTINUE] },
-          };
+        } else if (event.type === "answer") {
+          // An answer ends the job; one the app stopped (bot.run `stopped`) waits
+          // with the continue option. The outcome is the answer text verbatim;
+          // the same text is the thread line (bot.query linesOf).
+          ending = event.stopped
+            ? {
+                status: "waiting",
+                outcome: event.text,
+                pending: { toolCallId: null, options: [TASK_CONTINUE] },
+              }
+            : { status: "done", outcome: event.text, pending: null };
         } else if (event.type === "error") {
+          broken = {
+            message: event.message,
+            failure: event.failure,
+            budget: event.budget,
+          };
           ending = {
             status: "failed",
             outcome: broke(event.message),
@@ -474,16 +801,22 @@ async function drive(
       },
     });
   } catch (cause) {
+    broken = {
+      message: modelErrorToString(cause),
+      failure: modelFailureOf(cause),
+    };
     ending = {
       status: "failed",
-      outcome: broke(modelErrorToString(cause)),
+      outcome: broke(broken.message),
       pending: null,
     };
   } finally {
+    thread.close();
     running.delete(id);
   }
 
-  // Whoever aborted writes the row: cancel marks failed, answerTask relaunches.
+  // Whoever aborted writes the row: cancel marks failed, answerTask relaunches,
+  // a pause parks.
   if (signal.aborted) return;
 
   const final = ending ?? {
@@ -491,15 +824,49 @@ async function drive(
     outcome: "Stopped without handing anything back.",
     pending: null,
   };
-  await updateTask(id, {
-    ...final,
-    reported: false,
-    endedAt: final.status === "waiting" ? null : new Date(),
-  });
+  // A break a moment or a compaction can fix is the app's to pick back up, not
+  // a failure for a person to find (parkTask)
+  const park = broken && broken.failure !== "fatal" ? broken : null;
 
-  // Close the job's browser session (workspace.ts jobShellEnv) unless waiting:
-  // a bot stopped at a login wall needs the page the user is typing into.
-  if (final.status !== "waiting") void closeJobShell(id);
+  try {
+    if (park) {
+      await parkTask(id, {
+        why:
+          park.failure === "overflow"
+            ? `The model refused the context as too long (${park.message}); it is compacted before going on.`
+            : `The model call failed (${park.message}).`,
+        retry: park.failure === "transient",
+        budget: park.budget,
+      });
+    } else {
+      // A thread that simply stops cannot be read: the room shows a tool call
+      // with no answer, and a resumed run has no idea why. The task row says it
+      // too, but the row is a status and this is the story. Never at the cost of
+      // the status write, which is what tells anyone the job ended at all.
+      if (final.status === "failed") {
+        await thread
+          .note(`The run stopped here: ${broken?.message ?? final.outcome}`)
+          .catch((cause) =>
+            logger.warn(`task ${id}: break not written`, cause),
+          );
+      }
+      await writeEnding(id, {
+        ...final,
+        seen: false,
+        endedAt: final.status === "waiting" ? null : new Date(),
+      });
+    }
+  } catch (cause) {
+    // Said plainly rather than thrown into a promise nobody awaits; the row
+    // stays `running`, which the next boot reconciles (sweepTasks)
+    logger.error(`task ${id}: could not record how it ended`, cause);
+    return;
+  }
+
+  // A waiting job keeps its browser: answering resumes into the page it left
+  // off at. An ended one closes only what nobody can see (closeHiddenBrowser).
+  if (park || final.status === "waiting") void pruneJobFiles();
+  else void closeHiddenBrowser(id);
 
   const task = await findTask(id);
   if (!task) return;
@@ -515,6 +882,9 @@ async function drive(
     return;
   }
 
+  // A parked job picks itself back up; nobody needs telling yet
+  if (park) return;
+
   await announce(task.label, final);
 
   // A finished job naming a document opens it on the screen (workspace artifact-view).
@@ -526,7 +896,7 @@ async function drive(
   }
 }
 
-/** The document a report names: the artifacts folder first, otherwise the first drawable file. */
+/** The document an answer names: the artifacts folder first, otherwise the first drawable file. */
 function artifactIn(outcome: string): string | null {
   const paths = pathsIn(outcome);
   return (