@saadnvd1/agent-os 0.3.518 → 0.3.519

package/README.md

@@ -1587,7 +1587,10 @@ Once linked:
   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
+  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.

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

@@ -2,6 +2,8 @@ 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(
@@ -13,5 +15,10 @@ export async function POST(
   if (held) return NextResponse.json({ error: held }, { status: 403 });
   const { to } = await request.json().catch(() => ({}));
   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/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/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

@@ -16,6 +16,7 @@ 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";
@@ -54,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)
@@ -76,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
@@ -208,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))) {
@@ -225,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();
@@ -260,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

package/lib/db/migrations.ts

@@ -1714,6 +1714,31 @@ const migrations: Migration[] = [
         add(col);
     },
   },
+  {
+    id: 74,
+    name: "held_task_replies",
+    up: (db) => {
+      // held_for / held_for_name: the orchestrator (id, name there) a held
+      // task messages. relay_state: a held task's message to it, waiting for
+      // the holder to pull it (pending) or pulled (relayed). relay_key: a
+      // pulled message's key on the orchestrator's machine, so a repeat pull
+      // is not delivered twice.
+      const has = (table: string, col: string) =>
+        (
+          db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]
+        ).some((c) => c.name === col);
+      for (const col of ["held_for", "held_for_name"])
+        if (!has("sessions", col))
+          db.exec(`ALTER TABLE sessions ADD COLUMN ${col} TEXT`);
+      for (const col of ["relay_state", "relay_key"])
+        if (!has("bus_messages", col))
+          db.exec(`ALTER TABLE bus_messages ADD COLUMN ${col} TEXT`);
+      db.exec(
+        `CREATE UNIQUE INDEX IF NOT EXISTS idx_bus_relay_key ON bus_messages(relay_key) WHERE relay_key IS NOT NULL;
+         CREATE INDEX IF NOT EXISTS idx_bus_relay_pending ON bus_messages(relay_state) WHERE relay_state = 'pending'`
+      );
+    },
+  },
 ];
 
 // `upTo`: stop after this id (tests that start from an older database).

package/lib/db/types.ts

@@ -124,6 +124,8 @@ export interface Session {
   // The device and machine of the orchestrator that moved this task here.
   held_by_device?: string | null;
   held_from?: string | null;
+  held_for?: string | null;
+  held_for_name?: string | null;
   // A held task's "plan written" line, for its orchestrator to read.
   plan_note?: string | null;
   // Orchestration fields

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/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/security/demo.ts

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

package/lib/status-detector.ts

@@ -537,6 +537,10 @@ class SessionStatusDetector {
     if (this.peersAsked.has(hostId)) return;
     this.peersAsked.add(hostId);
     this.hostListedAt.set(hostId, Date.now());
+    // What its held tasks have said to their orchestrators here.
+    void import("./tasks/held-replies")
+      .then((m) => m.pullHeldReplies(link))
+      .catch(() => undefined);
     void peerTmuxSessions(link)
       .then(
         (list) => {

package/lib/tasks/held-remote.ts

@@ -5,7 +5,12 @@
  */
 
 import type { Session } from "../db";
-import { cleanRemoteText, hostApi, requireHostLink } from "../hosts/remote-api";
+import {
+  cleanRemoteBlock,
+  cleanRemoteText,
+  hostApi,
+  requireHostLink,
+} from "../hosts/remote-api";
 import type { Delivery } from "../bus/delivery";
 
 const path = (id: string, leaf: string) =>
@@ -54,7 +59,31 @@ export async function heldChatTail(
     `${path(task.id, "chat-tail")}?lines=${lines}`,
     { timeout: 10000 }
   ).catch(() => ({ text: undefined }));
-  return typeof text === "string" ? cleanRemoteText(text) : null;
+  // Whole lines, as a local read has them (read.ts caps and trims them).
+  return typeof text === "string" ? cleanRemoteBlock(text, 16000) : null;
+}
+
+/**
+ * What its chat says about being blocked or asking, as that machine reads it
+ * (the same reading a local chat task gets). Null when it can't be asked,
+ * which callers treat as unread, never as clear.
+ */
+export async function heldChatFacts(
+  task: Pick<Session, "id" | "host_id">
+): Promise<{ blocked: string | null; turn: string | null } | null> {
+  const link = requireHostLink(task.host_id);
+  const res = await hostApi<{ blocked?: unknown; turn?: unknown }>(
+    link,
+    path(task.id, "chat-facts"),
+    { timeout: 10000 }
+  ).catch(() => null);
+  if (!res || (res.blocked !== null && typeof res.blocked !== "string"))
+    return null;
+  if (res.turn !== null && typeof res.turn !== "string") return null;
+  return {
+    blocked: res.blocked ? cleanRemoteBlock(res.blocked, 2000) : null,
+    turn: res.turn,
+  };
 }
 
 /** Stops its agent there; its conversation and worktree are kept. */

package/lib/tasks/held-replies.ts

@@ -0,0 +1,106 @@
+/**
+ * What the tasks this machine's orchestrators moved to a linked machine say
+ * to those orchestrators. That machine only stores the messages (bus/held-reply);
+ * this machine, which polls, pulls them and delivers each as that task's own
+ * message to the orchestrator that started it. Who receives it is this
+ * machine's own record (started_by), never anything the other machine names.
+ */
+
+import { db, type Session } from "../db";
+import { sendMessage } from "../bus";
+import { hostApi, type HostLink } from "../hosts/remote-api";
+
+const PULL_EVERY_MS = 5000;
+const MISSING_FOR_MS = 10 * 60 * 1000;
+const MAX_BODY = 8000;
+
+const g = globalThis as unknown as {
+  __agentosRepliesAt?: Map<string, number>;
+  __agentosRepliesBusy?: Set<string>;
+};
+const lastAsked = (g.__agentosRepliesAt ??= new Map());
+const busy = (g.__agentosRepliesBusy ??= new Set());
+
+interface Pulled {
+  id: number;
+  fromId: string;
+  body: string;
+}
+
+const heldMirror = (hostId: string, id: string) =>
+  db
+    .prepare(
+      `SELECT * FROM sessions WHERE id = ? AND host_id = ?
+         AND started_by IS NOT NULL AND task_status IN ('running', 'moving')`
+    )
+    .get(id, hostId) as Session | undefined;
+
+export function hasHeldMirrors(hostId: string): boolean {
+  return !!db
+    .prepare(
+      `SELECT 1 FROM sessions WHERE host_id = ? AND started_by IS NOT NULL
+         AND task_prompt IS NOT NULL AND task_status IN ('running', 'moving')`
+    )
+    .get(hostId);
+}
+
+/** Delivers what the link's machine holds for this machine's orchestrators. */
+export async function pullHeldReplies(link: HostLink): Promise<number> {
+  const hostId = link.hostId;
+  if (busy.has(hostId) || !hasHeldMirrors(hostId)) return 0;
+  const now = Date.now();
+  if (now - (lastAsked.get(hostId) ?? 0) < PULL_EVERY_MS) return 0;
+  lastAsked.set(hostId, now);
+  busy.add(hostId);
+  try {
+    let messages: Pulled[];
+    try {
+      const res = await hostApi<{ messages?: unknown }>(
+        link,
+        "/api/tasks/held-replies",
+        { timeout: 8000 }
+      );
+      messages = (Array.isArray(res.messages) ? res.messages : []).filter(
+        (m): m is Pulled =>
+          !!m &&
+          Number.isSafeInteger(m.id) &&
+          typeof m.fromId === "string" &&
+          typeof m.body === "string"
+      );
+    } catch (err) {
+      // A machine that predates replies: leave it alone for a while.
+      if ((err as { status?: number }).status === 404)
+        lastAsked.set(hostId, now + MISSING_FOR_MS);
+      return 0;
+    }
+    const handled: number[] = [];
+    let delivered = 0;
+    for (const m of messages) {
+      const mirror = heldMirror(hostId, m.fromId);
+      if (!mirror) {
+        handled.push(m.id); // nothing here to deliver it from
+        continue;
+      }
+      try {
+        await sendMessage({
+          fromId: mirror.id,
+          to: mirror.started_by!,
+          body: m.body.slice(0, MAX_BODY),
+          relayKey: `${hostId}:${m.id}`,
+        });
+        handled.push(m.id);
+        delivered++;
+      } catch {
+        // Gone, or rate limited: offered again at the next pull.
+      }
+    }
+    if (handled.length)
+      await hostApi(link, "/api/tasks/held-replies", {
+        body: { ids: handled },
+        timeout: 8000,
+      }).catch(() => undefined);
+    return delivered;
+  } finally {
+    busy.delete(hostId);
+  }
+}

package/lib/tasks/import.ts

@@ -174,10 +174,13 @@ async function arrive(
       if (holder)
         db.prepare(
           `UPDATE sessions SET held_by_device = ?, held_from = ?,
+             held_for = ?, held_for_name = ?,
              model_provider = ?, model_overrides = ? WHERE id = ?`
         ).run(
           holder,
           orch.heldFrom,
+          orch.orchestrator?.id ?? null,
+          orch.orchestrator?.name ?? null,
           orch.modelProvider,
           orch.modelOverrides,
           id
@@ -203,9 +206,8 @@ async function arrive(
         });
       }, `setup-moved-${bundle.branch}`);
     }
-    const prompt = claude
-      ? arrivalNote(bundle, worktreePath)
-      : `${bundle.prompt}\n\n${arrivalNote(bundle, worktreePath)}`;
+    const note = arrivalNote(bundle, worktreePath, os.hostname());
+    const prompt = claude ? note : `${bundle.prompt}\n\n${note}`;
     if (bundle.chat) {
       // Its worker starts on the carried conversation, takes the note
       // first, then what was queued.

package/lib/tasks/move-bundle.ts

@@ -71,6 +71,9 @@ export interface OrchestratedBundle {
   planPhase: "planning" | "implementing" | null;
   // .agentos/plan.md, which is never in git.
   planFile: string | null;
+  // The orchestrator that holds the task (its id and name on the machine
+  // that runs it), so the task can message it from where it runs.
+  orchestrator?: { id: string; name: string };
 }
 
 export interface ChatBundle {
@@ -147,6 +150,19 @@ function validateOrchestrated(o: OrchestratedBundle): OrchestratedBundle {
     modelOverrides: o.modelOverrides,
     planPhase: o.planPhase,
     planFile: o.planFile,
+    orchestrator:
+      o.orchestrator &&
+      isSessionId(o.orchestrator.id) &&
+      typeof o.orchestrator.name === "string" &&
+      o.orchestrator.name.trim()
+        ? {
+            id: o.orchestrator.id,
+            name: o.orchestrator.name
+              .replace(/[\u0000-\u001f]/g, " ")
+              .trim()
+              .slice(0, 200),
+          }
+        : undefined,
   };
 }
 
@@ -192,10 +208,11 @@ export function validateBundle(b: TaskBundle): TaskBundle {
 
 export function arrivalNote(
   b: { from: string; branch: string },
-  cwd: string
+  cwd: string,
+  here: string
 ): string {
   return [
-    `This task just moved here from ${b.from}. Your worktree is now ${cwd}, on branch ${b.branch}.`,
+    `This task just moved from ${b.from} to ${here}. It now runs on ${here}: every command you run executes there, not on ${b.from}, so name ${here} when you report where something ran. Your worktree is now ${cwd}, on branch ${b.branch}.`,
     `Anything that was uncommitted came over as a commit starting "wip: moving to"; fold it into your own commits as you see fit.`,
     `Continue the task where you left off.`,
   ].join(" ");

package/lib/tasks/move-flow.ts

@@ -10,7 +10,7 @@ import { db, type Session } from "../db";
 import { isRemoteHost } from "../hosts";
 import { requireHostLink, type HostLink } from "../hosts/remote-api";
 import { getTaskSession } from "./session";
-import { exportOrResume, markMoved, resumeTask, type TaskBundle } from "./move";
+import { exportOrResume, resumeTask, type TaskBundle } from "./move";
 import { isOrchestrated, moveRefusal } from "./move-guard";
 import { holderRefusal } from "./held";
 import { isPaused } from "../orchestrator/pause";
@@ -146,6 +146,13 @@ async function moveOut(session: Session, hostId: string): Promise<Session> {
   return settleMovedOut(session, hostId, link.hostName, there);
 }
 
+function mirrorRunning(id: string): void {
+  db.prepare(
+    `UPDATE sessions SET task_status = 'running', moved_to = NULL
+       WHERE id = ? AND task_status = 'moving'`
+  ).run(id);
+}
+
 async function moveIn(mirror: Session): Promise<Session> {
   const link = requireHostLink(mirror.host_id);
   if (mirror.view === "chat") await requireChatMoves(link);
@@ -154,6 +161,12 @@ async function moveIn(mirror: Session): Promise<Session> {
   // A retry after it arrived here but that machine didn't hear: tidy up.
   let here = arrivedHere(mirror.id);
   if (!here) {
+    // Moving, so nothing reads the mirror as a task to judge, or sign off,
+    // while it leaves (a refusal below puts it back).
+    db.prepare(
+      `UPDATE sessions SET task_status = 'moving', moved_to = 'this machine'
+         WHERE id = ? AND task_status = 'running'`
+    ).run(mirror.id);
     // That machine resumes the agent itself if its half fails there.
     stepProgress(mirror.id, "export");
     let bundle: TaskBundle;
@@ -165,6 +178,7 @@ async function moveIn(mirror: Session): Promise<Session> {
         300000
       ));
     } catch (err) {
+      mirrorRunning(mirror.id);
       if (unknownOutcome(err)) throw unconfirmed(link.hostName, err);
       throw err;
     }
@@ -176,6 +190,7 @@ async function moveIn(mirror: Session): Promise<Session> {
           `${(err as Error).message}; and ${link.hostName} didn't resume it: ${e.message}`
         );
       });
+      mirrorRunning(mirror.id);
       throw err;
     }
   }
@@ -190,7 +205,11 @@ async function moveIn(mirror: Session): Promise<Session> {
       `It's running here now, but ${link.hostName} didn't confirm (${(err as Error).message}). Press Move here again to tidy up.`
     );
   }
-  markMoved(mirror.id, os.hostname());
+  // The mirror was only how this machine showed it: the task is the new row.
+  db.prepare(`DELETE FROM sessions WHERE id = ? AND host_id = ?`).run(
+    mirror.id,
+    mirror.host_id
+  );
   forgetHostTasks(link.hostId);
   return db
     .prepare(`SELECT * FROM sessions WHERE id = ?`)

package/lib/tasks/move.ts

@@ -115,6 +115,20 @@ const readPlanFile = (cwd: string): string | null => {
   }
 };
 
+// The orchestrator that holds the task: its own, or the one on the machine
+// that moved it here.
+function orchestratorOf(
+  session: Session
+): { id: string; name: string } | undefined {
+  if (session.held_for && session.held_for_name)
+    return { id: session.held_for, name: session.held_for_name };
+  if (!session.started_by) return undefined;
+  const o = db
+    .prepare(`SELECT name FROM sessions WHERE id = ?`)
+    .get(session.started_by) as { name: string } | undefined;
+  return o ? { id: session.started_by, name: o.name } : undefined;
+}
+
 // What an orchestrator's task carries besides its work (the orchestrator's
 // own state is re-keyed here; see move-carry).
 function orchestratedBundle(session: Session): OrchestratedBundle {
@@ -125,6 +139,7 @@ function orchestratedBundle(session: Session): OrchestratedBundle {
     modelOverrides: session.model_overrides ?? null,
     planPhase: session.plan_phase ?? null,
     planFile: readPlanFile(session.working_directory),
+    orchestrator: orchestratorOf(session),
   };
 }
 

package/lib/tasks/moved-away.ts

@@ -0,0 +1,37 @@
+/**
+ * What a machine tidies up after a task it held went back to the machine
+ * that sent it: its agent and chat worker stop, its ports are released, and
+ * its worktree goes when nothing in it would be lost (no uncommitted change,
+ * no commit a remote lacks). The row stays, archived, as history.
+ */
+
+import { db, type Session } from "../db";
+import { endSessionAgent } from "../sessions/end";
+import { releasePorts } from "../ports";
+import { settleWorktree, type WorktreeFate } from "../done/worktree";
+import { archiveSession } from "../done/archive";
+
+export async function cleanUpMovedAway(id: string): Promise<WorktreeFate> {
+  const s = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id) as
+    | Session
+    | undefined;
+  if (!s || s.task_status !== "moved" || !s.held_by_device)
+    return { action: "none" };
+  await endSessionAgent(s).catch((err) =>
+    console.error(`[moved-away] ${id}: agent not stopped:`, err)
+  );
+  releasePorts(id);
+  const fate = await settleWorktree(s, null, true).catch(
+    (err): WorktreeFate => ({
+      action: "kept",
+      why: `it couldn't be checked: ${err instanceof Error ? err.message : err}`,
+      path: s.worktree_path ?? "",
+    })
+  );
+  archiveSession(id);
+  if (fate.action === "kept")
+    console.warn(
+      `[moved-away] ${id}: worktree kept at ${fate.path}: ${fate.why}`
+    );
+  return fate;
+}

package/lib/tasks/remote.ts

@@ -30,6 +30,9 @@ export const TASK_CAPABILITIES = [
   // Holds an orchestrator's task for the machine that sent it, and answers
   // its messages, reads, stops and done (lib/tasks/held.ts).
   "orchestrated-move",
+  // A held task's chat facts and its messages for its orchestrator.
+  "held-chat-facts",
+  "held-replies",
 ] as const;
 
 export interface HostTasks {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.518",
+  "version": "0.3.519",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"