@saadnvd1/agent-os 0.3.592 → 0.3.594

package/lib/resurrect/plan.ts

@@ -0,0 +1,61 @@
+/**
+ * A plan-only task's plan file lives in its worktree and in git nowhere, so a
+ * worktree that's gone takes it along. The conversation still has it: the
+ * Write that made it and the Edits after. Replays them.
+ */
+
+import { PLAN_FILE } from "../models/plan-step";
+
+interface ToolUse {
+  name?: string;
+  input?: {
+    file_path?: unknown;
+    content?: unknown;
+    old_string?: unknown;
+    new_string?: unknown;
+    replace_all?: unknown;
+  };
+}
+
+function* toolUses(jsonl: string): Generator<ToolUse> {
+  for (const line of jsonl.split("\n")) {
+    if (!line.includes("tool_use")) continue;
+    let entry: { message?: { content?: unknown } };
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const content = entry.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const part of content)
+      if (part?.type === "tool_use") yield part as ToolUse;
+  }
+}
+
+export function planFromTranscript(jsonl: string): string | null {
+  let text: string | null = null;
+  for (const use of toolUses(jsonl)) {
+    const file = use.input?.file_path;
+    if (typeof file !== "string" || !file.endsWith(PLAN_FILE)) continue;
+    if (use.name === "Write" && typeof use.input?.content === "string") {
+      text = use.input.content;
+    } else if (
+      use.name === "Edit" &&
+      text !== null &&
+      typeof use.input?.old_string === "string" &&
+      typeof use.input.new_string === "string" &&
+      text.includes(use.input.old_string)
+    ) {
+      const { old_string: from, new_string: to } = use.input as {
+        old_string: string;
+        new_string: string;
+      };
+      text =
+        use.input.replace_all === true
+          ? text.split(from).join(to)
+          : text.replace(from, () => to);
+    }
+  }
+  return text;
+}

package/lib/resurrect/snapshot.ts

@@ -0,0 +1,229 @@
+/**
+ * A session's worktree, saved as one hidden commit before an end removes it:
+ * refs/agentos/ended/<session id>, parented on the branch tip, holding the
+ * tracked changes, the untracked files and the (git-ignored) plan file. It is
+ * built in a temporary index, so the worktree, its index and its branch are
+ * never touched, and takes about a tenth of a second.
+ *
+ * Restoring puts the worktree back on its branch with those files unstaged.
+ * Without a snapshot (an end from before this existed, or one that failed) it
+ * falls back to the branch, wherever it still exists.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { git as runGit, gitOk } from "../git-exec";
+import { PLAN_FILE, preparePlanDir } from "../models/plan-step";
+import { addWorktree } from "../worktree-add";
+import { installWorktreeHooks } from "../worktree-hooks";
+
+const SNAPSHOT_TIMEOUT_MS = 5000;
+// An untracked file bigger than this is left out: a build artefact, not work.
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_FILES = 2000;
+
+const IDENTITY = {
+  GIT_AUTHOR_NAME: "AgentOS",
+  GIT_AUTHOR_EMAIL: "agentos@localhost",
+  GIT_COMMITTER_NAME: "AgentOS",
+  GIT_COMMITTER_EMAIL: "agentos@localhost",
+};
+
+export const snapshotRef = (sessionId: string) =>
+  `refs/agentos/ended/${sessionId}`;
+
+const git = (cwd: string, args: string[], extra: object = {}) =>
+  runGit(cwd, args, { timeout: SNAPSHOT_TIMEOUT_MS, ...extra });
+
+async function build(worktree: string, sessionId: string): Promise<string> {
+  const [head, indexFile] = (
+    await git(worktree, [
+      "rev-parse",
+      "HEAD",
+      "--path-format=absolute",
+      "--git-path",
+      "index",
+    ])
+  )
+    .trim()
+    .split("\n");
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "aos-snap-"));
+  try {
+    const index = path.join(tmp, "index");
+    if (fs.existsSync(indexFile)) {
+      fs.copyFileSync(indexFile, index);
+      // Git trusts a file's stat only if it is older than the index. A copy
+      // is newer, so an edit of the same size made within the index's last
+      // timestamp tick would read as unchanged and be missed.
+      const stat = fs.statSync(indexFile);
+      fs.utimesSync(index, stat.atime, stat.mtime);
+    }
+    const env = { GIT_INDEX_FILE: index, ...IDENTITY };
+    const opts = { env, literalPathspecs: true };
+    await git(worktree, ["add", "-u"], opts);
+    const untracked = (
+      await git(worktree, ["ls-files", "-o", "--exclude-standard", "-z"])
+    )
+      .split("\0")
+      .filter(Boolean)
+      .filter((file) => {
+        try {
+          const stat = fs.statSync(path.join(worktree, file));
+          return stat.isFile() && stat.size <= MAX_FILE_BYTES;
+        } catch {
+          return false;
+        }
+      })
+      .slice(0, MAX_FILES);
+    if (untracked.length)
+      await git(worktree, ["add", "--", ...untracked], opts);
+    if (fs.existsSync(path.join(worktree, PLAN_FILE)))
+      await git(worktree, ["add", "-f", "--", PLAN_FILE], opts);
+    const tree = (await git(worktree, ["write-tree"], opts)).trim();
+    const commit = (
+      await git(
+        worktree,
+        ["commit-tree", tree, "-p", head, "-m", `ended ${sessionId}`],
+        opts
+      )
+    ).trim();
+    await git(worktree, ["update-ref", snapshotRef(sessionId), commit]);
+    return commit;
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Saves the worktree's work under a hidden ref. Never throws and never waits
+ * past its ceiling: a snapshot that fails only means the restore falls back
+ * to the branch.
+ */
+export async function snapshotWorktree(
+  worktree: string | null,
+  sessionId: string
+): Promise<string | null> {
+  if (!worktree || process.env.AGENTOS_NO_END_SNAPSHOT) return null;
+  const started = Date.now();
+  try {
+    // The index can be mid-write when copied; a second read is whole.
+    const commit = await build(worktree, sessionId).catch(() =>
+      build(worktree, sessionId)
+    );
+    console.log(
+      `[resurrect] snapshot ${sessionId} in ${Date.now() - started} ms`
+    );
+    return commit;
+  } catch (error) {
+    console.error(`[resurrect] no snapshot for ${sessionId}:`, error);
+    return null;
+  }
+}
+
+export const hasSnapshot = (repo: string, sessionId: string) =>
+  gitOk(repo, ["rev-parse", "--verify", "--quiet", snapshotRef(sessionId)]);
+
+export async function dropSnapshot(
+  repo: string,
+  sessionId: string
+): Promise<void> {
+  await gitOk(repo, ["update-ref", "-d", snapshotRef(sessionId)]);
+}
+
+export type RestoredAs = "kept" | "snapshot" | "branch" | "origin" | "fresh";
+
+export interface RestoreOptions {
+  sessionId: string;
+  repo: string;
+  branch: string;
+  base: string | null;
+  // Where it was: used again when free, so Claude's conversation (filed by
+  // folder) is found as it is.
+  oldPath: string | null;
+  // A branch that never held work of its own may be made anew.
+  allowFresh: boolean;
+}
+
+const addRun = (args: string[], cwd: string) =>
+  runGit(cwd, args, { timeout: 120_000 });
+
+const refOk = (repo: string, ref: string) =>
+  gitOk(repo, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+
+/** The worktree back, or null when there's nothing to make it from. */
+export async function restoreWorktree(
+  o: RestoreOptions
+): Promise<{ path: string; mode: RestoredAs } | null> {
+  if (o.oldPath && fs.existsSync(o.oldPath))
+    return { path: o.oldPath, mode: "kept" };
+  const free = o.oldPath && !fs.existsSync(o.oldPath);
+  // Lazily: branch-worktree reaches back into the tasks code that ends sessions.
+  const { worktreeDirFor } = await import("../tasks/branch-worktree");
+  const dir = free ? o.oldPath! : worktreeDirFor(o.repo, o.branch);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  await git(o.repo, ["worktree", "prune"]).catch(() => "");
+  const snap = snapshotRef(o.sessionId);
+  let mode: RestoredAs;
+  if (await refOk(o.repo, snap)) {
+    await addWorktree(addRun, o.repo, dir, `${snap}^`, ["-B", o.branch]);
+    mode = "snapshot";
+  } else if (await refOk(o.repo, `refs/heads/${o.branch}`)) {
+    await addWorktree(addRun, o.repo, dir, o.branch);
+    mode = "branch";
+  } else if (await fetchBranch(o.repo, o.branch)) {
+    await addWorktree(addRun, o.repo, dir, `origin/${o.branch}`, [
+      "-B",
+      o.branch,
+    ]);
+    await git(dir, ["branch", "--set-upstream-to", `origin/${o.branch}`]).catch(
+      () => ""
+    );
+    mode = "origin";
+  } else if (o.allowFresh) {
+    const base = o.base || "main";
+    const start = (await refOk(o.repo, `origin/${base}`))
+      ? `origin/${base}`
+      : base;
+    await addWorktree(addRun, o.repo, dir, start, ["-b", o.branch]);
+    mode = "fresh";
+  } else return null;
+  await installWorktreeHooks(dir).catch(() => "");
+  if (mode === "snapshot") await layFiles(dir, snap);
+  return { path: dir, mode };
+}
+
+async function fetchBranch(repo: string, branch: string): Promise<boolean> {
+  const ok = await gitOk(
+    repo,
+    [
+      "fetch",
+      "-q",
+      "origin",
+      `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
+    ],
+    { timeout: 60_000 }
+  );
+  return ok && refOk(repo, `origin/${branch}`);
+}
+
+// The snapshot's files over the fresh checkout, left as uncommitted changes.
+async function layFiles(dir: string, snap: string): Promise<void> {
+  const deleted = (
+    await runGit(dir, [
+      "diff",
+      "--name-only",
+      "--diff-filter=D",
+      "-z",
+      "HEAD",
+      snap,
+    ])
+  )
+    .split("\0")
+    .filter(Boolean);
+  await runGit(dir, ["checkout", snap, "--", "."]);
+  await runGit(dir, ["reset", "-q"]);
+  for (const file of deleted) fs.rmSync(path.join(dir, file), { force: true });
+  // Its .gitignore isn't in the snapshot: without it the plan reads as new.
+  if (fs.existsSync(path.join(dir, PLAN_FILE))) preparePlanDir(dir);
+}

package/lib/security/demo.ts

@@ -58,6 +58,7 @@ export const STATIC_SIBLINGS = [
   "detect",
   "done-idle",
   "draft",
+  "ended",
   "held-replies",
   "import",
   "init",

package/lib/sidebar/paused.ts

@@ -2,10 +2,17 @@ import { wakeLabel } from "./snooze";
 
 // What a paused row says under its title.
 export function pauseSubtitle(
-  paused: { state: "pausing" | "paused" | "resuming"; until: number | null },
+  paused: {
+    state: "pausing" | "paused" | "resuming";
+    until: number | null;
+    // Why a requested resume hasn't happened yet.
+    note?: string | null;
+  },
   now: number = Date.now(),
   timeZone?: string
 ): string {
+  if (paused.note && paused.state !== "pausing")
+    return paused.note[0].toUpperCase() + paused.note.slice(1);
   if (paused.state === "pausing") return "Pausing · finishing its step";
   if (paused.state === "resuming") return "Resuming · waiting for a slot";
   if (paused.until === null) return "Paused until you resume";

package/lib/sidebar/row-actions.ts

@@ -3,13 +3,17 @@ import type { Session } from "@/lib/db/types";
 // What a row's ⋯ menu offers to finish it: Done (merge through the gates,
 // stop, leave it on the Done shelf) for a task, Archive (put it away) for
 // every session but an orchestrator. A plain session is finished with Mark
-// done, so it only gets Archive here.
-export type FinishAction = "done" | "archive";
+// done, so it only gets Archive here. A task that is already done is
+// restored instead (its worktree and conversation come back).
+export type FinishAction = "done" | "restore" | "archive";
 
 export function finishActions(
   session: Pick<Session, "role" | "task_status">,
   plain: boolean
 ): FinishAction[] {
   if (session.role === "orchestrator") return [];
-  return plain ? ["archive"] : ["done", "archive"];
+  if (plain) return ["archive"];
+  return session.task_status === "done"
+    ? ["restore", "archive"]
+    : ["done", "archive"];
 }

package/lib/sidebar/shelves.ts

@@ -70,7 +70,11 @@ export interface SidebarRow {
   // Its agent is being stopped, is stopped, or is starting again
   // (lib/tasks/pause): until is when it resumes by itself (ms), null: when
   // someone resumes it.
-  paused?: { state: "pausing" | "paused" | "resuming"; until: number | null };
+  paused?: {
+    state: "pausing" | "paused" | "resuming";
+    until: number | null;
+    note?: string | null;
+  };
 }
 
 export interface Shelves {
@@ -261,6 +265,7 @@ function toRow(input: ShelfInput, session: Session, now: number): SidebarRow {
       paused: {
         state: pauseState,
         until: session.paused_until ? ms(session.paused_until) : null,
+        ...(session.pause_note && { note: session.pause_note }),
       },
     }),
     working:
@@ -421,6 +426,7 @@ export function sameRow(a: SidebarRow, b: SidebarRow): boolean {
     a.wakesAt === b.wakesAt &&
     a.paused?.state === b.paused?.state &&
     a.paused?.until === b.paused?.until &&
+    a.paused?.note === b.paused?.note &&
     a.settled === b.settled &&
     a.workers.length === b.workers.length &&
     a.workers.every((w, i) => sameRow(w, b.workers[i])) &&

package/lib/tasks/auto-hold.ts

@@ -0,0 +1,17 @@
+import { brakesEnabled } from "../orchestrator/brakes";
+import { isPaused } from "../orchestrator/pause";
+import { readUsage, windowRefusal } from "../orchestrator/usage";
+import type { Hold } from "./schedule";
+
+// Why an automatic start has to wait, or null. A start now by a person
+// isn't held.
+export function autoHold(
+  workspaceId: string | null,
+  planOnly = false
+): Hold | null {
+  if (workspaceId && isPaused(workspaceId))
+    return { code: "orch_paused", text: "Waiting: the orchestrator is paused" };
+  if (planOnly) return null;
+  const window = brakesEnabled() ? windowRefusal(readUsage()) : null;
+  return window ? { code: "window", text: `Waiting: ${window}` } : null;
+}

package/lib/tasks/finish.ts

@@ -26,6 +26,7 @@ import { getProject } from "../projects";
 import { canSignOff } from "./state";
 import {
   forgetPR,
+  expandHome,
   getTaskSession,
   isAllowedBase,
   prFor,
@@ -34,6 +35,7 @@ import {
 import { dropSessionDatabase } from "../project-config/database";
 import { captureMergedTask } from "../session-logs";
 import { sessionEnded } from "../experiments/hooks";
+import { snapshotWorktree } from "../resurrect/snapshot";
 
 // Never deleted, whatever a setting says.
 export const PROTECTED_BRANCHES = new Set(["main", "master", "HEAD"]);
@@ -233,6 +235,12 @@ export async function dropTask(id: string): Promise<void> {
       `${names} ${children.length === 1 ? "is" : "are"} stacked on this task and built on its branch. Drop ${children.length === 1 ? "it" : "them"} first, or sign this one off.`
     );
   }
+  // Saved while the PR is closed below, and settled before the worktree goes:
+  // a restore finds its uncommitted files and plan here. Never throws.
+  const snapshot = snapshotWorktree(
+    session.worktree_path && expandHome(session.worktree_path),
+    id
+  );
   const pr = await prFor(session, true);
   if (pr?.state === "OPEN") {
     await run("gh", ["pr", "close", String(pr.number)], repo).catch(() => {});
@@ -245,5 +253,6 @@ export async function dropTask(id: string): Promise<void> {
     `UPDATE stack_items SET status = 'dropped' WHERE session_id = ?`
   ).run(id);
   syncTaskCardInBackground(session, "dropped", pr);
+  await snapshot;
   await cleanup(session, repo);
 }

package/lib/tasks/pause-hold.ts

@@ -46,7 +46,7 @@ export function endPause(
        WHERE id = ? AND state != 'ended'`
     ).run(reason, row.id);
     db.prepare(
-      `UPDATE sessions SET pause_state = NULL, paused_until = NULL, pause_id = NULL
+      `UPDATE sessions SET pause_state = NULL, paused_until = NULL, pause_id = NULL, pause_note = NULL
        WHERE id = ? AND pause_id = ?`
     ).run(row.session_id, row.id);
   })();

package/lib/tasks/pause.ts

@@ -34,6 +34,9 @@ import { openBySubject, workSubject } from "../orchestrator/asks";
 import { queueEventOnce } from "../orchestrator/events";
 import { isPaused } from "../orchestrator/pause";
 import { isMerging } from "./finish";
+import { autoHold } from "./auto-hold";
+import { localView } from "../load/machines";
+import { machineHold } from "./schedule";
 import {
   continuePrompt,
   durationText,
@@ -373,7 +376,8 @@ export function resumeBlock(sessionId: string, actor: PauseBy): string | null {
 }
 
 // Marks a paused session's resume as due: a task then competes for a slot
-// (queue tick), anything else resumes at once.
+// (queue tick), anything else resumes at once. Only the timer uses this for
+// a task; a person or the orchestrator resuming goes through resumeNow.
 export function requestResume(sessionId: string, actor: PauseBy): void {
   const refusal = resumeBlock(sessionId, actor);
   if (refusal) throw new PauseRefused(refusal);
@@ -391,13 +395,73 @@ export function requestResume(sessionId: string, actor: PauseBy): void {
     );
 }
 
-// A person's Resume now: past the slot limit, like Start now.
-export async function resumeNow(sessionId: string, actor: PauseBy = "person") {
+// Why this machine's load rules out starting an agent now, or null. Only a
+// red (or still settling) machine holds a resume; amber doesn't.
+export function loadHoldFor(s: Session): string | null {
+  const project = s.project_id ? getProject(s.project_id) : null;
+  if (!project || isRemoteHost(s.host_id ?? project.host_id)) return null;
+  const hold = machineHold(
+    {
+      heavy: false,
+      needsUnmet: false,
+      remote: false,
+      priority: DEFAULT_PRIORITY,
+    },
+    localView(),
+    Date.now()
+  );
+  return hold?.code === "load_red" ? hold.text.replace(/^Waiting: /, "") : null;
+}
+
+// Why a resume this actor asked for must wait: this machine's load, and for
+// the orchestrator also what holds its own starts (it is paused, or the
+// usage window). Saad's own resume skips the second.
+export function resumeHoldFor(s: Session, actor: PauseBy): string | null {
+  const load = loadHoldFor(s);
+  if (load) return load;
+  if (actor !== "orchestrator") return null;
+  const ws = s.project_id ? getProject(s.project_id)?.workspace_id : null;
+  return autoHold(ws ?? null)?.text.replace(/^Waiting: /, "") ?? null;
+}
+
+export function setPauseNote(sessionId: string, note: string | null): void {
+  db.prepare(
+    `UPDATE sessions SET pause_note = ? WHERE id = ? AND pause_state = 'paused' AND COALESCE(pause_note, '') != COALESCE(?, '')`
+  ).run(note, sessionId, note);
+}
+
+export type ResumeOutcome =
+  | { outcome: "resumed" | "cancelled" }
+  | { outcome: "held"; note: string };
+
+// A deliberate Resume, by a person or the orchestrator: starts at once, past
+// the slot limit, like Start now. A machine in the red still holds it: it is
+// recorded as asked for, says why on the task, and goes when the load
+// calms.
+export async function resumeNow(
+  sessionId: string,
+  actor: PauseBy = "person"
+): Promise<ResumeOutcome> {
   const refusal = resumeBlock(sessionId, actor);
   if (refusal) throw new PauseRefused(refusal);
   const row = activePause(sessionId)!;
-  if (row.state === "pausing") return cancelPause(sessionId);
+  if (row.state === "pausing") {
+    cancelPause(sessionId);
+    return { outcome: "cancelled" };
+  }
+  const s = sessionOf(sessionId);
+  const why = s ? resumeHoldFor(s, actor) : null;
+  if (s && why && row.state === "paused") {
+    db.prepare(
+      `UPDATE task_pauses SET resume_requested_at = COALESCE(resume_requested_at, datetime('now')), resume_by_kind = ? WHERE id = ?`
+    ).run(actor, row.id);
+    const note = `held: ${why}`;
+    setPauseNote(sessionId, note);
+    nudge();
+    return { outcome: "held", note };
+  }
   await claimResume(sessionId, { reason: actor, force: true });
+  return { outcome: "resumed" };
 }
 
 export interface DueResume {
@@ -407,6 +471,8 @@ export interface DueResume {
   priority: Priority;
   dueAtMs: number;
   byKind: PauseBy;
+  // A person or the orchestrator asked: it isn't queued behind the slot limit.
+  resumeBy: PauseBy | null;
 }
 
 // Paused tasks whose time came (or that someone asked to resume), for the
@@ -414,7 +480,7 @@ export interface DueResume {
 export function dueResumes(): DueResume[] {
   const rows = db
     .prepare(
-      `SELECT p.id AS pause_id, p.session_id, p.by_kind, p.until_at, p.resume_requested_at,
+      `SELECT p.id AS pause_id, p.session_id, p.by_kind, p.until_at, p.resume_requested_at, p.resume_by_kind,
               s.project_id, s.priority
        FROM task_pauses p JOIN sessions s ON s.id = p.session_id
        WHERE p.state = 'paused' AND p.resume_requested_at IS NOT NULL
@@ -426,6 +492,7 @@ export function dueResumes(): DueResume[] {
     by_kind: PauseBy;
     until_at: string | null;
     resume_requested_at: string;
+    resume_by_kind: string | null;
     project_id: string | null;
     priority: string | null;
   }[];
@@ -438,6 +505,7 @@ export function dueResumes(): DueResume[] {
       priority: isPriority(r.priority) ? r.priority : DEFAULT_PRIORITY,
       dueAtMs: r.until_at ? ms(r.until_at) : ms(r.resume_requested_at),
       byKind: r.by_kind,
+      resumeBy: (r.resume_by_kind as PauseBy | null) ?? null,
     }));
 }
 
@@ -544,9 +612,9 @@ export async function claimResume(
         }),
         Date.now()
       );
-    db.prepare(`UPDATE sessions SET pause_state = 'resuming' WHERE id = ?`).run(
-      sessionId
-    );
+    db.prepare(
+      `UPDATE sessions SET pause_state = 'resuming', pause_note = NULL WHERE id = ?`
+    ).run(sessionId);
     return true;
   })();
   if (!claimed) return "gone";

package/lib/tasks/queue.ts

@@ -22,6 +22,7 @@ import { getProject } from "../projects";
 import { isRemoteHost } from "../hosts";
 import { getWorkspace } from "../workspaces";
 import { isPaused } from "../orchestrator/pause";
+import { autoHold } from "./auto-hold";
 import {
   BrakeRefused,
   braked,
@@ -77,7 +78,13 @@ import { peerReading, peerSource, refreshPeers } from "../hosts/peer-load";
 import { hostLink, linkedHostIds } from "../hosts/remote-api";
 import { hostTasks } from "./remote";
 import { projectMachines } from "../hosts/project-machines";
-import { claimResume, dueResumes } from "./pause";
+import {
+  type DueResume,
+  claimResume,
+  dueResumes,
+  resumeHoldFor,
+  setPauseNote,
+} from "./pause";
 
 export type QueueStatus =
   | "queued"
@@ -562,16 +569,6 @@ const sqliteMs = (v: string) =>
 export const queuedView = (id: string) =>
   listQueue().find((q) => q.id === id) ?? null;
 
-// Why an automatic start has to wait, or null. A start now by a person
-// isn't held.
-function autoHold(workspaceId: string | null, planOnly = false): Hold | null {
-  if (workspaceId && isPaused(workspaceId))
-    return { code: "orch_paused", text: "Waiting: the orchestrator is paused" };
-  if (planOnly) return null;
-  const window = brakesEnabled() ? windowRefusal(readUsage()) : null;
-  return window ? { code: "window", text: `Waiting: ${window}` } : null;
-}
-
 const requestNeeds = (
   projectId: string,
   workingDirectory: string,
@@ -959,7 +956,18 @@ export async function tickOnce(now = Date.now()): Promise<"stale" | void> {
        WHERE q.status IN ('queued', 'starting') ORDER BY q.position`
     )
     .all() as QueueRowWithWorkspace[];
-  const resumes = dueResumes();
+  const due = dueResumes();
+  // A deliberate resume starts past the slot limit; only a red machine holds
+  // it, and the task says so.
+  for (const d of due.filter((x) => x.resumeBy)) {
+    const s = db
+      .prepare(`SELECT * FROM sessions WHERE id = ?`)
+      .get(d.sessionId) as Session | undefined;
+    const why = s ? resumeHoldFor(s, d.resumeBy!) : null;
+    if (why) setPauseNote(d.sessionId, `held: ${why}`);
+    else await claimResume(d.sessionId, { reason: d.resumeBy!, force: true });
+  }
+  const resumes = due.filter((x) => !x.resumeBy);
   if (!rows.length && !resumes.length) return;
   const queued = rows.filter((r) => r.status === "queued");
   const used = usedFinishes();
@@ -1051,6 +1059,11 @@ export async function tickOnce(now = Date.now()): Promise<"stale" | void> {
   const plan = planStarts(candidates, groups, home, now);
   for (const r of queued)
     noteWaiting(r, withStayReason(r, plan.explain.get(r.id)));
+  for (const d of resumes)
+    setPauseNote(
+      d.sessionId,
+      resumeWaitNote(d, plan.explain.get(`resume:${d.sessionId}`))
+    );
 
   for (const id of plan.start) {
     if (id.startsWith("resume:")) {
@@ -1067,6 +1080,20 @@ export async function tickOnce(now = Date.now()): Promise<"stale" | void> {
   }
 }
 
+// What a timed resume still waiting for its turn says on its task.
+function resumeWaitNote(
+  d: DueResume,
+  explain: { code: WaitCode | null; text: string | null } | undefined
+): string | null {
+  if (!explain) return null;
+  if (explain.code && explain.code !== "slot" && explain.text)
+    return `held: ${explain.text.replace(/^Waiting: /, "")}`;
+  const slots = slotState(d.projectId);
+  return slots.limit === null
+    ? "resuming: waiting for its turn"
+    : `resuming: waiting for a slot, ${slots.running} of ${slots.limit} running`;
+}
+
 // Writes why a row waits when that changed: its hold text and code. A bare
 // rank isn't stored (the view computes it), so the stream stays quiet.
 const MACHINE_HOLDS = new Set<WaitCode>([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.592",
+  "version": "0.3.594",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"