@saadnvd1/agent-os 0.3.698 → 0.3.715

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.`
+  );
+}

package/lib/orchestrator/conditions.ts

@@ -10,6 +10,8 @@
 import { runForSession } from "../recipes/store";
 import { db, type StackItemStatus, type StackStatus } from "../db";
 import { isFinished, type TaskPR } from "../tasks/state";
+import { eventLine } from "../claims/overlapText";
+import type { SessionOverlap } from "../claims/mine";
 import { ciWord } from "./describe";
 import type { SessionFacts } from "./facts";
 import { untrusted } from "./untrusted";
@@ -192,6 +194,29 @@ function stackConditions(s: StackFacts): Condition[] {
   return out;
 }
 
+// A strong overlap between a session here and other work, anywhere. Held
+// until it ends, so it goes through the events' two-diff damping and
+// REFIRE_MS, and an overlap that only flickers is dropped.
+function overlapConditions(
+  facts: SessionFacts[],
+  overlaps: SessionOverlap[]
+): Condition[] {
+  const names = new Map(facts.map((f) => [f.id, f.name]));
+  return overlaps.flatMap((o) => {
+    const name = names.get(o.sessionId);
+    if (!name) return [];
+    return [
+      {
+        key: conditionKey(`overlap:${o.pairKey}`, o.sessionId),
+        subject: o.sessionId,
+        line: eventLine(o, name),
+        sticky: false,
+        low: true,
+      },
+    ];
+  });
+}
+
 // Sessions the orchestrator itself messaged this recently don't raise
 // "needs input": that's most likely it waiting on its own question.
 export const QUIET_AFTER_MESSAGE_MS = 2 * 60 * 1000;
@@ -200,11 +225,13 @@ export function conditionsFor(
   facts: SessionFacts[],
   stacks: StackFacts[],
   now = Date.now(),
-  quiet: ReadonlySet<string> = new Set()
+  quiet: ReadonlySet<string> = new Set(),
+  overlaps: SessionOverlap[] = []
 ): Condition[] {
   return [
     ...facts.flatMap((f) => sessionConditions(f, now, quiet.has(f.id))),
     ...stacks.flatMap(stackConditions),
+    ...overlapConditions(facts, overlaps),
   ];
 }
 

package/lib/orchestrator/describe.ts

@@ -37,10 +37,24 @@ function sessionLine(f: SessionFacts): string {
       task += `, BLOCKED: ${untrusted(f.name, f.task.blocked)}`;
     parts.push(task);
   }
+  if (f.group) parts.push(`in group "${f.group}"`);
   if (f.plan)
     parts.push(
       `${f.plan.awaiting ? "plan ready, awaiting your approve_plan" : f.plan.planned ? "planned" : "no plan"}${f.plan.reason ? `: ${untrusted(f.name, f.plan.reason)}` : ""}`
     );
+  if (f.waits?.on.length)
+    parts.push(
+      `waiting on ${f.waits.on
+        .map(
+          (w) =>
+            `${untrusted(f.name, w.name)} (${w.kind === "reply" ? "reply" : w.kind === "idle" ? "to go idle" : "to merge"}, ${Math.max(1, Math.round(w.leftMs / 60_000))}m left)`
+        )
+        .join(", ")}`
+    );
+  if (f.waits?.by.length)
+    parts.push(
+      `${f.waits.by.map((n) => untrusted(f.name, n)).join(", ")} waiting on it`
+    );
   if (f.stack) {
     const card = f.stack.ticket ? ` ${f.stack.ticket}` : "";
     parts.push(
@@ -53,7 +67,8 @@ function sessionLine(f: SessionFacts): string {
 // The sessions tool's answer: one line per session, busiest news first.
 export function describeSessions(
   workspace: string,
-  facts: SessionFacts[]
+  facts: SessionFacts[],
+  groups: readonly string[] = []
 ): string {
   if (!facts.length) return `No sessions are running in ${workspace}.`;
   const rank = { waiting: 0, running: 1, idle: 2, dead: 3 };
@@ -69,5 +84,8 @@ export function describeSessions(
   return [
     `${facts.length} ${noun} in ${workspace}${summary}:`,
     ...sorted.map(sessionLine),
+    ...(groups.length
+      ? [`Saad's groups here: ${groups.map((g) => `"${g}"`).join(", ")}.`]
+      : []),
   ].join("\n");
 }

package/lib/orchestrator/facts.ts

@@ -5,6 +5,7 @@
  * read this.
  */
 
+import { groupNames } from "../session-groups/store";
 import { db, type Session, type StackItemStatus } from "../db";
 import { statusDetector } from "../status-detector";
 import { hostLink } from "../hosts/remote-api";
@@ -20,6 +21,7 @@ import { prFor, storedPR } from "../tasks/session";
 import { lastActiveOf } from "../tasks/last-active";
 import * as taskClient from "../tasks/contract/client";
 import { deriveTaskState } from "../tasks";
+import { waitBadges } from "../bus/waits/store";
 import { waitingState } from "./task-state";
 import { commitTime, repoOf } from "./repo";
 import { CHECKLESS_MS, checklessFor, ciSettleIn } from "./task-state";
@@ -42,8 +44,15 @@ export interface SessionFacts {
   stalled?: Stall | null;
   // Its agent is summarising the context: not stuck, not plain work.
   compacting?: boolean;
+  // Saad's group it sits in, when it is in one.
+  group?: string | null;
   // Last sign of life, in ms.
   lastActive: number;
+  // Open waits (aos send --await, aos wait): who it waits on, and who waits on it.
+  waits?: {
+    on: { name: string; kind: string; leftMs: number }[];
+    by: string[];
+  } | null;
   // Work that should end in a PR: a task, or a session on its own branch.
   branch: string | null;
   // A quick change the orchestrator makes itself (quick.ts): no agent.
@@ -301,6 +310,8 @@ export async function sessionFacts(
   workspaceId: string
 ): Promise<SessionFacts[]> {
   await statusDetector.refreshCache();
+  const badges = waitBadges();
+  const groups = groupNames();
   return Promise.all(
     workspaceSessions(workspaceId).map(async (s) => {
       const [{ status, activity, needsInput }, task] = await Promise.all([
@@ -315,10 +326,21 @@ export async function sessionFacts(
         status,
         activity,
         needsInput,
+        waits: badges.has(s.id)
+          ? {
+              on: badges.get(s.id)!.on.map((w) => ({
+                name: w.name,
+                kind: w.kind,
+                leftMs: Math.max(0, w.deadline - Date.now()),
+              })),
+              by: badges.get(s.id)!.by.map((w) => w.name),
+            }
+          : null,
         stalled:
           s.view === "chat" && !hostLink(s.host_id) ? chatStall(s.id) : null,
         compacting:
           s.view === "chat" && !hostLink(s.host_id) && !!chatCompacting(s.id),
+        group: groups.get(s.session_group_id ?? "") ?? null,
         lastActive: await lastActiveFor(s),
         branch: s.branch_name,
         quick: !!s.quick_of,

package/lib/orchestrator/serve.ts

@@ -1,6 +1,7 @@
 import { resumeOnModel } from "../models/resume";
 import { workspaceTask } from "./targets";
 import { getWorkspace } from "../workspaces";
+import { listGroups } from "../session-groups/store";
 import {
   approveTaskPlan,
   archive,
@@ -11,6 +12,7 @@ import {
   send,
   stack,
   stackStatus,
+  setGroup,
   startSession,
   startTask,
   startNow,
@@ -19,6 +21,10 @@ import {
   resumeTask,
   stop,
 } from "./act";
+import { describeClaims, liveClaims } from "../claims";
+import { repoKey } from "../git-remote";
+import { expandHome } from "../tasks/session";
+import { workspaceProjects } from "./brief";
 import { readCards } from "./cards";
 import { readLogs } from "./logs";
 import { describeSessions } from "./describe";
@@ -59,6 +65,7 @@ const ACTING = new Set<ToolName>([
   "start_task",
   "set_task_model",
   "start_session",
+  "set_group",
   "run_recipe",
   "recipe_save",
   "recipe_update",
@@ -83,6 +90,21 @@ const ACTING = new Set<ToolName>([
   "add_project",
 ]);
 
+// What live sessions on other machines claim in this workspace's repos.
+async function claimedElsewhere(w: string): Promise<string> {
+  const keys = await Promise.all(
+    workspaceProjects(w)
+      .filter((p) => !p.host_id || p.host_id === "local")
+      .map((p) => repoKey(expandHome(p.working_directory)))
+  );
+  const repos = new Set(keys.filter((k): k is string => !!k));
+  if (!repos.size) return "";
+  return describeClaims(
+    liveClaims().filter((c) => repos.has(c.repo)),
+    { onlyOthers: true }
+  );
+}
+
 // The orchestrator's tools, each scoped to its workspace and its arguments
 // validated, answered as compact text.
 export async function runTool(
@@ -97,14 +119,20 @@ export async function runTool(
   switch (tool) {
     case "sessions": {
       p(tool, raw);
-      const [facts, external] = await Promise.all([
+      const [facts, external, claimed] = await Promise.all([
         sessionFacts(w),
         externalSessions(w).catch(() => []),
+        claimedElsewhere(w).catch(() => ""),
       ]);
       resolveStaleAsks(w);
       return [
-        describeSessions(workspace.name, facts),
+        describeSessions(
+          workspace.name,
+          facts,
+          listGroups(w).map((g) => g.name)
+        ),
         describeExternal(external),
+        claimed,
       ]
         .filter(Boolean)
         .join("\n\n");
@@ -147,7 +175,9 @@ export async function runTool(
         machine: a.machine,
         now: a.now,
         nowReason: a.now_reason,
+        ignoreClaims: a.ignore_claims,
         piece: a.piece,
+        group: a.group,
       });
     }
     case "start_now": {
@@ -187,8 +217,13 @@ export async function runTool(
         name: a.name,
         view: a.view,
         model: a.model,
+        group: a.group,
       });
     }
+    case "set_group": {
+      const a = p(tool, raw);
+      return setGroup(w, a.session, a.group);
+    }
     case "quick_change": {
       const a = p(tool, raw);
       return quickChange(w, a.project, a.name);

package/lib/orchestrator/tool-names.ts

@@ -20,6 +20,7 @@ export const TOOL_NAMES = {
   start_task: name("start_task"),
   set_task_model: name("set_task_model"),
   start_session: name("start_session"),
+  set_group: name("set_group"),
   quick_change: name("quick_change"),
   quick_pr: name("quick_pr"),
   stack: name("stack"),

package/lib/orchestrator/tool-schemas.ts

@@ -22,6 +22,16 @@ const view = z
     "How its agent runs: chat (the default), or terminal only when the job needs a TUI (an interactive program, a full-screen tool)"
   );
 
+const group = z
+  .string()
+  .trim()
+  .min(1)
+  .max(60)
+  .optional()
+  .describe(
+    "One of Saad's groups in this workspace, by name (see sessions): file it there when he asked, or when it continues work already in that group. It must exist; you can't create groups"
+  );
+
 const sweepMachine = z
   .string()
   .trim()
@@ -96,6 +106,7 @@ export const TOOL_SHAPES = {
   },
   start_task: {
     project,
+    group,
     prompt: z
       .string()
       .trim()
@@ -122,7 +133,7 @@ export const TOOL_SHAPES = {
       .max(200)
       .optional()
       .describe(
-        'Queue it until this task finishes (id or name), or "any" for whichever running task finishes first'
+        'Queue it until this task finishes (id or name), or "any" for whichever running task finishes first, or "claim:<id>" for work another machine has claimed'
       ),
     priority: z
       .enum(PRIORITIES)
@@ -149,6 +160,12 @@ export const TOOL_SHAPES = {
       .max(300)
       .optional()
       .describe("With now: why it can't wait for a slot; logged for Saad"),
+    ignore_claims: z
+      .boolean()
+      .optional()
+      .describe(
+        "Don't queue it after work another session (here or on a linked machine) has claimed on the same branch or files; start it as usual. Not needed with now"
+      ),
     piece: z
       .string()
       .trim()
@@ -196,6 +213,7 @@ export const TOOL_SHAPES = {
   },
   start_session: {
     project,
+    group,
     prompt: z.string().trim().min(1).max(20000),
     name: z
       .string()
@@ -211,6 +229,18 @@ export const TOOL_SHAPES = {
         'One model for the session, "provider/model"; default: the implementation model. Opus only when the work needs deep reasoning'
       ),
   },
+  set_group: {
+    session,
+    group: z
+      .string()
+      .trim()
+      .min(1)
+      .max(60)
+      .nullable()
+      .describe(
+        "One of Saad's groups in this workspace by name, or null to take the session out of its group"
+      ),
+  },
   quick_change: {
     project,
     name: z

package/lib/orchestrator/tools.ts

@@ -126,11 +126,13 @@ 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. now true (with now_reason) starts it at once past the running-task limit instead of queueing for a slot, logged; not with after. piece names the waiting piece of a plan this task builds, so it is claimed and not started a second time. 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. A strong overlap with work another session has claimed (same branch, or the same files, here or on a linked machine) queues the start after it and says so; the result also lists weaker overlaps. ignore_claims true skips that. piece names the waiting piece of a plan this task builds, so it is claimed and not started a second time. 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:
     'Start an agent session in a project with a prompt, for work that isn\'t a PR task. It runs on the implementation model unless you give model (one "provider/model"; Opus only when the work needs deep reasoning), as a chat unless view is terminal (only for a job that needs a TUI). Refused while a brake holds.',
+  set_group:
+    "File a session of this workspace in one of Saad's groups (by name), or out of its group with null. Groups only organise his sidebar; they change nothing about the session. You can use groups that exist but can't create, rename or delete them.",
   quick_change:
     "Make a change yourself (without full access, a small low-risk one: a typo, a config value, a one-file fix): cuts a worktree and branch from the project's default branch and returns its path. Its dependencies install in the background (a note says when). You may write there (Write, Edit) and, with Orchestrator full access, run any git there; without it, only `git -C <path> ...` status, diff, add, rm, mv, restore, reset, log, show, and nowhere else in a project. Without full access, anything needing real work, tests or an investigation is a task (start_task).",
   quick_pr:

package/lib/orchestrator/watcher.ts

@@ -14,6 +14,9 @@ import { deliverEvents } from "./deliver";
 import { recordConditions } from "./events";
 import { sessionFacts, type SessionFacts } from "./facts";
 import { listOrchestrators } from "./home";
+import { claimsShared, machineId } from "../claims/machine";
+import { sessionOverlaps, type SessionOverlap } from "../claims/mine";
+import { liveClaims } from "../claims/store";
 import { BRAKE_SUBJECT, openAsks } from "./asks";
 import { settleStaleAsks } from "./ask-settle";
 import { brakesOn, liftBrake } from "./brakes";
@@ -35,6 +38,15 @@ async function settleAsks(workspaceId: string): Promise<void> {
   if (brake && !(await brakesOn(workspaceId)).length) liftBrake(workspaceId);
 }
 
+// Claims code never breaks the watcher: any error means no overlaps.
+function localOverlaps(): SessionOverlap[] {
+  try {
+    return claimsShared() ? sessionOverlaps(machineId(), liveClaims()) : [];
+  } catch {
+    return [];
+  }
+}
+
 const DELIVER_EVERY_MS = 5000;
 export const DIFF_BUSY_MS = 15 * 1000;
 export const DIFF_IDLE_MS = 60 * 1000;
@@ -58,7 +70,13 @@ export async function diffWorkspace(
   ];
   recordConditions(
     workspaceId,
-    conditionsFor(facts, stacks, now, recentlyMessaged(orchestratorId, now)),
+    conditionsFor(
+      facts,
+      stacks,
+      now,
+      recentlyMessaged(orchestratorId, now),
+      localOverlaps()
+    ),
     subjects,
     now
   );