@saadnvd1/agent-os 0.3.700 → 0.3.715

package/lib/db/migrations/20261020T1800_session_groups.ts

@@ -0,0 +1,49 @@
+import type { Migration } from "../migration-types";
+import {
+  installChangeTriggers,
+  TABLES_WATCHED_SESSION_GROUPS,
+} from "../changes";
+import { createSessionRowsView } from "../session-parts/view";
+
+export default {
+  key: "20261020T1800_session_groups",
+  up: (db) => {
+    // Named shelves a user files sessions into (lib/session-groups). Not the
+    // old `groups` table, which nothing reads. Additive.
+    db.exec(`CREATE TABLE IF NOT EXISTS session_groups (
+      id TEXT PRIMARY KEY,
+      workspace_id TEXT REFERENCES workspaces(id) ON DELETE SET NULL,
+      name TEXT NOT NULL,
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      collapsed INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      deleted_at TEXT
+    )`);
+    db.exec(
+      `CREATE UNIQUE INDEX IF NOT EXISTS session_groups_name
+         ON session_groups(COALESCE(workspace_id, ''), lower(name))
+         WHERE deleted_at IS NULL`
+    );
+    const has = (
+      db.prepare(`PRAGMA table_info(sessions)`).all() as { name: string }[]
+    ).some((c) => c.name === "session_group_id");
+    if (!has)
+      db.exec(
+        `ALTER TABLE sessions ADD COLUMN session_group_id TEXT
+           REFERENCES session_groups(id) ON DELETE SET NULL`
+      );
+    db.exec(
+      `CREATE INDEX IF NOT EXISTS sessions_session_group
+         ON sessions(session_group_id)`
+    );
+    // A queued task remembers the group it starts in.
+    const queueHas = (
+      db.prepare(`PRAGMA table_info(task_queue)`).all() as { name: string }[]
+    ).some((c) => c.name === "session_group_id");
+    if (!queueHas)
+      db.exec(`ALTER TABLE task_queue ADD COLUMN session_group_id TEXT`);
+    createSessionRowsView(db);
+    installChangeTriggers(db, TABLES_WATCHED_SESSION_GROUPS);
+  },
+} satisfies Migration;

package/lib/db/migrations/20261020T1900_task_queue_after_claim.ts

@@ -0,0 +1,13 @@
+import type { Migration } from "../migration-types";
+
+export default {
+  key: "20261020T1900_task_queue_after_claim",
+  up: (db) => {
+    // The work claim (lib/claims) a queued task waits on, by claim id.
+    const cols = db.prepare(`PRAGMA table_info(task_queue)`).all() as {
+      name: string;
+    }[];
+    if (!cols.some((c) => c.name === "after_claim"))
+      db.exec(`ALTER TABLE task_queue ADD COLUMN after_claim TEXT`);
+  },
+} satisfies Migration;

package/lib/db/migrations/20261020T2000_claim_notices.ts

@@ -0,0 +1,20 @@
+import type { Migration } from "../migration-types";
+
+export default {
+  key: "20261020T2000_claim_notices",
+  up: (db) => {
+    // What a mid-work overlap between two claims has told the local session:
+    // how many syncs it has held, the shared paths last told, and whether the
+    // winner's merge has been passed on. Times are this machine's clock in ms.
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS claim_notices (
+        pair_key TEXT PRIMARY KEY,
+        hits INTEGER NOT NULL DEFAULT 0,
+        shared TEXT NOT NULL DEFAULT '[]',
+        told_at INTEGER,
+        merged_at INTEGER,
+        seen_at INTEGER NOT NULL
+      );
+    `);
+  },
+} satisfies Migration;

package/lib/db/migrations/20261020T2100_claims_via_host.ts

@@ -0,0 +1,21 @@
+import type { Migration } from "../migration-types";
+
+export default {
+  key: "20261020T2100_claims_via_host",
+  up: (db) => {
+    // The link (hosts.id) a remote claim arrived through, and which claims
+    // machine each link talks to, so a machine linked twice is asked once.
+    const cols = db.prepare(`PRAGMA table_info(work_claims)`).all() as {
+      name: string;
+    }[];
+    if (!cols.some((c) => c.name === "via_host"))
+      db.exec(`ALTER TABLE work_claims ADD COLUMN via_host TEXT`);
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS claim_peers (
+        host_id TEXT PRIMARY KEY,
+        machine_id TEXT NOT NULL,
+        seen_at INTEGER NOT NULL
+      );
+    `);
+  },
+} satisfies Migration;

package/lib/db/migrations/20261020T2200_work_claims_watch.ts

@@ -0,0 +1,10 @@
+import type { Migration } from "../migration-types";
+import { installChangeTriggers, TABLES_WATCHED_WORK_CLAIMS } from "../changes";
+
+export default {
+  key: "20261020T2200_work_claims_watch",
+  up: (db) => {
+    // The claims sheet and the overlap pills refetch when a claim changes.
+    installChangeTriggers(db, TABLES_WATCHED_WORK_CLAIMS);
+  },
+} satisfies Migration;

package/lib/db/queries.ts

@@ -94,24 +94,6 @@ export const queries = {
       `UPDATE sessions SET worktree_path = ?, branch_name = ?, base_branch = ?, dev_server_port = ?, updated_at = datetime('now') WHERE id = ?`
     ),
 
-  updateSessionGroup: (db: Database.Database) =>
-    getStmt(
-      db,
-      `UPDATE sessions SET group_path = ?, updated_at = datetime('now') WHERE id = ?`
-    ),
-
-  getSessionsByGroup: (db: Database.Database) =>
-    getStmt(
-      db,
-      `SELECT * FROM session_rows WHERE group_path = ? ORDER BY updated_at DESC`
-    ),
-
-  moveSessionsToGroup: (db: Database.Database) =>
-    getStmt(
-      db,
-      `UPDATE sessions SET group_path = ?, updated_at = datetime('now') WHERE group_path = ?`
-    ),
-
   updateSessionProject: (db: Database.Database) =>
     getStmt(
       db,
@@ -196,28 +178,6 @@ export const queries = {
       `SELECT * FROM tool_calls WHERE message_id = ? ORDER BY timestamp ASC`
     ),
 
-  // Groups
-  getAllGroups: (db: Database.Database) =>
-    getStmt(db, `SELECT * FROM groups ORDER BY sort_order ASC, name ASC`),
-
-  getGroup: (db: Database.Database) =>
-    getStmt(db, `SELECT * FROM groups WHERE path = ?`),
-
-  createGroup: (db: Database.Database) =>
-    getStmt(db, `INSERT INTO groups (path, name, sort_order) VALUES (?, ?, ?)`),
-
-  updateGroupName: (db: Database.Database) =>
-    getStmt(db, `UPDATE groups SET name = ? WHERE path = ?`),
-
-  updateGroupExpanded: (db: Database.Database) =>
-    getStmt(db, `UPDATE groups SET expanded = ? WHERE path = ?`),
-
-  updateGroupOrder: (db: Database.Database) =>
-    getStmt(db, `UPDATE groups SET sort_order = ? WHERE path = ?`),
-
-  deleteGroup: (db: Database.Database) =>
-    getStmt(db, `DELETE FROM groups WHERE path = ?`),
-
   // Projects
   createProject: (db: Database.Database) =>
     getStmt(

package/lib/db/session-parts/columns.ts

@@ -183,4 +183,5 @@ export const SESSION_ROW_COLUMNS: readonly string[] = [
   "started_via",
   "plan_waits_for_caller",
   "plan_handoff_message",
+  "session_group_id",
 ];

package/lib/db/types.ts

@@ -94,11 +94,23 @@ export interface Session {
   // it, as a short line (lib/bus/waits/store).
   waiting_on?: string | null;
   waited_by?: string | null;
+  // Set only by GET /api/sessions: the strongest overlap of this session's
+  // work with a claim here or on a linked machine (lib/claims/overlapCache).
+  overlap?: {
+    strength: "strong" | "weak";
+    machine: string;
+    goal: string;
+    shared: number;
+    claimId: string;
+    mineId: string;
+  } | 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).
   pinned: boolean;
+  // The user's group it sits in (session_groups), or null.
+  session_group_id?: string | null;
   // A workspace's standing orchestrator chat (and that workspace), or null.
   role: "orchestrator" | null;
   // An orchestrator's tool-call secret.
@@ -165,14 +177,6 @@ export interface Session {
   worker_status: "pending" | "running" | "completed" | "failed" | null;
 }
 
-export interface Group {
-  path: string;
-  name: string;
-  expanded: boolean;
-  sort_order: number;
-  created_at: string;
-}
-
 // production: every merge gate applies. fast: a task's PR merges when it opens.
 export type ProjectTier = "production" | "fast";
 
@@ -314,4 +318,8 @@ export interface Host {
   kind?: "ssh" | "connect";
   // Paired with that machine's own AgentOS (lib/hosts/link.ts); 0/1 from SQLite.
   linked?: boolean | number;
+  // Connect hosts (lib/peer): the link's state, and why it's suspended or
+  // who unlinked it.
+  peer_state?: "active" | "suspended" | "unlinked" | null;
+  peer_note?: string | null;
 }

package/lib/doctor/checks.ts

@@ -5,7 +5,11 @@
  */
 
 import { execFile } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
 import { promisify } from "util";
+import { agentOsHome, liveCheckout } from "../dev-instance/liveServer";
 import { probeAgents, type AgentProbe } from "../agents/probe";
 import { getAllProviderDefinitions } from "../providers/registry";
 
@@ -37,12 +41,14 @@ export interface DoctorDeps {
   exec: ExecFn;
   probe: (fresh: boolean) => Promise<Record<string, AgentProbe>>;
   nodeVersion: string;
+  cliLinks: () => DoctorCheck | null;
 }
 
 const defaultDeps: DoctorDeps = {
   exec: promisify(execFile) as ExecFn,
   probe: probeAgents,
   nodeVersion: process.versions.node,
+  cliLinks: () => checkCliLinks(),
 };
 
 const INSTALL = {
@@ -190,6 +196,62 @@ export function checkAgents(probes: Record<string, AgentProbe>): DoctorCheck {
   };
 }
 
+const CLI_LINKS: Array<[string, string]> = [
+  ["agent-os", "scripts/agent-os"],
+  ["aos", "bin/aos"],
+];
+
+const real = (p: string) => {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Do the CLI links in ~/.local/bin run the checkout the live server runs from?
+ * A link into an older clone runs an old `aos`. Null when there is no live
+ * server record or no link to judge.
+ */
+export function checkCliLinks(
+  binDir = process.env.AOS_BIN_DIR || path.join(os.homedir(), ".local/bin"),
+  home = agentOsHome()
+): DoctorCheck | null {
+  const live = liveCheckout(home);
+  if (!live) return null;
+  const stale: string[] = [];
+  let seen = 0;
+  for (const [name, rel] of CLI_LINKS) {
+    const link = path.join(binDir, name);
+    let target: string;
+    try {
+      target = fs.readlinkSync(link);
+    } catch {
+      continue;
+    }
+    seen++;
+    const want = real(path.join(live, rel));
+    if (!want || real(path.resolve(binDir, target)) !== want)
+      stale.push(`${name} -> ${target}`);
+  }
+  if (seen === 0) return null;
+  if (stale.length === 0)
+    return {
+      id: "cli-links",
+      label: "CLI links",
+      status: "ok",
+      detail: `Point at ${live}`,
+    };
+  return {
+    id: "cli-links",
+    label: "CLI links",
+    status: "warn",
+    detail: `${stale.join(", ")}; the live server runs from ${live}`,
+    fix: `${live}/scripts/sync-cli-links`,
+  };
+}
+
 let cache: { at: number; checks: Promise<DoctorCheck[]> } | null = null;
 
 /** Every check, in parallel, cached for a minute. `fresh` runs them again. */
@@ -214,7 +276,8 @@ export function runDoctor(
         detail: "Couldn't check the agent CLIs",
         fix: "Check again",
       })),
-  ]);
+    Promise.resolve(d.cliLinks()),
+  ]).then((all) => all.filter((c): c is DoctorCheck => c !== null));
   if (!custom) cache = { at: Date.now(), checks };
   return checks;
 }

package/lib/git-remote.ts

@@ -12,6 +12,36 @@ export function slugOfRemote(url: string | null | undefined): string | null {
   return m ? `${m[1]}/${m[2]}`.toLowerCase() : null;
 }
 
+// A repository's key across clones and URL forms: ssh and https of the same
+// remote give the same key, with no scheme, credentials, port or ".git".
+// "host/path", lower case; null for anything that isn't a remote URL.
+export function repoKeyOfRemote(url: string | null | undefined): string | null {
+  const raw = (url ?? "").trim();
+  if (!raw) return null;
+  let host = "";
+  let path = "";
+  const scp = /^(?:[^@/:\s]+@)?([^/:\s]+):(?!\/\/)(.+)$/.exec(raw);
+  if (scp && !/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    host = scp[1];
+    path = scp[2];
+  } else {
+    try {
+      const u = new URL(raw);
+      if (!/^(https?|ssh|git):$/.test(u.protocol)) return null;
+      host = u.hostname;
+      path = u.pathname;
+    } catch {
+      return null;
+    }
+  }
+  path = path
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/\.git$/i, "")
+    .toLowerCase();
+  host = host.toLowerCase();
+  return host && path.includes("/") ? `${host}/${path}` : null;
+}
+
 // A remote's URL doesn't change under a running server often enough to ask
 // git on every lookup.
 const SLUG_TTL_MS = 5 * 60 * 1000;
@@ -45,3 +75,16 @@ export function repoSlugSync(dir: string): string | null {
   slugs.set(dir, { at: Date.now(), slug });
   return slug;
 }
+
+const keys = new Map<string, { at: number; key: string | null }>();
+
+export async function repoKey(dir: string): Promise<string | null> {
+  const hit = keys.get(dir);
+  if (hit && Date.now() - hit.at < SLUG_TTL_MS) return hit.key;
+  const url = await git(dir, ["config", "--get", "remote.origin.url"], {
+    timeout: 10000,
+  }).catch(() => "");
+  const key = repoKeyOfRemote(url);
+  keys.set(dir, { at: Date.now(), key });
+  return key;
+}

package/lib/hosts/index.ts

@@ -29,7 +29,16 @@ export function listRemoteHosts(): Host[] {
       `SELECT h.*, CASE WHEN h.kind = 'connect'
           THEN EXISTS (SELECT 1 FROM peer_links p WHERE p.host_id = h.id)
           ELSE EXISTS (SELECT 1 FROM host_links l WHERE l.host_id = h.id)
-        END AS linked
+        END AS linked,
+        CASE WHEN h.kind = 'connect' THEN COALESCE(
+          (SELECT p.state FROM peer_links p WHERE p.host_id = h.id),
+          (SELECT 'unlinked' FROM peer_unlinked u WHERE u.host_id = h.id LIMIT 1))
+        END AS peer_state,
+        CASE WHEN h.kind = 'connect' THEN COALESCE(
+          (SELECT p.suspended_reason FROM peer_links p WHERE p.host_id = h.id),
+          (SELECT u.reason FROM peer_unlinked u WHERE u.host_id = h.id
+            ORDER BY u.at DESC LIMIT 1))
+        END AS peer_note
          FROM hosts h ORDER BY sort_order, created_at`
     )
     .all() as Host[];

package/lib/orchestration.ts

@@ -19,6 +19,7 @@ import { UNSET_SERVER_ENV } from "./agents/server-env";
 import { runInBackground } from "./async-operations";
 import { tmux } from "./tmux/exec";
 import { endTmuxSession } from "./tmux/end";
+import { inheritGroup } from "@/lib/session-groups/assignSessions";
 
 export interface SpawnWorkerOptions {
   conductorSessionId: string;
@@ -146,6 +147,7 @@ export async function spawnWorker(
     agentType,
     "uncategorized" // project_id
   );
+  inheritGroup(conductorSessionId, sessionId);
 
   // Update worktree info if created
   if (worktreePath) {

package/lib/orchestrator/act.ts

@@ -22,6 +22,7 @@ import {
 import { assertMovable, createTask, dropTask, moveTask } from "../tasks";
 import { getHost, hostIdNamed } from "../hosts";
 import { queueEvent } from "./events";
+import { claimQueuedEvent, claimWait } from "./claim-wait";
 import {
   findQueued,
   queuedLabel,
@@ -45,6 +46,7 @@ import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
 import { addNote } from "./notes";
 import { findWorkspaceSession } from "./read";
+import { assignSessions, resolveGroup } from "../session-groups";
 import {
   assertTakesMessages,
   findQueuedTarget,
@@ -162,7 +164,9 @@ export async function startTask(
     machine?: "mac" | "any";
     now?: boolean;
     nowReason?: string;
+    ignoreClaims?: boolean;
     piece?: string;
+    group?: string;
   } = {}
 ): Promise<string> {
   if (opts.planOnly && opts.plan === false)
@@ -170,6 +174,7 @@ export async function startTask(
   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 groupId = groupIdOf(workspaceId, opts.group);
   const model = parseOverride(opts.model) ?? undefined;
   const startedBy = orchestratorId(workspaceId);
   const pieceId = opts.piece
@@ -182,6 +187,19 @@ export async function startTask(
     );
   const view = opts.view ?? DEFAULT_START_VIEW;
   const slots = slotState(project.id);
+  // Work claimed elsewhere: a strong overlap queues this start after it,
+  // unless it starts now or the caller said to ignore claims.
+  const claims = opts.ignoreClaims
+    ? null
+    : await claimWait(
+        { projectId: project.id, name: opts.name, prompt, base: opts.base },
+        {
+          workspaceId,
+          queue: !opts.now && !opts.after,
+        }
+      );
+  const after = opts.after ?? claims?.after;
+  const headsUp = claims?.headsUp ?? "";
   // 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(
@@ -199,11 +217,12 @@ export async function startTask(
       startedVia: "orchestrator",
       pieceId,
       baseBranch: opts.base || undefined,
-      after: opts.after,
+      after,
       originWorkspaceId: workspaceId,
       priority: opts.priority,
       machine: opts.machine,
       now: opts.now,
+      groupId,
     },
     () =>
       braked(
@@ -224,14 +243,17 @@ export async function startTask(
             parentSessionId: startedBy,
             startedVia: "orchestrator",
             pieceId,
+            groupId,
           }),
         (s) => s.id
       )
   );
   if ("queued" in out) {
     const { queued } = out;
+    if (claims?.strong && !opts.after)
+      claimQueuedEvent(workspaceId, queued, claims.strong);
     const builds = pieceId ? ` It builds ${pieceLabel(pieceId)}.` : "";
-    return `Queued (position ${queued.position}) task "${queued.name}" (id ${queued.id.slice(0, 8)}) in ${project.name}${queued.after ? `, after ${queued.after}` : ""}.${builds} It starts by itself; you'll get an event when it does.`;
+    return `Queued (position ${queued.position}) task "${queued.name}" (id ${queued.id.slice(0, 8)}) in ${project.name}${queued.after ? `, after ${queued.after}` : ""}.${builds} It starts by itself; you'll get an event when it does.${headsUp}`;
   }
   const task = out.started;
   if (opts.priority) stampPriority(task.id, opts.priority);
@@ -248,7 +270,7 @@ 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.${pieceId ? ` It builds ${pieceLabel(pieceId)}.` : ""}${skipped}${planOnlyNote}${past ? " Started past the running-task limit." : ""}`;
+  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.${pieceId ? ` It builds ${pieceLabel(pieceId)}.` : ""}${skipped}${planOnlyNote}${past ? " Started past the running-task limit." : ""}${headsUp}`;
 }
 
 // Starts a queued task now, past the running-task limit and its `after`.
@@ -299,9 +321,15 @@ export async function startSession(
   workspaceId: string,
   projectRef: string,
   prompt: string,
-  opts: { name?: string; view?: StartView; model?: string } = {}
+  opts: {
+    name?: string;
+    view?: StartView;
+    model?: string;
+    group?: string;
+  } = {}
 ): Promise<string> {
   const project = workspaceProject(workspaceId, projectRef);
+  const groupId = groupIdOf(workspaceId, opts.group);
   const startedBy = orchestratorId(workspaceId);
   const model = parseOverride(opts.model);
   if (model && typeof model !== "string")
@@ -326,6 +354,7 @@ export async function startSession(
               startedBy,
               parentSessionId: startedBy,
               startedVia: "orchestrator",
+              groupId,
             })
           ).session
         : spawnSession({
@@ -335,6 +364,7 @@ export async function startSession(
             model,
             startedBy,
             parentSessionId: startedBy,
+            groupId,
           }),
     (s) => s.id
   );
@@ -408,6 +438,26 @@ export async function drop(
   return `Dropped ${task.name}: its PR is closed and its worktree removed.`;
 }
 
+// One of Saad's groups in the workspace by name; the error lists the ones
+// there are. The orchestrator files into groups, it never creates them.
+function groupIdOf(workspaceId: string, name?: string): string | undefined {
+  return name ? resolveGroup(workspaceId, name).id : undefined;
+}
+
+// Files a session of this workspace in a group, or out of its group (null).
+export async function setGroup(
+  workspaceId: string,
+  ref: string,
+  group: string | null
+): Promise<string> {
+  const s = findWorkspaceSession(workspaceId, ref);
+  const target = group === null ? null : resolveGroup(workspaceId, group);
+  assignSessions([s.id], target?.id ?? null);
+  return target
+    ? `Filed ${s.name} in "${target.name}".`
+    : `Took ${s.name} out of its group.`;
+}
+
 // Finished work: merged through the gates if its PR is open, then
 // stopped and cleaned up, then left on the Done shelf (lib/done).
 export async function done(workspaceId: string, ref: string): Promise<string> {

package/lib/orchestrator/brief.ts

@@ -122,11 +122,12 @@ 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?, 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 in a production project (see "Triage every job"); a fast project skips the plan unless you pass plan true. 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?, ignore_claims?, 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. If another session (here or on a linked machine) has claimed the same branch or files, it is queued after that work and you get an event saying so; pass ignore_claims only when the overlap is wrong. 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 in a production project (see "Triage every job"); a fast project skips the plan unless you pass plan true. 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.
 - \`${TOOL_NAMES.start_session}\` (project, prompt, name?, view?, model?): a session without a worktree or PR, a chat unless view is terminal. It runs on the implementation model (Sonnet) unless you pass model; use it for work outside a repository, with the steps in the prompt.
+- \`${TOOL_NAMES.set_group}\` (session, group): file a session in one of Saad's groups by name, or out of its group with null. Saad's groups organise his sidebar: put a task in one when he asks, or when it continues work that's already in that group. \`start_task\` and \`start_session\` take a group too. A group has to exist: you can't create, rename or delete one, so if he asks for one that doesn't, say so.
 - \`${TOOL_NAMES.recipes}\` (name?): the workspace's recipes with their last runs; with a name, one in full.
 - \`${TOOL_NAMES.run_recipe}\` (name, note?): run a recipe now: a fresh task or session from its saved brief. See "Recipes".
 - \`${TOOL_NAMES.recipe_save}\` (name, project, kind, brief, model?, view?): save a recipe (kind task ends in a PR; session has none).

package/lib/orchestrator/claim-wait.ts

@@ -0,0 +1,71 @@
+// What the orchestrator's start_task does about work claimed elsewhere: a
+// strong overlap queues the start after that claim, any other overlap is a
+// heads-up. A person's start never comes through here.
+
+import { checkStart, overlapText } from "../claims/startCheck";
+import { machineId } from "../claims/machine";
+import { IN_FLIGHT, resolveAfter, sessionOf } from "../tasks/queue-rows";
+import { queueEvent } from "./events";
+import type { Overlap } from "../claims/types";
+
+export interface ClaimWait {
+  // The `after` to queue with: a local task's id, or "claim:<id>".
+  after?: string;
+  // The overlap that set it, for the event once the start is queued.
+  strong: Overlap | null;
+  headsUp: string;
+}
+
+const isLocalTask = (sessionId: string) => {
+  const s = sessionOf(sessionId);
+  return !!s?.task_status && IN_FLIGHT.includes(s.task_status);
+};
+
+// A local task is waited on as a task (the existing `after`); anything else
+// as a claim.
+function afterOf(o: Overlap, workspaceId: string): string | undefined {
+  const c = o.b;
+  if (c.origin !== machineId() || !c.sessionId) return `claim:${c.id}`;
+  if (!isLocalTask(c.sessionId)) return `claim:${c.id}`;
+  try {
+    return resolveAfter(c.sessionId, workspaceId).id;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function claimWait(
+  start: { projectId: string; name?: string; prompt: string; base?: string },
+  opts: { workspaceId: string; queue: boolean }
+): Promise<ClaimWait> {
+  const check = await checkStart(start);
+  if (!check.overlaps.length) return { strong: null, headsUp: "" };
+  const strong =
+    (opts.queue && check.overlaps.find((o) => o.strength === "strong")) || null;
+  const after = strong ? afterOf(strong, opts.workspaceId) : undefined;
+  const lines = check.overlaps
+    .slice(0, 3)
+    .map((o) => `- ${o.strength}: ${overlapText(o)}`);
+  return {
+    after,
+    strong: after ? strong : null,
+    headsUp: `\nHeads-up, work already claimed:\n${lines.join("\n")}`,
+  };
+}
+
+// Tells the orchestrator it was queued behind a claim, and how to override.
+export function claimQueuedEvent(
+  workspaceId: string,
+  queued: { id: string; name: string },
+  o: Overlap
+): void {
+  const shared = o.shared.length
+    ? ` (shared: ${o.shared.slice(0, 5).join(", ")})`
+    : "";
+  queueEvent(
+    workspaceId,
+    `claim-queued:${queued.id}`,
+    queued.id,
+    `Queued "${queued.name}" (id ${queued.id.slice(0, 8)}) after ${overlapText(o)}${shared}. It starts when that work ends; start_now overrides, or drop it.`
+  );
+}