@saadnvd1/agent-os 0.3.591 → 0.3.594

package/lib/chat/pending.ts

@@ -0,0 +1,169 @@
+import type { ChatImage } from "./events";
+
+// A message the composer sent that isn't in the chat or its queue yet. It
+// shows as a bubble at once, and stays (as failed, with Retry) if it never
+// arrives, so a long paste is never lost to a dead socket.
+export interface PendingSend {
+  id: string;
+  text: string;
+  images?: ChatImage[];
+  compact?: boolean;
+  // "sending": not taken in yet. "accepted": the server has it and is
+  // starting the agent.
+  status: "sending" | "accepted" | "failed";
+  error?: string;
+  // When it was last sent or accepted, for the timeouts below.
+  at: number;
+  // Sends so far; each reconnect resends once, up to MAX_SENDS.
+  sends: number;
+}
+
+export type PendingAction =
+  | {
+      type: "add";
+      send: Omit<PendingSend, "status" | "at" | "sends">;
+      now: number;
+    }
+  // Sent again on a new socket, or by Retry.
+  | { type: "resent"; id: string; now: number }
+  | { type: "accepted"; id: string; now: number }
+  | { type: "failed"; id: string; error: string }
+  // Ids now in the chat or its queue: those sends are done.
+  | { type: "resolved"; ids: Iterable<string> }
+  | { type: "drop"; id: string }
+  | { type: "tick"; now: number };
+
+// No answer at all: the socket is likely dead though not yet closed.
+export const SEND_TIMEOUT_MS = 10_000;
+// Taken in but never shown: a new agent takes seconds, not a minute.
+export const ACCEPTED_TIMEOUT_MS = 60_000;
+export const MAX_SENDS = 3;
+
+export const NOT_SENT = "connection lost";
+const NO_ANSWER = "no answer from AgentOS";
+const NEVER_ARRIVED = "the agent didn't take it";
+
+export function pendingReducer(
+  state: PendingSend[],
+  action: PendingAction
+): PendingSend[] {
+  const update = (id: string, fn: (p: PendingSend) => PendingSend | null) => {
+    const i = state.findIndex((p) => p.id === id);
+    if (i === -1) return state;
+    const next = fn(state[i]);
+    if (next === state[i]) return state;
+    const out = state.slice();
+    if (next) out[i] = next;
+    else out.splice(i, 1);
+    return out;
+  };
+  switch (action.type) {
+    case "add":
+      if (state.some((p) => p.id === action.send.id)) return state;
+      return [
+        ...state,
+        { ...action.send, status: "sending", at: action.now, sends: 1 },
+      ];
+    case "resent":
+      return update(action.id, (p) => ({
+        ...p,
+        status: "sending",
+        error: undefined,
+        at: action.now,
+        sends: p.sends + 1,
+      }));
+    case "accepted":
+      return update(action.id, (p) =>
+        p.status === "sending"
+          ? { ...p, status: "accepted", at: action.now }
+          : p
+      );
+    case "failed":
+      return update(action.id, (p) => ({
+        ...p,
+        status: "failed",
+        error: action.error,
+      }));
+    case "resolved": {
+      const ids = new Set(action.ids);
+      const kept = state.filter((p) => !ids.has(p.id));
+      return kept.length === state.length ? state : kept;
+    }
+    case "drop":
+      return update(action.id, () => null);
+    case "tick": {
+      let changed = false;
+      const next = state.map((p) => {
+        const limit =
+          p.status === "sending"
+            ? SEND_TIMEOUT_MS
+            : p.status === "accepted"
+              ? ACCEPTED_TIMEOUT_MS
+              : Infinity;
+        if (action.now - p.at < limit) return p;
+        changed = true;
+        return {
+          ...p,
+          status: "failed" as const,
+          error: p.status === "sending" ? NO_ANSWER : NEVER_ARRIVED,
+        };
+      });
+      return changed ? next : state;
+    }
+  }
+}
+
+// What a new socket sends again: anything not failed and not over its sends.
+// Safe to repeat: the server drops an id already in the chat or its queue.
+export const toResend = (state: PendingSend[]) =>
+  state.filter((p) => p.status !== "failed" && p.sends < MAX_SENDS);
+
+// A new socket that can't send again what's still pending marks it failed.
+export const overSends = (state: PendingSend[]) =>
+  state.filter((p) => p.status !== "failed" && p.sends >= MAX_SENDS);
+
+// getRandomValues, not randomUUID: a phone on plain http over the tailnet
+// isn't a secure context.
+export const clientId = () =>
+  `user-c-${Array.from(crypto.getRandomValues(new Uint8Array(12)), (b) =>
+    b.toString(16).padStart(2, "0")
+  ).join("")}`;
+
+const keyFor = (sessionId: string) => `agentos:pending:${sessionId}`;
+
+// Kept in this browser so a reload doesn't lose a failed article. Over
+// quota, images go first and the words stay.
+export function savePending(sessionId: string, state: PendingSend[]): void {
+  try {
+    const key = keyFor(sessionId);
+    if (!state.length) return localStorage.removeItem(key);
+    for (const kept of [
+      state,
+      state.map((p) => ({ ...p, images: undefined })),
+    ]) {
+      try {
+        localStorage.setItem(key, JSON.stringify(kept));
+        return;
+      } catch {
+        // Too big; try without images.
+      }
+    }
+  } catch {
+    // Storage unavailable.
+  }
+}
+
+export function loadPending(sessionId: string): PendingSend[] {
+  try {
+    const raw = localStorage.getItem(keyFor(sessionId));
+    const list = raw ? (JSON.parse(raw) as PendingSend[]) : [];
+    // From an earlier page: each is sent once more on connecting.
+    return Array.isArray(list)
+      ? list.filter(
+          (p) => typeof p?.id === "string" && typeof p.text === "string"
+        )
+      : [];
+  } catch {
+    return [];
+  }
+}

package/lib/chat/runner.ts

@@ -384,6 +384,10 @@ const sentBy = ({ from, peer, origin }: SentBy): SentBy => ({
   origin,
 });
 
+// Already a message in the chat or its queue.
+const taken = (sessionId: string, id: string) =>
+  hasItem(sessionId, id) || listQueue(sessionId).some((q) => q.id === id);
+
 export async function sendChat(
   sessionId: string,
   input: {
@@ -393,16 +397,20 @@ export async function sendChat(
     queue?: boolean;
     // Compact a stale chat first (lib/chat/stale).
     compact?: CompactFirst;
+    // The client's own id for it, so a resend after a reconnect is a no-op.
+    id?: string;
   } & SentBy
 ): Promise<void> {
   const text = input.text.trim();
   if (!text && !input.images?.length) return;
+  if (input.id && taken(sessionId, input.id)) return;
   refuseAway(sessionId);
+  const id = input.id ?? `user-${Date.now()}-${randomUUID().slice(0, 5)}`;
   // Its worktree is still being set up, its task hasn't launched (held by
   // Pause, say), or it's moving or landing: the message waits its turn.
   if (settingUp(sessionId) || launchPending(sessionId) || chatHold(sessionId)) {
     enqueue(sessionId, {
-      id: `user-${Date.now()}-${randomUUID().slice(0, 5)}`,
+      id,
       text,
       images: input.images,
       ...sentBy(input),
@@ -411,7 +419,8 @@ export async function sendChat(
     return;
   }
   const live = await ensureLive(sessionId);
-  const id = `user-${Date.now()}-${randomUUID().slice(0, 5)}`;
+  // Sent again while the worker was starting.
+  if (input.id && taken(sessionId, id)) return;
   if (queuedIfHeld(sessionId, { ...input, id, text })) return;
   live.worker.command({
     type: "send",

package/lib/chat/socket.ts

@@ -145,7 +145,18 @@ function onChatMessage(
     void Promise.resolve(p).catch(fail);
   if (msg.type === "send") {
     const send = clientSend(msg);
-    run(sendChat(sessionId, { ...send, queue: true }));
+    const id = send.id;
+    // Taken in now: a new worker can take seconds to start.
+    if (id) reply({ type: "accepted", id });
+    void sendChat(sessionId, { ...send, queue: true }).catch((err) => {
+      if (id)
+        reply({
+          type: "send_failed",
+          id,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      fail(err);
+    });
     // "Session 4" is named after its first message.
     run(titleChatFromMessage(sessionId, send.text));
   } else if (msg.type === "queue_edit" && typeof msg.text === "string")

package/lib/db/migrations.ts

@@ -2298,6 +2298,17 @@ export const migrations: Migration[] = [
       `);
     },
   },
+  {
+    key: "20261014T1900_pause_note",
+    up: (db) => {
+      // Why a resume that was asked for hasn't happened yet (waiting for a
+      // slot, held by load), shown on the task row. Additive.
+      const has = (
+        db.prepare(`PRAGMA table_info(sessions)`).all() as { name: string }[]
+      ).some((c) => c.name === "pause_note");
+      if (!has) db.exec(`ALTER TABLE sessions ADD COLUMN pause_note TEXT`);
+    },
+  },
   {
     key: "20261014T2000_chat_bookmarks",
     up: (db) => {

package/lib/db/types.ts

@@ -92,6 +92,8 @@ export interface Session {
   pause_state?: "pausing" | "paused" | "resuming" | null;
   paused_until?: string | null;
   pause_id?: number | null;
+  // Why a requested resume hasn't happened yet.
+  pause_note?: string | null;
   placed_note?: string | null;
   // Set by done: hidden from the sidebar and the orchestrator, never deleted.
   archived_at: string | null;

package/lib/done/worktree.ts

@@ -13,6 +13,7 @@ import { getProject } from "../projects";
 import { deleteWorktree, isAgentOSWorktree } from "../worktrees";
 import { removalRunning, removalSettled } from "../worktree-removal";
 import { describeChanges, unsavedChanges } from "../worktree-placed";
+import { dropSnapshot, snapshotWorktree } from "../resurrect/snapshot";
 
 export type WorktreeFate =
   | { action: "none" }
@@ -100,7 +101,7 @@ export type FatePreview =
   | { action: "remove"; why: string; repo: string };
 
 type Judged = Pick<Session, "worktree_path" | "base_branch"> &
-  Partial<Pick<Session, "project_id">>;
+  Partial<Pick<Session, "project_id" | "id">>;
 
 // Gone, or still going: removed by whatever else got to it first.
 const gone = (merged: MergedAs | null, still = false) => ({
@@ -215,8 +216,23 @@ export async function settleWorktree(
   merged: MergedAs | null,
   movedAway = false
 ): Promise<WorktreeFate> {
+  // Unmerged work is saved for a restore while the fate is judged, and kept
+  // only if the worktree is really removed.
+  const snapshot =
+    !merged && !movedAway && session.id && session.worktree_path
+      ? snapshotWorktree(session.worktree_path, session.id)
+      : null;
   const fate = await worktreeFate(session, merged, undefined, movedAway);
-  if (fate.action !== "remove") return fate;
+  if (fate.action !== "remove") {
+    if (snapshot && fate.action === "kept") {
+      const { path } = fate;
+      void snapshot.then((made) => {
+        if (made) void dropSnapshot(path, session.id!);
+      });
+    }
+    return fate;
+  }
+  await snapshot;
   const path = session.worktree_path!;
   await deleteWorktree(path, fate.repo, true).catch(() => {});
   if (fs.existsSync(path))

package/lib/orchestrator/act.ts

@@ -36,7 +36,9 @@ import type { StackItemView } from "../stacks/types";
 import { doneSession } from "../done";
 import { archiveChecked } from "../done/archive";
 import { amendBrief, amendmentsOf } from "./amendments";
-import type { Session } from "../db";
+import { db, type Session } from "../db";
+import { resurrectSession } from "../resurrect";
+import { resolveEnded } from "../resurrect/find";
 import { approvePlanNow } from "../models/plan-step";
 import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
@@ -54,7 +56,7 @@ import {
   PauseRefused,
   activePause,
   requestPause,
-  requestResume,
+  resumeNow,
 } from "../tasks/pause";
 import { pauseUntil, type PausePreset } from "../sidebar/snooze";
 import type { Priority } from "../tasks/schedule-types";
@@ -411,6 +413,30 @@ export async function archive(
   return `Archived ${s.name}: out of the sidebar, in Archived.`;
 }
 
+// Brings a dropped, done or archived session back, same id and conversation.
+// A task takes a running slot again, so it goes through the brakes like a
+// start; an unarchive or reopen starts nothing.
+export async function resurrect(
+  workspaceId: string,
+  ref: string,
+  reason: string
+): Promise<string> {
+  if (!reason.trim()) throw new Error("Say why it's restored");
+  const id = resolveEnded(ref, { workspaceId });
+  const row = db
+    .prepare(`SELECT task_status, archived_at FROM sessions WHERE id = ?`)
+    .get(id) as { task_status: string | null; archived_at: string | null };
+  const task =
+    row.task_status === "dropped" ||
+    (row.task_status === "done" && !row.archived_at);
+  const go = () => resurrectSession(id);
+  const out = task
+    ? await braked(workspaceId, "task", go, (o) => o.id)
+    : await go();
+  addNote(workspaceId, `Restored ${out.name}: ${reason.trim()}`);
+  return out.text;
+}
+
 // Stops the agent and keeps everything else: a chat's turn is interrupted,
 // a terminal's tmux session ends. Its worktree and branch stay.
 export async function stop(workspaceId: string, ref: string): Promise<string> {
@@ -507,14 +533,27 @@ export function pauseTask(
   return `Pausing ${task.name} ${now ? "now" : "at the end of its step"}. Its slot frees once it has stopped; an event says when.`;
 }
 
-export function resumeTask(workspaceId: string, ref: string): string {
+export async function resumeTask(
+  workspaceId: string,
+  ref: string
+): Promise<string> {
   const task = workspaceTask(workspaceId, ref);
   if (!activePause(task.id)) throw new Error(`${task.name} isn't paused`);
+  const slots = task.project_id ? slotState(task.project_id) : null;
+  let out;
   try {
-    requestResume(task.id, "orchestrator");
+    out = await resumeNow(task.id, "orchestrator");
   } catch (error) {
     if (error instanceof PauseRefused) throw new Error(error.message);
     throw error;
   }
-  return `${task.name} will resume as soon as it has a slot.`;
+  if (out.outcome === "held")
+    return `${task.name} is ${out.note}. It resumes by itself when that clears.`;
+  if (out.outcome === "cancelled")
+    return `${task.name} keeps running: its pause was cancelled.`;
+  const past = slots?.full
+    ? ` past the running-task limit (${slots.running} of ${slots.limit} running)`
+    : "";
+  addNote(workspaceId, `Resumed ${task.name} now${past}.`);
+  return `Resumed ${task.name} now${past}. It carries on with what was held for it.`;
 }

package/lib/orchestrator/brief.ts

@@ -137,10 +137,11 @@ Acting:
 - \`${TOOL_NAMES.set_priority}\` (task, priority): re-rank a queued task (urgent, blocking, normal, background), or tag a running one. Urgent is a bug Saad hit; background starts last.
 - \`${TOOL_NAMES.start_now}\` (task, reason): start a queued task now, past the running-task limit and its after. Still refused while paused or braked, and a Mac-only task stays queued. Use it sparingly, when Saad asks or it unblocks others; the reason is logged for Saad.
 - \`${TOOL_NAMES.pause_task}\` (task, for, now?, reason): pause a running task for 1h, 2h, until tomorrow 9 AM or until resumed. Its agent ends at the end of its step (now interrupts the step); its worktree and conversation stay and its slot frees for the next queued task. It resumes by itself, ahead of new arrivals, with what was held (CI and review notes, messages) in one prompt. Use it to make room for urgent work or to wait out a loaded machine. Refused for a task that is merging, moving, setting up or waiting on Saad.
-- \`${TOOL_NAMES.resume_task}\` (task): resume a pause you set now. A pause Saad set is his to lift.
+- \`${TOOL_NAMES.resume_task}\` (task): resume a pause you set now, past the running-task limit unless the machine load holds it. A pause Saad set is his to lift.
 - \`${TOOL_NAMES.stop}\` (session): stop a session's agent, keeping its work.
 - \`${TOOL_NAMES.done}\` (session): finish a session whose work is complete. A task with an open PR merges through the same gates as sign_off first (refused naming the gate otherwise); then the agent stops, the worktree goes only if nothing in it would be lost, and the session lands on the sidebar's Done shelf (it is not archived). Not a rejection: use drop for that.
 - \`${TOOL_NAMES.archive}\` (session): put a session away, out of the sidebar, when Saad asks. Nothing is merged or cleaned up; refused while it works or has an open PR.
+- \`${TOOL_NAMES.resurrect}\` (session, reason): bring a dropped, done or archived session back with its conversation and worktree, in the state it had (a plan-only task waits for approval again). Use it when a drop or done was a mistake, or when Saad asks; refused for a merged PR, a missing conversation or a removed project. A restored task counts against the running limit and the brakes like a start.
 - \`${TOOL_NAMES.add_project}\` (path, name?): make a git repository on this machine a project of this workspace, or move the project already at that path in when it's in no workspace. Use it rather than sending Saad steps. It refuses a folder that isn't a git repository or holds secrets, and a project another workspace has: moving that is Saad's call, so ask_saad.
 - \`${TOOL_NAMES.note}\` (text): a line in this workspace's decision log, shown in your chat. Note each decision that matters, with why.
 - \`${TOOL_NAMES.rule_add}\` (text): keep a standing rule for this workspace, in your brief on every start. Saad sees and edits them in Settings → Workspaces.

package/lib/orchestrator/digest.ts

@@ -58,6 +58,7 @@ interface TaskRow {
   armed_at: string | null;
   pause_state: string | null;
   paused_until: string | null;
+  pause_note: string | null;
   placed_note: string | null;
 }
 
@@ -165,7 +166,7 @@ function tasksSection(
   const tasks = db
     .prepare(
       `SELECT s.id, s.name, p.name AS project, s.pr_number, s.pr_status, s.view,
-         s.merge_armed_at AS armed_at, s.pause_state, s.paused_until, s.placed_note
+         s.merge_armed_at AS armed_at, s.pause_state, s.paused_until, s.pause_note, s.placed_note
        FROM sessions s JOIN projects p ON p.id = s.project_id
        WHERE p.workspace_id = ? AND s.role IS NULL AND s.archived_at IS NULL
          AND s.task_status = 'running'
@@ -181,7 +182,7 @@ function tasksSection(
       const gates = gateState(checks.get(t.id), failures.get(t.id));
       const arm = t.armed_at ? " | armed to merge" : "";
       const paused = t.pause_state
-        ? ` | ${t.pause_state}${t.paused_until ? ` until ${t.paused_until} UTC` : t.pause_state === "paused" ? " until resumed" : ""}`
+        ? ` | ${t.pause_state}${t.paused_until ? ` until ${t.paused_until} UTC` : t.pause_state === "paused" ? " until resumed" : ""}${t.pause_note ? ` (${t.pause_note})` : ""}`
         : "";
       const placed = t.placed_note ? ` | ${t.placed_note}` : "";
       return `- ${clip(t.name, 80)} (${t.project ?? "?"}, ${t.view}, id ${shortId(t.id)}): ${pr}${arm}${paused}${placed}${gates ? ` | ${gates}` : ""}`;

package/lib/orchestrator/serve.ts

@@ -6,6 +6,7 @@ import {
   archive,
   done,
   drop,
+  resurrect,
   moveTaskTo,
   send,
   stack,
@@ -64,6 +65,7 @@ const ACTING = new Set<ToolName>([
   "stack",
   "land",
   "drop",
+  "resurrect",
   "move",
   "approve_plan",
   "plan_pieces",
@@ -219,6 +221,10 @@ export async function runTool(
       return done(w, p(tool, raw).session);
     case "archive":
       return archive(w, p(tool, raw).session);
+    case "resurrect": {
+      const a = p(tool, raw);
+      return resurrect(w, a.session, a.reason);
+    }
     case "add_project": {
       const a = p(tool, raw);
       return addProject(w, a.path, a.name);

package/lib/orchestrator/shell-guard.ts

@@ -211,7 +211,7 @@ const PULL_MERGE = /(^|\/)pulls\/[^/?\s]+\/merge\/?(\?|$)/;
 
 const MERGE_MSG = `Refused: a PR merges only through the gates: ${T.sign_off} (or ${T.arm}) for a task's or an external PR, ${T.land} for a stack. Nothing merges, closes or retargets a PR from the shell.`;
 
-// aos move, done, archive, stop and drop reach a session by name, past the tools'
+// aos move, done, archive, resurrect, stop and drop reach a session by name, past the tools'
 // Pause check and logging; the tools do the same work.
 function aosRefusal(args: string[]): string | null {
   const [sub] = positionals(args);
@@ -219,6 +219,7 @@ function aosRefusal(args: string[]): string | null {
     move: T.move,
     done: T.done,
     archive: T.archive,
+    resurrect: T.resurrect,
     stop: T.stop,
   };
   if (sub && tool[sub])

package/lib/orchestrator/tool-names.ts

@@ -36,6 +36,7 @@ export const TOOL_NAMES = {
   stop: name("stop"),
   done: name("done"),
   archive: name("archive"),
+  resurrect: name("resurrect"),
   add_project: name("add_project"),
   note: name("note"),
   question: name("question"),

package/lib/orchestrator/tool-schemas.ts

@@ -291,6 +291,12 @@ export const TOOL_SHAPES = {
   stop: { session },
   done: { session },
   archive: { session },
+  resurrect: {
+    session: ref(
+      "A dropped, done or archived session: its name, project/name or id (from the decision log, or as Saad named it)"
+    ),
+    reason: z.string().trim().min(1).max(2000),
+  },
   add_project: {
     path: z
       .string()

package/lib/orchestrator/tools.ts

@@ -88,11 +88,13 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   pause_task:
     "Pause a running task for a set time: its agent ends at the end of its current step (now true interrupts the step), its worktree and conversation stay, and it frees its slot so the next queued task can start. It resumes by itself at the time, ahead of new arrivals of the same priority, with whatever was held (CI and review notes, messages) in one continue prompt. Refused for a task that is merging, moving, setting up or waiting on Saad. Give a reason; it is shown with the pause.",
   resume_task:
-    "Resume a task you paused (or the scheduler did) now. A pause Saad set is his to lift: this refuses and says so.",
+    "Resume a task you paused (or the scheduler did) now: it starts at once, past the running-task limit, unless the machine load holds it (the answer says so). A pause Saad set is his to lift: this refuses and says so.",
   stop: "Stop a session's agent mid-turn, even while it's thinking, keeping its conversation, worktree and branch; your next message runs as its next turn.",
   done: "Finish a session whose work is complete: a task's open PR merges through the sign-off gates first (refused naming the failing gate), then its agent stops, its worktree is removed if nothing would be lost, and it lands on the sidebar's Done shelf; it no longer archives (use archive for that). Not a rejection.",
   archive:
     "Put a finished session away, out of the sidebar (it stays in Archived, and Saad can unarchive it). Nothing is merged or cleaned up: refused while the session is working or has an open PR; done first for finished work.",
+  resurrect:
+    "Bring a dropped, done or archived session back: the same session and conversation, its worktree (with its uncommitted files and plan) back from what was saved or from its branch, its status as it was (a plan-only task waits for approval again, one with a PR is idle), and a PR a drop closed reopened. Archived sessions just unarchive. Held by Pause and braked like a start. Refused when its conversation is gone, its PR was merged, its project was removed or its branch is in use. Give a reason; it goes in the decision log.",
   add_project:
     "Make a git repository on this machine a project of this workspace, by its absolute path, or move the project already at that path into this workspace when it's in no workspace. Says its default branch, detected from git. Refuses a folder that isn't a git repository or that holds secrets, and a project another workspace has.",
   note: "Add a line to this workspace's decision log; it shows in your chat.",

package/lib/resurrect/find.ts

@@ -0,0 +1,111 @@
+/** Sessions that ended (dropped, done, archived) and can be asked for back. */
+
+import { db } from "../db";
+import { resolveRef } from "../bus/resolve";
+
+export type EndedKind = "dropped" | "done" | "archived" | "settled";
+
+export interface EndedSession {
+  id: string;
+  name: string;
+  projectId: string | null;
+  projectName: string | null;
+  kind: EndedKind;
+  taskStatus: string | null;
+  // A plan-only task whose plan was written and never approved.
+  planWaiting: boolean;
+  endedAt: string;
+}
+
+// A workspace's, or one project's, or everyone's (a person's own shell).
+export type EndedScope = { workspaceId: string } | { projectId: string } | null;
+
+interface Row {
+  id: string;
+  name: string;
+  tmux_name: string;
+  project_id: string | null;
+  project_name: string | null;
+  task_status: string | null;
+  archived_at: string | null;
+  plan_phase: string | null;
+  ended_at: string;
+}
+
+function kindOf(r: Row): EndedKind {
+  if (r.task_status === "dropped") return "dropped";
+  if (r.archived_at) return "archived";
+  return r.task_status === "done" ? "done" : "settled";
+}
+
+function rows(scope: EndedScope, limit: number, kind?: EndedKind): Row[] {
+  const where = [
+    "s.role IS NULL",
+    "s.peer_mirror = 0",
+    "s.held_by_device IS NULL",
+  ];
+  const args: (string | number)[] = [];
+  if (scope && "workspaceId" in scope) {
+    where.push("p.workspace_id = ?");
+    args.push(scope.workspaceId);
+  } else if (scope) {
+    where.push("s.project_id = ?");
+    args.push(scope.projectId);
+  }
+  where.push(
+    `(s.archived_at IS NOT NULL OR s.task_status IN ('dropped', 'done')
+       OR (s.task_status IS NULL AND s.settled_at IS NOT NULL))`
+  );
+  if (kind === "dropped") where.push("s.task_status = 'dropped'");
+  if (kind === "archived") where.push("s.archived_at IS NOT NULL");
+  if (kind === "done")
+    where.push("s.task_status = 'done' AND s.archived_at IS NULL");
+  return db
+    .prepare(
+      `SELECT s.id, s.name, s.tmux_name, s.project_id, p.name AS project_name,
+         s.task_status, s.archived_at, s.plan_phase,
+         COALESCE(s.task_ended_at, s.archived_at, s.settled_at, s.updated_at) AS ended_at
+       FROM sessions s LEFT JOIN projects p ON p.id = s.project_id
+       WHERE ${where.join(" AND ")}
+       ORDER BY ended_at DESC LIMIT ?`
+    )
+    .all(...args, limit) as Row[];
+}
+
+export function endedSessions(
+  scope: EndedScope,
+  opts: { limit?: number; kind?: EndedKind } = {}
+): EndedSession[] {
+  return rows(scope, opts.limit ?? 50, opts.kind).map((r) => ({
+    id: r.id,
+    name: r.name,
+    projectId: r.project_id,
+    projectName: r.project_name,
+    kind: kindOf(r),
+    taskStatus: r.task_status,
+    planWaiting: r.plan_phase === "awaiting",
+    endedAt: r.ended_at,
+  }));
+}
+
+/** An ended session by name, project/name, id or id prefix, within the scope. */
+export function resolveEnded(ref: string, scope: EndedScope): string {
+  const all = rows(scope, 500);
+  const r = resolveRef(
+    ref,
+    all.map((s) => ({
+      id: s.id,
+      name: s.name,
+      projectName: s.project_name,
+      tmuxName: s.tmux_name,
+      previousNames: [],
+    }))
+  );
+  if (!r.ok)
+    throw new Error(
+      r.reason === "none"
+        ? `No dropped, done or archived session "${ref}"${scope ? " here" : ""}.`
+        : r.error
+    );
+  return r.id;
+}