@saadnvd1/agent-os 0.3.517 → 0.3.518

package/README.md

@@ -1201,7 +1201,7 @@ it may do on its own, and the lines that always come back to you as asks.
 - **Tools:** `sessions` (every session's status, activity, task, PR, CI and
   stack position), `read` (the end of a terminal or chat) and `cards` (the
   linked boards' cards), plus acting tools: `send`, `start_task`,
-  `start_session`, `stack`, `stack_status`, `land`, `drop`, `stop`, `done`,
+  `start_session`, `stack`, `stack_status`, `land`, `drop`, `stop`, `done`, `move`,
   `add_project` (a git repository on the machine becomes a project of the
   workspace, or the project already at that path moves in from no workspace;
   folders that hold secrets and projects of another workspace are refused),
@@ -1222,7 +1222,8 @@ it may do on its own, and the lines that always come back to you as asks.
   naming the tool to use instead: merging, closing or retargeting a PR
   (`gh pr merge`, `gh pr close`, `gh pr edit --base`, and `gh api` or `curl`
   calls that merge a pull request or PATCH or PUT one; use `sign_off`, `arm`,
-  `land` or `drop`), `git push` (`quick_pr` pushes), writing in a project
+  `land` or `drop`), `aos move`, `aos done` and `aos stop` (use `move`, `done` and
+  `stop`, which are scoped to the workspace and held by Pause), `git push` (`quick_pr` pushes), writing in a project
   repository or task worktree other than its own open quick changes (git
   commit, reset, checkout, rebase, merge, stash, clean or rm there, and `rm`,
   `mv`, `cp`, `tee` or a redirect into one), writing AgentOS's state (`sqlite3`
@@ -1574,6 +1575,22 @@ Once linked:
   press Move again to finish it, or **Resume here**, which first asks the
   other machine whether it arrived. Tasks waiting on you (an escalated gate or
   an open ask), card tasks and stacked tasks don't move yet.
+- **An orchestrator's task moves too**, by the orchestrator's `move` tool (`task`,
+  `machine`; `here` brings it back) or the Move button. Its state is re-keyed to
+  the task's new session id in the same step it lands: brief and scope changes,
+  plan file and phase, gate checks and failure counts, asks, wakes, queue
+  order, arm, model and provider. Both machines need an AgentOS that can do
+  it, and the arriving one must have the task's provider. The machine it lands
+  on holds it for the orchestrator's machine alone: only that device can
+  merge, arm, message, stop, done or read it, and the arriving machine's own
+  orchestrator, armed merges and bulk done skip it. The orchestrator keeps
+  judging the PR at its head, reads BLOCKED lines and open approvals from the
+  task's chat there, and gets PR, CI, idle and plan events by polling that
+  machine. Its messages arrive marked as from the orchestrator, never as
+  yours. Guards (write guard, shell deny list, attribution settings) run in
+  the task's worker on either machine, and the task can't merge or push to
+  the default branch. Moving counts toward the brakes and Pause refuses the
+  tool.
 - **A chat task moves the same way**, between turns: a running turn is let
   finish (up to 3 minutes, else the move is refused and it carries on here),
   and one waiting on your answer isn't moved. What's sent to it while its
@@ -1586,7 +1603,7 @@ Once linked:
 Works for any project. Requests to the other machine carry its device token,
 so it can sit behind a proxy that never trusts loopback. Linking needs this
 machine or the tailnet, and only pairs with the ssh target's own host name.
-The orchestrator still starts tasks on its own machine only.
+The orchestrator starts tasks on its own machine and moves them afterwards.
 
 ## Security
 

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

@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from "next/server";
 import { db, type Session } from "@/lib/db";
 import { armTask, setArmed } from "@/lib/orchestrator/armed";
+import { callingDevice } from "@/lib/security/device-me";
+import { heldRefusal } from "@/lib/tasks/held";
 
 // { armed: true } merges the task's PR by itself once every gate passes;
 // false takes that back.
@@ -8,6 +10,9 @@ export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
+  const id = (await params).id;
+  const held = heldRefusal(id, callingDevice(request));
+  if (held) return NextResponse.json({ error: held }, { status: 403 });
   const { armed } = await request.json().catch(() => ({}));
   if (typeof armed !== "boolean")
     return NextResponse.json(

package/app/api/tasks/[id]/chat-tail/route.ts

@@ -0,0 +1,15 @@
+import { NextRequest } from "next/server";
+import { chatTailText } from "@/lib/orchestrator/read";
+import { heldRoute } from "@/lib/tasks/held-routes";
+
+// GET /api/tasks/:id/chat-tail?lines= - the last lines of its conversation,
+// for the orchestrator that moved it here to read.
+export async function GET(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  const lines = Number(request.nextUrl.searchParams.get("lines")) || 60;
+  return heldRoute(request, ctx, async (task) => ({
+    text: task.view === "chat" ? chatTailText(task.id, lines) : "",
+  }));
+}

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

@@ -0,0 +1,15 @@
+import { NextRequest } from "next/server";
+import { doneSession } from "@/lib/done";
+import { heldRoute } from "@/lib/tasks/held-routes";
+
+// POST /api/tasks/:id/done - its orchestrator finishes it: the agent stops
+// and the worktree goes. Never a merge (noMerge): an open PR is refused
+// here, since only its orchestrator's gates merge it.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  return heldRoute(request, ctx, async (task) => ({
+    outcome: await doneSession(task.id, { by: "direct", noMerge: true }),
+  }));
+}

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

@@ -1,5 +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";
 
 // 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
@@ -8,10 +10,13 @@ export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
+  const id = (await params).id;
+  const held = heldRefusal(id, callingDevice(request));
+  if (held) return NextResponse.json({ error: held }, { status: 403 });
   try {
     const { to } = await request.json().catch(() => ({}));
     const bundle = await exportOrResume(
-      (await params).id,
+      id,
       String(to || "another machine").slice(0, 100)
     );
     return NextResponse.json({ bundle });

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

@@ -1,5 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import { signOffTask } from "@/lib/tasks";
+import { callingDevice } from "@/lib/security/device-me";
+import { heldRefusal } from "@/lib/tasks/held";
 
 // head: merge only if the PR is still at this commit; the answer names the
 // commit it was pinned to, so another machine forwarding a merge can check.
@@ -7,6 +9,9 @@ export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
+  const id = (await params).id;
+  const held = heldRefusal(id, callingDevice(request));
+  if (held) return NextResponse.json({ error: held }, { status: 403 });
   const { head } = await request.json().catch(() => ({}));
   if (
     head !== undefined &&
@@ -14,7 +19,10 @@ export async function POST(
   )
     return NextResponse.json({ error: "Bad head commit" }, { status: 400 });
   try {
-    const method = await signOffTask((await params).id, { head });
+    const method = await signOffTask(id, {
+      head,
+      device: callingDevice(request),
+    });
     return NextResponse.json({ success: true, head: head ?? null, method });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

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

@@ -0,0 +1,39 @@
+import { NextRequest } from "next/server";
+import { statusDetector } from "@/lib/status-detector";
+import { deliver } from "@/lib/bus";
+import { sendChatConfirmed } from "@/lib/chat/runner";
+import { cleanRemoteText } from "@/lib/hosts/remote-api";
+import { heldRoute } from "@/lib/tasks/held-routes";
+
+const MAX_LINE = 40_000;
+
+// POST /api/tasks/:id/message {id?, line, from} - the orchestrator that moved
+// this task here speaks to it. It arrives as that orchestrator's message,
+// never as the user's, and a repeat of the same id is not delivered twice.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  const body = await request.json().catch(() => ({}));
+  return heldRoute(request, ctx, async (task) => {
+    const line = typeof body.line === "string" ? body.line.trim() : "";
+    if (!line || line.length > MAX_LINE) throw new Error("Bad message");
+    const id = typeof body.id === "string" ? body.id.slice(0, 100) : undefined;
+    const from = cleanRemoteText(body.from).slice(0, 100) || "the orchestrator";
+    const label = `${from} on ${task.held_from ?? "another machine"}`;
+    if (task.view === "chat") {
+      const state = await sendChatConfirmed(task.id, {
+        id,
+        text: line,
+        from: label,
+        origin: { kind: "peer", label },
+        compact: "auto",
+      });
+      return { state };
+    }
+    await statusDetector.refreshCache();
+    const delivery = await deliver(task, line, { name: label });
+    if (delivery.state === "failed") throw new Error(delivery.why);
+    return { state: delivery.state };
+  });
+}

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

@@ -1,12 +1,17 @@
 import { NextRequest, NextResponse } from "next/server";
 import { markMoved } from "@/lib/tasks/move";
+import { callingDevice } from "@/lib/security/device-me";
+import { heldRefusal } from "@/lib/tasks/held";
 
 // POST /api/tasks/:id/moved - the task now runs on the machine named `to`
 export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
+  const id = (await params).id;
+  const held = heldRefusal(id, callingDevice(request));
+  if (held) return NextResponse.json({ error: held }, { status: 403 });
   const { to } = await request.json().catch(() => ({}));
-  markMoved((await params).id, String(to || "another machine").slice(0, 100));
+  markMoved(id, String(to || "another machine").slice(0, 100));
   return NextResponse.json({ success: true });
 }

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

@@ -1,5 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import { resumeHere } from "@/lib/tasks/move-recover";
+import { callingDevice } from "@/lib/security/device-me";
+import { heldRefusal } from "@/lib/tasks/held";
 
 // POST /api/tasks/:id/resume {force?} - start its agent again here, on its
 // conversation. A task left moving asks its target first unless forced.
@@ -7,9 +9,12 @@ export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
+  const id = (await params).id;
+  const held = heldRefusal(id, callingDevice(request));
+  if (held) return NextResponse.json({ error: held }, { status: 403 });
   const { force } = await request.json().catch(() => ({}));
   try {
-    const result = await resumeHere((await params).id, force === true);
+    const result = await resumeHere(id, force === true);
     return NextResponse.json({ success: true, ...result });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

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

@@ -0,0 +1,14 @@
+import { NextRequest } from "next/server";
+import { stopSession } from "@/lib/sessions/stop";
+import { heldRoute } from "@/lib/tasks/held-routes";
+
+// POST /api/tasks/:id/stop - its orchestrator stops the agent; the
+// conversation and worktree are kept.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  return heldRoute(request, ctx, async (task) => ({
+    text: await stopSession(task),
+  }));
+}

package/app/api/tasks/import/route.ts

@@ -1,4 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
+import { callingDevice } from "@/lib/security/device-me";
 import { importTask } from "@/lib/tasks/import";
 import { MAX_BUNDLE_BYTES, statusFor } from "@/lib/tasks/move-bundle";
 
@@ -11,7 +12,16 @@ export async function POST(request: NextRequest) {
       { status: 413 }
     );
   try {
-    const session = await importTask(await request.json());
+    const bundle = await request.json();
+    // An orchestrator's task is held for the device that sent it, which
+    // only a paired device is.
+    const holder = callingDevice(request);
+    if (bundle?.orchestrated && !holder)
+      return NextResponse.json(
+        { error: "An orchestrator's task comes only from a paired machine" },
+        { status: 403 }
+      );
+    const session = await importTask(bundle, { holder });
     return NextResponse.json({ session }, { status: 201 });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/lib/bus/index.ts

@@ -14,6 +14,8 @@ import { previousNames } from "../session-names";
 import { deliverToPane, type Delivery } from "./delivery";
 import { resolveRef, wasNames, type Candidate } from "./resolve";
 import { tmuxPane } from "./tmux-pane";
+import { hostLink } from "../hosts/remote-api";
+import { relayToHeldTask } from "../tasks/held-remote";
 import { HUMAN, overRateLimit, wakeLine, type BusMessageView } from "./format";
 
 export * from "./format";
@@ -142,11 +144,21 @@ function pairTimestamps(a: string | null, b: string): number[] {
 
 // Hands the message to the recipient: a chat session's worker, or typed
 // into a terminal's pane and checked that it went in.
-async function deliver(
+export async function deliver(
   to: Session,
   line: string,
-  from: { name: string; peer?: PeerMessage; origin?: ChatOrigin }
+  from: {
+    name: string;
+    peer?: PeerMessage;
+    origin?: ChatOrigin;
+    // The stored message's id, which a relayed one is keyed by.
+    messageId?: number;
+  }
 ): Promise<Delivery> {
+  // A task this machine's orchestrator moved to a linked machine: that
+  // machine's AgentOS delivers it, labelled as the orchestrator's (held.ts).
+  if (to.task_prompt && to.started_by && hostLink(to.host_id))
+    return relayToHeldTask(to, line, from.name, from.messageId);
   // A linked machine's own session: an agent's message would reach it as
   // the user's (see runner.ts), so none is relayed yet.
   if (to.peer_mirror && !to.task_prompt)
@@ -228,6 +240,7 @@ export async function sendMessage(opts: {
     opts.line ?? wakeLine({ fromName, fromId: from?.id ?? null, body }),
     {
       name: fromName,
+      messageId: id,
       peer: from ? { sessionId: from.id, body } : undefined,
       origin: from
         ? { kind: "peer", label: from.name, sessionId: from.id }

package/lib/db/migrations.ts

@@ -1689,6 +1689,31 @@ const migrations: Migration[] = [
       `);
     },
   },
+  {
+    id: 73,
+    name: "orchestrated_task_moves",
+    up: (db) => {
+      // task_since: when the task first started, kept across moves (null:
+      // created_at). held_by_device / held_from: the device and machine of
+      // the orchestrator that moved this task here; only that device may
+      // merge, arm, message or move it. plan_note: the "plan written" line
+      // of a held task, for its orchestrator to read.
+      const add = (col: 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} TEXT`);
+      };
+      for (const col of [
+        "task_since",
+        "held_by_device",
+        "held_from",
+        "plan_note",
+      ])
+        add(col);
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/db/types.ts

@@ -119,6 +119,13 @@ export interface Session {
   rebase_asked_head?: string | null;
   // When its PR's reviews and comments started being watched (pr-wake.ts).
   pr_wake_since?: string | null;
+  // When the task first started, kept across moves (null: created_at).
+  task_since?: string | null;
+  // The device and machine of the orchestrator that moved this task here.
+  held_by_device?: string | null;
+  held_from?: string | null;
+  // A held task's "plan written" line, for its orchestrator to read.
+  plan_note?: string | null;
   // Orchestration fields
   conductor_session_id: string | null;
   worker_task: string | null;

package/lib/done/bulk.ts

@@ -54,6 +54,8 @@ function scopeSessions(scope: DoneScope): Session[] {
          AND role IS NULL AND archived_at IS NULL
          -- A linked machine's own sessions are cleaned up there.
          AND peer_mirror = 0
+         -- A task another machine's orchestrator moved here is its to finish.
+         AND held_by_device IS NULL
          AND (task_status IS NULL OR task_status = 'running')
        ORDER BY created_at`
     )
@@ -75,6 +77,12 @@ export async function idleSessions(
 
 // The caller's workspace when its project has one, else its project.
 export function scopeOf(session: Session): DoneScope {
+  // An orchestrator acts through its tools, which Pause holds and which are
+  // logged; aos would reach the same sessions past both.
+  if (session.role === "orchestrator")
+    throw new Error(
+      `${session.name} is an orchestrator: it moves, finishes and stops sessions with its move, done and stop tools, not aos`
+    );
   const project = session.project_id ? getProject(session.project_id) : null;
   if (!project || project.is_uncategorized)
     throw new Error(`${session.name} isn't in a project`);

package/lib/done/index.ts

@@ -25,6 +25,8 @@ import { sessionMergePolicy } from "../tasks/finish";
 import { releasePorts } from "../ports";
 import { dropSessionDatabase } from "../project-config/database";
 import { doneOnPeer, peerSessionLink } from "../hosts/peer-actions";
+import { hostLink } from "../hosts/remote-api";
+import { doneHeldTask } from "../tasks/held-remote";
 import { captureMergedTask } from "../session-logs";
 import { pushMerged } from "../notify/push/events";
 
@@ -161,6 +163,19 @@ export async function doneSession(
     await stopAgent(s);
     // The sign-off's cleanup has already settled it; this reads the result.
     worktree = await settleWorktree(s, { prHead: m.sha });
+  } else if (s.started_by && s.task_prompt && hostLink(s.host_id)) {
+    // Moved to a linked machine by its orchestrator: that machine stops the
+    // agent and removes the worktree, which is where they are.
+    await doneHeldTask(s);
+    if (plan.mark) mark(s, plan.mark, plan.pr);
+    else
+      db.prepare(
+        `UPDATE sessions SET task_status = 'done' WHERE id = ? AND task_status = 'running'`
+      ).run(s.id);
+    worktree = {
+      action: "removed",
+      why: `on ${hostLink(s.host_id)?.hostName ?? "its machine"}`,
+    };
   } else {
     if (plan.mark) mark(s, plan.mark, plan.pr);
     if (

package/lib/models/plan-step.ts

@@ -73,9 +73,12 @@ 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 {
-  if (!s.started_by) return;
+  if (!s.started_by && !s.held_by_device) return;
   const workspaceId = sessionWorkspace(s);
-  if (!workspaceId || !s.worktree_path) return;
+  // A task held for another machine's orchestrator can't reach it: the line
+  // waits on the task for that orchestrator to read (orchestrator/facts).
+  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.`;
   try {
@@ -85,7 +88,14 @@ function announcePlan(s: Session, ref: string): void {
   } catch {
     // No plan file: the line says so.
   }
-  queueEvent(workspaceId, `plan-done:${s.id}`, s.id, head);
+  if (s.held_by_device) {
+    db.prepare(`UPDATE sessions SET plan_note = ? WHERE id = ?`).run(
+      head,
+      s.id
+    );
+    return;
+  }
+  queueEvent(workspaceId!, `plan-done:${s.id}`, s.id, head);
 }
 
 export const implementMessageId = (sessionId: string) =>

package/lib/orchestrator/act.ts

@@ -19,7 +19,9 @@ import {
   launchSession,
   type StartView,
 } from "../sessions/launch";
-import { createTask, dropTask } from "../tasks";
+import { assertMovable, createTask, dropTask, moveTask } from "../tasks";
+import { getHost, hostIdNamed } from "../hosts";
+import { queueEvent } from "./events";
 import {
   findQueued,
   queuedLabel,
@@ -280,3 +282,41 @@ export async function done(workspaceId: string, ref: string): Promise<string> {
 export async function stop(workspaceId: string, ref: string): Promise<string> {
   return stopSession(findWorkspaceSession(workspaceId, ref));
 }
+
+// Carries a task to a linked machine, or back ("here"): heavy test or build
+// work can run on the box. The move takes minutes, so it runs in the
+// background; the orchestrator is told when the task lands or doesn't.
+// Everything about the task (gates, events, read/send/stop/drop) is the same
+// wherever it runs; the machine it lands on holds it for this one.
+export async function moveTaskTo(
+  workspaceId: string,
+  ref: string,
+  machine: string
+): Promise<string> {
+  const task = workspaceTask(workspaceId, ref);
+  const hostId = hostIdNamed(machine);
+  assertMovable(task.id, hostId);
+  const where = hostId === "local" ? "this machine" : machineName(hostId);
+  void moveTask(task.id, hostId).then(
+    (moved) => {
+      addNote(workspaceId, `Moved task ${task.name} to ${where}.`);
+      queueEvent(
+        workspaceId,
+        `move:${moved.id}:${Date.now()}`,
+        moved.id,
+        `Task ${task.name} now runs on ${where}.`
+      );
+    },
+    (error) =>
+      queueEvent(
+        workspaceId,
+        `move-failed:${task.id}:${Date.now()}`,
+        task.id,
+        `Moving task ${task.name} to ${where} failed: ${error instanceof Error ? error.message : String(error)}. It carries on where it was unless it says it's paused as "moving".`
+      )
+  );
+  return `Moving ${task.name} to ${where}. It takes a few minutes; an event tells you when it runs there.`;
+}
+
+const machineName = (hostId: string) =>
+  getHost(hostId)?.name ?? "the other machine";

package/lib/orchestrator/armed.ts

@@ -58,7 +58,8 @@ function armedTasks(workspaceId: string): Session[] {
     .prepare(
       `SELECT s.* FROM sessions s JOIN projects p ON p.id = s.project_id
        WHERE p.workspace_id = ? AND s.merge_armed_at IS NOT NULL
-         AND s.task_status = 'running' AND s.peer_mirror = 0`
+         AND s.task_status = 'running' AND s.peer_mirror = 0
+         AND s.held_by_device IS NULL`
     )
     .all(workspaceId) as Session[];
 }
@@ -100,6 +101,10 @@ export function armTask(task: Session): void {
     );
   if (task.peer_mirror)
     throw new Error(`${task.name} runs on a linked machine; arm it there`);
+  if (task.held_by_device)
+    throw new Error(
+      `${task.name} is held for ${task.held_from ?? "another machine"}'s orchestrator; it arms it there`
+    );
   if (!armingWorkspace(task))
     throw new Error(
       `${task.name}'s project isn't in a workspace with an orchestrator, which an armed merge reports to`

package/lib/orchestrator/brakes.ts

@@ -74,6 +74,15 @@ export async function runningCount(
             "running";
     if (busy) running.add(s.id);
   }
+  // A task mid-move is out of the list above, but it runs again within
+  // minutes, here or there: it holds its slot.
+  const moving = db
+    .prepare(
+      `SELECT s.id FROM sessions s JOIN projects p ON p.id = s.project_id
+       WHERE p.workspace_id = ? AND s.task_status = 'moving' AND s.peer_mirror = 0`
+    )
+    .all(workspaceId) as { id: string }[];
+  for (const { id } of moving) running.add(id);
   for (const { target } of startsSince(workspaceId, now - WARMUP_MS))
     if (target) running.add(target);
   return running.size;

package/lib/orchestrator/brief.ts

@@ -109,7 +109,8 @@ Acting:
 - \`${TOOL_NAMES.quick_pr}\` (change, title, body): commit everything in a quick change, push its branch (never the default branch) and open its PR, or push to the PR it has; its review starts at once. Then it's gated like any task: CI, that review (also its code-review gate), scope, then sign_off or arm. It's in \`sessions\` as your quick change; drop it to throw it away, and it's cleaned up like a task when it merges or is dropped.
 - \`${TOOL_NAMES.stack}\` (target, plan_only?): run a board's open cards as stacked tasks; plan_only shows the plan without starting.
 - \`${TOOL_NAMES.land}\` (id): merge a stack bottom-up through the gates.
-- \`${TOOL_NAMES.drop}\` (task, reason): close a task's PR and remove its worktree.
+- \`${TOOL_NAMES.move}\` (task, machine): carry a running task to a linked machine (heavy test or build work), or back with machine "here". It keeps its branch, conversation and plan, and everything you do with a task works the same there: its events come to you, read, send, stop, done and drop reach it, and the gates judge its PR at its head. The machine it lands on holds it for you and can't merge it. It runs in the background; an event says when it lands. Refused while paused, and for a task waiting on Saad.
+- \`${TOOL_NAMES.drop}\` (task, reason): close a task's PR and remove its worktree (on whichever machine holds it).
 - \`${TOOL_NAMES.stop}\` (session): stop a session's agent, keeping its work.
 - \`${TOOL_NAMES.done}\` (session): finish a session whose work is complete. A task with an open PR merges through the same gates as sign_off first (refused naming the gate otherwise); then the agent stops, the worktree goes only if nothing in it would be lost, and the session is archived out of view. Not a rejection: use drop for that.
 - \`${TOOL_NAMES.add_project}\` (path, name?): make a git repository on this machine a project of this workspace, or move the project already at that path in when it's in no workspace. Use it rather than sending Saad steps. It refuses a folder that isn't a git repository or holds secrets, and a project another workspace has: moving that is Saad's call, so ask_saad.