@saadnvd1/agent-os 0.3.517 → 0.3.519

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,25 @@ 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. The task can `aos send` its orchestrator back: the machine it runs
+  on only stores the message, and the orchestrator's machine pulls it and
+  delivers it as that task's own. Moving it back stops its agent there and
+  removes its worktree when nothing in it would be lost. 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 +1606,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/bus/peers/route.ts

@@ -1,10 +1,16 @@
 import { NextRequest, NextResponse } from "next/server";
-import { listPeers, resolveTarget } from "@/lib/bus";
+import { listPeers, resolveHeldOrchestrator, resolveTarget } from "@/lib/bus";
 
 // ?ref=<name>: just the session that name reaches, the way aos send would.
 export async function GET(request: NextRequest) {
   const ref = request.nextUrl.searchParams.get("ref");
-  if (ref === null) return NextResponse.json({ peers: await listPeers() });
+  // from: the asking session, which a held task needs for its orchestrator.
+  const from = request.nextUrl.searchParams.get("from") ?? "";
+  if (ref === null)
+    return NextResponse.json({ peers: await listPeers(from || undefined) });
+  const held = from ? resolveHeldOrchestrator(from, ref) : null;
+  if (held)
+    return NextResponse.json({ peer: { id: held.id, name: held.name } });
   try {
     const { session, note } = resolveTarget(ref);
     return NextResponse.json({

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-facts/route.ts

@@ -0,0 +1,21 @@
+import { NextRequest } from "next/server";
+import { blockedReason } from "@/lib/tasks/state";
+import { saidSinceLastMessage } from "@/lib/chat/store";
+import { chatStateNow } from "@/lib/chat/runner";
+import { heldRoute } from "@/lib/tasks/held-routes";
+
+// GET /api/tasks/:id/chat-facts - what its chat says about being blocked
+// and whether a question is open, for the orchestrator that moved it here.
+// Cheap (no PR lookups), unlike the whole task list.
+export async function GET(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  return heldRoute(request, ctx, async (task) => {
+    if (task.view !== "chat") return { blocked: null, turn: null };
+    return {
+      blocked: blockedReason(saidSinceLastMessage(task.id)),
+      turn: await chatStateNow(task.id).catch(() => "unknown"),
+    };
+  });
+}

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,24 @@
 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";
+import { cleanUpMovedAway } from "@/lib/tasks/moved-away";
+import { runInBackground } from "@/lib/async-operations";
 
 // 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));
+  // A task its orchestrator took back: its agent and worktree here go.
+  if (held === null)
+    runInBackground(async () => {
+      await cleanUpMovedAway(id);
+    }, `moved-away-${id}`);
   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/held-replies/route.ts

@@ -0,0 +1,31 @@
+import { NextRequest, NextResponse } from "next/server";
+import { callingDevice } from "@/lib/security/device-me";
+import { ackReplies, pendingReplies } from "@/lib/bus/held-reply";
+
+// GET /api/tasks/held-replies - what the tasks this device moved here have
+// said to their orchestrator, for it to deliver there. Only that device's.
+export async function GET(request: NextRequest) {
+  const device = callingDevice(request);
+  if (!device)
+    return NextResponse.json(
+      { error: "Needs a paired device" },
+      { status: 403 }
+    );
+  return NextResponse.json({ messages: pendingReplies(device) });
+}
+
+// POST { ids } - those are delivered; they are not offered again.
+export async function POST(request: NextRequest) {
+  const device = callingDevice(request);
+  if (!device)
+    return NextResponse.json(
+      { error: "Needs a paired device" },
+      { status: 403 }
+    );
+  const { ids } = await request.json().catch(() => ({}));
+  const list = (Array.isArray(ids) ? ids : []).filter((n): n is number =>
+    Number.isSafeInteger(n)
+  );
+  ackReplies(device, list.slice(0, 200));
+  return NextResponse.json({ success: true });
+}

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/held-reply.ts

@@ -0,0 +1,89 @@
+/**
+ * A task its orchestrator moved here has no orchestrator on this machine to
+ * message, and this machine never reaches back to the one that holds it. Its
+ * message to the orchestrator is only stored here (relay_state 'pending');
+ * the holder pulls it (lib/tasks/held-replies.ts) and delivers it there as
+ * that task's own. This machine never delivers or attributes it, and the
+ * holder, not the sender, says who receives it.
+ */
+
+import { db, type Session } from "../db";
+import { resolveRef } from "./resolve";
+
+export interface HeldOrchestrator {
+  id: string;
+  name: string;
+  heldFrom: string;
+}
+
+/** The orchestrator a running held task messages, or null. */
+export function heldOrchestrator(
+  s: Session | undefined
+): HeldOrchestrator | null {
+  if (
+    !s ||
+    !s.held_by_device ||
+    !s.held_for ||
+    !s.held_for_name ||
+    s.task_status !== "running"
+  )
+    return null;
+  return {
+    id: s.held_for,
+    name: s.held_for_name,
+    heldFrom: s.held_from || "another machine",
+  };
+}
+
+/** The orchestrator `ref` names for this held sender: its name, id prefix or "orchestrator". */
+export function heldTarget(
+  from: Session | undefined,
+  ref: string
+): HeldOrchestrator | null {
+  const o = from && heldOrchestrator(from);
+  if (!o) return null;
+  if (ref.trim().toLowerCase() === "orchestrator") return o;
+  const r = resolveRef(ref, [
+    {
+      id: o.id,
+      name: o.name,
+      projectName: null,
+      tmuxName: "",
+      previousNames: [],
+    },
+  ]);
+  return r.ok ? o : null;
+}
+
+export interface PendingReply {
+  id: number;
+  fromId: string;
+  body: string;
+  createdAt: string;
+}
+
+/** What the calling device's held tasks have said to their orchestrators. */
+export function pendingReplies(device: string, limit = 50): PendingReply[] {
+  return (
+    db
+      .prepare(
+        `SELECT m.id, m.from_id AS fromId, m.body, m.created_at AS createdAt
+         FROM bus_messages m JOIN sessions s ON s.id = m.from_id
+         WHERE m.relay_state = 'pending' AND s.held_by_device = ?
+         ORDER BY m.id LIMIT ?`
+      )
+      .all(device, limit) as PendingReply[]
+  ).map((r) => ({ ...r, id: Number(r.id) }));
+}
+
+/** Marks them pulled; only the device's own are touched. */
+export function ackReplies(device: string, ids: number[]): void {
+  const mark = db.prepare(
+    `UPDATE bus_messages SET relay_state = 'relayed', delivered_at = datetime('now')
+     WHERE id = ? AND relay_state = 'pending'
+       AND from_id IN (SELECT id FROM sessions WHERE held_by_device = ?)`
+  );
+  db.transaction(() => {
+    for (const id of ids) mark.run(id, device);
+  })();
+}

package/lib/bus/index.ts

@@ -14,6 +14,9 @@ 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 { heldOrchestrator, heldTarget } from "./held-reply";
 import { HUMAN, overRateLimit, wakeLine, type BusMessageView } from "./format";
 
 export * from "./format";
@@ -52,11 +55,21 @@ function candidates(sessions: Session[]): Candidate[] {
   }));
 }
 
-export async function listPeers(): Promise<Peer[]> {
+const sessionById = (id: string | null | undefined) =>
+  id
+    ? (db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id) as
+        | Session
+        | undefined)
+    : undefined;
+
+// `callerId`: the asking session. A task its orchestrator moved here also
+// sees that orchestrator, which it can message though it runs elsewhere.
+export async function listPeers(callerId?: string): Promise<Peer[]> {
   await statusDetector.refreshCache();
   const sessions = liveSessions();
   const named = candidates(sessions);
-  return Promise.all(
+  const orchestrator = heldOrchestrator(sessionById(callerId));
+  const listed = await Promise.all(
     sessions.map(async (s, i) => {
       const status = statusDetector.sessionExists(s.tmux_name)
         ? await statusDetector.getStatus(s.tmux_name)
@@ -74,6 +87,25 @@ export async function listPeers(): Promise<Peer[]> {
       };
     })
   );
+  if (!orchestrator) return listed;
+  return [
+    ...listed,
+    {
+      id: orchestrator.id,
+      name: orchestrator.name,
+      was: [],
+      projectName: null,
+      tmuxName: "",
+      hostId: "remote",
+      running: true,
+      doing: `your orchestrator, on ${orchestrator.heldFrom}`,
+    },
+  ];
+}
+
+// The orchestrator a held caller's ref names, if it names it.
+export function resolveHeldOrchestrator(callerId: string, ref: string) {
+  return heldTarget(sessionById(callerId), ref);
 }
 
 // A live session by name, old name, project/name, id or id prefix. The note
@@ -142,11 +174,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)
@@ -196,16 +238,18 @@ export async function sendMessage(opts: {
   // It's never left unread for `aos inbox` to show in another form; a
   // failed one is the sender's to retry.
   line?: string;
+  // A message pulled from a linked machine, by its key there: one already
+  // stored is not stored or delivered again.
+  relayKey?: string;
 }): Promise<{ message: BusMessageView; delivery: Delivery; note?: string }> {
   const body = opts.body.trim();
   if (!body) throw new Error("Message is empty");
-  const { session: to, note } = resolveTarget(opts.to);
-  const from = opts.fromId
-    ? (db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(opts.fromId) as
-        | Session
-        | undefined)
-    : undefined;
+  const from = sessionById(opts.fromId);
   if (opts.fromId && !from) throw new Error("Unknown sender session");
+  // A held task's message to its orchestrator is kept for the holder to pull.
+  const held = heldTarget(from, opts.to);
+  if (from && held) return storeForHolder(from, held, body);
+  const { session: to, note } = resolveTarget(opts.to);
   if (from && from.id === to.id)
     throw new Error("A session can't message itself");
   if (from && overRateLimit(pairTimestamps(from.id, to.id))) {
@@ -213,13 +257,32 @@ export async function sendMessage(opts: {
       `Too many messages between ${from.name} and ${to.name}; wait a few minutes`
     );
   }
+  if (opts.relayKey) {
+    const seen = db
+      .prepare(`SELECT id FROM bus_messages WHERE relay_key = ?`)
+      .get(opts.relayKey) as { id: number } | undefined;
+    if (seen)
+      return {
+        message: toView(
+          db.prepare(`${SELECT} WHERE m.id = ?`).get(seen.id) as Row
+        ),
+        delivery: { state: "delivered" },
+      };
+  }
 
   const fromName = from?.name ?? opts.fromLabel ?? HUMAN;
   const { lastInsertRowid } = db
     .prepare(
-      `INSERT INTO bus_messages (from_id, from_name, to_id, to_name, body) VALUES (?, ?, ?, ?, ?)`
+      `INSERT INTO bus_messages (from_id, from_name, to_id, to_name, body, relay_key) VALUES (?, ?, ?, ?, ?, ?)`
     )
-    .run(from?.id ?? null, fromName, to.id, to.name, body);
+    .run(
+      from?.id ?? null,
+      fromName,
+      to.id,
+      to.name,
+      body,
+      opts.relayKey ?? null
+    );
   const id = Number(lastInsertRowid);
 
   await statusDetector.refreshCache();
@@ -228,6 +291,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 }
@@ -247,6 +311,31 @@ export async function sendMessage(opts: {
   return { message, delivery, note };
 }
 
+function storeForHolder(
+  from: Session,
+  to: { id: string; name: string; heldFrom: string },
+  body: string
+) {
+  if (overRateLimit(pairTimestamps(from.id, to.id)))
+    throw new Error(
+      `Too many messages between ${from.name} and ${to.name}; wait a few minutes`
+    );
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO bus_messages (from_id, from_name, to_id, to_name, body, relay_state)
+       VALUES (?, ?, ?, ?, ?, 'pending')`
+    )
+    .run(from.id, from.name, to.id, to.name, body);
+  const message = toView(
+    db.prepare(`${SELECT} WHERE m.id = ?`).get(Number(lastInsertRowid)) as Row
+  );
+  return {
+    message,
+    delivery: { state: "queued" as const },
+    note: `${to.name} runs on ${to.heldFrom}: it gets this when that machine next checks in, within a few seconds`,
+  };
+}
+
 // Unread messages for a session, marked read as they're returned.
 export function readInbox(sessionId: string): BusMessageView[] {
   const rows = db