@saadnvd1/agent-os 0.3.631 → 0.3.637

package/app/api/tasks/[id]/approve-plan/route.ts

@@ -1,5 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import { approvePlanNow } from "@/lib/models/plan-step";
+import { callingDevice } from "@/lib/security/device-me";
+import { planWaitRefusal } from "@/lib/tasks/held";
 
 // Approves a plan-only task's plan: it continues on the implementation
 // model. An optional message amends the plan (recorded as a scope change).
@@ -7,13 +9,16 @@ export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
+  const id = (await params).id;
+  const refusal = planWaitRefusal(id, callingDevice(request));
+  if (refusal) return NextResponse.json({ error: refusal }, { status: 403 });
   try {
     const body = await request.json().catch(() => ({}));
     const message =
       typeof body?.message === "string" && body.message.trim()
         ? body.message.trim().slice(0, 8000)
         : undefined;
-    const out = await approvePlanNow((await params).id, message);
+    const out = await approvePlanNow(id, message);
     return NextResponse.json({ success: true, model: out.ref });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/app/api/tasks/[id]/export/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import { exportOrResume } from "@/lib/tasks/move";
 import { callingDevice } from "@/lib/security/device-me";
-import { heldRefusal } from "@/lib/tasks/held";
+import { heldRefusal, planWaitRefusal } from "@/lib/tasks/held";
 
 // POST /api/tasks/:id/export - stop the agent, push, hand over the task.
 // The caller confirms with /moved, or restarts it here with /resume; if it
@@ -11,7 +11,8 @@ export async function POST(
   { params }: { params: Promise<{ id: string }> }
 ) {
   const id = (await params).id;
-  const held = heldRefusal(id, callingDevice(request));
+  const device = callingDevice(request);
+  const held = heldRefusal(id, device) ?? planWaitRefusal(id, device);
   if (held) return NextResponse.json({ error: held }, { status: 403 });
   try {
     const { to } = await request.json().catch(() => ({}));

package/app/api/tasks/[id]/plan/route.ts

@@ -0,0 +1,37 @@
+import fs from "fs/promises";
+import path from "path";
+import { NextRequest, NextResponse } from "next/server";
+import { db, type Session } from "@/lib/db";
+import { callingDevice } from "@/lib/security/device-me";
+import { heldRefusal, planWaitRefusal } from "@/lib/tasks/held";
+import { MAX_PLAN_BYTES } from "@/lib/tasks/move-bundle";
+import { PLAN_FILE } from "@/lib/models/plan-step";
+import { expandHome } from "@/lib/tasks/session";
+
+// GET /api/tasks/:id/plan - the plan file of a task whose plan is written, for
+// the machine that placed the plan here and decides what follows it.
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const id = (await params).id;
+  const device = callingDevice(request);
+  const refusal = heldRefusal(id, device) ?? planWaitRefusal(id, device);
+  if (refusal) return NextResponse.json({ error: refusal }, { status: 403 });
+  const s = db
+    .prepare(`SELECT plan_phase, worktree_path FROM sessions WHERE id = ?`)
+    .get(id) as Pick<Session, "plan_phase" | "worktree_path"> | undefined;
+  if (!s?.worktree_path)
+    return NextResponse.json({ error: "No such task" }, { status: 404 });
+  let text: string | null = null;
+  try {
+    const read = await fs.readFile(
+      path.join(expandHome(s.worktree_path), PLAN_FILE),
+      "utf8"
+    );
+    text = read.length > MAX_PLAN_BYTES ? read.slice(0, MAX_PLAN_BYTES) : read;
+  } catch {
+    // No plan file was written.
+  }
+  return NextResponse.json({ text, phase: s.plan_phase ?? null });
+}

package/app/api/tasks/route.ts

@@ -46,6 +46,7 @@ export async function POST(request: NextRequest) {
       plan,
       plan_reason,
       plan_only,
+      plan_waits,
       priority,
       machine,
       orchestrated,
@@ -76,7 +77,7 @@ export async function POST(request: NextRequest) {
           ? model
           : (parseOverride(model) ?? undefined),
       plan: typeof plan === "boolean" ? plan : undefined,
-      planOnly: plan_only === true ? true : undefined,
+      planOnly: plan_only === true || plan_waits === true ? true : undefined,
       planReason:
         typeof plan_reason === "string" && plan_reason.trim()
           ? plan_reason.trim().slice(0, 200)
@@ -107,6 +108,8 @@ export async function POST(request: NextRequest) {
         id,
         ...opts,
         held,
+        // Another machine's plan stops for it to decide what follows.
+        planWaits: plan_waits === true && !!device ? true : undefined,
         startedVia: "remote",
         startedByDevice: device ?? undefined,
       });

package/app/globals.css

@@ -110,6 +110,34 @@
     0 0 0 4px hsl(var(--primary) / 0.15);
 }
 
+/* One look for every link in the chat feed: it reacts to hover, keyboard focus
+   and touch (:active), since a phone has no hover. */
+@utility chat-link {
+  cursor: pointer;
+  overflow-wrap: anywhere;
+  border-radius: 0.125rem;
+  text-decoration-line: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+  transition:
+    color 120ms,
+    background-color 120ms,
+    text-decoration-thickness 120ms;
+  &:hover {
+    color: hsl(var(--primary));
+    background-color: hsl(var(--primary) / 0.1);
+    text-decoration-thickness: 2px;
+  }
+  &:active {
+    color: hsl(var(--primary));
+    background-color: hsl(var(--primary) / 0.2);
+  }
+  &:focus-visible {
+    outline: 2px solid hsl(var(--ring));
+    outline-offset: 2px;
+  }
+}
+
 @utility label-mono {
   font-family: var(--font-geist-mono);
   font-size: 0.6875rem;

package/components/Chat/ChatPanel.tsx

@@ -62,7 +62,7 @@ import { NeedsYouStrip } from "@/components/Orchestrator/NeedsYouStrip";
 import { useResolveQuestion } from "@/data/orchestrators";
 import { needsYouFocus, needsYouFocusActions } from "@/stores/needsYouFocus";
 import { hrefWithSession } from "@/lib/session-url";
-import { isQuestionTool } from "@/lib/chat/turns";
+import { questionSource } from "@/lib/chat/turns";
 import { useViewport } from "@/hooks/useViewport";
 import { useChatCommands } from "./useChatCommands";
 import { copySelection } from "./copy-selection";
@@ -751,16 +751,7 @@ export function ChatPanel({
                   )
                 );
                 window.dispatchEvent(new PopStateEvent("popstate"));
-              } else
-                goTo((all) => {
-                  const asked = all.findLast(
-                    (i) =>
-                      isQuestionTool(i) &&
-                      (i as { input?: { text?: string } }).input?.text ===
-                        item.question.text
-                  );
-                  return asked?.id ?? null;
-                });
+              } else goTo((all) => questionSource(all, item.question.text));
             }}
             onReply={(item) => {
               setReplyTo({ id: item.question.id, text: item.question.text });

package/components/Chat/EventTurns.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import type { ReactNode } from "react";
-import { ChevronRight, Loader2, MessageCircleQuestion } from "lucide-react";
+import { ChevronRight, Loader2 } from "lucide-react";
 import type { ChatItem } from "@/lib/chat/events";
 import type { EventTurn } from "@/lib/chat/turns";
 import { cn } from "@/lib/utils";
@@ -60,12 +60,6 @@ export function EventTurnRow({
         <span className="text-foreground/80 max-w-[40%] min-w-0 shrink-0 truncate font-medium">
           {turn.task}
         </span>
-        {turn.hasQuestion && (
-          <MessageCircleQuestion
-            className="h-3.5 w-3.5 shrink-0 text-amber-600 dark:text-amber-400"
-            aria-label="Asked a question"
-          />
-        )}
         <span className="min-w-0 flex-1 truncate">{turn.summary}</span>
         {turn.live && (
           <Loader2

package/components/Chat/Markdown.tsx

@@ -49,6 +49,7 @@ const components: Components = {
           href={local ? imageUrl(href) : href}
           target="_blank"
           rel="noreferrer"
+          className="chat-link"
         >
           {children}
         </a>

package/components/Chat/Messages.tsx

@@ -42,7 +42,7 @@ function UserLink({ href }: { href: string }) {
       target={id ? undefined : "_blank"}
       rel={id ? undefined : "noopener noreferrer"}
       onClick={id ? (e) => openSessionLink(e, id) : undefined}
-      className="font-medium [overflow-wrap:anywhere] underline underline-offset-2"
+      className="chat-link font-medium"
     >
       {href}
     </a>

package/lib/approvals/enable.ts

@@ -2,6 +2,7 @@
 // brings what already exists in line with it.
 
 import { db } from "../db";
+import { isRemoteHost } from "../hosts";
 import { reapplyChatModes } from "../chat/settings";
 import { approvePlanNow } from "../models/plan-step";
 import { autoApproveAsk, type AskRow } from "../orchestrator/asks";
@@ -28,10 +29,16 @@ async function sweep(): Promise<void> {
   }
   const plans = db
     .prepare(
-      `SELECT id FROM sessions WHERE plan_phase = 'awaiting' AND task_status = 'running'`
+      `SELECT id, host_id, plan_waits_for_caller FROM sessions WHERE plan_phase = 'awaiting' AND task_status = 'running'`
     )
-    .all() as { id: string }[];
+    .all() as {
+    id: string;
+    host_id: string;
+    plan_waits_for_caller: number | null;
+  }[];
   for (const p of plans) {
+    // A plan placed here by another machine is that machine's to decide.
+    if (p.plan_waits_for_caller && !isRemoteHost(p.host_id)) continue;
     try {
       await approvePlanNow(p.id, undefined, "no-approvals");
     } catch (e) {

package/lib/chat/events.ts

@@ -149,6 +149,10 @@ export type ChatItem =
       // Saved since messages were tagged where they're sent: without an
       // origin, the reader typed it. Older items are matched by their text.
       tagged?: true;
+      // Whether it was sent while a turn ran: the agent then reads it once
+      // that turn ends, so what follows until then is still that turn's.
+      // Always set when saved; absent only on history from before it was.
+      midTurn?: boolean;
       // The provider's id for this message, to undo file changes back to it.
       checkpoint?: string;
     })

package/lib/chat/group.ts

@@ -1,4 +1,5 @@
 import type { ChatItem } from "./events";
+import { readingOrder } from "./reading-order";
 import { eventTurnAt, type EventTurn } from "./turns";
 
 export type ToolItem = Extract<ChatItem, { kind: "tool" }>;
@@ -23,9 +24,10 @@ export const STANDALONE_TOOLS = new Set(["Skill", "Task", "Agent"]);
 // collapsible block, so a long turn reads as what was said, not every step.
 // Undone messages fold into one block behind the undo that took them back.
 export function groupTimeline(
-  items: ChatItem[],
+  all: ChatItem[],
   opts: GroupOptions = {}
 ): TimelineBlock[] {
+  const items = opts.foldEvents ? readingOrder(all) : all;
   const blocks: TimelineBlock[] = [];
   let tools: ToolItem[] = [];
   const flush = () => {

package/lib/chat/reading-order.ts

@@ -0,0 +1,50 @@
+import type { ChatItem } from "./events";
+import { activityOrigin } from "./turns";
+
+// Activity sent while a turn runs is saved when sent but read by the agent
+// once that turn ends. It moves to after the turn's end, so the turn a
+// person's message started stays whole and the activity gets its own reply.
+//
+// Several waiting at one turn's end are taken a turn each: the first starts
+// after the end, the next after the following one. Whether the agent
+// answers them together or apart isn't recorded, and this way a turn each
+// keeps every reply with its own event; answered together, the first takes
+// the reply and the rest show as bare rows.
+//
+// A message saved with `midTurn` is trusted either way. Only history from
+// before the field is guessed, from whether a turn was open when it landed.
+export function readingOrder(items: ChatItem[]): ChatItem[] {
+  const out: ChatItem[] = [];
+  const waiting: ChatItem[] = [];
+  let open = false;
+  let moved = false;
+  const release = () => out.push(...waiting.splice(0));
+  for (const item of items) {
+    if (item.kind === "user") {
+      const waits = item.midTurn === undefined ? open : item.midTurn;
+      if (waits && activityOrigin(item)) {
+        waiting.push(item);
+        moved = true;
+        continue;
+      }
+      release();
+      out.push(item);
+      open = true;
+    } else if (item.kind === "turn_end") {
+      out.push(item);
+      open = false;
+      const next = waiting.shift();
+      if (next) out.push(next);
+    } else if (
+      item.kind === "undo" ||
+      item.kind === "error" ||
+      item.kind === "command_output"
+    ) {
+      release();
+      out.push(item);
+      open = false;
+    } else out.push(item);
+  }
+  release();
+  return moved ? out : items;
+}

package/lib/chat/turns.ts

@@ -18,8 +18,6 @@ export interface EventTurn {
   at: number;
   // Still being answered.
   live: boolean;
-  // The reply opened a question for the reader.
-  hasQuestion: boolean;
 }
 
 const FOLDED_KINDS = new Set(["event", "peer", "schedule", "system"]);
@@ -39,6 +37,26 @@ export function activityOrigin(item: UserItem): ChatOrigin | null {
 export const isQuestionTool = (item: ChatItem): boolean =>
   item.kind === "tool" && /(^|__)question$/.test(item.name);
 
+export const isAskTool = (item: ChatItem): boolean =>
+  item.kind === "tool" && /(^|__)ask_saad$/.test(item.name);
+
+// The assistant message a question was asked in (its turn's last words
+// before the call), else the call itself.
+export function questionSource(items: ChatItem[], text: string): string | null {
+  const at = items.findLastIndex(
+    (i) =>
+      isQuestionTool(i) &&
+      (i as { input?: { text?: string } }).input?.text === text
+  );
+  if (at === -1) return null;
+  for (let i = at - 1; i >= 0; i--) {
+    const item = items[i];
+    if (item.kind === "user" || item.kind === "turn_end") break;
+    if (item.kind === "assistant" && item.text.trim()) return item.id;
+  }
+  return items[at].id;
+}
+
 export function plainSummary(text: string, max = 140): string {
   const line =
     text
@@ -89,6 +107,8 @@ export function eventTurnAt(
     (i) =>
       i.kind === "plan" ||
       i.kind === "error" ||
+      isQuestionTool(i) ||
+      isAskTool(i) ||
       (i.kind === "approval" && i.status === "pending")
   );
   if (needsReader) return null;
@@ -105,7 +125,6 @@ export function eventTurnAt(
       task: taskName(origin),
       at: user.createdAt,
       live: !ended && end >= items.length,
-      hasQuestion: replies.some(isQuestionTool),
     },
   };
 }

package/lib/chat/worker/host.ts

@@ -564,6 +564,8 @@ export class ChatHost {
     this.sent.add(m.id);
     this.currentTurn = m.id;
     this.hardStopAt = 0;
+    // A message sent now stops the turn and is read next: nothing waits.
+    const midTurn = this.busy() && !now;
     if (this.busy()) this.behind++;
     // Sent now, it stops the running turn, which still ends after this.
     if (!this.busy()) now = false;
@@ -599,6 +601,7 @@ export class ChatHost {
       peer: m.peer,
       origin: m.origin,
       tagged: true as const,
+      midTurn,
       createdAt: Date.now(),
       checkpoint,
     };

package/lib/db/migrations/20261015T1600_plan_waits_for_caller.ts

@@ -0,0 +1,19 @@
+import type { Migration } from "../migration-types";
+
+export default {
+  key: "20261015T1600_plan_waits_for_caller",
+  up: (db) => {
+    // A plan another machine placed here: it stops at the plan for that
+    // machine to decide what comes next. On the machine that placed it, the
+    // approval's message waits for the move home. Additive.
+    const add = (col: string, type: string) => {
+      const columns = db.prepare(`PRAGMA table_info(sessions)`).all() as {
+        name: string;
+      }[];
+      if (!columns.some((c) => c.name === col))
+        db.exec(`ALTER TABLE sessions ADD COLUMN ${col} ${type}`);
+    };
+    add("plan_waits_for_caller", "INTEGER");
+    add("plan_handoff_message", "TEXT");
+  },
+} satisfies Migration;

package/lib/db/types.ts

@@ -20,7 +20,7 @@ export interface Session {
   model_overrides?: string | null;
   // A task's plan step: planning on the planning model, then implementing.
   // 'awaiting': a plan-only task's plan is written; it waits for approval.
-  plan_phase?: "planning" | "awaiting" | "implementing" | null;
+  plan_phase?: "planning" | "awaiting" | "handoff" | "implementing" | null;
   plan_only?: number | null;
   // The orchestrator session that started this one; null for a person.
   started_by?: string | null;
@@ -156,6 +156,11 @@ export interface Session {
   held_for_name?: string | null;
   // A held task's "plan written" line, for its orchestrator to read.
   plan_note?: string | null;
+  // The task's plan stops for the machine that placed it here to decide what
+  // comes next (1); on that machine's mirror, the approval's message waits for
+  // the move home.
+  plan_waits_for_caller?: number | null;
+  plan_handoff_message?: string | null;
   // Orchestration fields
   conductor_session_id: string | null;
   worker_task: string | null;

package/lib/env-setup.ts

@@ -8,6 +8,7 @@
 
 import * as fs from "fs";
 import * as path from "path";
+import { gitOk } from "./git-exec";
 import { bringDependencies, runCommand } from "./worktree-deps";
 import { inside, realExisting } from "./worktree-deps/paths";
 import { seedBuildCaches } from "./worktree-deps/caches";
@@ -40,16 +41,20 @@ export interface SetupResult {
   durationMs: number;
 }
 
+// A gitignored CLAUDE.md holds the project's private notes. Only one the
+// worktree confirms is ignored is copied: any other would be committable.
+const PRIVATE_NOTES = "CLAUDE.md";
+
 /**
- * Find env files to copy (excludes .env.example)
+ * Find env files to copy (excludes .env.example), and the private notes
  */
 export function findEnvFiles(projectPath: string): string[] {
   try {
     const files = fs.readdirSync(projectPath);
     return files.filter(
       (f) =>
-        f.startsWith(".env") &&
-        !f.endsWith(".example") &&
+        ((f.startsWith(".env") && !f.endsWith(".example")) ||
+          f === PRIVATE_NOTES) &&
         fs.statSync(path.join(projectPath, f)).isFile()
     );
   } catch {
@@ -58,7 +63,7 @@ export function findEnvFiles(projectPath: string): string[] {
 }
 
 /**
- * Copy env files from source to worktree
+ * Copy env files (and the private CLAUDE.md) from source to worktree
  */
 export async function copyEnvFiles(
   sourcePath: string,
@@ -71,6 +76,14 @@ export async function copyEnvFiles(
     try {
       const src = path.join(sourcePath, file);
       const dest = path.join(worktreePath, file);
+      const there = await fs.promises.lstat(dest).catch(() => null);
+      if (file === PRIVATE_NOTES) {
+        if (there || !(await gitOk(worktreePath, ["check-ignore", "-q", file])))
+          continue;
+      } else if (there?.isSymbolicLink()) {
+        // Never written through: a committed link could point outside.
+        await fs.promises.unlink(dest);
+      }
       await fs.promises.copyFile(src, dest);
       copied.push(file);
     } catch (error) {

package/lib/models/plan-step.ts

@@ -24,6 +24,7 @@ import { addNote } from "../orchestrator/notes";
 import { amendBrief, scopeChangesOf } from "../orchestrator/amendments";
 import { PIECES_PROMPT, foldedBrief, pieceBrief } from "../plans/pieces";
 import { orchestratorOf } from "../tasks/starter";
+import { isRemoteHost } from "../hosts";
 import { refreshBase } from "../tasks/refresh-base";
 import {
   createFeature,
@@ -121,8 +122,35 @@ function piecesLine(r: NonNullable<ReturnType<typeof planFor>>): string {
   return `${r.pieces.length} pieces${folded}: ${parts.join("; ")}`;
 }
 
+// The "plan written" line for a task: where the plan is, what comes next,
+// its first lines and how it split. `file` is where this machine can read it.
+export function planNoteFor(
+  s: Session,
+  file: string,
+  next: string,
+  again = "",
+  after = ""
+): string {
+  let head = `Task "${s.name}": no plan file was written${again}; ${next}${after}.`;
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    const summary = planSummary(text);
+    head = `Task "${s.name}": plan written to ${file}; ${next}.`;
+    if (summary.length) head += `\n${summary.map((l) => `- ${l}`).join("\n")}`;
+    const pieces = planFor(s, text);
+    if (pieces && pieces.pieces.length > 1) head += `\n${piecesLine(pieces)}`;
+    if (pieces?.folded.length)
+      head += `\nPlan listed ${pieces.listed} pieces, building ${pieces.pieces.length}: ${pieces.folded.map((f) => `${f.name} folded (${f.why})`).join("; ")}`;
+  } catch {
+    // No plan file: the line says so.
+  }
+  return head;
+}
+
 // Tells the orchestrator that started a task its plan is written, once.
 function announcePlan(s: Session, ref: string | null, retried = false): void {
+  // The machine that placed it announces the plan, from its own copy.
+  if (s.plan_waits_for_caller) return;
   if (!orchestratorOf(s.started_by) && !s.held_by_device) return;
   const workspaceId = sessionWorkspace(s);
   // A task held for another machine's orchestrator can't reach it: the line
@@ -134,18 +162,7 @@ function announcePlan(s: Session, ref: string | null, retried = false): void {
     ? `implementing on ${ref}`
     : "waiting for approval, not implementing (approve_plan to go ahead, drop to reject)";
   const again = retried ? " (asked once more for it first)" : "";
-  let head = `Task "${s.name}": no plan file was written${again}; ${next}${ref ? " anyway" : ""}.`;
-  try {
-    const summary = planSummary(fs.readFileSync(file, "utf8"));
-    head = `Task "${s.name}": plan written to ${file}; ${next}.`;
-    if (summary.length) head += `\n${summary.map((l) => `- ${l}`).join("\n")}`;
-    const pieces = planFor(s, fs.readFileSync(file, "utf8"));
-    if (pieces && pieces.pieces.length > 1) head += `\n${piecesLine(pieces)}`;
-    if (pieces?.folded.length)
-      head += `\nPlan listed ${pieces.listed} pieces, building ${pieces.pieces.length}: ${pieces.folded.map((f) => `${f.name} folded (${f.why})`).join("; ")}`;
-  } catch {
-    // No plan file: the line says so.
-  }
+  const head = planNoteFor(s, file, next, again, ref ? " anyway" : "");
   if (s.held_by_device) {
     db.prepare(`UPDATE sessions SET plan_note = ? WHERE id = ?`).run(
       head,
@@ -244,7 +261,10 @@ async function startImplementing(
     ? undefined
     : fresh.note &&
       `Note: ${fresh.note}. Rebase onto the latest base before you open the PR.`;
-  let split = planText ? splitOf(s, planText) : null;
+  // A plan another machine placed here was checked there, against its
+  // projects; this one's workspace doesn't know them.
+  let split =
+    planText && !s.plan_waits_for_caller ? splitOf(s, planText) : null;
   const workspaceId = sessionWorkspace(s);
   // Approved despite pieces that couldn't be registered: built as one piece,
   // and told so, rather than guessing which repository each belongs to.
@@ -441,9 +461,12 @@ export async function handoffAfterPlan(
   forget(sessionId);
   // No approvals mode doesn't stop at the plan to wait for one. Pieces that
   // couldn't be registered always do: building on a guess is the bug.
-  const auto = !!s.plan_only && noApprovalsOn();
+  const auto = !!s.plan_only && noApprovalsOn() && !s.plan_waits_for_caller;
   const planText = readPlan(s);
-  const pieceErrors = (planText ? splitOf(s, planText)?.errors : null) ?? [];
+  const pieceErrors =
+    (planText && !s.plan_waits_for_caller
+      ? splitOf(s, planText)?.errors
+      : null) ?? [];
   if ((!s.plan_only || auto) && !pieceErrors.length) {
     const ref = await startImplementing(
       s,
@@ -482,14 +505,17 @@ export async function handoffAfterPlan(
       s.id,
       `Plan of "${s.name}": couldn't register its pieces: ${pieceErrors.join("; ")}. It is held, not building. Message the task to fix the plan, or approve_plan to build it as one piece.`
     );
+  // The machine that placed a plan sends its own push.
   try {
-    const text = readPlan(s);
-    const planned = text ? planFor(s, text) : null;
-    (await import("../notify/push/events")).pushPlanAwaiting(
-      s.id,
-      s.name,
-      planned?.pieces.length ?? 1
-    );
+    if (!s.plan_waits_for_caller) {
+      const text = readPlan(s);
+      const planned = text ? planFor(s, text) : null;
+      (await import("../notify/push/events")).pushPlanAwaiting(
+        s.id,
+        s.name,
+        planned?.pieces.length ?? 1
+      );
+    }
   } catch (e) {
     console.error("plan push failed:", e);
   }
@@ -560,9 +586,12 @@ export async function approvePlan(
     );
   const text = message?.trim() || undefined;
   const workspaceId = sessionWorkspace(s);
+  // A plan another machine placed here is approved by that machine, which
+  // keeps the brief its review reads.
+  const placedHere = !!s.plan_waits_for_caller && !isRemoteHost(s.host_id);
   // Every approval is on the brief, so the review judges the PR as the
   // implementation of the plan, not as plan-only work.
-  if (workspaceId) {
+  if (workspaceId && !placedHere) {
     if (text) {
       amendBrief(workspaceId, s.id, text);
       addNote(
@@ -571,7 +600,11 @@ export async function approvePlan(
       );
     } else amendBrief(workspaceId, s.id, APPROVAL_TEXT[by], "approval");
   }
-  const ref = await startImplementing(s, "awaiting", send, text);
+  // On another machine, the plan was written there: this machine decides
+  // where it is built, and the approval follows it.
+  const ref = isRemoteHost(s.host_id)
+    ? await (await import("../tasks/remote-plan")).continueRemotePlan(s, text)
+    : await startImplementing(s, "awaiting", send, text);
   if (!ref) throw new Error(`${s.name} isn't waiting for plan approval`);
   if (by === "no-approvals")
     recordAutoApproval({
@@ -583,3 +616,21 @@ export async function approvePlan(
     });
   return { ref, amendments: scopeChangesOf(s.id).length };
 }
+
+// A plan that moved here to be built (remote-plan.ts): implementation starts
+// on this machine, once, with the approval's change if it had one.
+export async function implementArrived(
+  sessionId: string,
+  message?: string
+): Promise<string | null> {
+  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 a plan`);
+  const { sendQueuedNow } = await import("../chat/runner");
+  return startImplementing(
+    s,
+    "awaiting",
+    (id, m) => sendQueuedNow(id, m),
+    message
+  );
+}