@saadnvd1/agent-os 0.3.584 → 0.3.587

package/lib/bookmarks/store.ts

@@ -0,0 +1,333 @@
+/**
+ * Bookmarks: a person's "come back to this" marks on single chat items,
+ * keyed by the item's stable id. Each keeps a redacted snapshot of what it
+ * marks, so it can be searched and still reads after the chat is gone.
+ */
+
+import { randomUUID } from "crypto";
+import { db, type Session } from "../db";
+import type { ChatItem } from "../chat/events";
+import { getItem } from "../chat/store";
+import { getProject } from "../projects";
+import { snapshotText } from "./snapshot";
+import {
+  BOOKMARKABLE_KINDS,
+  MAX_NOTE_CHARS,
+  type Bookmark,
+  type BookmarkKind,
+  type BookmarkScope,
+  type BookmarksPage,
+} from "./types";
+
+// An orchestrator's own workspace, or its project's (as sessionWorkspace in
+// lib/schedules/store, without pulling the scheduler into a move).
+const sessionWorkspace = (s: Session): string | null =>
+  s.workspace_id ??
+  (s.project_id ? (getProject(s.project_id)?.workspace_id ?? null) : null);
+
+/** A refusal the routes turn into its status. */
+export class BookmarkError extends Error {
+  constructor(
+    message: string,
+    readonly status: 400 | 404
+  ) {
+    super(message);
+  }
+}
+
+interface Row {
+  id: string;
+  session_id: string;
+  item_id: string;
+  scope: BookmarkScope;
+  workspace_id: string | null;
+  kind: BookmarkKind;
+  text: string;
+  session_name: string;
+  note: string | null;
+  created_at: string;
+}
+
+type Joined = Row & {
+  s_id: string | null;
+  task_status: string | null;
+  archived_at: string | null;
+};
+
+// The bookmark with its chat's state as of now.
+const SELECT = `
+  SELECT b.*, s.id AS s_id, s.task_status, s.archived_at
+  FROM chat_bookmarks b LEFT JOIN sessions s ON s.id = b.session_id`;
+
+function toBookmark(r: Joined): Bookmark {
+  return {
+    id: r.id,
+    sessionId: r.session_id,
+    itemId: r.item_id,
+    scope: r.scope,
+    kind: r.kind,
+    text: r.text,
+    note: r.note,
+    sessionName: r.session_name,
+    workspaceId: r.workspace_id,
+    createdAt: r.created_at,
+    state: !r.s_id
+      ? "deleted"
+      : r.task_status === "moved"
+        ? "moved"
+        : r.archived_at
+          ? "archived"
+          : "live",
+  };
+}
+
+export function getBookmark(id: string): Bookmark | null {
+  const r = db.prepare(`${SELECT} WHERE b.id = ?`).get(id) as
+    | Joined
+    | undefined;
+  return r ? toBookmark(r) : null;
+}
+
+const cleanNote = (note: unknown): string | null => {
+  if (note === null || note === undefined) return null;
+  if (typeof note !== "string") throw new BookmarkError("Bad note", 400);
+  const t = note.replace(/\s+/g, " ").trim().slice(0, MAX_NOTE_CHARS);
+  return t || null;
+};
+
+// The first reply in the turn a user item starts, for its excerpt.
+function firstReply(
+  sessionId: string,
+  userItemId: string
+): ChatItem | undefined {
+  const rows = db
+    .prepare(
+      `SELECT data FROM chat_items
+       WHERE session_id = ? AND seq > (
+         SELECT seq FROM chat_items WHERE session_id = ? AND item_id = ?)
+       ORDER BY seq LIMIT 200`
+    )
+    .all(sessionId, sessionId, userItemId) as { data: string }[];
+  for (const r of rows) {
+    let item: ChatItem | null;
+    try {
+      item = JSON.parse(r.data) as ChatItem | null;
+    } catch {
+      item = null;
+    }
+    // A row that isn't an item just isn't the reply.
+    if (!item || typeof item !== "object") continue;
+    if (item.kind === "user" || item.kind === "turn_end") return undefined;
+    if (item.kind === "assistant" && item.text.trim()) return item;
+  }
+  return undefined;
+}
+
+/**
+ * Marks an item. Idempotent: the same item and scope again returns the
+ * bookmark it already has, with `created: false`.
+ */
+export function createBookmark(input: {
+  sessionId: string;
+  itemId?: unknown;
+  scope?: unknown;
+  note?: unknown;
+}): { bookmark: Bookmark; created: boolean } {
+  const { sessionId } = input;
+  if (typeof input.itemId !== "string" || !input.itemId)
+    throw new BookmarkError("itemId is required", 400);
+  const scope = input.scope ?? "item";
+  if (scope !== "item" && scope !== "turn")
+    throw new BookmarkError("scope must be 'item' or 'turn'", 400);
+  const note = cleanNote(input.note);
+  const session = db
+    .prepare(`SELECT * FROM sessions WHERE id = ?`)
+    .get(sessionId) as Session | undefined;
+  if (!session) throw new BookmarkError("Session not found", 404);
+  const existing = db
+    .prepare(
+      `SELECT id FROM chat_bookmarks WHERE session_id = ? AND item_id = ? AND scope = ?`
+    )
+    .get(sessionId, input.itemId, scope) as { id: string } | undefined;
+  if (existing) return { bookmark: getBookmark(existing.id)!, created: false };
+  const item = getItem(sessionId, input.itemId);
+  if (!item) throw new BookmarkError("Message not found", 404);
+  if (!(BOOKMARKABLE_KINDS as readonly string[]).includes(item.kind))
+    throw new BookmarkError("That can't be bookmarked", 400);
+  if (scope === "turn" && item.kind !== "user")
+    throw new BookmarkError("A turn is bookmarked by its first message", 400);
+  const kind = (scope === "turn" ? "turn" : item.kind) as BookmarkKind;
+  const text = snapshotText(
+    item,
+    scope === "turn" ? firstReply(sessionId, item.id) : undefined
+  );
+  const id = randomUUID();
+  db.prepare(
+    `INSERT INTO chat_bookmarks
+       (id, session_id, item_id, scope, workspace_id, kind, text, session_name, note)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT (session_id, item_id, scope) DO NOTHING`
+  ).run(
+    id,
+    sessionId,
+    item.id,
+    scope,
+    sessionWorkspace(session),
+    kind,
+    text,
+    session.name,
+    note
+  );
+  // A request that raced this one may have made it first.
+  const made = db
+    .prepare(
+      `SELECT id FROM chat_bookmarks WHERE session_id = ? AND item_id = ? AND scope = ?`
+    )
+    .get(sessionId, item.id, scope) as { id: string };
+  return { bookmark: getBookmark(made.id)!, created: made.id === id };
+}
+
+/** One chat's bookmarks, in the order they appear in it. */
+export function listSessionBookmarks(sessionId: string): Bookmark[] {
+  return (
+    db
+      .prepare(
+        `${SELECT}
+         LEFT JOIN chat_items c ON c.session_id = b.session_id AND c.item_id = b.item_id
+         WHERE b.session_id = ?
+         ORDER BY c.seq IS NULL, c.seq, b.created_at, b.id`
+      )
+      .all(sessionId) as Joined[]
+  ).map(toBookmark);
+}
+
+const escapeLike = (s: string) => s.replace(/[\\%_]/g, (c) => `\\${c}`);
+
+const cursorOf = (b: Bookmark) => `${b.createdAt}|${b.id}`;
+
+/**
+ * Bookmarks across chats, newest first: one workspace's (null: those with
+ * none) or every one's, matching `q` in the text, the note or the chat's
+ * name. The copy a move left behind isn't listed: its live twin is.
+ */
+export function listBookmarks(opts: {
+  workspace: string | null | "all";
+  q?: string;
+  before?: string | null;
+  limit?: number;
+}): BookmarksPage {
+  const limit = Math.min(Math.max(opts.limit ?? 50, 1), 200);
+  const where = [`(s.task_status IS NULL OR s.task_status != 'moved')`];
+  const args: (string | number)[] = [];
+  if (opts.workspace === null) where.push(`b.workspace_id IS NULL`);
+  else if (opts.workspace !== "all") {
+    where.push(`b.workspace_id = ?`);
+    args.push(opts.workspace);
+  }
+  const q = opts.q?.trim();
+  if (q) {
+    const like = `%${escapeLike(q)}%`;
+    where.push(
+      `(b.text LIKE ? ESCAPE '\\' OR b.note LIKE ? ESCAPE '\\' OR b.session_name LIKE ? ESCAPE '\\')`
+    );
+    args.push(like, like, like);
+  }
+  if (opts.before) {
+    const at = opts.before.lastIndexOf("|");
+    if (at > 0) {
+      where.push(`(b.created_at < ? OR (b.created_at = ? AND b.id < ?))`);
+      const created = opts.before.slice(0, at);
+      args.push(created, created, opts.before.slice(at + 1));
+    }
+  }
+  const rows = (
+    db
+      .prepare(
+        `${SELECT} WHERE ${where.join(" AND ")}
+         ORDER BY b.created_at DESC, b.id DESC LIMIT ?`
+      )
+      .all(...args, limit + 1) as Joined[]
+  ).map(toBookmark);
+  const more = rows.length > limit;
+  const bookmarks = more ? rows.slice(0, limit) : rows;
+  return {
+    bookmarks,
+    next: more ? cursorOf(bookmarks[bookmarks.length - 1]) : null,
+  };
+}
+
+export function setBookmarkNote(id: string, note: unknown): Bookmark | null {
+  const clean = cleanNote(note);
+  const changed = db
+    .prepare(`UPDATE chat_bookmarks SET note = ? WHERE id = ?`)
+    .run(clean, id).changes;
+  return changed ? getBookmark(id) : null;
+}
+
+export function removeBookmark(id: string): boolean {
+  return (
+    db.prepare(`DELETE FROM chat_bookmarks WHERE id = ?`).run(id).changes > 0
+  );
+}
+
+/** What a move carries: the chat's bookmarks, as stored. */
+export interface MovedBookmark {
+  itemId: string;
+  scope: BookmarkScope;
+  kind: BookmarkKind;
+  text: string;
+  note: string | null;
+  createdAt: string;
+}
+
+export function bookmarksForMove(sessionId: string): MovedBookmark[] {
+  return (
+    db
+      .prepare(
+        `SELECT item_id, scope, kind, text, note, created_at
+         FROM chat_bookmarks WHERE session_id = ? ORDER BY created_at, id`
+      )
+      .all(sessionId) as Row[]
+  ).map((r) => ({
+    itemId: r.item_id,
+    scope: r.scope,
+    kind: r.kind,
+    text: r.text,
+    note: r.note,
+    createdAt: r.created_at,
+  }));
+}
+
+/**
+ * Writes a moved chat's bookmarks under the row it arrived as, scoped to
+ * that row's workspace here. Run inside the transaction that makes the row.
+ */
+export function insertMovedBookmarks(
+  sessionId: string,
+  rows: MovedBookmark[]
+): void {
+  if (!rows.length) return;
+  const session = db
+    .prepare(`SELECT * FROM sessions WHERE id = ?`)
+    .get(sessionId) as Session | undefined;
+  if (!session) return;
+  const workspace = sessionWorkspace(session);
+  const insert = db.prepare(
+    `INSERT OR IGNORE INTO chat_bookmarks
+       (id, session_id, item_id, scope, workspace_id, kind, text, session_name, note, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+  for (const r of rows)
+    insert.run(
+      randomUUID(),
+      sessionId,
+      r.itemId,
+      r.scope,
+      workspace,
+      r.kind,
+      r.text,
+      session.name,
+      r.note,
+      r.createdAt
+    );
+}

package/lib/bookmarks/types.ts

@@ -0,0 +1,38 @@
+// A person's mark on one chat item, shared by the routes, the web app and
+// the native app.
+
+export type BookmarkScope = "item" | "turn";
+export type BookmarkKind = "user" | "assistant" | "tool" | "turn";
+// live: the chat is there; archived: it is, archived; moved: this row is the
+// copy left behind by a move; deleted: the chat is gone, the snapshot stays.
+export type BookmarkState = "live" | "archived" | "moved" | "deleted";
+
+export interface Bookmark {
+  id: string;
+  sessionId: string;
+  itemId: string;
+  scope: BookmarkScope;
+  kind: BookmarkKind;
+  text: string;
+  note: string | null;
+  sessionName: string;
+  workspaceId: string | null;
+  createdAt: string;
+  state: BookmarkState;
+}
+
+export interface BookmarksPage {
+  bookmarks: Bookmark[];
+  // Pass as `before` for the next page; null on the last one.
+  next: string | null;
+}
+
+export const BOOKMARKABLE_KINDS = ["user", "assistant", "tool"] as const;
+
+export const MAX_NOTE_CHARS = 500;
+// A snapshot is clipped to this, plus the ellipsis that marks the cut.
+export const MAX_SNAPSHOT_CHARS = 4_000;
+
+// The key the stars look a bookmark up by.
+export const bookmarkKey = (itemId: string, scope: BookmarkScope) =>
+  `${itemId}:${scope}`;

package/lib/db/changes.ts

@@ -41,6 +41,8 @@ export const TABLES_WATCHED_80 = [
   "feature_pieces",
 ] as const;
 
+export const TABLES_WATCHED_CHAT_BOOKMARKS = ["chat_bookmarks"] as const;
+
 // Every table any migration watches, for the browser's topic map to cover.
 export const WATCHED_TABLES: readonly string[] = [
   ...TABLES_WATCHED_45,
@@ -49,6 +51,7 @@ export const WATCHED_TABLES: readonly string[] = [
   ...TABLES_WATCHED_58,
   ...TABLES_WATCHED_78,
   ...TABLES_WATCHED_80,
+  ...TABLES_WATCHED_CHAT_BOOKMARKS,
 ];
 
 export function installChangeTriggers(

package/lib/db/migrations.ts

@@ -6,6 +6,7 @@ import {
   TABLES_WATCHED_58,
   TABLES_WATCHED_78,
   TABLES_WATCHED_80,
+  TABLES_WATCHED_CHAT_BOOKMARKS,
 } from "./changes";
 import type Database from "better-sqlite3";
 import { moveSchedulesToRecipes } from "./schedules-move";
@@ -2297,6 +2298,33 @@ export const migrations: Migration[] = [
       `);
     },
   },
+  {
+    key: "20261014T2000_chat_bookmarks",
+    up: (db) => {
+      // A person's marks on single chat items. No FK to sessions: a
+      // bookmark outlives a deleted chat with its own snapshot. Additive.
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS chat_bookmarks (
+          id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          item_id TEXT NOT NULL,
+          scope TEXT NOT NULL DEFAULT 'item',
+          workspace_id TEXT,
+          kind TEXT NOT NULL,
+          text TEXT NOT NULL,
+          session_name TEXT NOT NULL,
+          note TEXT,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          UNIQUE (session_id, item_id, scope)
+        )
+      `);
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_chat_bookmarks_ws
+           ON chat_bookmarks(workspace_id, created_at DESC)`
+      );
+      installChangeTriggers(db, TABLES_WATCHED_CHAT_BOOKMARKS);
+    },
+  },
 ];
 
 // `upTo`: stop after this legacy id or timestamp key, inclusive (tests that

package/lib/orchestrator/act.ts

@@ -26,7 +26,9 @@ import {
   findQueued,
   queuedLabel,
   removeQueued,
+  slotState,
   startOrQueue,
+  startQueuedForOrchestrator,
 } from "../tasks/queue";
 import { getStack, previewStack, startStack } from "../stacks";
 import { treeOrder } from "../stacks/tree";
@@ -155,10 +157,14 @@ export async function startTask(
     planReason?: string;
     priority?: Priority;
     machine?: "mac" | "any";
+    now?: boolean;
+    nowReason?: string;
   } = {}
 ): Promise<string> {
   if (opts.planOnly && opts.plan === false)
     throw new Error("plan_only implies plan; pass plan true");
+  if (opts.now && !opts.nowReason)
+    throw new Error("now needs now_reason: say why it can't wait for a slot");
   const project = workspaceProject(workspaceId, projectRef);
   const model = parseOverride(opts.model) ?? undefined;
   const startedBy = orchestratorId(workspaceId);
@@ -168,6 +174,7 @@ export async function startTask(
       `${project.name} runs on another machine; the orchestrator starts tasks on this one only for now`
     );
   const view = opts.view ?? DEFAULT_START_VIEW;
+  const slots = slotState(project.id);
   // Held for a slot or its `after`, it starts by itself through the brakes;
   // you get an event when it does.
   const out = await startOrQueue(
@@ -186,6 +193,7 @@ export async function startTask(
       originWorkspaceId: workspaceId,
       priority: opts.priority,
       machine: opts.machine,
+      now: opts.now,
     },
     () =>
       braked(
@@ -213,6 +221,12 @@ export async function startTask(
   }
   const task = out.started;
   if (opts.priority) stampPriority(task.id, opts.priority);
+  const past = opts.now && slots.full && !opts.planOnly;
+  if (past)
+    addNote(
+      workspaceId,
+      `Started "${task.name}" past the running-task limit (${slots.running} of ${slots.limit} running): ${opts.nowReason}`
+    );
   const planOnlyNote = opts.planOnly
     ? " Plan only: it stops after the plan and waits; approve_plan continues it, drop rejects it."
     : "";
@@ -220,7 +234,39 @@ export async function startTask(
     opts.plan && !opts.planOnly && task.plan_phase !== "planning"
       ? ` Plan step skipped: ${view === "terminal" ? "a terminal task has none" : "planning and implementation use the same model"}.`
       : "";
-  return `Started task "${task.name}" (id ${task.id.slice(0, 8)}, ${view}) in ${project.name} on ${task.branch_name} (from ${task.base_branch}). It ends in a PR; you'll get an event when it opens.${skipped}${planOnlyNote}`;
+  return `Started task "${task.name}" (id ${task.id.slice(0, 8)}, ${view}) in ${project.name} on ${task.branch_name} (from ${task.base_branch}). It ends in a PR; you'll get an event when it opens.${skipped}${planOnlyNote}${past ? " Started past the running-task limit." : ""}`;
+}
+
+// Starts a queued task now, past the running-task limit and its `after`.
+// Pause, the brakes and a machine need still hold it.
+export async function startNow(
+  workspaceId: string,
+  ref: string,
+  reason: string
+): Promise<string> {
+  const queued = findQueued(workspaceId, ref, { byName: true });
+  if (!queued) {
+    const running = workspaceTask(workspaceId, ref);
+    throw new Error(`${running.name} is already started, not queued`);
+  }
+  const name = queuedLabel(queued);
+  const out = await startQueuedForOrchestrator(workspaceId, queued.id);
+  if (out.outcome === "held")
+    return `Not started: ${out.text}. ${name} stays in the queue.`;
+  if (out.outcome === "failed") return `Could not start ${name}: ${out.text}.`;
+  const skipped = [
+    out.wasFull
+      ? `past the running-task limit (${out.running} of ${out.limit} running)`
+      : "",
+    out.skippedAfter ? "without waiting for its after" : "",
+  ]
+    .filter(Boolean)
+    .join(", ");
+  addNote(
+    workspaceId,
+    `Started queued ${name} now${skipped ? `, ${skipped}` : ""}: ${reason}`
+  );
+  return `Started ${name} (id ${queued.id.slice(0, 8)}) now${skipped ? `, ${skipped}` : ""}. You'll get an event when its PR opens.`;
 }
 
 // The orchestrator approves a plan-only task's plan; a message amends it.

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?, 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.start_task}\` (project, prompt, base?, name?, view?, after?, priority?, machine?, now?, now_reason?, 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. now true (with now_reason, not with after) starts it at once past the limit instead; it's logged for Saad, so use it only when it can't wait. 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.
@@ -135,6 +135,7 @@ Acting:
 - \`${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.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.stop}\` (session): stop a session's agent, keeping its work.

package/lib/orchestrator/serve.ts

@@ -12,6 +12,7 @@ import {
   stackStatus,
   startSession,
   startTask,
+  startNow,
   setTaskPriority,
   pauseTask,
   resumeTask,
@@ -67,6 +68,7 @@ const ACTING = new Set<ToolName>([
   "approve_plan",
   "plan_pieces",
   "set_priority",
+  "start_now",
   "pause_task",
   "resume_task",
   "stop",
@@ -139,8 +141,14 @@ export async function runTool(
         planReason: a.plan_reason,
         priority: a.priority,
         machine: a.machine,
+        now: a.now,
+        nowReason: a.now_reason,
       });
     }
+    case "start_now": {
+      const a = p(tool, raw);
+      return startNow(w, a.task, a.reason);
+    }
     case "set_priority": {
       const a = p(tool, raw);
       return setTaskPriority(w, a.task, a.priority);

package/lib/orchestrator/tool-names.ts

@@ -30,6 +30,7 @@ export const TOOL_NAMES = {
   drop: name("drop"),
   move: name("move"),
   set_priority: name("set_priority"),
+  start_now: name("start_now"),
   pause_task: name("pause_task"),
   resume_task: name("resume_task"),
   stop: name("stop"),

package/lib/orchestrator/tool-schemas.ts

@@ -128,6 +128,19 @@ export const TOOL_SHAPES = {
       .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'
       ),
+    now: z
+      .boolean()
+      .optional()
+      .describe(
+        "Start it at once, past the workspace's running-task limit, instead of queueing for a slot. Needs now_reason; not with after"
+      ),
+    now_reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(300)
+      .optional()
+      .describe("With now: why it can't wait for a slot; logged for Saad"),
     model: modelOverride,
     plan: z
       .boolean()
@@ -250,6 +263,15 @@ export const TOOL_SHAPES = {
     task: ref("A queued or running task: name, project/name or id"),
     priority: z.enum(PRIORITIES),
   },
+  start_now: {
+    task: ref("A queued task: name, project/name or id"),
+    reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(300)
+      .describe("Why it can't wait for a slot; logged for Saad"),
+  },
   pause_task: {
     task,
     for: z

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). 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.',
+    '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. now true (with now_reason) starts it at once past the running-task limit instead of queueing for a slot, logged; not with after. 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:
@@ -83,6 +83,8 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   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.",
+  start_now:
+    "Start a queued task now, past the workspace's running-task limit and its after, when it can't wait for a slot (Saad asked, or it unblocks others). Still refused while paused or braked, and a task that needs a Mac stays queued. Give a reason: it goes in the decision log. Says whether it started, is still held and why, or failed.",
   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: