@saadnvd1/agent-os 0.3.597 → 0.3.601

package/lib/agents/spawn.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "crypto";
+import { orchestratorOf, recordStart } from "../tasks/starter";
 import os from "os";
 import { db, queries, type Session } from "../db";
 import { getProject, getAllProjects } from "../projects";
@@ -35,6 +36,7 @@ export async function spawnSession(opts: {
   // The orchestrator session that starts it: the implementation role's
   // model unless `model` is given.
   startedBy?: string | null;
+  parentSessionId?: string | null;
 }): Promise<Session> {
   const prompt = opts.prompt.trim();
   if (!prompt) throw new Error("Give the new session a prompt");
@@ -46,7 +48,7 @@ export async function spawnSession(opts: {
 
   const id = randomUUID();
   const tmuxName = `claude-${id}`;
-  const routed = opts.startedBy
+  const routed = orchestratorOf(opts.startedBy)
     ? resolveRole("implement", {
         workspaceId: project.workspace_id,
         override: parseOverride(opts.model),
@@ -76,9 +78,19 @@ export async function spawnSession(opts: {
       project.id,
       "local"
     );
-  db.prepare(
-    `UPDATE sessions SET name_source = ?, started_by = ? WHERE id = ?`
-  ).run(naming.source, opts.startedBy ?? null, id);
+  db.prepare(`UPDATE sessions SET name_source = ? WHERE id = ?`).run(
+    naming.source,
+    id
+  );
+  recordStart(id, {
+    startedBy: opts.startedBy ?? null,
+    parentSessionId: opts.parentSessionId ?? opts.startedBy ?? null,
+    startedVia: orchestratorOf(opts.startedBy)
+      ? "orchestrator"
+      : opts.startedBy
+        ? "session"
+        : "person",
+  });
   if (routed) setSessionModel(id, routed);
   void naming.refine?.(id);
   await launchClaude({ sessionId: id, tmuxName, cwd, model, prompt });

package/lib/chat/refresh.ts

@@ -13,7 +13,8 @@
 
 import { db } from "../db";
 import { effectiveModels } from "../models/config";
-import { sessionRole, type ModelRole } from "../models/roles";
+import { type ModelRole } from "../models/roles";
+import { sessionRole } from "../models/session-role";
 import { MAX_REFRESH_TOKENS, MIN_REFRESH_TOKENS } from "./refresh-limits";
 
 export const ORCHESTRATOR_KEY = "orchestrator.refresh_tokens";

package/lib/chat/runner.ts

@@ -41,10 +41,13 @@ import {
   setChatPlan,
 } from "./settings";
 import {
+  endOrphanedTasks,
+  endRunningTasks,
   getItem,
   hasItem,
   itemsOfKind,
   recentTasks,
+  sessionsWithRunningTasks,
   saveItem,
   settle,
 } from "./store";
@@ -167,8 +170,26 @@ function planEnv(sessionId: string): PlanHandoffEnv {
   };
 }
 
+// Tell watchers of tasks that just ended, and drop them from the live count.
+function emitEnded(
+  sessionId: string,
+  live: Live | undefined,
+  ended: ReturnType<typeof endRunningTasks>
+): void {
+  for (const item of ended) {
+    live?.activity.tasks.delete(item.taskId);
+    emit(sessionId, { type: "item", item });
+  }
+}
+
 function onWorkerEvent(sessionId: string, live: Live, e: WorkerEvent): void {
   track(live, e);
+  if (
+    e.type === "item" &&
+    e.item.kind === "tool" &&
+    (e.item.status === "stopped" || e.item.status === "error")
+  )
+    emitEnded(sessionId, live, endOrphanedTasks(sessionId));
   if (e.type === "item" && e.item.kind === "task")
     retireIfStale(sessionId, live);
   if (e.type === "item") {
@@ -297,7 +318,11 @@ async function ensureLive(sessionId: string, spawn = true): Promise<Live> {
             );
       },
     };
+    // No worker running: its agent ended, and with it every job it ran.
+    const hadWorker = runningWorkers().includes(sessionId);
     let { client, hello } = await connectWorker(sessionId, spawn, handlers);
+    if (!hadWorker) emitEnded(sessionId, undefined, endRunningTasks(sessionId));
+    emitEnded(sessionId, undefined, endOrphanedTasks(sessionId));
     let activity = restoreActivity(sessionId, hello.state);
     // An idle worker left over from before a redeploy: retire it, and start
     // a fresh one only when a message needs it. One still running background
@@ -316,6 +341,7 @@ async function ensureLive(sessionId: string, spawn = true): Promise<Live> {
           { code: RETIRED }
         );
       ({ client, hello } = await connectWorker(sessionId, true, handlers));
+      emitEnded(sessionId, undefined, endRunningTasks(sessionId));
       activity = restoreActivity(sessionId, hello.state);
     }
     live = {
@@ -965,6 +991,9 @@ export async function reattachChats(): Promise<void> {
         })
     )
   );
+  // A task saved as running with no worker behind it has no job either.
+  for (const id of sessionsWithRunningTasks())
+    if (!live.has(id)) endRunningTasks(id);
   // Turns cut off while no worker was left to finish them, then queues.
   // One at a time, and only what was queued recently: a backlog from long
   // ago isn't sent unasked by a restart (it stays on screen to send).

package/lib/chat/store.ts

@@ -235,6 +235,59 @@ export function runningItems<K extends "tool" | "task">(
   ).map((r) => JSON.parse(r.data));
 }
 
+const LOST = "Its agent ended before this finished";
+
+function endTasks(
+  sessionId: string,
+  which: (task: Extract<ChatItem, { kind: "task" }>) => boolean
+): Extract<ChatItem, { kind: "task" }>[] {
+  const ended: Extract<ChatItem, { kind: "task" }>[] = [];
+  for (const task of runningItems(sessionId, "task")) {
+    if (!which(task)) continue;
+    const item = {
+      ...task,
+      status: "stopped" as const,
+      endedAt: Date.now(),
+      summary: task.summary ?? LOST,
+    };
+    saveItem(sessionId, item);
+    ended.push(item);
+  }
+  return ended;
+}
+
+// Its agent is gone (a fresh worker, no worker at restart): nothing it ran
+// in the background is still going. Returns what it ended.
+export const endRunningTasks = (sessionId: string) =>
+  endTasks(sessionId, () => true);
+
+// A task whose tool call was stopped or errored has no job behind it.
+export function endOrphanedTasks(sessionId: string) {
+  const dead = new Set(
+    runningItems(sessionId, "task").flatMap((t) => {
+      const tool = t.toolUseId ? getItem(sessionId, t.toolUseId) : undefined;
+      return tool?.kind === "tool" &&
+        (tool.status === "stopped" || tool.status === "error")
+        ? [t.id]
+        : [];
+    })
+  );
+  return endTasks(sessionId, (t) => dead.has(t.id));
+}
+
+// Chats with a task saved as running.
+export function sessionsWithRunningTasks(): string[] {
+  flushItems();
+  return (
+    db
+      .prepare(
+        `SELECT DISTINCT session_id FROM chat_items WHERE kind = 'task'
+         AND json_extract(data, '$.status') = 'running'`
+      )
+      .all() as { session_id: string }[]
+  ).map((r) => r.session_id);
+}
+
 // Tool calls saved as still running.
 export const runningTools = (sessionId: string) =>
   runningItems(sessionId, "tool");

package/lib/db/migrations/20261014T2110_task_start_record.ts

@@ -0,0 +1,21 @@
+import type { Migration } from "../migration-types";
+
+export default {
+  key: "20261014T2110_task_start_record",
+  up: (db) => {
+    // Who started a task and how, on the session and its queue row; an
+    // approval kind on brief entries. Additive.
+    const add = (table: string, col: string, type: string) => {
+      const columns = db.prepare(`PRAGMA table_info(${table})`).all() as {
+        name: string;
+      }[];
+      if (!columns.some((c) => c.name === col))
+        db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${type}`);
+    };
+    add("sessions", "started_via", "TEXT");
+    add("task_queue", "parent_session_id", "TEXT");
+    add("task_queue", "started_by_device", "TEXT");
+    add("task_queue", "started_via", "TEXT");
+    add("brief_amendments", "kind", "TEXT NOT NULL DEFAULT 'scope'");
+  },
+} satisfies Migration;

package/lib/db/migrations/20261014T2200_end_orphaned_tasks.ts

@@ -0,0 +1,23 @@
+import type { Migration } from "../migration-types";
+
+export default {
+  key: "20261014T2200_end_orphaned_tasks",
+  up: (db) => {
+    // A background task still "running" whose tool call was stopped or
+    // errored has no job behind it. Settles the rows already stuck.
+    db.exec(`
+      UPDATE chat_items
+      SET data = json_set(data, '$.status', 'stopped',
+                          '$.endedAt', CAST(strftime('%s','now') AS INTEGER) * 1000,
+                          '$.summary', COALESCE(json_extract(data, '$.summary'),
+                                                'Its agent ended before this finished'))
+      WHERE kind = 'task' AND json_extract(data, '$.status') = 'running'
+        AND EXISTS (
+          SELECT 1 FROM chat_items t
+          WHERE t.session_id = chat_items.session_id
+            AND t.item_id = json_extract(chat_items.data, '$.toolUseId')
+            AND t.kind = 'tool'
+            AND json_extract(t.data, '$.status') IN ('stopped', 'error'))
+    `);
+  },
+} satisfies Migration;

package/lib/db/types.ts

@@ -24,6 +24,8 @@ export interface Session {
   plan_only?: number | null;
   // The orchestrator session that started this one; null for a person.
   started_by?: string | null;
+  // How it started: session, orchestrator, person, plan, schedule, recipe, stack or remote.
+  started_via?: string | null;
   // 1 planned, 0 no plan, null not stated; why, in the starter's words.
   plan_decided?: number | null;
   // JSON: the pieces Saad merged or dropped before approving the plan.

package/lib/learning-cards/apply.ts

@@ -80,6 +80,7 @@ async function toClaudeMd(card: Card, p: LessonPayload, line: string) {
     projectId: project.id,
     prompt: `Add exactly this line under a "${HEADING}" heading in CLAUDE.md at the repository root, creating the file and heading if missing, and change nothing else: ${line}`,
     startedBy: null,
+    startedVia: "person",
   });
   return task.id;
 }
@@ -105,7 +106,12 @@ async function applyLesson(card: Card, p: LessonPayload, edits: Edits) {
       if (!prompt || !p.projectId)
         throw new CardRefused("There's no task to start");
       return (
-        await createTask({ projectId: p.projectId, prompt, startedBy: null })
+        await createTask({
+          projectId: p.projectId,
+          prompt,
+          startedBy: null,
+          startedVia: "person",
+        })
       ).id;
     }
     case "rule":

package/lib/models/plan-step.ts

@@ -21,8 +21,9 @@ import { ANTHROPIC } from "./roles";
 import { queueEvent } from "../orchestrator/events";
 import { noApprovalsOn, recordAutoApproval } from "../approvals/no-approvals";
 import { addNote } from "../orchestrator/notes";
-import { amendBrief, amendmentsOf } from "../orchestrator/amendments";
+import { amendBrief, scopeChangesOf } from "../orchestrator/amendments";
 import { PIECES_PROMPT, foldedBrief, pieceBrief } from "../plans/pieces";
+import { orchestratorOf } from "../tasks/starter";
 import {
   createFeature,
   ownPieceOf,
@@ -119,7 +120,7 @@ function piecesLine(r: NonNullable<ReturnType<typeof planFor>>): string {
 
 // Tells the orchestrator that started a task its plan is written, once.
 function announcePlan(s: Session, ref: string | null, retried = false): void {
-  if (!s.started_by && !s.held_by_device) return;
+  if (!orchestratorOf(s.started_by) && !s.held_by_device) return;
   const workspaceId = sessionWorkspace(s);
   // A task held for another machine's orchestrator can't reach it: the line
   // waits on the task for that orchestrator to read (orchestrator/facts).
@@ -507,12 +508,21 @@ export async function recheckPlanning(
     );
 }
 
+export type ApprovedBy = "saad" | "orchestrator" | "no-approvals";
+
+const APPROVAL_TEXT: Record<ApprovedBy, string> = {
+  saad: "Saad approved the plan; implement it as planned.",
+  orchestrator: "The orchestrator approved the plan; implement it as planned.",
+  "no-approvals":
+    "The plan was approved automatically (no-approvals mode); implement it as planned.",
+};
+
 // approvePlan, sending through the chat runner (imported when needed: it
 // imports this file).
 export async function approvePlanNow(
   sessionId: string,
   message?: string,
-  by: "saad" | "no-approvals" = "saad"
+  by: ApprovedBy = "saad"
 ) {
   const { sendQueuedNow } = await import("../chat/runner");
   return approvePlan(sessionId, message, (id, m) => sendQueuedNow(id, m), by);
@@ -526,7 +536,7 @@ export async function approvePlan(
   sessionId: string,
   message: string | undefined,
   send: Send,
-  by: "saad" | "no-approvals" = "saad"
+  by: ApprovedBy = "saad"
 ): Promise<{ ref: string; amendments: number }> {
   const s = getSession(sessionId);
   if (!s || s.plan_phase !== "awaiting" || s.task_status !== "running")
@@ -535,9 +545,16 @@ export async function approvePlan(
     );
   const text = message?.trim() || undefined;
   const workspaceId = sessionWorkspace(s);
-  if (text && workspaceId) {
-    amendBrief(workspaceId, s.id, text);
-    addNote(workspaceId, `Plan approved with a change for ${s.name}: ${text}`);
+  // Every approval is on the brief, so the review judges the PR as the
+  // implementation of the plan, not as plan-only work.
+  if (workspaceId) {
+    if (text) {
+      amendBrief(workspaceId, s.id, text);
+      addNote(
+        workspaceId,
+        `Plan approved with a change for ${s.name}: ${text}`
+      );
+    } else amendBrief(workspaceId, s.id, APPROVAL_TEXT[by], "approval");
   }
   const ref = await startImplementing(s, "awaiting", send, text);
   if (!ref) throw new Error(`${s.name} isn't waiting for plan approval`);
@@ -549,5 +566,5 @@ export async function approvePlan(
       subject: `plan for ${s.name}`,
       detail: "already waiting when the mode was turned on",
     });
-  return { ref, amendments: amendmentsOf(s.id).length };
+  return { ref, amendments: scopeChangesOf(s.id).length };
 }

package/lib/models/resolve.ts

@@ -24,9 +24,9 @@ import {
   formatModelRef,
   isModelRole,
   parseModelRef,
-  sessionRole,
   type ModelRole,
 } from "./roles";
+import { sessionRole } from "./session-role";
 import {
   resolveSecret,
   secretShellExpansion,

package/lib/models/resume.ts

@@ -18,7 +18,7 @@ import {
   taskOverride,
   type ModelOverride,
 } from "./resolve";
-import { sessionRole } from "./roles";
+import { sessionRole } from "./session-role";
 
 export const RESUME_MESSAGE =
   "You were paused. Carry on where you left off: check the worktree and the conversation above for where things stand, then finish the task.";

package/lib/models/roles.ts

@@ -85,19 +85,3 @@ export function parseModelRef(ref: string): ModelRef {
 export const formatModelRef = (r: ModelRef) => `${r.provider}/${r.model}`;
 
 export const REF_PATTERN = /^[a-z0-9][a-z0-9_-]*\/[\w.:@/-]+$/i;
-
-// The role a session's next turn runs as.
-export function sessionRole(session: {
-  role?: string | null;
-  task_status?: string | null;
-  plan_phase?: string | null;
-  started_by?: string | null;
-}): ModelRole {
-  if (session.role === "orchestrator") return "orchestrator";
-  // Work an orchestrator started is implementation, not a person's session.
-  if (!session.task_status)
-    return session.started_by ? "implement" : "interactive";
-  return session.plan_phase === "planning" || session.plan_phase === "awaiting"
-    ? "plan"
-    : "implement";
-}

package/lib/models/session-role.ts

@@ -0,0 +1,19 @@
+import { orchestratorOf } from "../tasks/starter";
+import type { ModelRole } from "./roles";
+
+// Server-only: it reads the database, so the client-safe roles module can't hold it.
+// The role a session's next turn runs as.
+export function sessionRole(session: {
+  role?: string | null;
+  task_status?: string | null;
+  plan_phase?: string | null;
+  started_by?: string | null;
+}): ModelRole {
+  if (session.role === "orchestrator") return "orchestrator";
+  // Work an orchestrator started is implementation, not a person's session.
+  if (!session.task_status)
+    return orchestratorOf(session.started_by) ? "implement" : "interactive";
+  return session.plan_phase === "planning" || session.plan_phase === "awaiting"
+    ? "plan"
+    : "implement";
+}

package/lib/orchestrator/act.ts

@@ -35,10 +35,11 @@ import { treeOrder } from "../stacks/tree";
 import type { StackItemView } from "../stacks/types";
 import { doneSession } from "../done";
 import { archiveChecked } from "../done/archive";
-import { amendBrief, amendmentsOf } from "./amendments";
+import { amendBrief, scopeChangesOf } from "./amendments";
 import { db, type Session } from "../db";
 import { resurrectSession } from "../resurrect";
 import { resolveEnded } from "../resurrect/find";
+import { findPiece, pieceLabel, workspacePieces } from "../plans/claim";
 import { approvePlanNow } from "../models/plan-step";
 import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
@@ -96,7 +97,7 @@ export async function send(
     amendBrief(workspaceId, to.id, message);
     // In the decision log, so Saad sees every change of scope it records.
     addNote(workspaceId, `Scope change for ${to.name}: ${message}`);
-    amended = ` Recorded as scope change ${amendmentsOf(to.id).length} on its brief: reviews from now on judge against it (call review with fresh to judge the current head again).`;
+    amended = ` Recorded as scope change ${scopeChangesOf(to.id).length} on its brief: reviews from now on judge against it (call review with fresh to judge the current head again).`;
   }
   const { delivery } = await sendMessage({
     fromId: orchestratorId(workspaceId),
@@ -127,7 +128,7 @@ async function sendToQueued(
   if (opts.scopeChange) {
     amendBrief(workspaceId, queued.id, message);
     addNote(workspaceId, `Scope change for ${queued.name}: ${message}`);
-    amended = ` Recorded as scope change ${amendmentsOf(queued.id).length} on its brief: reviews judge against it once it has a PR.`;
+    amended = ` Recorded as scope change ${scopeChangesOf(queued.id).length} on its brief: reviews judge against it once it has a PR.`;
   }
   const sent = await sendMessage({
     fromId: orchestratorId(workspaceId),
@@ -161,6 +162,7 @@ export async function startTask(
     machine?: "mac" | "any";
     now?: boolean;
     nowReason?: string;
+    piece?: string;
   } = {}
 ): Promise<string> {
   if (opts.planOnly && opts.plan === false)
@@ -170,6 +172,9 @@ export async function startTask(
   const project = workspaceProject(workspaceId, projectRef);
   const model = parseOverride(opts.model) ?? undefined;
   const startedBy = orchestratorId(workspaceId);
+  const pieceId = opts.piece
+    ? findPiece(workspacePieces(workspaceId, project.id), opts.piece).id
+    : undefined;
   // Its brakes read this machine's usage, not the other machine's account.
   if (isRemoteHost(project.host_id))
     throw new Error(
@@ -190,6 +195,9 @@ export async function startTask(
       planOnly: opts.planOnly,
       planReason: opts.planReason,
       startedBy,
+      parentSessionId: startedBy,
+      startedVia: "orchestrator",
+      pieceId,
       baseBranch: opts.base || undefined,
       after: opts.after,
       originWorkspaceId: workspaceId,
@@ -213,13 +221,17 @@ export async function startTask(
             planOnly: opts.planOnly,
             planReason: opts.planReason,
             startedBy,
+            parentSessionId: startedBy,
+            startedVia: "orchestrator",
+            pieceId,
           }),
         (s) => s.id
       )
   );
   if ("queued" in out) {
     const { queued } = out;
-    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 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.`;
   }
   const task = out.started;
   if (opts.priority) stampPriority(task.id, opts.priority);
@@ -236,7 +248,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.${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." : ""}`;
 }
 
 // Starts a queued task now, past the running-task limit and its `after`.
@@ -276,10 +288,10 @@ export async function approveTaskPlan(
   task: Session,
   message?: string
 ): Promise<string> {
-  const out = await approvePlanNow(task.id, message);
+  const out = await approvePlanNow(task.id, message, "orchestrator");
   const amended = message
     ? ` Recorded as scope change ${out.amendments} on its brief: its review judges against it.`
-    : "";
+    : " Recorded the approval on its brief.";
   return `Approved the plan of ${task.name}: implementing on ${out.ref}.${amended}`;
 }
 
@@ -312,6 +324,8 @@ export async function startSession(
               access: "full",
               model,
               startedBy,
+              parentSessionId: startedBy,
+              startedVia: "orchestrator",
             })
           ).session
         : spawnSession({
@@ -320,6 +334,7 @@ export async function startSession(
             name: opts.name,
             model,
             startedBy,
+            parentSessionId: startedBy,
           }),
     (s) => s.id
   );

package/lib/orchestrator/amendments.ts

@@ -10,19 +10,22 @@ export interface Amendment {
   session_id: string;
   workspace_id: string;
   text: string;
+  // scope: a change to what the task builds; approval: a plan approved as written.
+  kind: "scope" | "approval";
   created_at: string;
 }
 
 export function amendBrief(
   workspaceId: string,
   taskId: string,
-  text: string
+  text: string,
+  kind: Amendment["kind"] = "scope"
 ): Amendment {
   const { lastInsertRowid } = db
     .prepare(
-      `INSERT INTO brief_amendments (session_id, workspace_id, text) VALUES (?, ?, ?)`
+      `INSERT INTO brief_amendments (session_id, workspace_id, text, kind) VALUES (?, ?, ?, ?)`
     )
-    .run(taskId, workspaceId, text.trim());
+    .run(taskId, workspaceId, text.trim(), kind);
   return db
     .prepare(`SELECT * FROM brief_amendments WHERE id = ?`)
     .get(Number(lastInsertRowid)) as Amendment;
@@ -34,3 +37,7 @@ export function amendmentsOf(taskId: string): Amendment[] {
     .prepare(`SELECT * FROM brief_amendments WHERE session_id = ? ORDER BY id`)
     .all(taskId) as Amendment[];
 }
+
+// Only the changes of scope: an approval as written changes nothing.
+export const scopeChangesOf = (taskId: string): Amendment[] =>
+  amendmentsOf(taskId).filter((a) => a.kind === "scope");

package/lib/orchestrator/serve.ts

@@ -145,6 +145,7 @@ export async function runTool(
         machine: a.machine,
         now: a.now,
         nowReason: a.now_reason,
+        piece: a.piece,
       });
     }
     case "start_now": {

package/lib/orchestrator/testing.ts

@@ -76,3 +76,11 @@ export function seedWorkspace(name = `ws-${randomUUID().slice(0, 6)}`) {
   });
   return { workspace, app, api, chat, task };
 }
+
+// An orchestrator session with this id, for rows that name it as started_by.
+export function seedOrchestrator(id: string): void {
+  db.prepare(
+    `INSERT OR IGNORE INTO sessions (id, name, tmux_name, working_directory, role)
+     VALUES (?, ?, ?, '/tmp', 'orchestrator')`
+  ).run(id, `orchestrator ${id}`, `claude-${id}`);
+}

package/lib/orchestrator/tool-schemas.ts

@@ -141,6 +141,15 @@ export const TOOL_SHAPES = {
       .max(300)
       .optional()
       .describe("With now: why it can't wait for a slot; logged for Saad"),
+    piece: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .optional()
+      .describe(
+        "The waiting plan piece this task builds (its name or number, or feature/piece): it is claimed so AgentOS won't start it again"
+      ),
     model: modelOverride,
     plan: z
       .boolean()

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. 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.',
+    '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.',
   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: