@saadnvd1/agent-os 0.3.558 → 0.3.561

package/lib/orchestrator/conditions.ts

@@ -39,7 +39,9 @@ export interface StackFacts {
   }[];
 }
 
-export const IDLE_NO_PR_MS = 30 * 60 * 1000;
+// How long after a task's turn ended with no PR before it is news: longer
+// than the open-PR cache, so a PR it just opened is seen first.
+export const NO_PR_AFTER_TURN_MS = 2 * 60 * 1000;
 
 function hash(text: string): string {
   let h = 0;
@@ -133,17 +135,23 @@ function sessionConditions(
   const shouldPR = (!!f.task || !!f.branch) && !f.quick && !runForSession(f.id);
   const finished = !!f.task && isFinished(f.task.state);
   const idleFor = now - f.lastActive;
+  // A turn that ended with no PR and nothing blocked is stuck: it may
+  // have opened a PR somewhere AgentOS doesn't look, or be waiting on
+  // nothing. Keyed on when it last did anything, so it is one event per
+  // stall and anything it does after makes the next stall a new one.
   if (
     shouldPR &&
     !pr &&
     !finished &&
     !f.plan?.awaiting &&
     f.status !== "running" &&
-    idleFor >= IDLE_NO_PR_MS
+    blocked === null &&
+    idleFor >= NO_PR_AFTER_TURN_MS
   )
     add(
-      "idle",
-      `${who}: idle ${Math.floor(idleFor / 60000)}m, no PR`,
+      `no-pr:${f.lastActive}`,
+      `${who}: ended its turn ${Math.floor(idleFor / 60000)}m ago with no PR${f.activity ? ` (last: ${untrusted(f.name, f.activity)})` : ""}. If it opened a PR in another repository, or finished without one, nothing tracks it.`,
+      false,
       false,
       true
     );

package/lib/orchestrator/events.ts

@@ -182,6 +182,29 @@ export function queueEvent(
   ).run(workspaceId, `${ONCE}${key}`, subject, line, ARMED, iso(now));
 }
 
+// Like queueEvent, for a line a sweep would otherwise repeat: a key that
+// already exists, delivered or not, is left alone. Put the state in the key
+// so a change of state is a new line.
+export function queueEventOnce(
+  workspaceId: string,
+  key: string,
+  subject: string | null,
+  line: string,
+  now = Date.now()
+): boolean {
+  return (
+    db
+      .prepare(
+        `INSERT INTO orchestrator_events
+           (workspace_id, key, subject, line, sticky, low, hits, created_at, delivered_at)
+         VALUES (?, ?, ?, ?, 1, 0, ?, ?, NULL)
+         ON CONFLICT(workspace_id, key) DO NOTHING`
+      )
+      .run(workspaceId, `${ONCE}${key}`, subject, line, ARMED, iso(now))
+      .changes > 0
+  );
+}
+
 // A condition the orchestrator has been told about another way (a one-off
 // event said it), so a later diff doesn't send it again.
 export function markTold(

package/lib/orchestrator/reconcile.ts

@@ -0,0 +1,201 @@
+// A task's agent opened a PR in a repository that isn't its task's: nothing
+// polls that repository for the task's branch, so no task owns the PR and no
+// CI or review gate runs. The PRs agents open are read back from their
+// stored `gh pr create` calls, and one outside its task's repository is
+// raised to the orchestrator once.
+
+import { db, type Session } from "../db";
+import { getSetting, putSetting } from "../settings-store";
+import { sessionWorkspace } from "../models/resolve";
+import { run } from "../tasks/gh";
+import { expandHome } from "../tasks/session";
+import { workspaceProjects } from "./brief";
+import { queueEventOnce } from "./events";
+import { repoSlug } from "./repo-slug";
+
+const MARK = "reconcile.chat_items_rowid";
+// An item is stored when its tool call starts and updated when it ends, so a
+// call that finished after the mark moved past it is still inside the window.
+const OVERLAP = 2000;
+const BATCH = 500;
+const EVERY_MS = 2 * 60 * 1000;
+const PR_URL = /https:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)/g;
+const CREATE = /\bgh\s+pr\s+create\b/;
+
+export interface ReconcileDeps {
+  slugOf: (dir: string) => Promise<string | null>;
+  // The PR's state and head branch, or null when it can't be read.
+  view: (url: string) => Promise<{ state: string; head: string } | null>;
+}
+
+export const realReconcileDeps: ReconcileDeps = {
+  slugOf: repoSlug,
+  view: async (url) => {
+    try {
+      const out = await run(
+        "gh",
+        ["pr", "view", url, "--json", "state,headRefName"],
+        process.cwd(),
+        15000
+      );
+      const pr = JSON.parse(out) as { state: string; headRefName: string };
+      return { state: pr.state, head: pr.headRefName };
+    } catch {
+      return null;
+    }
+  },
+};
+
+// Stores every PR URL an agent's `gh pr create` printed since last time.
+export function recordAgentPrs(): number {
+  const top =
+    (
+      db.prepare(`SELECT MAX(rowid) AS m FROM chat_items`).get() as {
+        m: number | null;
+      }
+    ).m ?? 0;
+  const mark = Number(getSetting(MARK) ?? top - OVERLAP);
+  const rows = db
+    .prepare(
+      `SELECT rowid AS rid, session_id, data FROM chat_items
+       WHERE rowid > ? AND data LIKE '%pr create%' AND data LIKE '%/pull/%'
+       ORDER BY rowid LIMIT ?`
+    )
+    .all(mark - OVERLAP, BATCH) as {
+    rid: number;
+    session_id: string;
+    data: string;
+  }[];
+  const insert = db.prepare(
+    `INSERT OR IGNORE INTO agent_prs (url, session_id, repo, number) VALUES (?, ?, ?, ?)`
+  );
+  let added = 0;
+  for (const row of rows) {
+    let item: { kind?: string; input?: unknown; output?: unknown };
+    try {
+      item = JSON.parse(row.data);
+    } catch {
+      continue;
+    }
+    if (
+      item.kind !== "tool" ||
+      typeof item.output !== "string" ||
+      !CREATE.test(JSON.stringify(item.input ?? ""))
+    )
+      continue;
+    for (const m of item.output.matchAll(PR_URL))
+      added += insert.run(
+        m[0],
+        row.session_id,
+        `${m[1]}/${m[2]}`.toLowerCase(),
+        Number(m[3])
+      ).changes;
+  }
+  putSetting(MARK, String(rows.length === BATCH ? rows[BATCH - 1].rid : top));
+  return added;
+}
+
+interface AgentPr {
+  url: string;
+  session_id: string;
+  repo: string;
+  number: number;
+}
+
+const told = (url: string) =>
+  db
+    .prepare(`UPDATE agent_prs SET told_at = datetime('now') WHERE url = ?`)
+    .run(url);
+
+async function ownedBy(
+  pr: AgentPr,
+  head: string,
+  deps: ReconcileDeps
+): Promise<boolean> {
+  const rows = db
+    .prepare(
+      `SELECT s.pr_url, s.branch_name, p.working_directory FROM sessions s
+       LEFT JOIN projects p ON p.id = s.project_id
+       WHERE s.task_status IS NOT NULL AND (LOWER(s.pr_url) = ? OR s.branch_name = ?)`
+    )
+    .all(pr.url.toLowerCase(), head) as {
+    pr_url: string | null;
+    branch_name: string | null;
+    working_directory: string | null;
+  }[];
+  for (const r of rows) {
+    if (r.pr_url?.toLowerCase() === pr.url.toLowerCase()) return true;
+    if (
+      r.working_directory &&
+      (await deps.slugOf(expandHome(r.working_directory))) === pr.repo
+    )
+      return true;
+  }
+  return false;
+}
+
+// Raises each unclaimed agent PR outside its task's repository, once.
+export async function classifyAgentPrs(
+  deps: ReconcileDeps = realReconcileDeps,
+  now = Date.now()
+): Promise<number> {
+  const open = db
+    .prepare(`SELECT * FROM agent_prs WHERE told_at IS NULL`)
+    .all() as AgentPr[];
+  let raised = 0;
+  for (const pr of open) {
+    const task = db
+      .prepare(`SELECT * FROM sessions WHERE id = ?`)
+      .get(pr.session_id) as Session | undefined;
+    const workspaceId = task ? sessionWorkspace(task) : null;
+    if (!task || !workspaceId) {
+      told(pr.url);
+      continue;
+    }
+    const projects = workspaceProjects(workspaceId);
+    const slugs = await Promise.all(
+      projects.map(async (p) => ({
+        name: p.name,
+        id: p.id,
+        slug: await deps.slugOf(expandHome(p.working_directory)),
+      }))
+    );
+    const own = slugs.find((p) => p.id === task.project_id);
+    // Its own repository is polled for its branch like any task's.
+    if (own?.slug === pr.repo) {
+      told(pr.url);
+      continue;
+    }
+    const view = await deps.view(pr.url);
+    // Unreadable now: look again next time.
+    if (!view) continue;
+    if (view.state !== "OPEN" || (await ownedBy(pr, view.head, deps))) {
+      told(pr.url);
+      continue;
+    }
+    const where = slugs.find((p) => p.slug === pr.repo);
+    queueEventOnce(
+      workspaceId,
+      `stray-pr:${pr.url}`,
+      task.id,
+      `Task "${task.name}" opened a PR outside its repo: ${pr.url} (${where ? `project ${where.name} of this workspace` : "not a repository of this workspace"}). No task owns it, so no CI or review gate runs on it: review and sign it off as an external PR, or drop it.`,
+      now
+    );
+    told(pr.url);
+    raised++;
+  }
+  return raised;
+}
+
+let last = 0;
+
+// From the settle loop; reads stored chat items, so a restart loses nothing.
+export async function reconcileSweep(
+  now = Date.now(),
+  deps: ReconcileDeps = realReconcileDeps
+): Promise<void> {
+  if (now - last < EVERY_MS) return;
+  last = now;
+  recordAgentPrs();
+  await classifyAgentPrs(deps, now);
+}

package/lib/orchestrator/untrusted.ts

@@ -20,8 +20,8 @@ const TOKEN_PATTERNS: RegExp[] = [...SECRET_TOKENS, /\b[a-fA-F0-9]{40,}\b/g];
 
 // A long base64-ish run that reads as random rather than as a path or a
 // slug: mixed case, digits, few separators.
-const BASE64_RUN = /[A-Za-z0-9+/_-]{40,}={0,2}/g;
-const looksRandom = (s: string) =>
+export const BASE64_RUN = /[A-Za-z0-9+/_-]{40,}={0,2}/g;
+export const looksRandom = (s: string) =>
   /[A-Z]/.test(s) &&
   /[a-z]/.test(s) &&
   /[0-9]/.test(s) &&
@@ -31,6 +31,16 @@ const looksRandom = (s: string) =>
 export const SECRET_ASSIGNMENT =
   /^(\s*(?:export\s+)?[A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASS|PWD|CREDENTIALS?|AUTH)[A-Z0-9_]*\s*[=:]\s*).+$/gm;
 
+// A URL's userinfo (https://key@host, postgres://user:pw@host) and a query
+// parameter that carries a credential (?token=, &api_key=).
+export const URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)[^@\s/]+@/gi;
+export const SECRET_PARAM =
+  /([?&][\w.-]*(?:key|token|secret|password|auth|sig|code)[\w.-]*=)[^&\s#]+/gi;
+
+// A private key block's opening line.
+export const PRIVATE_KEY_BLOCK =
+  /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----[\s\S]*?(?:-----END (?:[A-Z]+ )?PRIVATE KEY-----|$)/g;
+
 // The password in a URL: postgres://user:secret@host.
 const URL_PASSWORD = /\b([a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:)[^@\s]+@/gi;
 

package/lib/plans/features.ts

@@ -12,6 +12,7 @@ import {
   checkPieces,
   parseEdits,
   type CheckContext,
+  type Folded,
   type PiecesResult,
   type Piece,
   type ProjectRef,
@@ -35,6 +36,9 @@ export interface Feature {
   cost_usd: number | null;
   duration_ms: number | null;
   created_at: string;
+  // Items the plan's Pieces block listed, and what the checker folded.
+  listed: number | null;
+  folded: string | null;
 }
 
 export interface FeaturePiece {
@@ -131,33 +135,82 @@ export function featureOfPlan(sessionId: string): Feature | undefined {
 export interface Split {
   pieces: Piece[];
   notBuilding: string[];
+  listed: number;
+  folded: Folded[];
+  // Why the plan's pieces can't be registered; when set, nothing is built
+  // on a guess.
+  errors: string[];
+  // Whether the plan needs a feature: false for one piece in the task's own
+  // repository that only has edits to carry.
+  feature: boolean;
 }
 
-// The pieces to build for a plan (one, when it isn't split). Edits Saad
-// made on the plan view apply only here, at approval.
+// The pieces to build for a plan, or null when it is one piece in the task's
+// own repository, as almost every plan is. A plan that lists more than it
+// builds, or whose one piece belongs to another project, is not null: it
+// gets a feature so nothing it listed goes missing. Edits Saad made on the
+// plan view apply only here, at approval.
 export function splitOf(s: Session, text: string): Split | null {
   const result = planFor(s, text);
-  if (!result || result.pieces.length < 2) return null;
+  if (!result) return null;
   const { pieces, notBuilding } = applyEdits(result, parseEdits(s.plan_edits));
-  return { pieces, notBuilding };
+  const elsewhere = pieces.some((p) => p.project.id !== s.project_id);
+  const feature = pieces.length > 1 || elsewhere || result.folded.length > 0;
+  if (!feature && !notBuilding.length && !result.errors.length) return null;
+  return {
+    pieces,
+    notBuilding,
+    listed: result.listed,
+    folded: result.folded,
+    errors: result.errors,
+    feature,
+  };
+}
+
+// The piece the planning task builds itself: the first one in its own
+// repository that doesn't wait on another. Every other piece starts as its own
+// task in its own project.
+export function ownPieceOf(
+  pieces: Piece[],
+  ownProjectId: string | null
+): Piece | undefined {
+  return pieces.find(
+    (p) => p.project.id === ownProjectId && p.afterPosition === null
+  );
 }
 
 // One transaction: the feature, its pieces, and the plan kept past the
-// worktree. Piece 1 is the planning task's own.
+// worktree. The planning task's own piece (if it has one) is already
+// building; the rest wait to start as tasks of their own.
 export function createFeature(
   s: Session,
   text: string,
   pieces: Piece[],
-  workspaceId: string
+  workspaceId: string,
+  meta: { listed: number; folded: Folded[] } = {
+    listed: pieces.length,
+    folded: [],
+  }
 ): Feature {
+  const own = ownPieceOf(pieces, s.project_id)?.position;
   const id = randomUUID();
   fs.mkdirSync(plansDir(), { recursive: true });
   fs.writeFileSync(planPathOf(id), text);
   db.transaction(() => {
     db.prepare(
-      `INSERT INTO features (id, workspace_id, name, plan_session_id, plan_text, status)
-       VALUES (?, ?, ?, ?, ?, 'building')`
-    ).run(id, workspaceId, s.name, s.id, text);
+      `INSERT INTO features (id, workspace_id, name, plan_session_id, plan_text, status, listed, folded)
+       VALUES (?, ?, ?, ?, ?, 'building', ?, ?)`
+    ).run(
+      id,
+      workspaceId,
+      s.name,
+      s.id,
+      text,
+      meta.listed,
+      meta.folded.length
+        ? meta.folded.map((f) => `${f.name}: ${f.why}`).join("\n")
+        : null
+    );
     const insert = db.prepare(
       `INSERT INTO feature_pieces
          (feature_id, position, name, slice, project_id, after_position, after_kind,
@@ -175,8 +228,8 @@ export function createFeature(
         p.afterKind,
         p.reasons.join("+") || null,
         p.owns.join(", ") || null,
-        p.position === 1 ? "building" : "waiting",
-        p.position === 1 ? s.id : null
+        p.position === own ? "building" : "waiting",
+        p.position === own ? s.id : null
       );
   })();
   return getFeature(id)!;
@@ -195,6 +248,9 @@ export function reviewGoal(sessionId: string): string | null {
   const owns = piece.owns ? `\nThis piece owns: ${piece.owns}.` : "";
   const head = `Piece ${piece.position} of ${live.length}, "${piece.name}": ${piece.slice}${owns}`;
   const last = live.every((p) => p.id === piece.id || p.status === "merged");
-  if (!last || live.length < 2) return head;
-  return `${head}\n\nThis is the last piece. Also check that the plan as a whole is now done, and list anything in it that no piece built. The plan:\n${feature.plan_text.slice(0, PLAN_IN_REVIEW)}`;
+  const folded = feature.folded
+    ? ` Pieces the plan listed that were built into others: ${feature.folded}.`
+    : "";
+  if (!last || (live.length < 2 && !feature.folded)) return head;
+  return `${head}\n\nThis is the last piece.${folded} Also check that the plan as a whole is now done, and list anything in it that no piece built. The plan:\n${feature.plan_text.slice(0, PLAN_IN_REVIEW)}`;
 }

package/lib/plans/pieces.ts

@@ -37,6 +37,12 @@ export interface PiecesResult {
   pieces: Piece[];
   folded: Folded[];
   warnings: string[];
+  // Items the plan's Pieces block lists (0 when it has none), however well
+  // they parsed: a plan that builds as fewer than it listed is never silent.
+  listed: number;
+  // Problems that must stop a task from building on a guess: the pieces
+  // returned are then the one-piece fallback, for a person to approve or fix.
+  errors: string[];
 }
 
 interface Raw {
@@ -51,7 +57,10 @@ interface Raw {
 
 const HEADING = /^##\s+pieces\s*$/i;
 const ITEM = /^\s{0,3}(\d+)[.)]\s+(.*\S)\s*$/;
-const AFTER = /^\s*after:\s*(\d+)\s+is\s+(merged|deployed)\s*$/i;
+// An item as a person might write it, to count what the plan listed even
+// when the strict parser rejects the block.
+const LOOSE_ITEM = /^\s{0,3}(?:[-*+]\s+)?\**\d+[.)]/;
+const AFTER = /^\s*after:\s*(?:piece\s+)?(\d+)\s+is\s+(merged|deployed)\b.*$/i;
 const WHY = /^\s*why split:\s*(.+?)\s*$/i;
 const OWNS = /^\s*owns:\s*(.+?)\s*$/i;
 
@@ -70,6 +79,14 @@ function block(text: string): string[] | null {
   return out;
 }
 
+// Bullets and bold around the numbers and keys a model sometimes adds
+// ("- **after:** 1 is merged") don't change what a line says.
+function plain(line: string): string {
+  return line
+    .replace(/^(\s*)[-*+]\s+(?=\**(?:\d+[.)]|after|why split|owns))/i, "$1")
+    .replace(/\*\*|__/g, "");
+}
+
 function parseItem(position: number, rest: string): Raw {
   let repo: string | null = null;
   const withRepo = rest.match(/^(.*?)\s*\(repo:\s*([^)]+)\)\s*$/i);
@@ -93,8 +110,9 @@ function parseItem(position: number, rest: string): Raw {
 
 function parseBlock(lines: string[]): Raw[] | null {
   const items: Raw[] = [];
-  for (const line of lines) {
-    if (!line.trim()) continue;
+  for (const original of lines) {
+    if (!original.trim()) continue;
+    const line = plain(original);
     const item = line.match(ITEM);
     if (item) {
       items.push(parseItem(Number(item[1]), item[2]));
@@ -123,6 +141,8 @@ function parseBlock(lines: string[]): Raw[] | null {
         .split(/[,;]/)
         .map((o) => o.trim().toLowerCase())
         .filter(Boolean);
+    // A wrapped slice: an indented line that is none of the keys.
+    else if (/^\s{2,}\S/.test(original)) current.slice += ` ${line.trim()}`;
     else return null;
   }
   if (!items.length || items.some((it, i) => it.position !== i + 1))
@@ -136,7 +156,13 @@ export interface CheckContext {
   find: (name: string) => ProjectRef | null;
 }
 
-function one(text: string, ctx: CheckContext, warnings: string[]) {
+function one(
+  text: string,
+  ctx: CheckContext,
+  warnings: string[],
+  listed = 0,
+  errors: string[] = []
+): PiecesResult {
   return {
     pieces: [
       {
@@ -152,30 +178,41 @@ function one(text: string, ctx: CheckContext, warnings: string[]) {
     ],
     folded: [] as Folded[],
     warnings,
+    listed,
+    errors,
   };
 }
 
 export function checkPieces(text: string, ctx: CheckContext): PiecesResult {
   const lines = block(text);
   if (!lines) return one("", ctx, []);
+  const listed = lines.filter((l) => LOOSE_ITEM.test(l)).length;
   const raw = parseBlock(lines);
   if (!raw)
-    return one("", ctx, [
-      "The Pieces block couldn't be read, so this is one piece.",
+    return one("", ctx, [], listed, [
+      "the Pieces block couldn't be read (a numbered item followed by anything but after:, why split: and owns: lines)",
+    ]);
+  if (raw.length !== listed)
+    return one("", ctx, [], listed, [
+      `the Pieces block lists ${listed} items but ${raw.length} were read`,
     ]);
   if (raw.length > MAX_PIECES)
-    return one("", ctx, [
-      `${raw.length} pieces is past the limit of ${MAX_PIECES}; built as one piece.`,
+    return one("", ctx, [], listed, [
+      `${raw.length} pieces is past the limit of ${MAX_PIECES}`,
     ]);
 
   const warnings: string[] = [];
+  const errors: string[] = [];
   const projects = raw.map((r) => {
     if (!r.repo) return ctx.own;
     const found = ctx.find(r.repo);
     if (!found)
-      warnings.push(`"${r.name}": no project named ${r.repo}; using this one.`);
+      errors.push(
+        `"${r.name}": (repo: ${r.repo}) is not a project of this workspace`
+      );
     return found ?? ctx.own;
   });
+  if (errors.length) return one("", ctx, [], listed, errors);
 
   // Where each original piece ended up, for `after:` lines that pointed at a
   // piece that was folded.
@@ -212,12 +249,15 @@ export function checkPieces(text: string, ctx: CheckContext): PiecesResult {
     }
 
     let reasons = r.reasons;
-    if (!reasons.length) return fold("no reason for a separate piece");
+    if (!reasons.length)
+      return fold("no `why split:` line naming one of (a) to (d)");
+    const lost: string[] = [];
 
     if (reasons.includes("a")) {
       const others = projects.filter((_, j) => j !== i);
       if (others.some((p) => p.id === project.id)) {
         reasons = reasons.filter((x) => x !== "a");
+        lost.push("(a) shares a repo with another piece");
         warnings.push(
           `"${r.name}" claimed (a) but shares a repo with another piece.`
         );
@@ -240,8 +280,10 @@ export function checkPieces(text: string, ctx: CheckContext): PiecesResult {
       const dep = afterPosition ? pieces[afterPosition - 1] : null;
       if (afterKind !== "deployed" || !dep) {
         reasons = reasons.filter((x) => x !== "b");
+        lost.push("(b) needs `after: N is deployed`, not merged");
       } else if (!dep.project.deploys) {
         reasons = reasons.filter((x) => x !== "b");
+        lost.push(`(b) waits on a deploy ${dep.project.name} can't check`);
         afterKind = "merged";
         warnings.push(
           `"${r.name}" waits on a deploy that ${dep.project.name} can't check; it waits for the merge instead.`
@@ -252,7 +294,8 @@ export function checkPieces(text: string, ctx: CheckContext): PiecesResult {
       if (!dep?.project.deploys) afterKind = "merged";
     }
 
-    if (!reasons.length) return fold("its reason didn't hold");
+    if (!reasons.length)
+      return fold(`its reason didn't hold: ${lost.join("; ")}`);
 
     keep({
       name: r.name,
@@ -274,7 +317,15 @@ export function checkPieces(text: string, ctx: CheckContext): PiecesResult {
       else seen.set(o, p.position);
     }
 
-  return { pieces, folded, warnings };
+  return { pieces, folded, warnings, listed, errors };
+}
+
+// What a task that builds fewer pieces than its plan listed is told, so the
+// folded work is built here and not left for pieces that will never start.
+export function foldedBrief(
+  result: Pick<PiecesResult, "listed" | "folded">
+): string {
+  return `The plan listed ${result.listed} pieces; they're built as ONE here (${result.folded.map((f) => `${f.name}: ${f.why}`).join("; ")}). Build all of it in this PR, including the folded pieces: ${result.folded.map((f) => f.name).join(", ")}. Nothing else will build them.`;
 }
 
 export const PIECES_PROMPT = `At the end of the plan, add a \`## Pieces\` block. The default is exactly one piece, which is what almost every task is, and one piece needs no more than:
@@ -292,14 +343,15 @@ Diff size is never a reason. A later piece looks like:
    after: 1 is merged   (or: 1 is deployed)
    why split: (a) + (b)
    owns: migration 81
-A shared resource (a migration id, a new table, a config key) goes on exactly one piece's \`owns:\` line. A piece with no valid reason is folded into the one before it.`;
+A shared resource (a migration id, a new table, a config key) goes on exactly one piece's \`owns:\` line. A piece with no valid reason is folded into the one before it. Reason (b) needs \`after: N is deployed\`; \`after: N is merged\` alone is only ordering, not a reason. A piece in another project runs as its own task in that project; this task builds only the pieces in its own repository.`;
 
 // Shown to a piece's agent in place of the whole plan.
 export function pieceBrief(
   total: number,
   piece: Pick<Piece, "position" | "name" | "slice" | "owns">,
   planPath: string,
-  before: string[] = []
+  before: string[] = [],
+  project?: string
 ): string {
   const owns = piece.owns.length
     ? `\nThis piece owns: ${piece.owns.join(", ")}. No other piece touches it.`
@@ -307,7 +359,10 @@ export function pieceBrief(
   const earlier = before.length
     ? `\nPieces before you: ${before.join("; ")}.`
     : "";
-  return `Build piece ${piece.position} of ${total} only, "${piece.name}": ${piece.slice}${owns}${earlier}\nThe rest of the plan is other pieces' work; don't start it. Full plan: ${planPath}`;
+  const where = project
+    ? `\nWork only in this task's repository (${project}) and its worktree. Don't create worktrees, branches or PRs in another repository: AgentOS starts the pieces that belong there as their own tasks.`
+    : "";
+  return `Build piece ${piece.position} of ${total} only, "${piece.name}": ${piece.slice}${owns}${earlier}${where}\nThe rest of the plan is other pieces' work; don't start it. Full plan: ${planPath}`;
 }
 
 export interface PlanEdits {