@saadnvd1/agent-os 0.3.518 → 0.3.520

package/lib/done/worktree.ts

@@ -114,14 +114,15 @@ const gone = (merged: MergedAs | null, still = false) => ({
 export async function worktreeFate(
   session: Judged,
   merged: MergedAs | null,
-  waitMs = 60_000
+  waitMs = 60_000,
+  movedAway = false
 ): Promise<FatePreview> {
   const path = session.worktree_path;
   if (!path) return { action: "none" };
   for (;;) {
     if (!(await removalSettled(path, waitMs))) return gone(merged, true);
     if (!fs.existsSync(path)) return gone(merged);
-    const fate = await judge(session, merged);
+    const fate = await judge(session, merged, movedAway);
     // A removal that started while it read: read what it leaves.
     if (!removalRunning(path) && fs.existsSync(path)) return fate;
   }
@@ -133,8 +134,17 @@ async function commitsKeep(
   path: string,
   repo: string,
   session: Judged,
-  merged: MergedAs | null
+  merged: MergedAs | null,
+  movedAway = false
 ): Promise<string | null> {
+  // The task went on elsewhere: only commits no remote has would be lost.
+  if (movedAway) {
+    const stray = await strayCommits(path, {}).catch(() => null);
+    if (stray === null) return "its commits can't be checked";
+    return stray > 0
+      ? `${stray} commit${stray === 1 ? " is" : "s are"} on it that no remote has`
+      : null;
+  }
   if (merged) {
     const stray = await strayCommits(path, merged).catch(() => null);
     if (stray === null) return "its commits can't be checked";
@@ -163,7 +173,8 @@ async function commitsKeep(
 // kept one names every reason, the commits as well as the changes.
 async function judge(
   session: Judged,
-  merged: MergedAs | null
+  merged: MergedAs | null,
+  movedAway = false
 ): Promise<FatePreview> {
   const path = session.worktree_path!;
   const keep = (why: string) => ({ action: "kept" as const, why, path });
@@ -183,14 +194,16 @@ async function judge(
     unsaved.length
       ? `it has uncommitted changes (${describeChanges(unsaved)})`
       : null,
-    await commitsKeep(path, repo, session, merged),
+    await commitsKeep(path, repo, session, merged, movedAway),
   ].filter((w) => w !== null);
   if (why.length) return keep(why.join(", and "));
   return {
     action: "remove",
-    why: merged
-      ? "its branch is merged"
-      : "its branch has no commits of its own",
+    why: movedAway
+      ? "its work moved to another machine"
+      : merged
+        ? "its branch is merged"
+        : "its branch has no commits of its own",
     repo,
   };
 }
@@ -199,9 +212,10 @@ async function judge(
 // and says so only once it's really gone.
 export async function settleWorktree(
   session: Judged,
-  merged: MergedAs | null
+  merged: MergedAs | null,
+  movedAway = false
 ): Promise<WorktreeFate> {
-  const fate = await worktreeFate(session, merged);
+  const fate = await worktreeFate(session, merged, undefined, movedAway);
   if (fate.action !== "remove") return fate;
   const path = session.worktree_path!;
   await deleteWorktree(path, fate.repo, true).catch(() => {});

package/lib/hosts/remote-api.ts

@@ -70,6 +70,18 @@ export const cleanRemoteText = (s: unknown): string =>
     .trim()
     .slice(0, 300);
 
+/**
+ * Another machine's multi-line text (a chat's tail): control characters
+ * other than newline and tab become spaces, and the end is kept within `cap`.
+ */
+export const cleanRemoteBlock = (s: unknown, cap: number): string => {
+  const text = String(s ?? "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, " ")
+    .replace(/\s+$/, "");
+  return text.length > cap ? `…${text.slice(text.length - cap + 1)}` : text;
+};
+
 /**
  * Why a call failed. `refused`: that AgentOS answered and said no, so nothing
  * happened there. Otherwise the outcome is unknown (unreachable, timed out,

package/lib/lumifyhub/lists.ts

@@ -26,6 +26,7 @@ export function cardTargetFor(state: TaskState | "queued"): CardTarget {
       return "todo";
     case "working":
     case "needs-input":
+    case "plan-ready":
     case "blocked":
     case "moving":
       return "in_progress";

package/lib/models/plan-step.ts

@@ -19,20 +19,28 @@ import {
 } from "./resolve";
 import { ANTHROPIC } from "./roles";
 import { queueEvent } from "../orchestrator/events";
+import { addNote } from "../orchestrator/notes";
+import { amendBrief, amendmentsOf } from "../orchestrator/amendments";
 
 export const PLAN_FILE = ".agentos/plan.md";
 
-export function planPrompt(task: string): string {
+export function planPrompt(task: string, only = false): string {
+  const after = only
+    ? "it waits for approval before anything is implemented, so don't ask for it"
+    : "the implementation model takes over this conversation next and follows it";
   return `${task}
 
 ---
-Plan first. This turn, only read and plan: write the implementation plan for the task above to \`${PLAN_FILE}\` in this worktree (what to change, file by file; the tests; how you'll verify it; anything ambiguous and the call you'd make). Change no other file, and don't commit, push or open a PR. End the turn once the plan is written: the implementation model takes over this conversation next and follows it.`;
+Plan first. This turn, only read and plan: write the implementation plan for the task above to \`${PLAN_FILE}\` in this worktree (what to change, file by file; the tests; how you'll verify it; anything ambiguous and the call you'd make). Change no other file, and don't commit, push or open a PR. End the turn once the plan is written: ${after}.`;
 }
 
-export function implementPrompt(planned: boolean): string {
-  return planned
+export function implementPrompt(planned: boolean, amendment?: string): string {
+  const base = planned
     ? `The plan is in \`${PLAN_FILE}\`. Implement it now, finishing the task as its instructions above say. Where the plan turns out wrong, do what's right and say so.`
     : `No plan was written to \`${PLAN_FILE}\`. Plan briefly, then implement the task, finishing it as its instructions above say.`;
+  return amendment
+    ? `${base}\n\nThe plan was approved with this change, which is now part of the task's scope:\n${amendment}`
+    : base;
 }
 
 // The worktree's plan folder, kept out of git by its own .gitignore.
@@ -72,7 +80,7 @@ export function planSummary(text: string, max = 5): string[] {
 }
 
 // Tells the orchestrator that started a task its plan is written, once.
-function announcePlan(s: Session, ref: string): void {
+function announcePlan(s: Session, ref: string | null): void {
   if (!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
@@ -80,10 +88,13 @@ function announcePlan(s: Session, ref: string): void {
   if (!s.held_by_device && !workspaceId) return;
   if (!s.worktree_path) return;
   const file = path.join(s.worktree_path, PLAN_FILE);
-  let head = `Task "${s.name}": no plan file was written; implementing on ${ref} anyway.`;
+  const next = ref
+    ? `implementing on ${ref}`
+    : "waiting for approval, not implementing (approve_plan to go ahead, drop to reject)";
+  let head = `Task "${s.name}": no plan file was written; ${next}${ref ? " anyway" : ""}.`;
   try {
     const summary = planSummary(fs.readFileSync(file, "utf8"));
-    head = `Task "${s.name}": plan written to ${file}; implementing on ${ref}.`;
+    head = `Task "${s.name}": plan written to ${file}; ${next}.`;
     if (summary.length) head += `\n${summary.map((l) => `- ${l}`).join("\n")}`;
   } catch {
     // No plan file: the line says so.
@@ -101,56 +112,129 @@ function announcePlan(s: Session, ref: string): void {
 export const implementMessageId = (sessionId: string) =>
   `implement-${sessionId}`;
 
-// Called when a chat goes idle. A task whose plan turn has ended (it has a
-// recorded plan turn) moves to implementing, once, and the implementation
-// message is queued under a fixed id, which a restart sends rather than
-// repeats.
-export async function handoffAfterPlan(
-  sessionId: string,
-  send: (sessionId: string, id: string) => Promise<void>
-): Promise<boolean> {
-  const planned = db
-    .prepare(
-      `SELECT 1 FROM chat_turns WHERE session_id = ? AND role = 'plan' LIMIT 1`
-    )
-    .get(sessionId);
-  if (!planned) return false;
-  const s = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId) as
+type Send = (sessionId: string, id: string) => Promise<void>;
+
+function getSession(sessionId: string): Session | undefined {
+  return db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId) as
     | Session
     | undefined;
-  if (s?.plan_phase !== "planning" || !s.worktree_path) return false;
+}
+
+// Planning (or, once approved, awaiting) becomes implementing, once: the
+// phase, the model and the message in one go, so a restart part-way finds
+// either none of them or all, and sends the message on the new model. The
+// message goes under a fixed id, which a restart sends rather than repeats.
+async function startImplementing(
+  s: Session,
+  from: "planning" | "awaiting",
+  send: Send,
+  amendment?: string
+): Promise<string | null> {
+  const sessionId = s.id;
   const routed = resolveRole("implement", {
     workspaceId: sessionWorkspace(s),
     override: taskOverride(s),
   });
   const id = implementMessageId(sessionId);
-  // The phase, the model and the message in one go: a restart part-way
-  // finds either none of them or all, and sends the message on the new model.
   const claimed = db.transaction(() => {
     const changed = db
       .prepare(
         `UPDATE sessions SET plan_phase = 'implementing'
-         WHERE id = ? AND plan_phase = 'planning' AND task_status = 'running'`
+         WHERE id = ? AND plan_phase = ? AND task_status = 'running'`
       )
-      .run(sessionId).changes;
+      .run(sessionId, from).changes;
     if (!changed) return false;
     setSessionModel(sessionId, routed);
     enqueue(sessionId, {
       id,
       text: implementPrompt(
-        fs.existsSync(path.join(s.worktree_path!, PLAN_FILE))
+        fs.existsSync(path.join(s.worktree_path!, PLAN_FILE)),
+        amendment
       ),
       origin: { kind: "decision", label: "Plan step" },
     });
     return true;
   })();
-  if (!claimed) return false;
+  if (!claimed) return null;
+  if (from === "planning") {
+    try {
+      announcePlan(s, routed.ref);
+    } catch (e) {
+      console.error("plan-done event failed:", e);
+    }
+  }
+  await applySessionModel(sessionId, s.model_provider ?? ANTHROPIC, routed);
+  await send(sessionId, id);
+  return routed.ref;
+}
+
+// Called when a chat goes idle. A task whose plan turn has ended (it has a
+// recorded plan turn) moves to implementing, once; a plan-only task instead
+// waits for approval (approvePlan), holding no agent process.
+export async function handoffAfterPlan(
+  sessionId: string,
+  send: Send
+): Promise<boolean> {
+  const planned = db
+    .prepare(
+      `SELECT 1 FROM chat_turns WHERE session_id = ? AND role = 'plan' LIMIT 1`
+    )
+    .get(sessionId);
+  if (!planned) return false;
+  const s = getSession(sessionId);
+  if (s?.plan_phase !== "planning" || !s.worktree_path) return false;
+  if (!s.plan_only)
+    return (await startImplementing(s, "planning", send)) !== null;
+  const waiting = db
+    .prepare(
+      `UPDATE sessions SET plan_phase = 'awaiting'
+       WHERE id = ? AND plan_phase = 'planning' AND task_status = 'running'`
+    )
+    .run(sessionId).changes;
+  if (!waiting) return false;
   try {
-    announcePlan(s, routed.ref);
+    announcePlan(s, null);
   } catch (e) {
     console.error("plan-done event failed:", e);
   }
-  await applySessionModel(sessionId, s.model_provider ?? ANTHROPIC, routed);
-  await send(sessionId, id);
+  // The worker has nothing left to do: it ends at this turn boundary, and
+  // the next message (an approval, or a revision) starts one that resumes.
+  try {
+    await (await import("../chat/runner")).retireChat(sessionId);
+  } catch (e) {
+    console.error(`Releasing the worker of ${sessionId} failed:`, e);
+  }
   return true;
 }
+
+// approvePlan, sending through the chat runner (imported when needed: it
+// imports this file).
+export async function approvePlanNow(sessionId: string, message?: string) {
+  const { sendQueuedNow } = await import("../chat/runner");
+  return approvePlan(sessionId, message, (id, m) => sendQueuedNow(id, m));
+}
+
+// Approves a waiting plan-only task: implementation starts on the
+// implementation model, once. A message amends the plan and is recorded on
+// the task's brief as a scope change, before implementing, so its review
+// judges against it.
+export async function approvePlan(
+  sessionId: string,
+  message: string | undefined,
+  send: Send
+): Promise<{ ref: string; amendments: number }> {
+  const s = getSession(sessionId);
+  if (!s || s.plan_phase !== "awaiting" || s.task_status !== "running")
+    throw new Error(
+      `${s?.name ?? "That task"} isn't waiting for plan approval`
+    );
+  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}`);
+  }
+  const ref = await startImplementing(s, "awaiting", send, text);
+  if (!ref) throw new Error(`${s.name} isn't waiting for plan approval`);
+  return { ref, amendments: amendmentsOf(s.id).length };
+}

package/lib/models/roles.ts

@@ -97,5 +97,7 @@ export function sessionRole(session: {
   // 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" ? "plan" : "implement";
+  return session.plan_phase === "planning" || session.plan_phase === "awaiting"
+    ? "plan"
+    : "implement";
 }

package/lib/orchestrator/act.ts

@@ -33,6 +33,8 @@ import { treeOrder } from "../stacks/tree";
 import type { StackItemView } from "../stacks/types";
 import { doneSession } from "../done";
 import { amendBrief, amendmentsOf } from "./amendments";
+import type { Session } from "../db";
+import { approvePlanNow } from "../models/plan-step";
 import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
 import { addNote } from "./notes";
@@ -99,9 +101,12 @@ export async function startTask(
     after?: string;
     model?: ModelOverride;
     plan?: boolean;
+    planOnly?: boolean;
     planReason?: string;
   } = {}
 ): Promise<string> {
+  if (opts.planOnly && opts.plan === false)
+    throw new Error("plan_only implies plan; pass plan true");
   const project = workspaceProject(workspaceId, projectRef);
   const model = parseOverride(opts.model) ?? undefined;
   const startedBy = orchestratorId(workspaceId);
@@ -121,6 +126,7 @@ export async function startTask(
       view,
       model,
       plan: opts.plan,
+      planOnly: opts.planOnly,
       planReason: opts.planReason,
       startedBy,
       baseBranch: opts.base || undefined,
@@ -140,6 +146,7 @@ export async function startTask(
             view,
             model,
             plan: opts.plan,
+            planOnly: opts.planOnly,
             planReason: opts.planReason,
             startedBy,
           }),
@@ -151,11 +158,26 @@ export async function startTask(
     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 task = out.started;
+  const planOnlyNote = opts.planOnly
+    ? " Plan only: it stops after the plan and waits; approve_plan continues it, drop rejects it."
+    : "";
   const skipped =
-    opts.plan && task.plan_phase !== "planning"
+    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}`;
+  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}`;
+}
+
+// The orchestrator approves a plan-only task's plan; a message amends it.
+export async function approveTaskPlan(
+  task: Session,
+  message?: string
+): Promise<string> {
+  const out = await approvePlanNow(task.id, message);
+  const amended = message
+    ? ` Recorded as scope change ${out.amendments} on its brief: its review judges against it.`
+    : "";
+  return `Approved the plan of ${task.name}: implementing on ${out.ref}.${amended}`;
 }
 
 export async function startSession(

package/lib/orchestrator/brief.ts

@@ -41,6 +41,7 @@ You may act without asking on anything inside this workspace that's additive or
 Before you start work, decide what it needs, and hand it to the cheapest model that can do it.
 - Small and clear (a known change, a few files, nothing to discover): start_task with plan false and a plan_reason saying why. Write the steps into the prompt yourself, from what Saad or the card said; do not read code in your own context to do it.
 - Big, unclear or cross-cutting (many files, a design choice, unknown ground): start_task with plan true and a plan_reason. The planning model writes the plan, then the implementation model carries it out; you get one event with the plan file's path and a short summary when it is written.
+- Saad (or the card) says plan only, or you want to see a plan before any code is written: start_task with plan_only true (it implies plan true). It writes the plan and then stops: no implementation model, no implement prompt. You get one event with the plan file's path and a short summary saying it is waiting for approval. While it waits it isn't blocked and isn't idle; read the plan, then \`approve_plan\` (a message amends the plan and is recorded as a scope change, so the review judges against it) or \`drop\` it.
 - Not in a repository (research, a document, a machine task): start_session, which runs on the implementation model, with the steps in the prompt.
 - Implementation on Opus only when the work needs deep reasoning (a subtle concurrency or security change, say). Pass model and say why. Sonnet is the default.
 
@@ -102,7 +103,8 @@ Reading:
 Acting:
 - \`${TOOL_NAMES.send}\` (session, message, scope_change?): message a session; it arrives as its next prompt. scope_change records it on the task's brief for its review.
 - \`${TOOL_NAMES.message_orchestrator}\` (workspace, message): message another workspace's orchestrator, the only thing you reach outside this workspace. Use it to hand over a bug or ask for something in its projects; it decides what to do there.
-- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, model?, plan, plan_reason): a task in its own worktree that ends in a PR. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
+- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, model?, plan, plan_only?, plan_reason): a task in its own worktree that ends in a PR. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
+- \`${TOOL_NAMES.approve_plan}\` (task, message?): continue a plan_only task whose plan is ready; it implements on the implementation model, once. message amends the plan and is recorded on the task's brief as a scope change. Reject a plan with drop.
 - \`${TOOL_NAMES.set_task_model}\` (task, model, message?): move a paused task to another model and carry on in the same conversation and worktree; it keeps that model from then on. Only when Saad asks.
 - \`${TOOL_NAMES.start_session}\` (project, prompt, name?, view?, model?): a session without a worktree or PR, a chat unless view is terminal. It runs on the implementation model (Sonnet) unless you pass model; use it for work outside a repository, with the steps in the prompt.
 - \`${TOOL_NAMES.quick_change}\` (project, name): a worktree and branch cut from the project's default branch for a small, low-risk edit you make yourself: a typo, a config value, a one-file fix. It returns the worktree's path; edit there with Write and Edit, and run git there only as \`git -C <path> <status|diff|log|show|add|rm|mv|restore|reset>\`. Anything that needs real work, tests or a long investigation is a task: start_task. At most a few open at once.

package/lib/orchestrator/conditions.ts

@@ -135,6 +135,7 @@ function sessionConditions(
     shouldPR &&
     !pr &&
     !finished &&
+    !f.plan?.awaiting &&
     f.status !== "running" &&
     idleFor >= IDLE_NO_PR_MS
   )

package/lib/orchestrator/describe.ts

@@ -39,7 +39,7 @@ function sessionLine(f: SessionFacts): string {
   }
   if (f.plan)
     parts.push(
-      `${f.plan.planned ? "planned" : "no plan"}${f.plan.reason ? `: ${untrusted(f.name, f.plan.reason)}` : ""}`
+      `${f.plan.awaiting ? "plan ready, awaiting your approve_plan" : f.plan.planned ? "planned" : "no plan"}${f.plan.reason ? `: ${untrusted(f.name, f.plan.reason)}` : ""}`
     );
   if (f.stack) {
     const card = f.stack.ticket ? ` ${f.stack.ticket}` : "";

package/lib/orchestrator/facts.ts

@@ -50,7 +50,12 @@ export interface SessionFacts {
   // A quick change the orchestrator makes itself (quick.ts): no agent.
   quick?: boolean;
   // The orchestrator's call on a plan step, with its reason, when stated.
-  plan?: { planned: boolean; reason: string | null } | null;
+  plan?: {
+    planned: boolean;
+    reason: string | null;
+    // A plan-only task's plan is written; it waits for approve_plan.
+    awaiting?: boolean;
+  } | null;
   task: {
     state: TaskState;
     pr: TaskPR | null;
@@ -344,7 +349,11 @@ export async function sessionFacts(
         plan:
           s.plan_decided == null
             ? null
-            : { planned: !!s.plan_decided, reason: s.plan_reason ?? null },
+            : {
+                planned: !!s.plan_decided,
+                reason: s.plan_reason ?? null,
+                awaiting: s.plan_phase === "awaiting",
+              },
         task,
         stack: stackOf(s.id),
       };

package/lib/orchestrator/serve.ts

@@ -2,6 +2,7 @@ import { resumeOnModel } from "../models/resume";
 import { workspaceTask } from "./targets";
 import { getWorkspace } from "../workspaces";
 import {
+  approveTaskPlan,
   done,
   drop,
   moveTaskTo,
@@ -48,6 +49,7 @@ const ACTING = new Set<ToolName>([
   "land",
   "drop",
   "move",
+  "approve_plan",
   "stop",
   "done",
   "review",
@@ -114,9 +116,15 @@ export async function runTool(
         after: a.after,
         model: a.model,
         plan: a.plan,
+        planOnly: a.plan_only,
         planReason: a.plan_reason,
       });
     }
+    case "approve_plan": {
+      const a = p(tool, raw);
+      const task = workspaceTask(w, a.task);
+      return approveTaskPlan(task, a.message);
+    }
     case "set_task_model": {
       const a = p(tool, raw);
       const task = workspaceTask(w, a.task);

package/lib/orchestrator/task-state.ts

@@ -9,6 +9,7 @@ import { blockedReason } from "../tasks/state";
 import { checkWaitingPatterns, statusDetector } from "../status-detector";
 import { getCheck, putCheck } from "./checks";
 import { cleanRemoteText, hostLink, type HostLink } from "../hosts/remote-api";
+import { heldChatFacts } from "../tasks/held-remote";
 import { hostTasks } from "../tasks/remote";
 import { peerPane } from "../hosts/peer-sessions";
 import { untrusted } from "./untrusted";
@@ -24,21 +25,7 @@ export async function waitingState(
   // its own reading of the task is asked for, fresh.
   const link = hostLink(task.host_id);
   if (link && task.view === "chat") return peerChatWaiting(link, task);
-  if (task.view === "chat") {
-    const reason = blockedReason(saidSinceLastMessage(task.id));
-    // Asked of a worker still running from before a restart, too; one
-    // that can't be reached can't be cleared.
-    const state = await chatStateNow(task.id).catch(() => "unknown");
-    return {
-      blocked: reason === null ? null : untrusted(task.name, reason),
-      waitingOn:
-        state === "waiting"
-          ? "an approval or question in its chat"
-          : state === "unknown"
-            ? "its chat worker couldn't be reached, so an open approval or question can't be ruled out"
-            : null,
-    };
-  }
+  if (task.view === "chat") return localChatWaiting(task);
   // A linked machine reads its own screens: asked, and an answer it can't
   // give is a screen that can't be cleared.
   let tail: string;
@@ -71,6 +58,26 @@ export async function waitingState(
   };
 }
 
+// A chat task whose conversation is in this machine's store (or, for a held
+// task, the one the holder asks about).
+export async function localChatWaiting(
+  task: Pick<Session, "id" | "name">
+): Promise<{ blocked: string | null; waitingOn: string | null }> {
+  const reason = blockedReason(saidSinceLastMessage(task.id));
+  // Asked of a worker still running from before a restart, too; one
+  // that can't be reached can't be cleared.
+  const state = await chatStateNow(task.id).catch(() => "unknown");
+  return {
+    blocked: reason === null ? null : untrusted(task.name, reason),
+    waitingOn:
+      state === "waiting"
+        ? "an approval or question in its chat"
+        : state === "unknown"
+          ? "its chat worker couldn't be reached, so an open approval or question can't be ruled out"
+          : null,
+  };
+}
+
 async function peerChatWaiting(
   link: HostLink,
   task: Session
@@ -79,6 +86,24 @@ async function peerChatWaiting(
     blocked: `its chat on ${link.hostName} couldn't be read, so a BLOCKED: line or open question can't be ruled out`,
     waitingOn: null,
   };
+  // A task its orchestrator moved is asked about directly: the whole task
+  // list is slow, and a miss there reads as unread.
+  const facts = task.started_by ? await heldChatFacts(task) : null;
+  if (facts) {
+    const { turn } = facts;
+    return {
+      blocked: facts.blocked ? untrusted(task.name, facts.blocked) : null,
+      waitingOn:
+        turn === "waiting"
+          ? `an approval or question in its chat on ${link.hostName}`
+          : turn === null ||
+              turn === "running" ||
+              turn === "idle" ||
+              turn === "error"
+            ? null
+            : `its chat on ${link.hostName} couldn't say whether a question is open`,
+    };
+  }
   const view = await hostTasks(link, true)
     .then(({ tasks, capabilities }) =>
       // One that can't say its chat's turn can't rule out an open question.

package/lib/orchestrator/tool-names.ts

@@ -22,6 +22,7 @@ export const TOOL_NAMES = {
   stack: name("stack"),
   stack_status: name("stack_status"),
   land: name("land"),
+  approve_plan: name("approve_plan"),
   drop: name("drop"),
   move: name("move"),
   stop: name("stop"),

package/lib/orchestrator/tool-schemas.ts

@@ -121,6 +121,12 @@ export const TOOL_SHAPES = {
       .describe(
         "Your decision for this job: true to plan first on the planning model, then implement on the implementation model; false to skip the plan and put the steps in the prompt yourself"
       ),
+    plan_only: z
+      .boolean()
+      .optional()
+      .describe(
+        "true: write the plan on the planning model, then stop and wait; implementation starts only when you approve_plan it (drop rejects it). Implies plan true"
+      ),
     plan_reason: z
       .string()
       .trim()
@@ -192,6 +198,18 @@ export const TOOL_SHAPES = {
   },
   stack_status: { id: stackId },
   land: { id: stackId },
+  approve_plan: {
+    task,
+    message: z
+      .string()
+      .trim()
+      .min(1)
+      .max(8000)
+      .optional()
+      .describe(
+        "Amends the plan: recorded on the task's brief as a scope change, so its review judges the PR against it. Only for a change Saad made"
+      ),
+  },
   drop: { task, reason: z.string().trim().min(1).max(2000) },
   move: {
     task,

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). 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 true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. 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). 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. 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:
@@ -75,6 +75,8 @@ const DESCRIPTIONS: Record<ToolName, string> = {
     "Run a LumifyHub board's open cards as stacked tasks (each start braked), or with plan_only just show the plan.",
   stack_status: "One stack's items, PRs and progress.",
   land: "Merge a whole stack bottom-up, each PR through the sign-off gates at its current head.",
+  approve_plan:
+    'Approve the plan of a plan_only task that is waiting ("plan ready"): it continues on the implementation model, once. An optional message amends the plan and is recorded on the task\'s brief as a scope change. Reject a plan with drop.',
   drop: "Reject a task: close its PR and remove its worktree. A task still waiting in the queue is removed by its id. Logged with the reason.",
   move: 'Carry a running task to a linked machine, or back with "here": for heavy test or build work. It keeps its branch, conversation and plan; the gates, events, read, send, stop, done and drop work the same wherever it runs, and the machine it lands on can\'t merge it. Takes a few minutes and runs in the background; an event says when it lands. Refused while paused, for a task waiting on Saad (an escalation or open ask), and for card and stacked tasks.',
   stop: "Stop a session's agent mid-turn, even while it's thinking, keeping its conversation, worktree and branch; your next message runs as its next turn.",

package/lib/security/demo.ts

@@ -56,6 +56,7 @@ export const STATIC_SIBLINGS = [
   "clone",
   "detect",
   "done-idle",
+  "held-replies",
   "import",
   "init",
   "init-script",