@saadnvd1/agent-os 0.3.592 → 0.3.594

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;
+}

package/lib/resurrect/index.ts

@@ -0,0 +1,422 @@
+/**
+ * Resurrect: bring a dropped, done or archived session back with the same id
+ * and the same agent conversation. An archived session is unarchived; a plain
+ * one on the Done shelf is reopened; a task gets its worktree back (from the
+ * snapshot an end saved, or its branch), its status back to what it was (a
+ * plan-only task waits for approval again, one with a PR is idle) and a PR
+ * that a drop closed is reopened. Everything is checked before anything is
+ * changed, and a failure part-way puts the status back. The agent isn't
+ * started: a chat resumes on its next message, so a restore costs no tokens.
+ */
+
+import fs from "fs";
+import path from "path";
+import { db, queries, type Session } from "../db";
+import { getProject } from "../projects";
+import { unarchiveSession } from "../done/archive";
+import { reopenSession } from "../sidebar/shelf-state";
+import { peerSessionLink } from "../hosts/peer-actions";
+import { hostApi, hostLink } from "../hosts/remote-api";
+import { forgetHostTasks, isMirror, unknownOutcome } from "../tasks/remote";
+import { heldRefusal } from "../tasks/held";
+import { expandHome, projectPathFor } from "../tasks/session";
+import { run } from "../tasks/gh";
+import { gitPush } from "../git-exec";
+import {
+  isClaudeSessionId,
+  readTranscript,
+  rewritePaths,
+  transcriptPath,
+  writeTranscript,
+} from "../tasks/transcript";
+import { buildTaskBrief } from "../tasks/brief";
+import { syncTaskCardInBackground } from "../lumifyhub/task-cards";
+import { allocatePorts } from "../ports";
+import { loadProjectConfig, portBases } from "../project-config";
+import { ensureSessionDatabase } from "../project-config/database";
+import { runInBackground } from "../async-operations";
+import { setupWorktree } from "../env-setup";
+import { launchClaude } from "../agents/launch";
+import { PLAN_FILE, preparePlanDir } from "../models/plan-step";
+import { planFromTranscript } from "./plan";
+import { dropSnapshot, restoreWorktree, type RestoredAs } from "./snapshot";
+
+export interface ResurrectOptions {
+  // The paired device asking: a task held for another machine's orchestrator
+  // is restored only from there.
+  device?: string | null;
+}
+
+export interface ResurrectOutcome {
+  id: string;
+  name: string;
+  restored: "unarchived" | "reopened" | "task";
+  worktree: RestoredAs | "chat-only" | "none";
+  prReopened: number | null;
+  text: string;
+}
+
+const row = (id: string) =>
+  queries.getSession(db).get(id) as Session | undefined;
+
+const ENDED_TASK = new Set(["dropped", "done"]);
+
+// Restores in flight here, so two clicks can't both build a worktree.
+const g = globalThis as unknown as { __agentosResurrecting?: Set<string> };
+const inFlight = (g.__agentosResurrecting ??= new Set());
+
+interface PrInfo {
+  number: number;
+  state: string;
+}
+
+// The task's PR as GitHub has it now. Throws when GitHub can't be asked: a
+// merged PR must never be mistaken for an open one.
+async function prState(repo: string, number: number): Promise<PrInfo | null> {
+  const out = await run(
+    "gh",
+    ["pr", "view", String(number), "--json", "number,state"],
+    repo
+  ).catch((err) => {
+    throw new Error(
+      `Can't check PR #${number} on GitHub (${(err as Error).message.split("\n")[0]}); try again.`
+    );
+  });
+  try {
+    const pr = JSON.parse(out) as PrInfo;
+    return typeof pr.state === "string" ? pr : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function resurrectSession(
+  id: string,
+  opts: ResurrectOptions = {}
+): Promise<ResurrectOutcome> {
+  const s = row(id);
+  if (!s) throw new Error("Session not found");
+  if (s.role === "orchestrator")
+    throw new Error(`${s.name} is an orchestrator; it isn't ended.`);
+  const held = opts.device !== undefined && heldRefusal(id, opts.device);
+  if (held) throw new Error(held);
+  const peer = peerSessionLink(s);
+  if (peer)
+    throw new Error(`${s.name} runs on ${peer.hostName}: restore it there.`);
+  if (isMirror(s)) return onItsMachine(s);
+
+  const endedTask = !!s.task_status && ENDED_TASK.has(s.task_status);
+  if (s.task_status === "merged")
+    throw new Error(
+      `${s.name} was merged: its work is in the base branch. Start a new task to continue it.`
+    );
+  if (s.task_status === "running" || s.task_status === "moving")
+    throw new Error(`${s.name} is still running; nothing to restore.`);
+  if (s.task_status === "moved")
+    throw new Error(`${s.name} was moved to another machine; it runs there.`);
+
+  // Archived work just unarchives; a dropped task is hidden either way, so
+  // restoring it is the whole of it.
+  if (!endedTask || (s.archived_at && s.task_status !== "dropped")) {
+    if (s.archived_at) {
+      unarchiveSession(id);
+      return outcome(s, "unarchived", `${s.name} is back in the sidebar.`);
+    }
+    if (s.settled_at) {
+      reopenSession(id);
+      return outcome(s, "reopened", `${s.name} reopened.`);
+    }
+    throw new Error(`${s.name} isn't dropped, done or archived.`);
+  }
+  return restoreTask(s, s.task_status as "dropped" | "done");
+}
+
+const outcome = (
+  s: Pick<Session, "id" | "name">,
+  restored: ResurrectOutcome["restored"],
+  text: string,
+  extra: Partial<ResurrectOutcome> = {}
+): ResurrectOutcome => ({
+  id: s.id,
+  name: s.name,
+  restored,
+  worktree: "none",
+  prReopened: null,
+  text,
+  ...extra,
+});
+
+// A task that runs on a linked machine resumes there; when that machine is
+// gone for good, the task it was moved from is brought back here instead.
+async function onItsMachine(s: Session): Promise<ResurrectOutcome> {
+  const link = hostLink(s.host_id);
+  if (link) {
+    try {
+      const res = await hostApi<{ outcome?: Partial<ResurrectOutcome> }>(
+        link,
+        `/api/sessions/${encodeURIComponent(s.id)}/resurrect`,
+        { body: {}, timeout: 120_000 }
+      );
+      db.prepare(
+        `UPDATE sessions SET task_status = 'running' WHERE id = ? AND task_status IN ('dropped', 'done')`
+      ).run(s.id);
+      forgetHostTasks(link.hostId);
+      return outcome(
+        s,
+        "task",
+        `${link.hostName}: ${String(res.outcome?.text ?? `${s.name} restored.`).slice(0, 500)}`
+      );
+    } catch (err) {
+      if (!unknownOutcome(err)) throw err;
+    }
+  }
+  const before = db
+    .prepare(
+      `SELECT * FROM sessions WHERE host_id = 'local' AND task_status = 'moved'
+         AND project_id IS ? AND branch_name IS ? ORDER BY updated_at DESC LIMIT 1`
+    )
+    .get(s.project_id, s.branch_name) as Session | undefined;
+  const where = link?.hostName ?? "its machine";
+  if (!before)
+    throw new Error(
+      `${s.name} ran on ${where}, which can't be reached, and nothing of it was kept here.`
+    );
+  const here = await restoreTask(before, "moved");
+  return {
+    ...here,
+    text: `${where} can't be reached, so ${here.name} is back here from before it moved: anything it did there that was never pushed is lost. ${here.text}`,
+  };
+}
+
+async function restoreTask(
+  s: Session,
+  prev: "dropped" | "done" | "moved"
+): Promise<ResurrectOutcome> {
+  const project = s.project_id ? getProject(s.project_id) : null;
+  const repo = project ? projectPathFor(s) : null;
+  if (!project || !repo)
+    throw new Error(`${s.name}'s project was removed; it can't come back.`);
+  if (!fs.existsSync(repo))
+    throw new Error(`${s.name}'s project folder ${repo} is gone.`);
+  const oldCwd = expandHome(s.worktree_path ?? s.working_directory);
+  const claudeId = s.claude_session_id;
+  if (claudeId) {
+    if (
+      !isClaudeSessionId(claudeId) ||
+      !fs.existsSync(transcriptPath(oldCwd, claudeId))
+    )
+      throw new Error(
+        `${s.name}'s conversation is gone (no transcript on disk), so it can't be resumed. Start a new task.`
+      );
+  } else if (
+    !db
+      .prepare(`SELECT 1 FROM chat_items WHERE session_id = ? LIMIT 1`)
+      .get(s.id)
+  )
+    throw new Error(`${s.name} has no conversation to bring back.`);
+  if (s.branch_name) {
+    const busy = db
+      .prepare(
+        `SELECT name FROM sessions WHERE project_id = ? AND branch_name = ? AND id != ?
+           AND task_status IN ('running', 'moving') AND host_id = 'local'`
+      )
+      .get(project.id, s.branch_name, s.id) as { name: string } | undefined;
+    if (busy)
+      throw new Error(
+        `${busy.name} is running on ${s.branch_name} now; finish or drop it first.`
+      );
+  }
+  const pr =
+    s.pr_number && s.pr_status !== "merged"
+      ? await prState(repo, s.pr_number)
+      : null;
+  if (s.pr_status === "merged" || pr?.state === "MERGED")
+    throw new Error(
+      `${s.name}'s PR #${s.pr_number} was merged; start a new task to continue it.`
+    );
+
+  if (inFlight.has(s.id))
+    throw new Error(`${s.name} is being restored already.`);
+  inFlight.add(s.id);
+  const claimed = db
+    .prepare(
+      `UPDATE sessions SET task_status = 'running', task_ended_at = NULL WHERE id = ? AND task_status = ?`
+    )
+    .run(s.id, prev).changes;
+  if (!claimed) {
+    inFlight.delete(s.id);
+    throw new Error(`${s.name} is being restored already.`);
+  }
+  try {
+    return await bringBack(s, prev, repo, oldCwd, pr);
+  } catch (err) {
+    db.prepare(
+      `UPDATE sessions SET task_status = ? WHERE id = ? AND task_status = 'running'`
+    ).run(prev, s.id);
+    throw err;
+  } finally {
+    inFlight.delete(s.id);
+  }
+}
+
+// Claude files a conversation under the folder it ran in: a worktree that
+// comes back elsewhere takes its transcript with it.
+async function carryTranscript(
+  claudeId: string,
+  from: string,
+  to: string
+): Promise<void> {
+  if (path.resolve(from) === path.resolve(to)) return;
+  const text = await readTranscript(from, claudeId);
+  if (text === null) return;
+  const home = process.env.HOME ?? "";
+  await writeTranscript(
+    to,
+    claudeId,
+    rewritePaths(text, { cwd: from, home }, { cwd: to, home })
+  );
+}
+
+async function bringBack(
+  s: Session,
+  prev: "dropped" | "done" | "moved",
+  repo: string,
+  oldCwd: string,
+  pr: PrInfo | null
+): Promise<ResurrectOutcome> {
+  // A plan that was never approved has no commits to lose.
+  const planOnly =
+    !!s.plan_only &&
+    !s.pr_number &&
+    (s.plan_phase === "awaiting" || s.plan_phase === "planning");
+  const restored = s.branch_name
+    ? await restoreWorktree({
+        sessionId: s.id,
+        repo,
+        branch: s.branch_name,
+        base: s.base_branch,
+        oldPath: s.worktree_path ? expandHome(s.worktree_path) : null,
+        allowFresh: planOnly,
+      })
+    : null;
+  const cwd = restored?.path ?? repo;
+  if (s.claude_session_id)
+    await carryTranscript(s.claude_session_id, oldCwd, cwd);
+
+  if (restored && s.plan_phase === "awaiting")
+    await recoverPlan(s, restored.path, oldCwd);
+
+  const notes: string[] = [];
+  if (!restored) {
+    // Nothing to make a worktree from: the conversation alone, in the project.
+    db.prepare(
+      `UPDATE sessions SET task_status = NULL, task_ended_at = NULL, worktree_path = NULL,
+         working_directory = ?, settled_at = NULL, snoozed_until = NULL, snoozed_at = NULL,
+         archived_at = NULL, active_at = datetime('now') WHERE id = ?`
+    ).run(cwd, s.id);
+    notes.push(
+      "its branch and worktree were gone, so only the conversation came back, in the project folder"
+    );
+  } else {
+    db.prepare(
+      `UPDATE sessions SET worktree_path = ?, working_directory = ?, settled_at = NULL,
+         snoozed_until = NULL, snoozed_at = NULL, archived_at = NULL,
+         active_at = datetime('now') WHERE id = ?`
+    ).run(restored.path, restored.path, s.id);
+    if (restored.mode !== "kept") await setUp(s, repo, restored.path);
+    if (restored.mode === "fresh")
+      notes.push(
+        "its branch was gone: a new one from its base (it had no commits)"
+      );
+  }
+
+  let reopened: number | null = null;
+  if (restored && pr?.state === "CLOSED" && prev === "dropped") {
+    try {
+      await gitPush(restored.path, ["-u", "origin", s.branch_name!]);
+      await run("gh", ["pr", "reopen", String(pr.number)], repo);
+      db.prepare(`UPDATE sessions SET pr_status = 'open' WHERE id = ?`).run(
+        s.id
+      );
+      reopened = pr.number;
+    } catch (err) {
+      notes.push(
+        `PR #${pr.number} stays closed (${(err as Error).message.split("\n")[0]})`
+      );
+    }
+  } else if (pr?.state === "CLOSED")
+    notes.push(`PR #${pr.number} stays closed: it wasn't closed by a drop`);
+
+  const after = row(s.id)!;
+  if (restored && after.view !== "chat") await relaunch(after, restored.path);
+  syncTaskCardInBackground(after, "working", null);
+  void dropSnapshot(repo, s.id);
+  const text = `${s.name} is back${restored ? ` in ${restored.path}` : ""}${reopened ? `, PR #${reopened} reopened` : ""}${notes.length ? `; ${notes.join("; ")}` : ""}.`;
+  return outcome(s, "task", text, {
+    worktree: restored?.mode ?? "chat-only",
+    prReopened: reopened,
+  });
+}
+
+// A plan-only task's plan isn't in git: the snapshot has it, otherwise the
+// conversation's own Write of it does.
+async function recoverPlan(
+  s: Session,
+  worktree: string,
+  oldCwd: string
+): Promise<void> {
+  if (fs.existsSync(path.join(worktree, PLAN_FILE))) return;
+  if (!s.claude_session_id) return;
+  const text = await readTranscript(oldCwd, s.claude_session_id);
+  const plan = text && planFromTranscript(text);
+  if (!plan) return;
+  preparePlanDir(worktree);
+  fs.writeFileSync(path.join(worktree, PLAN_FILE), plan);
+}
+
+// Ports, its private database and the setup commands, the way a move's
+// arrival does. A failure here leaves the worktree usable.
+async function setUp(
+  s: Session,
+  repo: string,
+  worktree: string
+): Promise<void> {
+  try {
+    const { config } = loadProjectConfig(repo);
+    const { ports } = await allocatePorts(s.id, portBases(config));
+    if (config.database) await ensureSessionDatabase(s.id, config.database);
+    runInBackground(
+      () =>
+        setupWorktree({
+          worktreePath: worktree,
+          sourcePath: repo,
+          ports,
+          sessionId: s.id,
+        }).then(() => {}),
+      `setup-restored-${s.id}`
+    );
+  } catch (err) {
+    console.error(`[resurrect] setup for ${s.id}:`, err);
+  }
+}
+
+// A terminal task's agent is a process, so it's started again on its
+// conversation. (A chat's worker starts with its next message.)
+async function relaunch(s: Session, cwd: string): Promise<void> {
+  await launchClaude({
+    sessionId: s.id,
+    tmuxName: s.tmux_name,
+    cwd,
+    model: s.model,
+    prompt: s.claude_session_id
+      ? "This task was dropped and has been restored. Carry on where you left off."
+      : (s.task_prompt ?? ""),
+    resume: s.claude_session_id ?? undefined,
+    brief: s.branch_name
+      ? buildTaskBrief({
+          branch: s.branch_name,
+          baseBranch: s.base_branch ?? "main",
+        })
+      : undefined,
+  });
+}