@saadnvd1/agent-os 0.3.570 → 0.3.572

package/lib/db/migrations.ts

@@ -14,7 +14,7 @@ import { moveSchedulesToRecipes } from "./schedules-move";
 // integer `id`: `key: "YYYYMMDDTHHMM_snake_name"` (UTC, e.g.
 // "20261014T0130_share_links"). Hand-picked numbers collide when two tasks run
 // in parallel and the loser is silently skipped on databases that already
-// applied the winner. Ids 1..88 are legacy: they run first, by number, and
+// applied the winner. Ids 1..89 are legacy: they run first, by number, and
 // never change. Timestamp keys run after them, in lexical order. Never edit a
 // migration that has shipped; add a new one. lib/db/migrations.test.ts
 // enforces all of this.
@@ -2187,6 +2187,61 @@ export const migrations: Migration[] = [
       );
     },
   },
+  {
+    key: "20261014T0900_task_scheduling",
+    up: (db) => {
+      // Priority, "after any" consumption, and timed pause. Additive: every
+      // existing row reads as normal priority and not paused.
+      const has = (table: string, col: string) =>
+        (
+          db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]
+        ).some((c) => c.name === col);
+      const add = (table: string, col: string, def: string) => {
+        if (!has(table, col))
+          db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${def}`);
+      };
+      add("task_queue", "priority", "TEXT NOT NULL DEFAULT 'normal'");
+      add("task_queue", "machine_needs", "TEXT");
+      add("task_queue", "after_any_used", "TEXT");
+      add("task_queue", "wait_code", "TEXT");
+      db.exec(
+        `CREATE UNIQUE INDEX IF NOT EXISTS idx_task_queue_after_any_used
+           ON task_queue(after_any_used) WHERE after_any_used IS NOT NULL`
+      );
+      add("sessions", "priority", "TEXT");
+      add("sessions", "pause_state", "TEXT");
+      add("sessions", "paused_until", "TEXT");
+      add("sessions", "pause_id", "INTEGER");
+      // "Started on <machine> · <why>" for a task the scheduler placed.
+      add("sessions", "placed_note", "TEXT");
+      add("bus_messages", "held_pause_id", "INTEGER");
+      add("projects", "machine_needs", "TEXT");
+      add("projects", "machine_needs_source", "TEXT");
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS task_pauses (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id TEXT NOT NULL,
+          mode TEXT NOT NULL DEFAULT 'turn',
+          by_kind TEXT NOT NULL DEFAULT 'person',
+          by_id TEXT,
+          reason TEXT,
+          until_at TEXT,
+          state TEXT NOT NULL DEFAULT 'pausing',
+          requested_at TEXT NOT NULL DEFAULT (datetime('now')),
+          paused_at TEXT,
+          resume_requested_at TEXT,
+          resume_by_kind TEXT,
+          resumed_at TEXT,
+          ended_at TEXT,
+          end_reason TEXT,
+          interrupted INTEGER NOT NULL DEFAULT 0,
+          held_count INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE INDEX IF NOT EXISTS idx_task_pauses_session
+          ON task_pauses(session_id, state);
+      `);
+    },
+  },
 ];
 
 // `upTo`: stop after this legacy id or timestamp key, inclusive (tests that

package/lib/db/types.ts

@@ -86,6 +86,13 @@ export interface Session {
   // Snoozed until this time, from snoozed_at; activity since wakes it early.
   snoozed_until?: string | null;
   snoozed_at?: string | null;
+  // Task priority (null reads as normal) and timed pause (lib/tasks/pause.ts):
+  // pausing, paused or resuming, until when (null: until resumed).
+  priority?: string | null;
+  pause_state?: "pausing" | "paused" | "resuming" | null;
+  paused_until?: string | null;
+  pause_id?: number | null;
+  placed_note?: string | null;
   // Set by done: hidden from the sidebar and the orchestrator, never deleted.
   archived_at: string | null;
   // On the sidebar's Pinned shelf (0/1 from SQLite).
@@ -172,10 +179,33 @@ export interface Project {
   lh_board_id: string | null;
   lh_board_name: string | null;
   lh_board_page_id: string | null;
+  // What its tasks need from a machine (JSON array), and where that came from.
+  machine_needs?: string | null;
+  machine_needs_source?: string | null;
   created_at: string;
   updated_at: string;
 }
 
+export interface TaskPause {
+  id: number;
+  session_id: string;
+  mode: "turn" | "now";
+  by_kind: "person" | "orchestrator" | "scheduler";
+  by_id: string | null;
+  reason: string | null;
+  until_at: string | null;
+  state: "pausing" | "paused" | "resuming" | "ended";
+  requested_at: string;
+  paused_at: string | null;
+  resume_requested_at: string | null;
+  resume_by_kind: string | null;
+  resumed_at: string | null;
+  ended_at: string | null;
+  end_reason: "resumed" | "cancelled" | "finished" | "failed" | null;
+  interrupted: number;
+  held_count: number;
+}
+
 export interface ProjectDevServer {
   id: string;
   project_id: string;

package/lib/done/index.ts

@@ -8,6 +8,7 @@
  * its own action, archive.ts). What it will do is decided first (plan.ts).
  */
 
+import { endPauseOnFinish } from "../tasks/pause-hold";
 import { db, queries, type Session } from "../db";
 import { endSessionAgent } from "../sessions/end";
 import { clearQueue } from "../chat/queued";
@@ -112,6 +113,7 @@ function mark(s: Session, status: "merged" | "done", pr: TaskPR | null) {
       ? `UPDATE sessions SET task_status = 'merged', pr_status = 'merged' WHERE id = ?`
       : `UPDATE sessions SET task_status = 'done' WHERE id = ?`
   ).run(s.id);
+  endPauseOnFinish(s.id);
   syncTaskCardInBackground(s, status, pr);
   void sessionEnded(s.id, status);
   if (status === "merged") {

package/lib/drafts.ts

@@ -4,6 +4,7 @@
  */
 
 import type { AgentType } from "./providers";
+import type { Priority } from "@/lib/tasks/schedule-types";
 import type { ChatAccess } from "./chat/events";
 import { resolveModelForAgent } from "./model-catalog";
 import { projectsInWorkspace } from "./sidebar/shelves";
@@ -26,6 +27,8 @@ export interface Draft {
   // A task's own model, "provider/model"; unset, its roles' models
   // (lib/models).
   taskModel?: string | null;
+  // A task's priority in the queue; unset: normal.
+  taskPriority?: Priority;
   createdAt: number;
 }
 

package/lib/hosts/peer-load.ts

@@ -0,0 +1,120 @@
+/**
+ * How loaded each linked machine is, for placing tasks. The placing server
+ * polls a peer's GET /api/load every PEER_POLL_MS, only while a task is
+ * waiting that could go there. A reading older than PEER_STALE_MS counts as
+ * red, so nothing is placed on a machine that can't be seen.
+ */
+
+import { getHost } from "./index";
+import { hostApi, hostLink, linkedHostIds } from "./remote-api";
+import { feedGate } from "../load/start-gate";
+import type { MachineSource } from "../load/machines";
+import type { LoadLevel } from "../load/level";
+
+export const PEER_POLL_MS = 15_000;
+export const PEER_STALE_MS = 60_000;
+
+export interface PeerReading {
+  at: number;
+  level: LoadLevel;
+  load1: number;
+  cores: number;
+  memUsedPct: number;
+  booted: number;
+  capabilities: string[];
+}
+
+const g = globalThis as unknown as {
+  __agentosPeerLoad?: Map<string, PeerReading>;
+  __agentosPeerPolling?: Map<string, Promise<void>>;
+};
+const readings = (g.__agentosPeerLoad ??= new Map<string, PeerReading>());
+const polling = (g.__agentosPeerPolling ??= new Map<string, Promise<void>>());
+
+const LEVELS = ["green", "amber", "red"];
+const num = (v: unknown, max = 1e6) =>
+  typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= max ? v : null;
+
+// Another machine's answer is data, not trust: anything off is no reading.
+export function parseReading(body: unknown, at: number): PeerReading | null {
+  if (!body || typeof body !== "object") return null;
+  const b = body as Record<string, unknown>;
+  const level = b.level;
+  const load1 = num(b.load1);
+  const cores = num(b.cores, 4096);
+  if (typeof level !== "string" || !LEVELS.includes(level)) return null;
+  if (load1 === null || !cores) return null;
+  const caps = Array.isArray(b.capabilities)
+    ? b.capabilities
+        .filter((c): c is string => typeof c === "string" && c.length <= 24)
+        .slice(0, 12)
+    : [];
+  return {
+    at,
+    level: level as LoadLevel,
+    load1,
+    cores,
+    memUsedPct: num(b.memUsedPct, 100) ?? 0,
+    booted: num(b.booted, 1000) ?? 0,
+    capabilities: caps,
+  };
+}
+
+export type LoadFetch = (hostId: string) => Promise<unknown>;
+
+const fetchLoad: LoadFetch = async (hostId) => {
+  const link = hostLink(hostId);
+  if (!link) throw new Error("not linked");
+  return hostApi<unknown>(link, "/api/load", { timeout: 5000 });
+};
+
+// Reads every linked machine whose last reading is older than the poll time.
+// A failure keeps the old reading, which then ages into stale.
+export async function refreshPeers(
+  hostIds: Iterable<string> = linkedHostIds(),
+  now = Date.now(),
+  fetcher: LoadFetch = fetchLoad
+): Promise<void> {
+  await Promise.all(
+    [...hostIds].map((hostId) => {
+      const last = readings.get(hostId);
+      if (last && now - last.at < PEER_POLL_MS) return;
+      const running = polling.get(hostId);
+      if (running) return running;
+      const p = fetcher(hostId)
+        .then((body) => {
+          const r = parseReading(body, now);
+          if (!r) return;
+          readings.set(hostId, r);
+          feedGate(hostId, r.level, now);
+        })
+        .catch(() => undefined)
+        .finally(() => polling.delete(hostId));
+      polling.set(hostId, p);
+      return p;
+    })
+  );
+}
+
+export function setPeerReading(hostId: string, r: PeerReading | null): void {
+  if (r) readings.set(hostId, r);
+  else readings.delete(hostId);
+}
+
+export function peerReading(hostId: string): PeerReading | null {
+  return readings.get(hostId) ?? null;
+}
+
+export function peerSource(hostId: string, now: number): MachineSource {
+  const r = readings.get(hostId);
+  const stale = !r || now - r.at > PEER_STALE_MS;
+  return {
+    hostId,
+    label: getHost(hostId)?.name ?? "that machine",
+    level: r?.level ?? null,
+    booted: r?.booted ?? 0,
+    maxBooted: 2,
+    capabilities: r?.capabilities ?? [],
+    stale,
+  };
+}

package/lib/load/machines.ts

@@ -0,0 +1,124 @@
+/**
+ * What the scheduler knows about a machine when it decides to start a task
+ * there: how loaded it is (sampled by the monitor every 10s, or polled from a
+ * linked machine every 15s), whether it has been calm long enough, how many
+ * simulators are booted, and when it last started something. Nothing here
+ * samples anything itself: the load is the thing being protected.
+ */
+
+import os from "os";
+import { bootedCount, maxBooted } from "../simulator/lease";
+import { simulatorAvailable } from "../simulator/available";
+import { currentLevel, loadEnabled } from "./monitor";
+import type { LoadLevel } from "./level";
+import type { MachineLevel, MachineView } from "../tasks/schedule";
+import { HEAVY_BOOT_MS, LOCAL, gateOf, startsBy } from "./start-gate";
+
+export {
+  HEAVY_BOOT_MS,
+  LOCAL,
+  StartGate,
+  feedGate,
+  recordAutoStart,
+  resetMachineStarts,
+} from "./start-gate";
+
+// Development only: pin the level so the holds can be shown without loading
+// the machine.
+function overrideLevel(): MachineLevel | null {
+  if (process.env.NODE_ENV !== "development") return null;
+  const v = process.env.AGENTOS_LOAD_LEVEL;
+  return v === "red" || v === "amber" || v === "green" ? v : null;
+}
+
+export interface LocalFacts {
+  level: LoadLevel | null;
+  load1: number;
+  cores: number;
+  memUsedPct: number;
+  booted: number;
+  capabilities: string[];
+}
+
+// What this machine can run. Only a Mac with Xcode's tools gives a simulator.
+export function machineCapabilities(): string[] {
+  if (process.platform !== "darwin") return [process.platform];
+  return simulatorAvailable() ? ["mac", "xcode", "simulator"] : ["mac"];
+}
+
+export function localFacts(): LocalFacts {
+  const cores = os.cpus().length || 1;
+  const total = os.totalmem();
+  return {
+    level: overrideLevel() ?? currentLevel(),
+    load1: Math.round(os.loadavg()[0] * 10) / 10,
+    cores,
+    memUsedPct: Math.round(((total - os.freemem()) / total) * 100),
+    booted: bootedCount(),
+    capabilities: machineCapabilities(),
+  };
+}
+
+export interface MachineSource {
+  hostId: string;
+  label: string;
+  level: LoadLevel | null;
+  booted: number;
+  maxBooted: number;
+  capabilities: string[];
+  // A peer whose reading is missing or older than the stale limit.
+  stale?: boolean;
+}
+
+// The scheduler's view of a machine, from its readings and the start
+// bookkeeping. Pure given those.
+export function viewOf(src: MachineSource, now: number): MachineView {
+  const gate = gateOf(src.hostId).view(now, src.level);
+  const s = startsBy.get(src.hostId);
+  const level: MachineLevel = src.stale ? "red" : (src.level ?? "green");
+  return {
+    label: src.label,
+    enabled: src.hostId !== LOCAL || loadEnabled(),
+    reading: src.stale ? false : gate.reading && src.level === null,
+    level,
+    settled: src.stale ? false : gate.settled,
+    settleLeftMs: gate.settleLeftMs,
+    booted: src.booted,
+    maxBooted: src.maxBooted,
+    heavyStarting: (s?.heavy ?? []).filter((t) => now - t < HEAVY_BOOT_MS)
+      .length,
+    lastAutoStartAt: s?.auto ?? null,
+    lastHeavyStartAt: s?.heavy.length ? Math.max(...s.heavy) : null,
+  };
+}
+
+export function localView(now = Date.now()): MachineView {
+  const facts = localFacts();
+  const over = overrideLevel();
+  if (over) {
+    // The pinned level counts as long observed: calm unless red.
+    const view = viewOf(
+      {
+        hostId: LOCAL,
+        label: "this machine",
+        level: over,
+        booted: facts.booted,
+        maxBooted: maxBooted(),
+        capabilities: facts.capabilities,
+      },
+      now
+    );
+    return { ...view, reading: false, settled: over !== "red" };
+  }
+  return viewOf(
+    {
+      hostId: LOCAL,
+      label: "this machine",
+      level: facts.level,
+      booted: facts.booted,
+      maxBooted: maxBooted(),
+      capabilities: facts.capabilities,
+    },
+    now
+  );
+}

package/lib/load/monitor.ts

@@ -1,6 +1,7 @@
 // The machine-load monitor: samples the load every 10s and each session's
 // process trees every 30s, pushes both over /ws/status, and raises one alert
-// when the load stays red. It never stops, pauses or queues anything.
+// when the load stays red. It never stops or pauses anything; it feeds the
+// start gate (start-gate.ts) that holds queued tasks while the load is red.
 import os from "os";
 import { db } from "../db";
 import { publishLoad } from "../status/hub";
@@ -11,6 +12,7 @@ import { readPressure } from "./pressure";
 import { readUsage, type Usage } from "./usage";
 import { workerTmuxName } from "../chat/worker/protocol";
 import { alertText, raiseAlert } from "./alert";
+import { LOCAL, feedGate, gateOpen } from "./start-gate";
 
 export const SAMPLE_MS = 10_000;
 export const USAGE_MS = 30_000;
@@ -53,6 +55,13 @@ const state: State = (g.__agentosLoad ??= {
   timers: [],
 });
 
+// The queue lives above this module (it reads the load); reach it lazily.
+function nudgeQueue(): void {
+  void import("../tasks/queue")
+    .then((q) => q.tickQueueSoon())
+    .catch(() => undefined);
+}
+
 export const heavyRegistry = () => state.registry;
 // AGENTOS_LOAD=off: no sampling, no notes, no alerts.
 export const loadEnabled = () => process.env.AGENTOS_LOAD !== "off";
@@ -78,8 +87,14 @@ async function sample(): Promise<void> {
   const cores = os.cpus().length || 1;
   const load1 = os.loadavg()[0];
   const pressure = await readPressure();
-  const level = nextLevel(state.level ?? "green", load1 / cores, pressure);
+  const prev = state.level;
+  const level = nextLevel(prev ?? "green", load1 / cores, pressure);
   state.level = level;
+  const t = Date.now();
+  const wasOpen = gateOpen(LOCAL, prev, t);
+  feedGate(LOCAL, level, t);
+  // Starts held for load go ahead within a sample of the gate opening.
+  if (prev !== level || wasOpen !== gateOpen(LOCAL, level, t)) nudgeQueue();
   const total = os.totalmem();
   const sessions: Record<string, Usage> = {};
   for (const s of Object.values(state.usage))

package/lib/load/start-gate.ts

@@ -0,0 +1,95 @@
+/**
+ * The start gate and the per-machine start bookkeeping, apart from the
+ * monitor so the monitor can feed it without a cycle.
+ */
+
+import type { LoadLevel } from "./level";
+import { LOAD_SETTLE_MS } from "../tasks/schedule";
+
+// A simulator takes about this long to boot and hold a lease.
+export const HEAVY_BOOT_MS = 2 * 60_000;
+
+// Closed while red; opens once the level has stayed out of red for the
+// settle time. Before the first sample it is closed too ("reading").
+export class StartGate {
+  private lastRedAt: number | null = null;
+  private seen = false;
+
+  constructor(private settleMs = LOAD_SETTLE_MS) {}
+
+  // True when the gate's answer changed (the queue may start something).
+  feed(level: LoadLevel, now: number): boolean {
+    const before = this.view(now, level);
+    this.seen = true;
+    if (level === "red") this.lastRedAt = now;
+    const after = this.view(now, level);
+    return before.reading !== after.reading || before.settled !== after.settled;
+  }
+
+  view(now: number, level: LoadLevel | null) {
+    const calm = this.lastRedAt === null ? Infinity : now - this.lastRedAt;
+    const settled = this.seen && level !== "red" && calm >= this.settleMs;
+    return {
+      reading: !this.seen,
+      settled,
+      settleLeftMs:
+        this.lastRedAt === null ? 0 : Math.max(0, this.settleMs - calm),
+    };
+  }
+}
+
+interface Starts {
+  auto: number | null;
+  heavy: number[];
+}
+
+const g = globalThis as unknown as {
+  __agentosStartGates?: Map<string, StartGate>;
+  __agentosMachineStarts?: Map<string, Starts>;
+};
+const gates = (g.__agentosStartGates ??= new Map<string, StartGate>());
+export const startsBy = (g.__agentosMachineStarts ??= new Map<
+  string,
+  Starts
+>());
+
+export const LOCAL = "local";
+
+export const gateOf = (hostId: string) => {
+  let gate = gates.get(hostId);
+  if (!gate) gates.set(hostId, (gate = new StartGate()));
+  return gate;
+};
+
+// Fed by the monitor after each sample, and by the peer poll. True when it
+// opened or closed.
+export function feedGate(hostId: string, level: LoadLevel, now = Date.now()) {
+  return gateOf(hostId).feed(level, now);
+}
+
+// An automatic start on a machine just happened (or was placed there).
+export function recordAutoStart(
+  hostId: string,
+  heavy: boolean,
+  now = Date.now()
+): void {
+  const s = startsBy.get(hostId) ?? { auto: null, heavy: [] };
+  s.auto = now;
+  if (heavy) s.heavy.push(now);
+  startsBy.set(hostId, s);
+}
+
+export function resetMachineStarts(): void {
+  startsBy.clear();
+  gates.clear();
+}
+
+// Whether automatic starts may go ahead on a machine, by its gate alone.
+export function gateOpen(
+  hostId: string,
+  level: LoadLevel | null,
+  now: number
+): boolean {
+  const v = gateOf(hostId).view(now, level);
+  return v.settled && !v.reading;
+}

package/lib/model-catalog.ts

@@ -84,3 +84,14 @@ export function resolveModelForAgent(
 
   return getDefaultModelForAgent(agentType);
 }
+
+// A readable name for a model id: "claude-opus-5-5" is "Opus 5.5", the alias
+// "opus" is "Opus". An id it can't read passes through unchanged.
+export function modelDisplayName(id: string): string {
+  const alias = CLAUDE_MODEL_OPTIONS.find((o) => o.value === id);
+  if (alias) return alias.label;
+  const m = /^claude-([a-z]+)-(\d{1,2}(?:-\d{1,2})*)(?:-\d{8})?$/.exec(id);
+  if (!m) return id;
+  const family = m[1][0].toUpperCase() + m[1].slice(1);
+  return `${family} ${m[2].replace(/-/g, ".")}`;
+}

package/lib/orchestrator/act.ts

@@ -41,6 +41,15 @@ import { getOrchestrator } from "./home";
 import { addNote } from "./notes";
 import { findWorkspaceSession } from "./read";
 import { workspaceProject, workspaceStack, workspaceTask } from "./targets";
+import { setPriority, stampPriority } from "../tasks/queue";
+import {
+  PauseRefused,
+  activePause,
+  requestPause,
+  requestResume,
+} from "../tasks/pause";
+import { pauseUntil, type PausePreset } from "../sidebar/snooze";
+import type { Priority } from "../tasks/schedule-types";
 
 function orchestratorId(workspaceId: string): string {
   const o = getOrchestrator(workspaceId);
@@ -104,6 +113,8 @@ export async function startTask(
     plan?: boolean;
     planOnly?: boolean;
     planReason?: string;
+    priority?: Priority;
+    machine?: "mac" | "any";
   } = {}
 ): Promise<string> {
   if (opts.planOnly && opts.plan === false)
@@ -133,6 +144,8 @@ export async function startTask(
       baseBranch: opts.base || undefined,
       after: opts.after,
       originWorkspaceId: workspaceId,
+      priority: opts.priority,
+      machine: opts.machine,
     },
     () =>
       braked(
@@ -159,6 +172,7 @@ export async function startTask(
     return `Queued (position ${queued.position}) task "${queued.name}" (id ${queued.id.slice(0, 8)}) in ${project.name}${queued.after ? `, after ${queued.after}` : ""}. It starts by itself; you'll get an event when it does.`;
   }
   const task = out.started;
+  if (opts.priority) stampPriority(task.id, opts.priority);
   const planOnlyNote = opts.planOnly
     ? " Plan only: it stops after the plan and waits; approve_plan continues it, drop rejects it."
     : "";
@@ -354,3 +368,67 @@ export async function moveTaskTo(
 
 const machineName = (hostId: string) =>
   getHost(hostId)?.name ?? "the other machine";
+
+// A queued task re-ranks at once; a running one only carries the word.
+export function setTaskPriority(
+  workspaceId: string,
+  ref: string,
+  priority: Priority
+): string {
+  const queued = findQueued(workspaceId, ref, { byName: true });
+  if (queued) {
+    setPriority(queued.id, priority);
+    return `${queued.name} is ${priority} in the queue now.`;
+  }
+  const task = workspaceTask(workspaceId, ref);
+  setPriority(task.id, priority);
+  const running = task.task_status === "running";
+  return running
+    ? `${task.name} is ${priority}. It's running, so this only matters if it is paused and waits to resume.`
+    : `${task.name} is ${priority}. It's ${task.task_status ?? "not queued"}, so this changes nothing now.`;
+}
+
+const PAUSE_FOR: Record<string, PausePreset> = {
+  "1h": "1h",
+  "2h": "2h",
+  tomorrow: "tomorrow",
+  until_resumed: "until-resumed",
+};
+
+export function pauseTask(
+  workspaceId: string,
+  ref: string,
+  howLong: string,
+  now: boolean,
+  reason: string
+): string {
+  const task = workspaceTask(workspaceId, ref);
+  const preset = PAUSE_FOR[howLong];
+  if (!preset) throw new Error("for is 1h, 2h, tomorrow or until_resumed");
+  try {
+    requestPause(task.id, {
+      until: pauseUntil(preset),
+      mode: now ? "now" : "turn",
+      by: "orchestrator",
+      byId: orchestratorId(workspaceId),
+      reason,
+    });
+  } catch (error) {
+    if (error instanceof PauseRefused)
+      throw new Error(`Can't pause ${task.name}: ${error.message}`);
+    throw error;
+  }
+  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 {
+  const task = workspaceTask(workspaceId, ref);
+  if (!activePause(task.id)) throw new Error(`${task.name} isn't paused`);
+  try {
+    requestResume(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.`;
+}

package/lib/orchestrator/brakes.ts

@@ -53,6 +53,8 @@ export async function runningCount(
   const running = new Set<string>();
   for (const s of workspaceSessions(workspaceId)) {
     if (s.task_status && s.task_status !== "running") continue;
+    // A paused task has stopped its agent and holds no slot.
+    if (s.pause_state === "paused") continue;
     // A task still setting up, or held at launch, has no terminal yet, and
     // its agent will launch.
     if (