@saadnvd1/agent-os 0.3.571 → 0.3.572

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/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 (

package/lib/orchestrator/brief.ts

@@ -119,7 +119,7 @@ Reading:
 Acting:
 - \`${TOOL_NAMES.send}\` (session, message, scope_change?): message a session; it arrives as its next prompt. scope_change records it on the task's brief for its review.
 - \`${TOOL_NAMES.message_orchestrator}\` (workspace, message): message another workspace's orchestrator, the only thing you reach outside this workspace. Use it to hand over a bug or ask for something in its projects; it decides what to do there.
-- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, model?, plan, plan_only?, plan_reason): a task in its own worktree that ends in a PR. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
+- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, priority?, machine?, model?, plan, plan_only?, plan_reason): a task in its own worktree that ends in a PR. priority (urgent, blocking, normal, background) sets where it stands in the queue; machine mac pins work that needs this Mac. A busy or loaded machine holds a queued start and says why; don't retry it. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
 - \`${TOOL_NAMES.plan_pieces}\` (task, merge?, drop?): when a plan split into pieces (the plan-done event names them), list them; merge or drop edits the ones still waiting. A piece starts by itself once what it waits on has merged (or deployed); you don't start it.
 - \`${TOOL_NAMES.approve_plan}\` (task, message?): continue a plan_only task whose plan is ready; it implements on the implementation model, once. message amends the plan and is recorded on the task's brief as a scope change. Reject a plan with drop.
 - \`${TOOL_NAMES.set_task_model}\` (task, model, message?): move a paused task to another model and carry on in the same conversation and worktree; it keeps that model from then on. Only when Saad asks.
@@ -134,6 +134,9 @@ Acting:
 - \`${TOOL_NAMES.land}\` (id): merge a stack bottom-up through the gates.
 - \`${TOOL_NAMES.move}\` (task, machine): carry a running task to a linked machine (heavy test or build work), or back with machine "here". It keeps its branch, conversation and plan, and everything you do with a task works the same there: its events come to you, read, send, stop, done and drop reach it, and the gates judge its PR at its head. The machine it lands on holds it for you and can't merge it. It runs in the background; an event says when it lands. Refused while paused, and for a task waiting on Saad.
 - \`${TOOL_NAMES.drop}\` (task, reason): close a task's PR and remove its worktree (on whichever machine holds it).
+- \`${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.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.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.

package/lib/orchestrator/digest.ts

@@ -56,6 +56,9 @@ interface TaskRow {
   pr_status: string | null;
   view: string;
   armed_at: string | null;
+  pause_state: string | null;
+  paused_until: string | null;
+  placed_note: string | null;
 }
 
 export interface CheckRow {
@@ -162,7 +165,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.merge_armed_at AS armed_at, s.pause_state, s.paused_until, 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'
@@ -177,7 +180,11 @@ function tasksSection(
         : "no PR yet";
       const gates = gateState(checks.get(t.id), failures.get(t.id));
       const arm = t.armed_at ? " | armed to merge" : "";
-      return `- ${clip(t.name, 80)} (${t.project ?? "?"}, ${t.view}, id ${shortId(t.id)}): ${pr}${arm}${gates ? ` | ${gates}` : ""}`;
+      const paused = t.pause_state
+        ? ` | ${t.pause_state}${t.paused_until ? ` until ${t.paused_until} UTC` : t.pause_state === "paused" ? " until resumed" : ""}`
+        : "";
+      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}` : ""}`;
     }),
     empty: "- None.",
     more: "the sessions tool",
@@ -210,7 +217,7 @@ function externalSection(
 function queueSection(workspaceId: string): Section {
   const rows = db
     .prepare(
-      `SELECT q.id, q.name, q.prompt, q.status, q.after_task, q.after_any,
+      `SELECT q.id, q.name, q.prompt, q.status, q.after_task, q.after_any, q.priority, q.note,
          p.name AS project, a.name AS after_name
        FROM task_queue q JOIN projects p ON p.id = q.project_id
        LEFT JOIN sessions a ON a.id = q.after_task
@@ -226,6 +233,8 @@ function queueSection(workspaceId: string): Section {
     after_any: string | null;
     project: string;
     after_name: string | null;
+    priority: string;
+    note: string | null;
   }[];
   return {
     title: "Queued tasks, in line order",
@@ -236,7 +245,9 @@ function queueSection(workspaceId: string): Section {
           ? " | after any running task"
           : "";
       const status = r.status === "queued" ? "" : ` | ${r.status}`;
-      return `- ${i + 1}. ${clip(r.name ?? r.prompt, 80)} (${r.project}, id ${shortId(r.id)})${after}${status}`;
+      const priority = r.priority === "normal" ? "" : ` | ${r.priority}`;
+      const why = r.note ? ` | ${clip(r.note, 100)}` : "";
+      return `- ${i + 1}. ${clip(r.name ?? r.prompt, 80)} (${r.project}, id ${shortId(r.id)})${after}${priority}${status}${why}`;
     }),
     more: "the sessions tool",
   };

package/lib/orchestrator/serve.ts

@@ -12,6 +12,9 @@ import {
   stackStatus,
   startSession,
   startTask,
+  setTaskPriority,
+  pauseTask,
+  resumeTask,
   stop,
 } from "./act";
 import { readCards } from "./cards";
@@ -63,6 +66,9 @@ const ACTING = new Set<ToolName>([
   "move",
   "approve_plan",
   "plan_pieces",
+  "set_priority",
+  "pause_task",
+  "resume_task",
   "stop",
   "done",
   "review",
@@ -131,8 +137,20 @@ export async function runTool(
         plan: a.plan,
         planOnly: a.plan_only,
         planReason: a.plan_reason,
+        priority: a.priority,
+        machine: a.machine,
       });
     }
+    case "set_priority": {
+      const a = p(tool, raw);
+      return setTaskPriority(w, a.task, a.priority);
+    }
+    case "pause_task": {
+      const a = p(tool, raw);
+      return pauseTask(w, a.task, a.for, a.now ?? false, a.reason);
+    }
+    case "resume_task":
+      return resumeTask(w, p(tool, raw).task);
     case "approve_plan": {
       const a = p(tool, raw);
       const task = workspaceTask(w, a.task);

package/lib/orchestrator/tool-names.ts

@@ -29,6 +29,9 @@ export const TOOL_NAMES = {
   plan_pieces: name("plan_pieces"),
   drop: name("drop"),
   move: name("move"),
+  set_priority: name("set_priority"),
+  pause_task: name("pause_task"),
+  resume_task: name("resume_task"),
   stop: name("stop"),
   done: name("done"),
   archive: name("archive"),

package/lib/orchestrator/tool-schemas.ts

@@ -7,6 +7,7 @@ import { RAISED_KINDS } from "./asks";
 import { MAX_RULE_CHARS } from "./rules";
 import { PROJECT_NAME } from "../project-add/name";
 import { TASK_ROLES, type ModelRole } from "../models/roles";
+import { PRIORITIES } from "../tasks/schedule-types";
 
 const ref = (what: string) => z.string().trim().min(1).max(300).describe(what);
 const session = ref("Session name, project/name, or id from sessions");
@@ -115,6 +116,18 @@ export const TOOL_SHAPES = {
       .describe(
         'Queue it until this task finishes (id or name), or "any" for whichever running task finishes first'
       ),
+    priority: z
+      .enum(PRIORITIES)
+      .optional()
+      .describe(
+        "Where it stands in the queue: urgent (a bug Saad hit), blocking (something waits on it), normal (the default), background"
+      ),
+    machine: z
+      .enum(["mac", "any"])
+      .optional()
+      .describe(
+        'Where it may run: "mac" for work that needs this Mac (Xcode, a simulator); "any" if no machine need applies. Unset: the project\'s setting, else decided from its files'
+      ),
     model: modelOverride,
     plan: z
       .boolean()
@@ -233,6 +246,26 @@ export const TOOL_SHAPES = {
         'A linked machine\'s name (see Machines), or "here" to bring the task back'
       ),
   },
+  set_priority: {
+    task: ref("A queued or running task: name, project/name or id"),
+    priority: z.enum(PRIORITIES),
+  },
+  pause_task: {
+    task,
+    for: z
+      .enum(["1h", "2h", "tomorrow", "until_resumed"])
+      .describe(
+        "How long: 1h, 2h, tomorrow (9 AM, Saad's time) or until_resumed (until you or Saad resume it)"
+      ),
+    now: z
+      .boolean()
+      .optional()
+      .describe(
+        "Interrupt its step now. Default: let the step finish, then pause"
+      ),
+    reason: z.string().trim().min(1).max(300),
+  },
+  resume_task: { task },
   stop: { session },
   done: { session },
   archive: { session },

package/lib/orchestrator/tools.ts

@@ -62,7 +62,7 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   message_orchestrator:
     "Message another workspace's orchestrator, by workspace name; never any other session there. It arrives as its next prompt, marked as from you and fenced as untrusted.",
   start_task:
-    "Start a task: an agent in its own worktree that ends in a PR. It runs as a chat unless view is terminal (only for a job that needs a TUI). With after (a task's id or name, or \"any\"), or over the workspace's running task limit, it's queued and starts by itself; the result says Queued (position N). Its models follow the role settings (planning, implementation, review, scope); give model only when Saad asks for one. Always state plan (true or false) and plan_reason (plan_only true plans, then stops and waits for approve_plan instead of implementing): plan true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. Refused while a brake holds.",
+    'Start a task: an agent in its own worktree that ends in a PR. It runs as a chat unless view is terminal (only for a job that needs a TUI). priority (urgent, blocking, normal, background) says where it stands in the queue; machine "mac" pins work that needs this Mac. A busy machine holds a start and the result says why. With after (a task\'s id or name, or "any"), or over the workspace\'s running task limit, it\'s queued and starts by itself; the result says Queued (position N). Its models follow the role settings (planning, implementation, review, scope); give model only when Saad asks for one. Always state plan (true or false) and plan_reason (plan_only true plans, then stops and waits for approve_plan instead of implementing): plan true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. Refused while a brake holds.',
   set_task_model:
     'Resume a paused task on another model ("provider/model", or a map of role to one), keeping its conversation and worktree; it\'s told to carry on (or message). Refused mid-turn.',
   start_session:
@@ -81,6 +81,12 @@ const DESCRIPTIONS: Record<ToolName, string> = {
     "A task whose plan split into pieces: each piece, its repo, what it waits on and its state. With merge or drop (position numbers) it edits the pieces still waiting: a merged piece's slice goes to the piece before it, a dropped one is left out and anything waiting on it is held. It can't add pieces or change reasons.",
   drop: "Reject a task: close its PR and remove its worktree. A task still waiting in the queue is removed by its id. Logged with the reason.",
   move: 'Carry a running task to a linked machine, or back with "here": for heavy test or build work. It keeps its branch, conversation and plan; the gates, events, read, send, stop, done and drop work the same wherever it runs, and the machine it lands on can\'t merge it. Takes a few minutes and runs in the background; an event says when it lands. Refused while paused, for a task waiting on Saad (an escalation or open ask), and for card and stacked tasks.',
+  set_priority:
+    "Change the priority of a queued task (it re-ranks the line at once) or a running one (it only matters if it is paused and waits to resume). urgent starts first even on a busy machine; background starts last.",
+  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.",
   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:

package/lib/project-config/agentos.schema.json

@@ -151,6 +151,19 @@
       "required": ["start"],
       "additionalProperties": false
     },
+    "machine": {
+      "type": "object",
+      "properties": {
+        "needs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["mac", "xcode", "simulator"]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "database": {
       "type": "object",
       "properties": {

package/lib/project-config/schema.ts

@@ -69,6 +69,14 @@ const simulator = z.strictObject({
   device: z.string().min(1).optional(),
 });
 
+// What a project's tasks need from a machine (lib/tasks/placement.ts): `mac`,
+// `xcode`, `simulator`. A task whose needs a machine can't meet never starts
+// there; with none listed, repo files decide (an Xcode project implies all).
+export const MACHINE_NEEDS = ["mac", "xcode", "simulator"] as const;
+const machine = z.strictObject({
+  needs: z.array(z.enum(MACHINE_NEEDS)).optional(),
+});
+
 const database = z.strictObject({
   from: z.string().min(1),
   env: projectEnvName.optional(),
@@ -119,6 +127,7 @@ const shape = {
   notes: notes.optional(),
   browse: browse.optional(),
   simulator: simulator.optional(),
+  machine: machine.optional(),
   database: database.optional(),
   mcp: z.array(z.string().min(1)).optional(),
   model: z.string().min(1).optional(),

package/lib/sidebar/paused.ts

@@ -0,0 +1,13 @@
+import { wakeLabel } from "./snooze";
+
+// What a paused row says under its title.
+export function pauseSubtitle(
+  paused: { state: "pausing" | "paused" | "resuming"; until: number | null },
+  now: number = Date.now(),
+  timeZone?: string
+): string {
+  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";
+  return `Paused · resumes ${wakeLabel(paused.until, now, timeZone)}`;
+}

package/lib/sidebar/queued.ts

@@ -1,4 +1,9 @@
 import type { QueuedTaskView } from "@/lib/tasks/queue";
+import {
+  PRIORITIES,
+  PRIORITY_LABEL,
+  type Priority,
+} from "@/lib/tasks/schedule-types";
 
 export interface QueuedRow {
   item: QueuedTaskView;
@@ -71,7 +76,35 @@ export function queuedSubtitle(item: QueuedTaskView): {
   // Why a start it tried is held: the orchestrator paused, a brake.
   if (item.note) return { lead: item.note, after: null };
   if (item.after) return { lead: "After", after: item.after };
-  return { lead: `#${item.position} in line`, after: null };
+  const priority =
+    item.priority === "normal" ? "" : ` · ${PRIORITY_LABEL[item.priority]}`;
+  return { lead: `#${item.rank} of ${item.of}${priority}`, after: null };
+}
+
+// The priority choices for a waiting task's menu, the current one marked.
+export function priorityMenu(
+  item: Pick<QueuedTaskView, "priority" | "status">
+): { priority: Priority; label: string; current: boolean }[] {
+  if (item.status !== "queued") return [];
+  return PRIORITIES.map((priority) => ({
+    priority,
+    label: PRIORITY_LABEL[priority],
+    current: priority === item.priority,
+  }));
+}
+
+export function priorityRequest(
+  id: string,
+  priority: Priority
+): { url: string; init: RequestInit } {
+  return {
+    url: `/api/tasks/${encodeURIComponent(id)}/priority`,
+    init: {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ priority }),
+    },
+  };
 }
 
 export type QueueMenuAction = "start" | "up" | "down" | "remove";

package/lib/sidebar/shelves.ts

@@ -67,6 +67,10 @@ export interface SidebarRow {
   wakesAt?: number;
   // A plain session in Done: marked by hand, or settled by itself.
   settled?: "manual" | "auto";
+  // 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 };
 }
 
 export interface Shelves {
@@ -234,6 +238,7 @@ export function recipeRunOpen(session: Pick<Session, "recipe_run">): boolean {
 function toRow(input: ShelfInput, session: Session, now: number): SidebarRow {
   const status = input.statuses[session.id];
   const wakesAt = snoozedUntil(session, now);
+  const pauseState = session.pause_state;
   return {
     session,
     status,
@@ -241,6 +246,12 @@ function toRow(input: ShelfInput, session: Session, now: number): SidebarRow {
     unread: !!status?.unread || wokeUnread(session, now),
     activeAt: activeMs(session, now),
     ...(wakesAt && { wakesAt }),
+    ...(pauseState && {
+      paused: {
+        state: pauseState,
+        until: session.paused_until ? ms(session.paused_until) : null,
+      },
+    }),
     working:
       status?.status === "running" ||
       (status?.background ?? 0) > 0 ||
@@ -305,6 +316,8 @@ export function buildShelves(input: ShelfInput): Shelves {
     if (pinned && current) shelves.orchestrators.push(row);
     else if (pinned && role !== "orchestrator") shelves.pinned.push(row);
     else if (row.need) shelves.needsYou.push(row);
+    // A stopped agent is not working, whatever its last status said.
+    else if (row.paused?.state === "paused") shelves.snoozed.push(row);
     else if (row.working) shelves.working.push(row);
     else if (row.wakesAt) shelves.snoozed.push(row);
     else if (row.task || row.session.task_status)
@@ -323,7 +336,12 @@ export function buildShelves(input: ShelfInput): Shelves {
   shelves.working.sort(newestFirst);
   shelves.inReview.sort(newestFirst);
   shelves.ongoing.sort((a, b) => b.activeAt - a.activeAt);
-  shelves.snoozed.sort((a, b) => a.wakesAt! - b.wakesAt!);
+  // By when each comes back; a pause with no end goes last.
+  const comesBack = (r: SidebarRow) =>
+    r.paused?.state === "paused"
+      ? (r.paused.until ?? Number.POSITIVE_INFINITY)
+      : r.wakesAt!;
+  shelves.snoozed.sort((a, b) => comesBack(a) - comesBack(b));
   shelves.done.sort((a, b) => doneAtMs(b) - doneAtMs(a));
   return shelves;
 }
@@ -390,6 +408,8 @@ export function sameRow(a: SidebarRow, b: SidebarRow): boolean {
     a.task === b.task &&
     a.activeAt === b.activeAt &&
     a.wakesAt === b.wakesAt &&
+    a.paused?.state === b.paused?.state &&
+    a.paused?.until === b.paused?.until &&
     a.settled === b.settled &&
     a.workers.length === b.workers.length &&
     a.workers.every((w, i) => sameRow(w, b.workers[i])) &&