@sleds/cli 0.1.57 → 0.1.59

package/README.md

@@ -64,7 +64,7 @@ sleds engine                          the long-running loop over every route Run
 sleds engine --jira EPIC-7            the same loop over a Jira epic's Blocks links, no SLEDS route needed
 ```
 
-For each ready node the engine makes a worktree, starts an agent session on the node's branch (default `route/{item}-{node}`), and follows its PR to the merge: CI failures and review feedback go back to the session; a merge lands the node, closes the session, removes the worktree and, on Jira, moves the issue to Done. Stopping the engine leaves its sessions running — the next start picks them up from its state file. `sleds route run` keeps its own state file, so it can run beside a `sleds engine` on the same box.
+For each ready node the engine makes a worktree, starts an agent session on the node's branch (default `route/{item}-{node}`; an item synced from Jira or Linear carries its key after the SLEDS key — `route/sl-2091-WORK-123-a`, worktree `sleds-sl-2091-WORK-123-a` — and the session starts its commit subjects and PR title with it, so the ticket's Development panel shows the work), and follows its PR to the merge: CI failures and review feedback go back to the session; a merge lands the node, closes the session, removes the worktree and, on Jira, moves the issue to Done. Stopping the engine leaves its sessions running — the next start picks them up from its state file. `sleds route run` keeps its own state file, so it can run beside a `sleds engine` on the same box.
 
 Where each node runs is `--runner`:
 

package/dist/sleds.mjs

@@ -7089,11 +7089,21 @@ function planTakes(o) {
   }
   return out;
 }
-function nodeBranch(item, node) {
-  return `route/${slugify(`${item}-${node}`, 60) || "node"}`;
+function trackerTicket(item, ticket) {
+  const t = ticket?.trim();
+  if (!t || !/^[A-Za-z][A-Za-z0-9]*-\d+$/.test(t) || t.toUpperCase() === item.toUpperCase())
+    return;
+  return t.toUpperCase();
+}
+function nodeBranch(item, node, ticket) {
+  const t = trackerTicket(item, ticket);
+  if (!t)
+    return `route/${slugify(`${item}-${node}`, 60) || "node"}`;
+  const n = slugify(node, 60);
+  return `route/${[slugify(item, 60), t, n === t.toLowerCase() ? "" : n].filter(Boolean).join("-")}`;
 }
-function sessionName(item, node) {
-  return nodeBranch(item, node).replace(/^route\//, "sleds-");
+function sessionName(item, node, ticket) {
+  return nodeBranch(item, node, ticket).replace(/^route\//, "sleds-");
 }
 function fill(template, values) {
   return template.replace(/\{([A-Za-z_]+)\}/g, (whole, name) => Object.prototype.hasOwnProperty.call(values, name) ? values[name] : whole);
@@ -7123,7 +7133,7 @@ function branchFor(template, claim) {
     slug: slugify(claim.title, 40),
     ticket: one(claim.ticket ?? "")
   }));
-  return name || nodeBranch(claim.item, claim.node);
+  return name || nodeBranch(claim.item, claim.node, claim.ticket);
 }
 function prTitleFor(template, claim) {
   return fill(template, {
@@ -7197,11 +7207,16 @@ function nodePrompt(o) {
   const plan = planBlock(o.plan, o.upstream ?? []);
   const visual = visualSurface(claim.pack);
   const deviations = planLines(o.plan).length ? ", and where you departed from the plan and why" : "";
+  const ticket = trackerTicket(claim.item, claim.ticket);
+  const title = o.prTitle ? ` and title it exactly \`${o.prTitle}\` (the repo's CI checks it)` : ticket ? ` and start its title with \`${ticket}\`` : "";
   const lines = [
     `You are node ${claim.node} of ${claim.item}'s route — "${claim.title}" — started by ${o.engine}.`,
     "",
     `- Work on branch \`${o.branch}\` from the latest \`origin/${base}\` (create it if this checkout is not on it). One branch, one PR.`,
-    `- Open the PR against \`${base}\` with \`gh pr create${visual ? " --draft" : ""}\`${o.prTitle ? ` and title it exactly \`${o.prTitle}\` (the repo's CI checks it)` : ""}. Its body carries \`SLEDS-Node: ${claim.node}\` on the line under \`SLEDS-Source:\` when the pack names a source.`,
+    ...ticket ? [
+      `- Start every commit subject with \`${ticket}\` — ${claim.item} is synced from its tracker, which shows the branch, commits and PR on the ticket by that key.`
+    ] : [],
+    `- Open the PR against \`${base}\` with \`gh pr create${visual ? " --draft" : ""}\`${title}. Its body carries \`SLEDS-Node: ${claim.node}\` on the line under \`SLEDS-Source:\` when the pack names a source.`,
     ...claim.pack.includes(PR_HEADER_OPEN) ? [
       `- The PR body starts with the pack's PR header block (\`${PR_HEADER_OPEN}\` … \`${PR_HEADER_CLOSE}\`, in its part 5), above everything else. The pack wrote it before your work existed: when you make a mock (a screenshot or an artifact) or write a doc, put its link on that part's line in place of \`None\` — not only lower in the body (SL-1746). When you edit the body later, keep it on top.`
     ] : [],
@@ -7559,7 +7574,8 @@ var init_engine = __esm(() => {
   };
   VERDICT_SHAPE = [
     "- **Verdict first.** The first line of `md` (and of `why`) is the verdict on its own, in plain words: what to do, or what is so. No file paths, line numbers or links in it.",
-    "- Then at most 3 short points, one line each, as a `-` list. Cites go in `cites`, not in the prose."
+    "- Then at most 3 short points, one line each, as a `-` list. Cites go in `cites`, not in the prose.",
+    "- **One cite per span, no prose in it.** Code is `code:<path>:<line>`, the path from the repo root (`code:apps/web/src/App.tsx:42`); cite each line on its own, the cards merge them by file."
   ];
   DECIDER_RULES = [
     "- **Text after the input prompt was never sent.** On a session's screen, whatever sits after its last input prompt (`>`, `❯`, `›`) is a draft in the input box: nobody sent it. It is not a person's words, an instruction or a decision — never read it, or cite it, as one.",
@@ -7567,6 +7583,9 @@ var init_engine = __esm(() => {
     "- **No third repeat.** When the decision log shows this node already asked this question (or one the same in substance) and it was answered twice, a third answer of the same kind will not move it. Escalate, saying it keeps coming back, or release it: tell the session to stop waiting and finish with what it has (open its PR, or land and say what is owed)."
   ];
 });
+
+// ../../packages/shared/src/route/sources.ts
+var init_sources = () => {};
 // ../../packages/shared/src/cowork/otlp.ts
 var OTLP_KEEP;
 var init_otlp = __esm(() => {
@@ -8225,6 +8244,7 @@ var init_src = __esm(() => {
   init_doneChecks();
   init_routeFix();
   init_engine();
+  init_sources();
   init_otlp();
   init_session();
   init_effort();
@@ -8627,6 +8647,7 @@ function parseRun(v) {
     ...typeof v.mcpConfig === "string" ? { mcpConfig: v.mcpConfig } : {},
     ...v.onRunToken === true ? { onRunToken: true } : {},
     ...isObject8(v.group) && typeof v.group.key === "string" && typeof v.group.title === "string" ? { group: { key: v.group.key, title: v.group.title } } : {},
+    ...typeof v.ticket === "string" ? { ticket: v.ticket } : {},
     branch,
     repoPath,
     handle,
@@ -8676,7 +8697,14 @@ function parseRun(v) {
         ...typeof v.pr.resolving === "string" ? { resolving: v.pr.resolving } : {},
         ...conflicted ? { conflicted } : {},
         ...typeof v.pr.reviewed === "string" ? { reviewed: v.pr.reviewed } : {},
-        ...typeof v.pr.look === "string" ? { look: v.pr.look } : {}
+        ...typeof v.pr.look === "string" ? { look: v.pr.look } : {},
+        ...isObject8(v.pr.instructed) && Array.isArray(v.pr.instructed.ids) && (v.pr.instructed.how === "told" || v.pr.instructed.how === "restarted") ? {
+          instructed: {
+            ids: v.pr.instructed.ids.filter((x) => typeof x === "string"),
+            how: v.pr.instructed.how
+          }
+        } : {},
+        ...typeof v.pr.findings === "string" ? { findings: v.pr.findings } : {}
       }
     } : {}
   };
@@ -8971,6 +8999,7 @@ init_route();
 init_doneChecks();
 init_routeFix();
 init_engine();
+init_sources();
 init_otlp();
 init_session();
 init_effort();
@@ -11422,6 +11451,26 @@ function orcaRunner(exec, deps = {}) {
     return env;
   };
   const retries = new Map;
+  const terminalIn = (cwd, o) => {
+    const launcher = launcherPath2(o.promptFile);
+    writeFile(launcher, orcaLauncher(o));
+    const shown = orca([
+      "terminal",
+      "create",
+      "--worktree",
+      `path:${cwd}`,
+      "--title",
+      o.name,
+      "--command",
+      orcaCommand(launcher),
+      "--json"
+    ], `orca terminal create ${o.name} (worktree ${cwd})`);
+    const terminal = parseOrcaTerminal(shown);
+    if (!terminal) {
+      throw new Error(`orca terminal create ${o.name} started in ${cwd} but returned no terminal handle`);
+    }
+    return terminal;
+  };
   return {
     name: "orca",
     makesWorktree: true,
@@ -11443,27 +11492,14 @@ function orcaRunner(exec, deps = {}) {
       if (!cwd) {
         throw new Error(`orca worktree create ${o.name} returned no worktree path; the agent was not started`);
       }
-      const launcher = launcherPath2(o.promptFile);
-      writeFile(launcher, orcaLauncher(o));
-      const shown = orca([
-        "terminal",
-        "create",
-        "--worktree",
-        `path:${cwd}`,
-        "--title",
-        o.name,
-        "--command",
-        orcaCommand(launcher),
-        "--json"
-      ], `orca terminal create ${o.name} (worktree ${cwd})`);
-      const terminal = parseOrcaTerminal(shown);
-      if (!terminal) {
-        throw new Error(`orca terminal create ${o.name} started in ${cwd} but returned no terminal handle`);
-      }
+      const terminal = terminalIn(cwd, o);
       const own = parseOrcaBranch(created);
       const h = { runner: "orca", id: terminal, cwd, ...own ? { own } : {} };
       return h;
     },
+    reopen(h, o) {
+      return { ...h, id: terminalIn(h.cwd, o) };
+    },
     status(h) {
       const r = exec("orca", ["terminal", "show", "--terminal", h.id, "--json"]);
       return orcaTerminalLive(r.status, r.stdout) ? "running" : "exited";
@@ -11578,7 +11614,7 @@ function beatBody(state, flags, host = {}, cap = {}) {
     name: flags.name,
     os: host.os ?? process.platform,
     runner: flags.runner,
-    version: host.version ?? "0.1.57" ?? "dev",
+    version: host.version ?? "0.1.59" ?? "dev",
     running: live.length,
     items: live.slice(0, BEAT_ITEMS).map((r) => `${r.item}/${r.node}`),
     ...cap.atOnce !== undefined ? { atOnce: cap.atOnce } : {},
@@ -11870,7 +11906,7 @@ function noteEvent(line) {
 
 // src/engine/gh.ts
 init_src();
-var isGhError = (r) => r !== null && ("error" in r);
+var isGhError = (r) => r !== null && typeof r === "object" && ("error" in r);
 function prForBranch(exec, repoPath, branch) {
   try {
     const r = exec("gh", [
@@ -11912,6 +11948,74 @@ function prForBranch(exec, repoPath, branch) {
     return { error: e instanceof Error ? e.message : String(e) };
   }
 }
+function carriesKey(text, key) {
+  const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[^A-Za-z0-9])${k}(?![0-9])`, "i").test(text);
+}
+var isTrackerKey = (key) => /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(key);
+function otherWork(exec, repoPath, key, own) {
+  const out = [];
+  try {
+    const r = exec("gh", [
+      "pr",
+      "list",
+      "--state",
+      "open",
+      "--json",
+      "url,title,headRefName,isCrossRepository,author",
+      "--limit",
+      "100"
+    ], { cwd: repoPath });
+    if (r.status !== 0)
+      return { error: r.stderr.trim() || `gh pr list exited with status ${r.status}` };
+    let rows;
+    try {
+      rows = JSON.parse(r.stdout);
+    } catch {
+      return { error: "gh pr list did not print JSON" };
+    }
+    if (!Array.isArray(rows))
+      return { error: "gh pr list did not print a list" };
+    for (const row of rows) {
+      if (typeof row !== "object" || row === null)
+        continue;
+      const { url, title, headRefName, isCrossRepository, author } = row;
+      if (typeof url !== "string" || !url)
+        continue;
+      const branch = typeof headRefName === "string" ? headRefName : "";
+      const named = typeof title === "string" ? title : "";
+      if (!carriesKey(branch, key) && !carriesKey(named, key))
+        continue;
+      if (isCrossRepository !== true && own(branch))
+        continue;
+      const login = typeof author === "object" && author !== null ? author.login : undefined;
+      out.push({
+        branch,
+        pr: { url, title: named, ...typeof login === "string" && login ? { author: login } : {} }
+      });
+    }
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+  try {
+    const r = exec("git", ["ls-remote", "--heads", "origin"], { cwd: repoPath });
+    if (r.status === 0) {
+      const listed = new Set(out.map((w) => w.branch));
+      for (const line of r.stdout.split(`
+`)) {
+        const branch = line.split("\t")[1]?.trim().replace(/^refs\/heads\//, "") ?? "";
+        if (!branch || listed.has(branch) || own(branch) || !carriesKey(branch, key))
+          continue;
+        listed.add(branch);
+        out.push({ branch });
+      }
+    }
+  } catch {}
+  return out;
+}
+function otherWorkLine(work) {
+  return work.map((w) => w.pr ? `${w.pr.url}${w.pr.author ? ` by ${w.pr.author}` : ""} (${w.branch})` : `branch ${w.branch} (no PR yet)`).join("; ");
+}
 var URL_RE = /https:\/\/[^\s)>\]"']+/;
 var ARTIFACT_RE = /https:\/\/claude\.ai\/[^\s)>\]"']*artifact\/[^\s)>\]"']+/;
 function mockOf(body) {
@@ -11993,6 +12097,8 @@ function countFeedback(stdout, author) {
   const n = { all: 0, author: 0 };
   for (const line of stdout.split(`
 `)) {
+    if (line.startsWith(BOT_LINE))
+      continue;
     const [login = "", marked, hasBody] = line.trim().split("\t");
     if (!login || marked === "true")
       continue;
@@ -12004,12 +12110,14 @@ function countFeedback(stdout, author) {
   }
   return n;
 }
-var FEEDBACK_JQ = `.[] | select(.user.type != "Bot") | [.user.login, ((.body // "") | contains("${ENGINE_MARK}") | tostring), ((.body // "") | length > 0 | tostring)] | @tsv`;
+var BOT_LINE = "bot\t";
+var FEEDBACK_JQ = `.[] | if .user.type == "Bot" then (select((.body // "") | length > 0) | "${BOT_LINE}" + ({by: .user.login, url: .html_url, md: .body, at: (.submitted_at // .created_at // "")} | tojson)) else ([.user.login, ((.body // "") | contains("${ENGINE_MARK}") | tostring), ((.body // "") | length > 0 | tostring)] | @tsv) end`;
 function prFeedback(exec, repoPath, url, author) {
   const ref = prRef(url);
   if (!ref)
     return null;
   const total = { all: 0, author: 0 };
+  const bots = [];
   for (const path of [
     `repos/${ref.repo}/issues/${ref.number}/comments`,
     `repos/${ref.repo}/pulls/${ref.number}/reviews`,
@@ -12022,11 +12130,38 @@ function prFeedback(exec, repoPath, url, author) {
       const n = countFeedback(r.stdout, author);
       total.all += n.all;
       total.author += n.author;
+      bots.push(...parseBotFindings(r.stdout));
     } catch {
       return null;
     }
   }
-  return total;
+  const findings = bots.sort((a, b) => a.at.localeCompare(b.at)).slice(-FINDINGS_MAX).map(({ by, url, md }) => ({ by, url, md }));
+  return { ...total, findings };
+}
+var FINDINGS_MAX = 20;
+var FINDING_MD_MAX = 2000;
+function parseBotFindings(stdout) {
+  const out = [];
+  for (const line of stdout.split(`
+`)) {
+    if (!line.startsWith(BOT_LINE))
+      continue;
+    try {
+      const o = JSON.parse(line.slice(BOT_LINE.length));
+      if (typeof o.by !== "string" || typeof o.url !== "string" || typeof o.md !== "string")
+        continue;
+      const md = o.md.trim();
+      if (!md || md.includes(ENGINE_MARK))
+        continue;
+      out.push({
+        by: o.by,
+        url: o.url,
+        md: md.slice(0, FINDING_MD_MAX),
+        at: typeof o.at === "string" ? o.at : ""
+      });
+    } catch {}
+  }
+  return out;
 }
 var MERGE_QUEUE_QUERY = "query($url: URI!) { resource(url: $url) { ... on PullRequest { mergeQueueEntry { state } } } }";
 function prInMergeQueue(exec, repoPath, url) {
@@ -12064,11 +12199,19 @@ function prView(exec, repoPath, url, last) {
     const ready = !parsed.queued && parsed.failing.length === 0 && parsed.pending === 0 && parsed.reviewDecision === "APPROVED";
     const view = ready && prInMergeQueue(exec, repoPath, url) === true ? { ...parsed, queued: true } : parsed;
     let read = view.updatedAt && last?.updatedAt === view.updatedAt ? last : undefined;
+    let findings = null;
     if (!read) {
       const f = prFeedback(exec, repoPath, url, view.author);
-      read = f && { ...f, updatedAt: view.updatedAt };
-    }
-    return read ? { ...view, feedback: read.all, authorFeedback: read.author, read } : view;
+      read = f && { all: f.all, author: f.author, updatedAt: view.updatedAt };
+      findings = f?.findings ?? null;
+    }
+    return read ? {
+      ...view,
+      feedback: read.all,
+      authorFeedback: read.author,
+      read,
+      ...findings ? { findings } : {}
+    } : view;
   } catch {
     return null;
   }
@@ -12616,6 +12759,32 @@ function resumesOf(s) {
   const r = s;
   return r && typeof r.resumeParked === "function" ? s : null;
 }
+function instructionsOf(s) {
+  const i = s;
+  return i && typeof i.instructions === "function" ? s : null;
+}
+function instructionsFrom(waiting) {
+  if (!Array.isArray(waiting))
+    return [];
+  return waiting.filter(isObject8).flatMap((w) => {
+    const id = str6(w.id);
+    const md = str6(w.md);
+    if (!id || !md)
+      return [];
+    const f = isObject8(w.finding) ? w.finding : null;
+    const kind = f?.kind === "review" || f?.kind === "bot" ? f.kind : null;
+    const url = f ? str6(f.url) : undefined;
+    const by = f ? str6(f.by) : undefined;
+    return [
+      {
+        id,
+        md,
+        by: str6(w.by) ?? "a person",
+        ...kind ? { finding: { kind, ...url ? { url } : {}, ...by ? { by } : {} } } : {}
+      }
+    ];
+  });
+}
 var FAIL_LOG_MAX = 2000;
 var UNREACHABLE3 = "SLEDS unreachable";
 function keysIn(states, state) {
@@ -12861,6 +13030,10 @@ function nextPickup(r, o) {
       continue;
     if (isPrMirror(row.source))
       continue;
+    if (route.packable === false)
+      continue;
+    if (isObject8(route.elsewhere))
+      continue;
     const states = isObject8(route.states) ? route.states : {};
     if (statesLanded(states) || keysIn(states, "running").length > 0)
       continue;
@@ -12890,6 +13063,8 @@ function armedDrafts(r, engine) {
       return false;
     if (route.drafting === true || route.proposed === true || route.draftParked)
       return false;
+    if (isObject8(route.elsewhere))
+      return false;
     if (strings(route.needsRoute).length === 0 || isPrMirror(row.source))
       return false;
     const states = isObject8(route.states) ? route.states : {};
@@ -13094,7 +13269,8 @@ function sledsSource(client, o) {
         ...str6(hit.answer) ? { answer: str6(hit.answer) } : {},
         ...runToken ? { runToken } : {},
         ...group ? { group } : {},
-        ...run ? { run } : {}
+        ...run ? { run } : {},
+        ...str6(hit.ticket) ? { ticket: str6(hit.ticket) } : {}
       };
       return { ok: true, claim };
     },
@@ -13117,7 +13293,7 @@ function sledsSource(client, o) {
         return "running";
       if (claim.kind === "draft") {
         const filed = Array.isArray(route.nodes) && route.nodes.length > 0;
-        if (filed || isObject8(route.proposed))
+        if (filed || isObject8(route.proposed) || isObject8(route.elsewhere))
           return "done";
         if (isObject8(route.draftParked))
           return "parked";
@@ -13317,6 +13493,23 @@ function sledsSource(client, o) {
         return false;
       }
     },
+    async instructions(item, node, o) {
+      try {
+        const r = await client.postFull("/proxy/prread", {
+          project: item,
+          node,
+          instructions: {
+            ...o.findings ? { findings: o.findings } : {},
+            ...o.delivered ? { delivered: o.delivered } : {}
+          }
+        });
+        if (!r || r.status < 200 || r.status >= 300 || !r.json)
+          return null;
+        return r.json.ok === false ? [] : instructionsFrom(r.json.waiting);
+      } catch {
+        return null;
+      }
+    },
     async answerDecision(a, engine, answer) {
       const r = await client.postFull("/proxy/run", { runId: a.runId, engine, answer });
       if (!r)
@@ -14284,8 +14477,8 @@ async function tickOnce(d) {
       await report({ kind: "release", why: repoPath.error });
       continue;
     }
-    const branch = d.branchOf ? d.branchOf(claim) : nodeBranch(claim.item, claim.node);
-    const name = sessionName(claim.item, claim.node);
+    const branch = d.branchOf ? d.branchOf(claim) : nodeBranch(claim.item, claim.node, claim.ticket);
+    const name = sessionName(claim.item, claim.node, claim.ticket);
     const found = d.prForBranch(d.exec, repoPath, branch);
     if (isGhError(found))
       d.log(`${at}: could not ask GitHub for ${branch}'s PR: ${found.error}`);
@@ -14295,6 +14488,12 @@ async function tickOnce(d) {
       await report({ kind: existing.state === "MERGED" ? "merged" : "pr", ref: existing.url });
       continue;
     }
+    const duplicate = duplicateQuestion(d, claim, repoPath, "run");
+    if (duplicate) {
+      d.log(`${at}: parked — ${duplicate}`);
+      await report({ kind: "park", question: duplicate });
+      continue;
+    }
     let start;
     let mcpConfig;
     try {
@@ -14380,6 +14579,7 @@ async function tickOnce(d) {
       ...mcpConfig ? { mcpConfig, ...claim.runToken ? { onRunToken: true } : {} } : {},
       ...claim.group ? { group: claim.group } : {},
       ...packBandOf(claim.pack) ? { band: packBandOf(claim.pack) } : {},
+      ...claim.ticket ? { ticket: claim.ticket } : {},
       branch,
       repoPath,
       handle,
@@ -14505,7 +14705,7 @@ async function settlePermission(d, runner, run, shown) {
   if (!perms || !run.runId)
     return false;
   const at = ref(run);
-  const markFile = d.permissionMark?.(sessionName(run.item, run.node));
+  const markFile = d.permissionMark?.(sessionName(run.item, run.node, run.ticket));
   const dialog = runner.readsSession ? permissionDialog(shown) : null;
   const p = run.permission;
   if (p) {
@@ -15354,6 +15554,25 @@ var safeWatch = (runner, h) => {
     return h.id;
   }
 };
+function duplicateQuestion(d, claim, repoPath, verb) {
+  if (!d.otherWork || claim.answer)
+    return null;
+  const key = claim.ticket ?? claim.item;
+  if (!isTrackerKey(key))
+    return null;
+  const prefix = nodeBranch(claim.item, "x").slice(0, -1);
+  const template = d.branchOf?.(claim);
+  const own = (b) => b.startsWith(prefix) || b === template;
+  const found = d.otherWork(d.exec, repoPath, key, own);
+  if (isGhError(found)) {
+    d.log(`${ref(claim)}: could not look for other work on ${key}: ${found.error}`);
+    return null;
+  }
+  if (!found.length)
+    return null;
+  const what = verb === "plan" ? "plan its route" : `run ${claim.node}`;
+  return `${key} already has work outside this engine: ${otherWorkLine(found)}. Answer to ${what} anyway; if that work is the one to keep, skip the node or close the item instead.`;
+}
 async function startDraft(d, claim, why, state, started, finished) {
   const at = ref(claim);
   const report = async (outcome) => {
@@ -15370,6 +15589,12 @@ async function startDraft(d, claim, why, state, started, finished) {
     await report({ kind: "park", question: repoPath.error });
     return;
   }
+  const duplicate = duplicateQuestion(d, claim, repoPath, "plan");
+  if (duplicate) {
+    d.log(`${at}: parked — ${duplicate}`);
+    await report({ kind: "park", question: duplicate });
+    return;
+  }
   const name = sessionName(claim.item, DRAFT_NODE);
   const branch = nodeBranch(claim.item, DRAFT_NODE);
   let handle;
@@ -15535,6 +15760,30 @@ function ciNudge(url, failing) {
 var SELF_NUDGES = 2;
 var FEEDBACK_REREAD_MS = 10 * 60000;
 var CONFLICT_RECHECK_MS = 10 * 60000;
+var INSTRUCTION_READ_MS = 60000;
+function instructionText(i) {
+  const from = i.finding ? ` about ${i.finding.kind === "review" ? "SLEDS's review" : `${i.finding.by ?? "a bot reviewer"}'s finding`}${i.finding.url ? ` (${i.finding.url})` : ""}` : "";
+  return `From ${i.by}${from}:
+
+${i.md.trim()}`;
+}
+function instructionNudge(url, items) {
+  const replies = items.some((i) => i.finding?.url) ? " Where one came from a finding on the PR, reply on that finding's thread with the fix or why not, and leave the thread for the reviewer to resolve." : "";
+  return `Instructions for your PR (${url}), written on its item in SLEDS:
+
+${items.map(instructionText).join(`
+
+---
+
+`)}
+
+Do them on your own branch, run the repo's gate, and push to the same PR.${replies} End every comment and reply you post on the PR with the line ${ENGINE_MARK}.`;
+}
+function instructionPrompt(run, url, items) {
+  return `You are picking up node ${run.node} of ${run.item}. Its PR is open: ${url}, on the branch ${run.branch}, checked out in this worktree. The session that opened it has ended. Read the PR first (gh pr view ${url} --comments, and the inline threads), then follow the instructions below. Never force-push, never merge, never open a second PR.
+
+${instructionNudge(url, items)}`;
+}
 function reviewNudge(url, count) {
   return `New review feedback on your PR (${count} ${count === 1 ? "comment" : "comments"} from people so far): ${url}. Read all of it (gh pr view ${url} --comments, and the inline threads), answer each comment on its own thread with the fix or a reasoned reply, push, and leave the threads for the reviewer to resolve. End every comment and reply you post on the PR with the line ${ENGINE_MARK} so the engine knows it is yours and not the reviewer's.`;
 }
@@ -15652,6 +15901,7 @@ async function follow(d, state, run, claim, runner, finished, attention, changes
       pr.selfNudges = selfNudges || undefined;
     }
   }
+  await carryInstructions(d, run, runner, view, attention);
   pr.failing = view.failing;
   pr.feedback = Math.max(pr.feedback, view.feedback);
   pr.authorFeedback = Math.max(pr.authorFeedback ?? 0, view.authorFeedback) || undefined;
@@ -16173,22 +16423,37 @@ async function answerBaseConflict(d, events, state, dec, attention, decided) {
   return false;
 }
 function startResolver(d, run, e, answer) {
+  const name = sessionName(run.item, `${run.node}-resolve`);
+  const started = restartInWorktree(d, run, name, eventAnswerNudge(e, answer), e.base);
+  if (started !== true) {
+    if (started)
+      d.log(`${ref(run)}: could not start a resolver session: ${started.error}`);
+    return false;
+  }
   const runner = runnerFor(d, run.handle);
-  if (!runner || runner.makesWorktree || run.handle.cwd === run.repoPath)
+  if (run.pr)
+    run.pr.resolving = e.baseSha;
+  d.log(`${ref(run)}: a resolver session has the conflict brief — ${safeWatch(runner, run.handle)}`);
+  return true;
+}
+function restartInWorktree(d, run, name, prompt, base) {
+  const runner = runnerFor(d, run.handle);
+  if (!runner || run.handle.cwd === run.repoPath)
+    return false;
+  if (runner.makesWorktree && !runner.reopen)
     return false;
-  const name = sessionName(run.item, `${run.node}-resolve`);
   try {
     runner.stop(run.handle);
   } catch {}
   try {
     const launch = nodeLaunchFor(d, ref(run));
-    run.handle = runner.start({
+    const o = {
       name,
       repoPath: run.repoPath,
       worktree: run.handle.cwd,
       branch: run.branch,
-      base: e.base,
-      promptFile: d.writePrompt(name, eventAnswerNudge(e, answer)),
+      ...base ? { base } : {},
+      promptFile: d.writePrompt(name, prompt),
       permissionMode: d.permissionMode,
       ...launchOptions(launch),
       ...run.mcpConfig ? { mcpConfig: run.mcpConfig, ...d.strictMcp ? { strictMcp: true } : {} } : {},
@@ -16196,16 +16461,75 @@ function startResolver(d, run, e, answer) {
       ...hooksFor(d, name),
       ...mainCheckoutFor(d, run.handle.cwd),
       ...run.group ? { group: run.group } : {}
-    });
+    };
+    run.handle = runner.makesWorktree ? runner.reopen(run.handle, o) : runner.start(o);
   } catch (err) {
-    d.log(`${ref(run)}: could not start a resolver session: ${message(err)}`);
-    return false;
+    return { error: message(err) };
   }
-  if (run.pr)
-    run.pr.resolving = e.baseSha;
-  d.log(`${ref(run)}: a resolver session has the conflict brief — ${safeWatch(runner, run.handle)}`);
   return true;
 }
+async function carryInstructions(d, run, runner, view, attention) {
+  const source = instructionsOf(d.source);
+  const pr = run.pr;
+  if (!source)
+    return;
+  const findings = view.findings;
+  const findingsKey = findings?.map((f) => f.url).join(" ");
+  const newFindings = findings !== undefined && findingsKey !== pr.findings;
+  const due = !pr.instructAt || d.now() - pr.instructAt >= INSTRUCTION_READ_MS;
+  if (!due && !newFindings && !pr.instructed)
+    return;
+  const waiting = await source.instructions(run.item, run.node, {
+    ...newFindings ? { findings } : {},
+    ...pr.instructed ? { delivered: pr.instructed } : {}
+  });
+  if (!waiting)
+    return;
+  pr.instructAt = d.now();
+  if (newFindings)
+    pr.findings = findingsKey;
+  const told = pr.instructed?.ids ?? [];
+  pr.instructed = undefined;
+  const fresh = waiting.filter((i) => !told.includes(i.id));
+  if (fresh.length === 0)
+    return;
+  const at = { item: run.item, node: run.node, url: pr.url };
+  const what = `${fresh.length} instruction${fresh.length === 1 ? "" : "s"} from the item`;
+  let status;
+  try {
+    status = runner.status(run.handle);
+    if (status === "running") {
+      const note = runner.send(run.handle, instructionNudge(pr.url, fresh));
+      d.log(`${ref(run)}: ${what} — told the session${note ? ` (${note})` : ""}`);
+      pr.instructed = { ids: fresh.map((i) => i.id), how: "told" };
+    }
+  } catch {}
+  if (!pr.instructed && status === "exited") {
+    const name = sessionName(run.item, `${run.node}-instruct`);
+    const started = restartInWorktree(d, run, name, instructionPrompt(run, pr.url, fresh));
+    if (started === true) {
+      d.log(`${ref(run)}: ${what} — its session had ended; a new one has them on ${run.branch}: ${safeWatch(runnerFor(d, run.handle) ?? d.runner, run.handle)}`);
+      pr.instructed = { ids: fresh.map((i) => i.id), how: "restarted" };
+      pr.selfNudges = undefined;
+    } else if (started)
+      d.log(`${ref(run)}: could not restart the session: ${started.error}`);
+  }
+  if (pr.instructed) {
+    const after = await source.instructions(run.item, run.node, { delivered: pr.instructed });
+    if (after)
+      pr.instructed = undefined;
+    return;
+  }
+  const said = `${ref(run)}:instruct:${fresh.map((i) => i.id).join(",")}`;
+  if (d.refused?.get(said))
+    return;
+  d.refused?.set(said, "said");
+  d.log(`${ref(run)}: ${what} could not reach a session (${status === "running" ? "the session takes no input" : "the runner cannot restart it"}) — needs a person: ${pr.url}`);
+  attention.push({
+    ...at,
+    what: `${what} waiting — no session can take them; open the worktree ${run.handle.cwd}`
+  });
+}
 async function startEventAnswerer(d, answers, state, dec, decided) {
   const at = ref(dec);
   const kind = dec.event.kind;
@@ -17355,7 +17679,7 @@ import {
 } from "node:fs";
 
 // ../../packages/shared/src/updates/releaseKey.ts
-var RELEASE_PUBLIC_KEY = "";
+var RELEASE_PUBLIC_KEY = "MCowBQYDK2VwAyEADIZiQghghQlN6WoLDF9xLmqMeFSQL4crcCBT4wINNCc=";
 
 // ../../packages/shared/src/updates/verify.ts
 import { createPrivateKey, createPublicKey as createPublicKey2, sign, verify } from "node:crypto";
@@ -17586,7 +17910,7 @@ async function fetchVersion(o) {
   const platform = o.platform ?? process.platform;
   const arch = o.arch ?? process.arch;
   const publicKey = o.publicKey ?? RELEASE_PUBLIC_KEY;
-  const running = o.running ?? "0.1.57";
+  const running = o.running ?? "0.1.59";
   if (!publicKey)
     return { ok: false, why: "no release key yet" };
   if (!VERSION_RE2.test(o.version))
@@ -18865,7 +19189,7 @@ function templateProblem(flag, template, jira = false) {
     return `--${flag} has ${unknown.map((f) => `{${f}}`).join(", ")}, which the engine does not fill — it knows ${known.map((f) => `{${f}}`).join(" ")}`;
   const perNode = jira ? ["node", "key", "ticket", "slug"] : ["node", "slug"];
   if (flag === "branch" && !used.some((f) => perNode.includes(f)))
-    return jira ? "--branch needs {node}, {key}, {ticket} or {slug}: without one every node of an item gets the same branch, and the second would find the first one's PR and stop" : "--branch needs {node} or {slug} on a SLEDS route: its nodes share the item's {key} and have no {ticket}, so without one every node gets the same branch and the second would find the first one's PR and stop";
+    return jira ? "--branch needs {node}, {key}, {ticket} or {slug}: without one every node of an item gets the same branch, and the second would find the first one's PR and stop" : "--branch needs {node} or {slug} on a SLEDS route: its nodes share the item's {key} and {ticket}, so without one every node gets the same branch and the second would find the first one's PR and stop";
   return null;
 }
 function defaultEngineName(host) {
@@ -19171,7 +19495,7 @@ function engineClient(o, org, breaker) {
       ...src,
       ...breaker ? { fetchFn: breaker.fetch } : {},
       timeoutMs: ENGINE_TIMEOUT_MS,
-      version: "0.1.57"
+      version: "0.1.59"
     });
   const asked = org?.trim() || env.SLEDS_ORG?.trim();
   if (asked && !selectOrg(readConfig(o.home), org, env).seat)
@@ -19348,6 +19672,7 @@ function engineDeps(o, flags, source, runner, stateName) {
     defaultBranch,
     runnerOf: (name) => name === runner.name ? runner : restoreRunner(name, exec),
     prForBranch,
+    otherWork,
     prView,
     mergeTree,
     prFiles,
@@ -19462,7 +19787,7 @@ async function driveEngine(o, flags, deps, until = {}) {
     runner: deps.runner.name,
     atOnce: flags.atOnce,
     interval: flags.interval,
-    cliVersion: "0.1.57"
+    cliVersion: "0.1.59"
   };
   const beat = (checkedAt) => {
     const m = deps.machine;
@@ -20971,7 +21296,7 @@ function templateProblem2(flag, template, jira = false) {
     return `--${flag} has ${unknown.map((f) => `{${f}}`).join(", ")}, which the engine does not fill — it knows ${known.map((f) => `{${f}}`).join(" ")}`;
   const perNode = jira ? ["node", "key", "ticket", "slug"] : ["node", "slug"];
   if (flag === "branch" && !used.some((f) => perNode.includes(f)))
-    return jira ? "--branch needs {node}, {key}, {ticket} or {slug}: without one every node of an item gets the same branch, and the second would find the first one's PR and stop" : "--branch needs {node} or {slug} on a SLEDS route: its nodes share the item's {key} and have no {ticket}, so without one every node gets the same branch and the second would find the first one's PR and stop";
+    return jira ? "--branch needs {node}, {key}, {ticket} or {slug}: without one every node of an item gets the same branch, and the second would find the first one's PR and stop" : "--branch needs {node} or {slug} on a SLEDS route: its nodes share the item's {key} and {ticket}, so without one every node gets the same branch and the second would find the first one's PR and stop";
   return null;
 }
 function defaultEngineName2(host) {
@@ -21329,7 +21654,7 @@ function engineClient2(o, org, breaker) {
       ...src,
       ...breaker ? { fetchFn: breaker.fetch } : {},
       timeoutMs: ENGINE_TIMEOUT_MS2,
-      version: "0.1.57"
+      version: "0.1.59"
     });
   const asked = org?.trim() || env.SLEDS_ORG?.trim();
   if (asked && !selectOrg(readConfig(o.home), org, env).seat)
@@ -21528,6 +21853,7 @@ function engineDeps2(o, flags, source, runner, stateName) {
     defaultBranch,
     runnerOf: (name) => name === runner.name ? runner : restoreRunner(name, exec),
     prForBranch,
+    otherWork,
     prView,
     mergeTree,
     prFiles,
@@ -21655,7 +21981,7 @@ async function driveEngine2(o, flags, deps, until = {}) {
     runner: deps.runner.name,
     atOnce: flags.atOnce,
     interval: flags.interval,
-    cliVersion: "0.1.57"
+    cliVersion: "0.1.59"
   };
   const beat = (checkedAt) => {
     const m = deps.machine;
@@ -23758,7 +24084,7 @@ function contextFor(deps) {
     ...src,
     fetchFn: deps.fetchFn,
     timeoutMs: deps.timeoutMs,
-    version: "0.1.57"
+    version: "0.1.59"
   }), deps.home, now) : null;
   return {
     channel: "code",
@@ -23872,6 +24198,8 @@ When the person asks what is on their sled, what they hold, or what to pick up n
 
 Offer the next step in one line: take one (\`sled\` with \`take: "<key>"\`, or \`"<key>/B"\` for one node of its route), or read one whole first (\`item\`).
 
+An item already being built outside the engine (by hand, in another app) is marked so no engine plans or runs it: \`sleds route elsewhere <key> --note "<why>"\`. It stays on the sled and lands from its PR.
+
 A key SLEDS cannot find may live in another org: the connector reads the org of the seat it signed in with. Say which org that is, and that the item has to be read from a seat in its own org. Do not report it as missing or done.
 
 ## Finish — leave what you learned
@@ -25553,12 +25881,13 @@ init_src();
 import { readFileSync as readFileSync29 } from "node:fs";
 import { hostname as hostname12 } from "node:os";
 var ARM_USAGE = "usage: sleds route arm <key> [--off] [--json] [--name <engine>] [--at-once <n>] [--runner tmux|headless|command|orca|cmux] [--runner-cmd '<launcher>'] [--agent '<command>'] [--mode <permission-mode>] [--model <id>] [--effort <e>] [--branch '<template>'] [--pr-title '<template>'] [--repos-dir <dir>]";
-var USAGE2 = "usage: sleds route <key> [--long | --dot | --json]   |   sleds route arm <key> [--off] [--json]   |   sleds route answer <key>/<node> --stdin   |   sleds route propose <key> --file <nodes.json>   |   sleds route approve <key>   |   sleds route redraft <key>   |   sleds route single <key>   |   sleds route decisions [<key>] [--flagged]   |   sleds route decision <key> <id> --seen | --answer --stdin [--route accept|keep|redraft] | --keep-route | --apply [--answer --stdin] | --overrule --stdin | --ready   |   sleds route run <key> [--at-once <n>] [--runner tmux|headless|command|orca|cmux] [--runner-cmd '<launcher>'] [--agent '<command>'] [--interval <s>] [--lease <min>] [--idle <min>] [--repo <path>] [--repos-dir <dir>] [--mode <permission-mode>] [--model <id>] [--branch '<template>'] [--pr-title '<template>'] [--once]";
+var USAGE2 = "usage: sleds route <key> [--long | --dot | --json]   |   sleds route arm <key> [--off] [--json]   |   sleds route answer <key>/<node> --stdin   |   sleds route propose <key> --file <nodes.json>   |   sleds route approve <key>   |   sleds route redraft <key>   |   sleds route single <key>   |   sleds route elsewhere <key> [--note <text>]   |   sleds route decisions [<key>] [--flagged]   |   sleds route decision <key> <id> --seen | --answer --stdin [--route accept|keep|redraft] | --keep-route | --apply [--answer --stdin] | --overrule --stdin | --ready   |   sleds route run <key> [--at-once <n>] [--runner tmux|headless|command|orca|cmux] [--runner-cmd '<launcher>'] [--agent '<command>'] [--interval <s>] [--lease <min>] [--idle <min>] [--repo <path>] [--repos-dir <dir>] [--mode <permission-mode>] [--model <id>] [--branch '<template>'] [--pr-title '<template>'] [--once]";
 var ANSWER_USAGE = "usage: sleds route answer <key>/<node> <answer…>   |   sleds route answer <key>/<node> --stdin   [--json]";
 var PROPOSE_USAGE = "usage: sleds route propose <key> (--file <nodes.json> | --stdin) [--name <engine>] [--json]";
 var APPROVE_USAGE = "usage: sleds route approve <key> [--file <nodes.json>] [--json]";
 var REDRAFT_USAGE = "usage: sleds route redraft <key> [--json]";
 var SINGLE_USAGE = "usage: sleds route single <key> [--json]";
+var ELSEWHERE_USAGE = "usage: sleds route elsewhere <key> [--note <text>] [--json]";
 var DECISION_USAGE = "usage: sleds route decision <key> <id> --seen   |   sleds route decision <key> <id> (--answer | --overrule) (<answer…> | --stdin)   |   sleds route decision <key> <id> [--answer (<answer…> | --stdin)] --route accept|keep|redraft   |   sleds route decision <key> <id> --keep-route   |   sleds route decision <key> <id> --apply [--answer (<answer…> | --stdin)]   |   sleds route decision <key> <id> --ready   [--json]";
 var ROUTE_VERDICTS = ["accept", "keep", "redraft"];
 function nodesFromJson(text) {
@@ -25611,6 +25940,8 @@ function parseVerbArgs(argv, allowed) {
         out.file = value;
       if (flag === "name")
         out.name = value;
+      if (flag === "note")
+        out.note = value;
       i++;
     } else if (a.startsWith("-"))
       return { error: `unknown flag ${a}` };
@@ -25843,10 +26174,13 @@ async function redraftCmd(o, argv) {
 async function singleCmd(o, argv) {
   return oneVerb(o, argv, SINGLE_USAGE, { single: true }, "nothing changed", (key) => singleLine(key));
 }
-async function oneVerb(o, argv, usage, body, unreachable, line) {
+async function elsewhereCmd(o, argv) {
+  return oneVerb(o, argv, ELSEWHERE_USAGE, (a) => ({ elsewhere: true, ...a.note ? { note: a.note } : {} }), "nothing marked", (key) => elsewhereLine(key), ["note"]);
+}
+async function oneVerb(o, argv, usage, body, unreachable, line, flags = []) {
   const log = o.log ?? console.log;
   const error = o.error ?? console.error;
-  const a = parseVerbArgs(argv, ["json"]);
+  const a = parseVerbArgs(argv, ["json", ...flags]);
   if ("error" in a) {
     error(a.error);
     error(usage);
@@ -25857,7 +26191,10 @@ async function oneVerb(o, argv, usage, body, unreachable, line) {
     error(client.error);
     return 1;
   }
-  const r = await client.postFull("/proxy/route", { project: a.key, ...body });
+  const r = await client.postFull("/proxy/route", {
+    project: a.key,
+    ...typeof body === "function" ? body(a) : body
+  });
   if (!r) {
     error(`${a.key}: SLEDS unreachable — ${unreachable}`);
     return 1;
@@ -25871,6 +26208,9 @@ function redraftLine(key) {
 function singleLine(key) {
   return `${key} runs as one node — it is not planned again`;
 }
+function elsewhereLine(key) {
+  return `${key} marked built elsewhere — no engine runs it`;
+}
 function answeredLine(key, route, held) {
   const nodes = Array.isArray(held) && held.length ? ` (${held.join(", ")})` : "";
   if (route === "accept")
@@ -26138,6 +26478,8 @@ var routeCmd = async (o) => {
     return redraftCmd(o, o.argv.slice(1));
   if (o.argv[0] === "single")
     return singleCmd(o, o.argv.slice(1));
+  if (o.argv[0] === "elsewhere")
+    return elsewhereCmd(o, o.argv.slice(1));
   if (o.argv[0] === "decision")
     return decisionCmd(o, o.argv.slice(1));
   if (o.argv[0] === "decisions")
@@ -27876,7 +28218,7 @@ var realPidAlive4 = (pid) => {
 };
 function machineClient(home, env) {
   const src = meterSource(home, undefined, { env });
-  return src ? fetchClient({ ...src, version: "0.1.57" }) : null;
+  return src ? fetchClient({ ...src, version: "0.1.59" }) : null;
 }
 async function noteAnswer2(home, a, now) {
   try {
@@ -28526,7 +28868,10 @@ commands:
               approve <key>          a person's yes to a planned route: files it and, under
                                      Pickup: Auto, arms it; --file <nodes.json> approves an
                                      edited set instead (--json)
-              run <key>              run the engine for this one item until its route lands
+              elsewhere <key>        built outside the engine: no engine plans or runs it, it
+                                     stays on your sled and lands from its PR; --note "<why>"
+                                     goes on the thread (--json)
+              run <key>             run the engine for this one item until its route lands
               --at-once <n>          sessions at once (default 1; one per seat \u2014 tick seats
                                      when you press Run to run more than one)
               --runner tmux|headless|command|orca   where each node runs (default tmux, any
@@ -28736,7 +29081,7 @@ var main = async (argv) => {
     now: Date.now(),
     stderr: (line) => console.error(line),
     isTTY: !!process.stderr.isTTY,
-    version: "0.1.57"
+    version: "0.1.59"
   });
   switch (cmd) {
     case "update":
@@ -28969,7 +29314,7 @@ ${renderHelpText(argv[1])}`);
     case "version":
     case "--version":
     case "-v":
-      console.log("sleds 0.1.57");
+      console.log("sleds 0.1.59");
       return 0;
     default:
       console.error(`unknown command: ${cmd}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleds/cli",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "description": "SLEDS CLI — the cost and limits of AI agent work, decided at the wall. Point Claude Code at a SLEDS proxy; estimate before you run; hold, switch model, or run overnight when you hit a limit.",
   "license": "UNLICENSED",
   "type": "module",