@saadnvd1/agent-os 0.3.592 → 0.3.594

package/app/api/bus/resurrect/route.test.ts

@@ -0,0 +1,47 @@
+import { NextRequest } from "next/server";
+import { describe, expect, it, vi } from "vitest";
+
+const resurrect = vi.hoisted(() => vi.fn());
+vi.mock("@/lib/resurrect", () => ({ resurrectSession: resurrect }));
+
+const { db } = await import("@/lib/db");
+const { seedWorkspace } = await import("@/lib/orchestrator/testing");
+const { POST } = await import("./route");
+
+const call = (body: object) =>
+  POST(
+    new NextRequest("http://localhost/api/bus/resurrect", {
+      method: "POST",
+      body: JSON.stringify(body),
+    })
+  );
+
+describe("POST /api/bus/resurrect (aos resurrect)", () => {
+  it("runs only from inside a session", async () => {
+    const res = await call({ session: "x" });
+    expect(res.status).toBe(409);
+    expect((await res.json()).error).toMatch(/inside an AgentOS session/);
+  });
+
+  it("reaches only the caller's workspace, and lists what ended with no session", async () => {
+    const mine = seedWorkspace("Bus mine");
+    const other = seedWorkspace("Bus other");
+    db.prepare(`UPDATE sessions SET task_status = 'dropped' WHERE id = ?`).run(
+      mine.task
+    );
+    db.prepare(`UPDATE sessions SET task_status = 'dropped' WHERE id = ?`).run(
+      other.task
+    );
+    const list = await (await call({ from: mine.chat })).json();
+    expect(list.sessions.map((s: { id: string }) => s.id)).toEqual([mine.task]);
+
+    const refused = await call({ from: mine.chat, session: other.task });
+    expect(refused.status).toBe(409);
+    expect(resurrect).not.toHaveBeenCalled();
+
+    resurrect.mockResolvedValueOnce({ text: "back" });
+    const ok = await call({ from: mine.chat, session: mine.task });
+    expect((await ok.json()).summary).toBe("back");
+    expect(resurrect).toHaveBeenCalledWith(mine.task);
+  });
+});

package/app/api/bus/resurrect/route.ts

@@ -0,0 +1,36 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getDoneTarget } from "@/lib/done";
+import { scopeOf } from "@/lib/done/bulk";
+import { resurrectSession } from "@/lib/resurrect";
+import { endedSessions, resolveEnded } from "@/lib/resurrect/find";
+
+// `aos resurrect [session]`, from inside a session: reaches only the
+// caller's workspace (or its project when it has none). Without a session it
+// lists the dropped and done ones that can come back.
+export async function POST(request: NextRequest) {
+  try {
+    const { from = null, session } = await request.json();
+    if (typeof from !== "string" || !from)
+      throw new Error("aos resurrect runs from inside an AgentOS session");
+    const scope = scopeOf(getDoneTarget(from));
+    if (typeof session !== "string" || !session.trim()) {
+      const ended = endedSessions(scope, { limit: 15 });
+      return NextResponse.json({
+        sessions: ended,
+        summary: ended.length
+          ? ended
+              .map(
+                (e) =>
+                  `${e.id.slice(0, 8)}  ${e.kind.padEnd(8)}  ${e.projectName ? `${e.projectName}/` : ""}${e.name}`
+              )
+              .join("\n")
+          : "Nothing dropped, done or archived to restore.",
+      });
+    }
+    const outcome = await resurrectSession(resolveEnded(session, scope));
+    return NextResponse.json({ summary: outcome.text, outcome });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 409 });
+  }
+}

package/app/api/sessions/[id]/pause/route.ts

@@ -89,8 +89,11 @@ export async function DELETE(
 ) {
   const { id } = await params;
   try {
-    await resumeNow(id, "person");
-    return NextResponse.json({ pause: pauseViewOf(id) });
+    const out = await resumeNow(id, "person");
+    return NextResponse.json({
+      pause: pauseViewOf(id),
+      ...(out.outcome === "held" && { note: out.note }),
+    });
   } catch (error) {
     return fail(error);
   }

package/app/api/sessions/[id]/resurrect/route.test.ts

@@ -0,0 +1,32 @@
+import { NextRequest } from "next/server";
+import { describe, expect, it, vi } from "vitest";
+
+const resurrect = vi.hoisted(() => vi.fn());
+vi.mock("@/lib/resurrect", () => ({ resurrectSession: resurrect }));
+
+const { POST } = await import("./route");
+
+const call = (id: string) =>
+  POST(
+    new NextRequest(`http://localhost/api/sessions/${id}/resurrect`, {
+      method: "POST",
+    }),
+    { params: Promise.resolve({ id }) }
+  );
+
+describe("POST /api/sessions/:id/resurrect", () => {
+  it("answers with the outcome", async () => {
+    resurrect.mockResolvedValueOnce({ id: "s1", text: "back" });
+    const res = await call("s1");
+    expect(res.status).toBe(200);
+    expect((await res.json()).outcome).toEqual({ id: "s1", text: "back" });
+    expect(resurrect).toHaveBeenCalledWith("s1", { device: null });
+  });
+
+  it("answers a refusal with 409 and the reason", async () => {
+    resurrect.mockRejectedValueOnce(new Error("its PR #3 was merged"));
+    const res = await call("s2");
+    expect(res.status).toBe(409);
+    expect(await res.json()).toEqual({ error: "its PR #3 was merged" });
+  });
+});

package/app/api/sessions/[id]/resurrect/route.ts

@@ -0,0 +1,24 @@
+import { NextRequest, NextResponse } from "next/server";
+import { resurrectSession } from "@/lib/resurrect";
+import { callingDevice } from "@/lib/security/device-me";
+import { db, queries, type Session } from "@/lib/db";
+
+// POST /api/sessions/:id/resurrect - bring a dropped, done or archived
+// session back: same id, same conversation, its status as it was. A refusal
+// (merged PR, conversation gone, project removed) is a 409 with the reason.
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const id = (await params).id;
+    const outcome = await resurrectSession(id, {
+      device: callingDevice(request),
+    });
+    const session = queries.getSession(db).get(id) as Session | undefined;
+    return NextResponse.json({ outcome, session });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 409 });
+  }
+}

package/app/api/sessions/ended/route.ts

@@ -0,0 +1,19 @@
+import { NextRequest, NextResponse } from "next/server";
+import { endedSessions, type EndedKind } from "@/lib/resurrect/find";
+
+const KINDS = new Set(["dropped", "done", "archived"]);
+
+// GET /api/sessions/ended[?workspace=id][&kind=dropped|done|archived][&limit=n]
+// - what can be restored, most recently ended first.
+export async function GET(request: NextRequest) {
+  const q = request.nextUrl.searchParams;
+  const workspace = q.get("workspace");
+  const kind = q.get("kind");
+  const limit = Math.min(Math.max(Number(q.get("limit")) || 50, 1), 200);
+  return NextResponse.json({
+    sessions: endedSessions(workspace ? { workspaceId: workspace } : null, {
+      limit,
+      kind: kind && KINDS.has(kind) ? (kind as EndedKind) : undefined,
+    }),
+  });
+}

package/components/Archived/ArchivedRow.tsx

@@ -3,7 +3,7 @@
 import { ArchiveRestore, ExternalLink, Loader2 } from "lucide-react";
 import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
-import { useUnarchiveSession } from "@/data/done";
+import { useResurrectSession } from "@/data/done";
 import type { ArchivedView } from "@/lib/done/archive";
 import { fromSqliteTime } from "@/lib/session-meta";
 
@@ -24,7 +24,7 @@ function when(at: string): string {
 }
 
 export function ArchivedRow({ session }: { session: ArchivedView }) {
-  const unarchive = useUnarchiveSession();
+  const restore = useResurrectSession();
   const kind = session.taskStatus ? STATUS[session.taskStatus] : "Session";
 
   return (
@@ -70,20 +70,24 @@ export function ArchivedRow({ session }: { session: ArchivedView }) {
               ? "Puts the entry back in the sidebar; its worktree was removed"
               : undefined
           }
-          disabled={unarchive.isPending}
+          disabled={restore.isPending}
           onClick={() =>
-            unarchive.mutate(session.id, {
-              onSuccess: () => toast.success(`${session.name} is back`),
+            restore.mutate(session.id, {
+              onSuccess: (outcome) => toast.success(outcome.text),
               onError: (e) => toast.error(e.message),
             })
           }
         >
-          {unarchive.isPending ? (
+          {restore.isPending ? (
             <Loader2 className="h-3.5 w-3.5 animate-spin" />
           ) : (
             <ArchiveRestore className="h-3.5 w-3.5" />
           )}
-          {session.worktreeRemoved ? "Restore entry" : "Unarchive"}
+          {session.taskStatus === "dropped"
+            ? "Restore"
+            : session.worktreeRemoved
+              ? "Restore entry"
+              : "Unarchive"}
         </Button>
       )}
     </div>

package/components/Chat/PausedBanner.tsx

@@ -28,7 +28,7 @@ export function PausedBanner({ sessionId }: { sessionId: string }) {
         className="h-4 w-4 shrink-0 text-amber-600 dark:text-amber-400"
       />
       <p className="min-w-0 flex-1 text-sm">
-        {pauseSubtitle({ state, until })}
+        {pauseSubtitle({ state, until, note: session.pause_note })}
         <span className="text-muted-foreground block text-xs">
           Messages you send now are held and delivered together when it resumes.
         </span>

package/components/SessionList/RowSubtitle.tsx

@@ -67,6 +67,7 @@ export function RowSubtitle({
             until: session.paused_until
               ? Date.parse(`${session.paused_until.replace(" ", "T")}Z`)
               : null,
+            note: session.pause_note,
           })}
         </span>
       ) : (

package/components/SessionList/SessionRowMenu.tsx

@@ -34,7 +34,11 @@ import { schedulesUiActions } from "@/stores/schedulesUi";
 import { recipesUiActions } from "@/stores/recipesUi";
 import { rowGroup } from "@/lib/recipes/chip";
 import { finishActions } from "@/lib/sidebar/row-actions";
-import { useArchiveAction, useDoneAction } from "./useDoneAction";
+import {
+  useArchiveAction,
+  useDoneAction,
+  useResurrectAction,
+} from "./useDoneAction";
 import { useShelfActions } from "./useShelfActions";
 import {
   PAUSE_PRESETS,
@@ -106,6 +110,7 @@ function FinishItems({
 }) {
   const markDone = useDoneAction();
   const archive = useArchiveAction();
+  const restore = useResurrectAction();
   const actions = finishActions(session, plain);
   return (
     <>
@@ -115,6 +120,12 @@ function FinishItems({
           Done
         </Item>
       )}
+      {actions.includes("restore") && (
+        <Item onClick={() => restore(session)}>
+          <RotateCcw className={icon} />
+          Restore
+        </Item>
+      )}
       {actions.includes("archive") && (
         <Item onClick={() => archive(session)}>
           <Archive className={icon} />

package/components/SessionList/useDoneAction.ts

@@ -3,6 +3,7 @@ import type { Session } from "@/lib/db";
 import {
   useArchiveSession,
   useDoneSession,
+  useResurrectSession,
   useUnarchiveSession,
 } from "@/data/done";
 import { useSettleSession } from "@/data/sessions/shelf";
@@ -68,3 +69,16 @@ export function useArchiveAction() {
       onError: (e) => toast.error(e.message, { duration: 12000 }),
     });
 }
+
+// Restore from a session's menu: the same conversation, its worktree back.
+export function useResurrectAction() {
+  const resurrect = useResurrectSession();
+  return (session: Session) => {
+    const id = toast.loading(`Restoring ${session.name}…`);
+    resurrect.mutate(session.id, {
+      onSuccess: (outcome) =>
+        toast.success(outcome.text, { id, duration: 8000 }),
+      onError: (e) => toast.error(e.message, { id, duration: 12000 }),
+    });
+  };
+}

package/components/SessionList/useResurrectAction.test.ts

@@ -0,0 +1,96 @@
+import "@/components/Chat/composer/test-dom";
+import { act, createElement, useEffect } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Session } from "@/lib/db/types";
+
+const toast = vi.hoisted(() =>
+  Object.assign(vi.fn(), {
+    loading: vi.fn(() => "t1"),
+    success: vi.fn(),
+    error: vi.fn(),
+  })
+);
+vi.mock("sonner", () => ({ toast }));
+
+const { useResurrectAction } = await import("./useDoneAction");
+
+(
+  globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root;
+let host: HTMLElement;
+const hook: { current: (s: Session) => void } = { current: () => {} };
+const fetchSpy = vi.fn();
+
+function Probe() {
+  const restore = useResurrectAction();
+  useEffect(() => {
+    hook.current = restore;
+  });
+  return null;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.stubGlobal("fetch", fetchSpy);
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() =>
+    root.render(
+      createElement(
+        QueryClientProvider,
+        { client: new QueryClient() },
+        createElement(Probe)
+      )
+    )
+  );
+});
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+  vi.unstubAllGlobals();
+});
+
+const task = {
+  id: "s1",
+  name: "Bookmark plan",
+  task_status: "done",
+} as Session;
+const respond = (status: number, body: object) =>
+  fetchSpy.mockResolvedValue({
+    ok: status < 400,
+    status,
+    json: async () => body,
+  });
+const restore = async () => {
+  await act(async () => {
+    hook.current(task);
+    await new Promise((r) => setTimeout(r, 0));
+  });
+};
+
+describe("Restore from a session's menu", () => {
+  it("posts to the resurrect route and shows what came back", async () => {
+    respond(200, { outcome: { text: "Bookmark plan is back" } });
+    await restore();
+    expect(fetchSpy.mock.calls[0][0]).toBe("/api/sessions/s1/resurrect");
+    expect(fetchSpy.mock.calls[0][1]).toMatchObject({ method: "POST" });
+    expect(toast.success).toHaveBeenCalledWith(
+      "Bookmark plan is back",
+      expect.objectContaining({ id: "t1" })
+    );
+  });
+
+  it("shows a refusal's reason", async () => {
+    respond(409, { error: "its PR #3 was merged" });
+    await restore();
+    expect(toast.error).toHaveBeenCalledWith(
+      "its PR #3 was merged",
+      expect.objectContaining({ id: "t1" })
+    );
+  });
+});

package/components/Tasks/TaskRow.tsx

@@ -5,6 +5,7 @@ import {
   ChefHat,
   ExternalLink,
   GitMerge,
+  RotateCcw,
   KanbanSquare,
   SquareTerminal,
 } from "lucide-react";
@@ -12,6 +13,7 @@ import { Button } from "@/components/ui/button";
 import type { TaskView } from "@/lib/tasks";
 import { isFinished } from "@/lib/tasks/state";
 import { useArmTask, useDropTask, useSignOffTask } from "@/data/tasks";
+import { useResurrectSession } from "@/data/done";
 import { tmuxAttachActions } from "@/stores/tmuxAttach";
 import { tasksUiActions } from "@/stores/tasksUi";
 import { recipesUiActions } from "@/stores/recipesUi";
@@ -27,6 +29,7 @@ export function TaskRow({ task }: { task: TaskView }) {
   const signOff = useSignOffTask();
   const drop = useDropTask();
   const arm = useArmTask();
+  const restore = useResurrectSession();
   const [confirmDrop, setConfirmDrop] = useState(false);
   const [moveError, setMoveError] = useState<string | null>(null);
   const live = !isFinished(task.state);
@@ -34,6 +37,7 @@ export function TaskRow({ task }: { task: TaskView }) {
     signOff.error?.message ||
     drop.error?.message ||
     arm.error?.message ||
+    restore.error?.message ||
     moveError ||
     task.hostError;
   const settingUp = live && task.setup?.status === "running";
@@ -165,6 +169,20 @@ export function TaskRow({ task }: { task: TaskView }) {
         </div>
       )}
       {live && task.state === "plan-ready" && <PlanReview task={task} />}
+      {!live && task.state !== "merged" && (
+        <div>
+          <Button
+            size="sm"
+            variant="outline"
+            className="h-11 md:h-8"
+            disabled={restore.isPending}
+            onClick={() => restore.mutate(task.id)}
+          >
+            <RotateCcw className="h-3.5 w-3.5" />
+            {restore.isPending ? "Restoring..." : "Restore"}
+          </Button>
+        </div>
+      )}
       {!live && !task.hostId && (
         <div>
           <Button

package/data/done/index.ts

@@ -2,6 +2,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { DoneOutcome } from "@/lib/done";
 import type { BulkResult, PreviewRow } from "@/lib/done/bulk";
 import type { ArchivedView } from "@/lib/done/archive";
+import type { ResurrectOutcome } from "@/lib/resurrect";
 import { sessionKeys } from "../sessions/keys";
 import { taskKeys } from "../tasks";
 
@@ -90,6 +91,22 @@ export function useUnarchiveSession() {
   );
 }
 
+// Brings a dropped, done or archived session back (lib/resurrect).
+export function useResurrectSession() {
+  return useDoneMutation(
+    async (id: string) =>
+      (
+        await json<{ outcome: ResurrectOutcome }>(
+          await post(
+            `/api/sessions/${id}/resurrect`,
+            undefined,
+            DONE_REQUEST_TIMEOUT_MS
+          )
+        )
+      ).outcome
+  );
+}
+
 export function useArchivedQuery(workspaceId?: string, enabled = true) {
   return useQuery({
     queryKey: archivedKeys.list(workspaceId),

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.