@saadnvd1/agent-os 0.3.579 → 0.3.580

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

@@ -0,0 +1,28 @@
+import { NextRequest, NextResponse } from "next/server";
+import { callingDevice } from "@/lib/security/device-me";
+import { holdExisting } from "@/lib/tasks/held";
+import { validateOrchestrated } from "@/lib/tasks/move-bundle";
+
+// POST /api/tasks/:id/hold - the paired device whose orchestrator started a
+// task here asks to hold it, as a move would have: for a queue-placed task
+// started before holding existed. It never starts a task.
+export async function POST(
+  request: NextRequest,
+  ctx: { params: Promise<{ id: string }> }
+) {
+  const id = (await ctx.params).id;
+  const device = callingDevice(request);
+  if (!device)
+    return NextResponse.json(
+      { error: "An orchestrator's task comes only from a paired machine" },
+      { status: 403 }
+    );
+  try {
+    const { orchestrated } = await request.json();
+    const held = holdExisting(id, device, validateOrchestrated(orchestrated));
+    return NextResponse.json({ held }, { status: held ? 200 : 404 });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 400 });
+  }
+}

package/app/api/tasks/route.ts

@@ -5,7 +5,12 @@ import { stampPriority, startOrQueue } from "@/lib/tasks/queue";
 import { isPriority } from "@/lib/tasks/schedule-types";
 import { TASK_CAPABILITIES } from "@/lib/tasks/remote";
 import { ensureProject, type ProjectRef } from "@/lib/tasks/project-ref";
-import { isSessionId, statusFor } from "@/lib/tasks/move-bundle";
+import { callingDevice } from "@/lib/security/device-me";
+import {
+  isSessionId,
+  statusFor,
+  validateOrchestrated,
+} from "@/lib/tasks/move-bundle";
 import { startView } from "@/lib/sessions/launch";
 import { isValidAgentType } from "@/lib/providers";
 import { isAgentModelName } from "@/lib/providers/registry";
@@ -43,6 +48,7 @@ export async function POST(request: NextRequest) {
       plan_only,
       priority,
       machine,
+      orchestrated,
     } = await request.json();
     if (id !== undefined && !isSessionId(id)) throw new Error("Bad task id");
     const pid =
@@ -81,7 +87,26 @@ export async function POST(request: NextRequest) {
       view: startView(view),
     };
     if (id !== undefined) {
-      const session = await createTask({ id, ...opts });
+      // An orchestrator's task is held for the paired device that sent it,
+      // as a moved one is (lib/tasks/held.ts).
+      const device = callingDevice(request);
+      let held;
+      if (orchestrated !== undefined) {
+        if (!device)
+          return NextResponse.json(
+            {
+              error: "An orchestrator's task comes only from a paired machine",
+            },
+            { status: 403 }
+          );
+        held = { device, orchestrated: validateOrchestrated(orchestrated) };
+      }
+      const session = await createTask({
+        id,
+        ...opts,
+        held,
+        startedByDevice: device ?? undefined,
+      });
       return NextResponse.json({ session }, { status: 201 });
     }
     const out = await startOrQueue(

package/lib/bus/index.ts

@@ -14,9 +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 { pauseHoldOf, pausedNote } from "../tasks/pause-hold";
-import { relayToHeldTask } from "../tasks/held-remote";
+import { isHeldRemote, relayToHeldTask } from "../tasks/held-remote";
 import {
   assertTakesMessages,
   findQueuedTarget,
@@ -210,7 +209,7 @@ export async function deliver(
 ): 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))
+  if (isHeldRemote(to))
     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.

package/lib/db/migrations.ts

@@ -2242,6 +2242,23 @@ export const migrations: Migration[] = [
       `);
     },
   },
+  {
+    key: "20261014T1235_placed_mirror_started_by",
+    up: (db) => {
+      // A task the queue started on a linked machine kept no record of the
+      // orchestrator that queued it, so it couldn't be read, messaged or
+      // stopped from there. Fills the mirror from the queue row; additive,
+      // only where the mirror has none.
+      db.exec(`
+        UPDATE sessions SET
+          started_by = (SELECT q.started_by FROM task_queue q WHERE q.id = sessions.id),
+          task_since = COALESCE(task_since, created_at)
+        WHERE started_by IS NULL AND task_prompt IS NOT NULL
+          AND host_id IS NOT NULL AND host_id != 'local'
+          AND (SELECT q.started_by FROM task_queue q WHERE q.id = sessions.id) IS NOT NULL
+      `);
+    },
+  },
   {
     key: "20261014T1600_queued_task_messages",
     up: (db) => {
@@ -2261,6 +2278,25 @@ export const migrations: Migration[] = [
       );
     },
   },
+  {
+    key: "20261014T1800_task_starter_device",
+    up: (db) => {
+      // The paired device that started a task over the API: the only one
+      // that may later hold it. Tasks already running have no record, so
+      // they're marked unrecorded. Additive.
+      const has = (
+        db.prepare(`PRAGMA table_info(sessions)`).all() as { name: string }[]
+      ).some((c) => c.name === "started_by_device");
+      if (!has)
+        db.exec(`ALTER TABLE sessions ADD COLUMN started_by_device TEXT`);
+      db.exec(`
+        UPDATE sessions SET started_by_device = 'unrecorded'
+        WHERE started_by_device IS NULL AND started_by IS NULL
+          AND held_by_device IS NULL AND task_status = 'running'
+          AND task_prompt IS NOT NULL AND (host_id IS NULL OR host_id = 'local')
+      `);
+    },
+  },
 ];
 
 // `upTo`: stop after this legacy id or timestamp key, inclusive (tests that

package/lib/db/types.ts

@@ -146,6 +146,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;
+  // The paired device that started this task here over the API.
+  started_by_device?: string | null;
   held_for?: string | null;
   held_for_name?: string | null;
   // A held task's "plan written" line, for its orchestrator to read.

package/lib/done/index.ts

@@ -31,7 +31,7 @@ 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 { doneHeldTask, isHeldRemote } from "../tasks/held-remote";
 import { captureMergedTask } from "../session-logs";
 import { sessionEnded } from "../experiments/hooks";
 import { pushMerged } from "../notify/push/events";
@@ -175,7 +175,7 @@ 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)) {
+  } else if (isHeldRemote(s)) {
     // 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);

package/lib/orchestrator/read.ts

@@ -10,7 +10,7 @@ import { hostLink } from "../hosts/remote-api";
 import { peerPane } from "../hosts/peer-sessions";
 import { workspaceSessions } from "./facts";
 import { untrusted } from "./untrusted";
-import { heldChatTail } from "../tasks/held-remote";
+import { heldChatTail, isHeldRemote } from "../tasks/held-remote";
 import {
   findExternalSession,
   knownExternalSession,
@@ -130,7 +130,7 @@ export async function readSession(
   const link = hostLink(s.host_id);
   if (s.view === "chat" && link) {
     // Its orchestrator's task is read through the machine that holds it.
-    const text = s.started_by ? await heldChatTail(s, n) : null;
+    const text = isHeldRemote(s) ? await heldChatTail(s, n) : null;
     return text
       ? `${s.name} (chat on ${link.hostName}), last ${n} lines:\n${untrusted(s.name, text)}`
       : `${s.name} (chat on ${link.hostName}): its messages are on that machine; open it to read them.`;

package/lib/orchestrator/task-state.ts

@@ -9,7 +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 { heldChatFacts, isHeldRemote } from "../tasks/held-remote";
 import { hostTasks } from "../tasks/remote";
 import { peerPane } from "../hosts/peer-sessions";
 import { untrusted } from "./untrusted";
@@ -88,7 +88,7 @@ async function peerChatWaiting(
   };
   // 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;
+  const facts = isHeldRemote(task) ? await heldChatFacts(task) : null;
   if (facts) {
     const { turn } = facts;
     return {

package/lib/sessions/stop.ts

@@ -2,7 +2,7 @@ import { endTmuxSession } from "../tmux/end";
 import { hostLink } from "../hosts/remote-api";
 import { stopChatTurn } from "../chat/stop";
 import type { Session } from "../db";
-import { stopHeldTask } from "../tasks/held-remote";
+import { isHeldRemote, stopHeldTask } from "../tasks/held-remote";
 import { releaseOnEnd } from "../simulator";
 import { forgetPlanWait } from "../models/plan-step";
 
@@ -21,12 +21,12 @@ export async function stopSession(
     | "tmux_name"
     | "started_by"
     | "task_prompt"
+    | "task_since"
   >
 ): Promise<string> {
   // A task its orchestrator moved to a linked machine stops through that
   // machine's AgentOS, chat or terminal.
-  if (s.started_by && s.task_prompt && hostLink(s.host_id))
-    return stopHeldTask(s);
+  if (isHeldRemote(s)) return stopHeldTask(s);
   if (s.view === "chat") {
     if (hostLink(s.host_id))
       throw new Error(

package/lib/tasks/held-remote.ts

@@ -4,43 +4,152 @@
  * orchestrator polls and calls; the other machine never reaches back.
  */
 
-import type { Session } from "../db";
+import { db, type Session } from "../db";
 import {
+  HostApiError,
   cleanRemoteBlock,
   cleanRemoteText,
   hostApi,
+  hostLink,
   requireHostLink,
 } from "../hosts/remote-api";
 import type { Delivery } from "../bus/delivery";
+import { wakeLine } from "../bus/format";
+import { orchestratedStart } from "./held";
 
 const path = (id: string, leaf: string) =>
   `/api/tasks/${encodeURIComponent(id)}/${leaf}`;
 
+/**
+ * A task its orchestrator put on a linked machine, whether by moving it or
+ * by the queue placing it there: the one test every relayed call goes by.
+ * (held-replies.ts reads the same rule in SQL: started_by IS NOT NULL.)
+ */
+export const isHeldRemote = (
+  s: Pick<Session, "started_by" | "task_prompt" | "host_id">
+): boolean => !!s.started_by && !!s.task_prompt && !!hostLink(s.host_id);
+
+type Held = Pick<
+  Session,
+  "id" | "name" | "host_id" | "started_by" | "task_since" | "task_prompt"
+>;
+
+const ADOPT_RETRY_MS = 5 * 60 * 1000;
+const STALE_MS = 24 * 60 * 60 * 1000;
+const g = globalThis as unknown as { __agentosAdopted?: Map<string, number> };
+const adopted = (g.__agentosAdopted ??= new Map());
+
+/**
+ * A task the queue placed before machines held them is unheld there, so its
+ * calls are refused as "No such held task". Asks the machine to hold it for
+ * this one, then sends what was left undelivered. False when it can't.
+ */
+async function adoptHeld(task: Held): Promise<boolean> {
+  const now = Date.now();
+  // Only failures are remembered, and only for the retry window.
+  for (const [id, at] of adopted)
+    if (now - at >= ADOPT_RETRY_MS) adopted.delete(id);
+  if (adopted.has(task.id)) return false;
+  adopted.set(task.id, now);
+  try {
+    const link = requireHostLink(task.host_id);
+    await hostApi(link, path(task.id, "hold"), {
+      body: {
+        orchestrated: orchestratedStart(
+          task.started_by!,
+          task.task_since ?? null
+        ),
+      },
+      timeout: 20000,
+    });
+  } catch {
+    return false;
+  }
+  adopted.delete(task.id);
+  await flushUndelivered(task);
+  return true;
+}
+
+/** The call, held first if that machine says it isn't, once. */
+async function withHold<T>(task: Held, call: () => Promise<T>): Promise<T> {
+  try {
+    return await call();
+  } catch (error) {
+    if (!(error instanceof HostApiError) || error.status !== 404) throw error;
+    if (!(await adoptHeld(task))) throw error;
+    return call();
+  }
+}
+
+/**
+ * Messages stored for the task while it couldn't be reached: sent now, each
+ * keyed by its stored id so one that did land isn't typed twice. Ones older
+ * than a day are marked read, not replayed into a later context.
+ */
+export async function flushUndelivered(
+  task: Pick<
+    Session,
+    "id" | "host_id" | "started_by" | "task_since" | "task_prompt" | "name"
+  >
+): Promise<void> {
+  const rows = db
+    .prepare(
+      `SELECT id, from_id, from_name, body, created_at FROM bus_messages
+       WHERE to_id = ? AND delivered_at IS NULL AND read_at IS NULL
+         AND held_pause_id IS NULL ORDER BY id`
+    )
+    .all(task.id) as {
+    id: number;
+    from_id: string | null;
+    from_name: string;
+    body: string;
+    created_at: string;
+  }[];
+  for (const m of rows) {
+    const age = Date.now() - Date.parse(`${m.created_at.replace(" ", "T")}Z`);
+    if (age > STALE_MS) {
+      db.prepare(
+        `UPDATE bus_messages SET read_at = datetime('now') WHERE id = ?`
+      ).run(m.id);
+      continue;
+    }
+    const line = wakeLine({
+      fromName: m.from_name,
+      fromId: m.from_id,
+      body: m.body,
+    });
+    const res = await relayToHeldTask(task, line, m.from_name, m.id, false);
+    if (res.state === "failed") return;
+    db.prepare(
+      `UPDATE bus_messages SET delivered_at = datetime('now') WHERE id = ?`
+    ).run(m.id);
+  }
+}
+
 /**
  * Delivered by that machine's AgentOS as a message from the orchestrator,
  * never as the user's own. Keyed by the stored message, so a retry that
  * already landed is not typed twice.
  */
 export async function relayToHeldTask(
-  to: Session,
+  to: Held,
   line: string,
   fromName: string,
-  messageId?: number
+  messageId?: number,
+  heal = true
 ): Promise<Delivery> {
   try {
     const link = requireHostLink(to.host_id);
-    const { state } = await hostApi<{ state?: unknown }>(
-      link,
-      path(to.id, "message"),
-      {
+    const send = () =>
+      hostApi<{ state?: unknown }>(link, path(to.id, "message"), {
         body: {
           id: messageId ? `bus-${messageId}` : undefined,
           line,
           from: fromName,
         },
         timeout: 20000,
-      }
-    );
+      });
+    const { state } = await (heal ? withHold(to, send) : send());
     return { state: state === "queued" ? "queued" : "delivered" };
   } catch (error) {
     const why = error instanceof Error ? error.message : String(error);
@@ -50,14 +159,16 @@ export async function relayToHeldTask(
 
 /** A held chat task's last lines of conversation, as that machine reads them. */
 export async function heldChatTail(
-  task: Session,
+  task: Held,
   lines: number
 ): Promise<string | null> {
   const link = requireHostLink(task.host_id);
-  const { text } = await hostApi<{ text?: unknown }>(
-    link,
-    `${path(task.id, "chat-tail")}?lines=${lines}`,
-    { timeout: 10000 }
+  const { text } = await withHold(task, () =>
+    hostApi<{ text?: unknown }>(
+      link,
+      `${path(task.id, "chat-tail")}?lines=${lines}`,
+      { timeout: 10000 }
+    )
   ).catch(() => ({ text: undefined }));
   // Whole lines, as a local read has them (read.ts caps and trims them).
   return typeof text === "string" ? cleanRemoteBlock(text, 16000) : null;
@@ -69,13 +180,15 @@ export async function heldChatTail(
  * which callers treat as unread, never as clear.
  */
 export async function heldChatFacts(
-  task: Pick<Session, "id" | "host_id">
+  task: Held
 ): 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 }
+  const res = await withHold(task, () =>
+    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;
@@ -87,23 +200,21 @@ export async function heldChatFacts(
 }
 
 /** Stops its agent there; its conversation and worktree are kept. */
-export async function stopHeldTask(
-  task: Pick<Session, "id" | "name" | "host_id">
-): Promise<string> {
+export async function stopHeldTask(task: Held): Promise<string> {
   const link = requireHostLink(task.host_id);
-  const { text } = await hostApi<{ text?: unknown }>(
-    link,
-    path(task.id, "stop"),
-    {
+  const { text } = await withHold(task, () =>
+    hostApi<{ text?: unknown }>(link, path(task.id, "stop"), {
       body: {},
       timeout: 30000,
-    }
+    })
   );
   return cleanRemoteText(text) || `Stopped ${task.name}.`;
 }
 
 /** Done there: its agent stops and its worktree goes. Never a merge. */
-export async function doneHeldTask(task: Session): Promise<void> {
+export async function doneHeldTask(task: Held): Promise<void> {
   const link = requireHostLink(task.host_id);
-  await hostApi(link, path(task.id, "done"), { body: {}, timeout: 120000 });
+  await withHold(task, () =>
+    hostApi(link, path(task.id, "done"), { body: {}, timeout: 120000 })
+  );
 }

package/lib/tasks/held.ts

@@ -5,7 +5,9 @@
  * a green CI, past the gates its orchestrator judges it by.
  */
 
+import os from "os";
 import { db, type Session } from "../db";
+import type { OrchestratedBundle } from "./move-bundle";
 
 export function holderRefusal(
   session: Pick<Session, "held_by_device" | "held_from">,
@@ -26,3 +28,107 @@ export function heldRefusal(
     .get(id) as Pick<Session, "held_by_device" | "held_from"> | undefined;
   return session ? holderRefusal(session, device) : null;
 }
+
+/** Holds a task here for the paired device that sent it, and the orchestrator there. */
+export function holdFor(
+  id: string,
+  holder: string,
+  held: {
+    heldFrom: string;
+    orchestrator?: { id: string; name: string };
+    since?: string | null;
+  }
+): void {
+  db.prepare(
+    `UPDATE sessions SET held_by_device = ?, held_from = ?, held_for = ?, held_for_name = ?,
+       task_since = COALESCE(?, task_since) WHERE id = ?`
+  ).run(
+    holder,
+    held.heldFrom,
+    held.orchestrator?.id ?? null,
+    held.orchestrator?.name ?? null,
+    held.since ?? null,
+    id
+  );
+}
+
+/**
+ * What a linked machine needs to hold a task this machine's orchestrator
+ * starts there: the same description a move carries, minus work already done.
+ */
+export function orchestratedStart(
+  startedBy: string,
+  since: string | null = new Date().toISOString()
+): OrchestratedBundle {
+  const o = db
+    .prepare(`SELECT name FROM sessions WHERE id = ?`)
+    .get(startedBy) as { name: string } | undefined;
+  return {
+    heldFrom: os.hostname(),
+    since,
+    modelProvider: null,
+    modelOverrides: null,
+    planPhase: null,
+    planFile: null,
+    orchestrator: o ? { id: startedBy, name: o.name } : undefined,
+  };
+}
+
+/** Stands in for a starter nobody recorded: tasks already running when starters began to be recorded. */
+const UNRECORDED_STARTER = "unrecorded";
+
+/** Records the paired device that started a task here, the only one that may later hold it. */
+export function recordStarter(id: string, device: string): void {
+  db.prepare(`UPDATE sessions SET started_by_device = ? WHERE id = ?`).run(
+    device,
+    id
+  );
+}
+
+type Holdable = Pick<
+  Session,
+  | "held_by_device"
+  | "started_by"
+  | "started_by_device"
+  | "task_status"
+  | "host_id"
+  | "task_prompt"
+>;
+
+/**
+ * Whether `device` may hold this task: a running task on this machine that
+ * nobody here (an orchestrator or a person) owns, which that device started.
+ */
+export function mayHold(s: Holdable, device: string): boolean {
+  if (!s.task_prompt || s.task_status !== "running") return false;
+  if (s.host_id && s.host_id !== "local") return false;
+  if (s.started_by || s.held_by_device) return false;
+  return (
+    s.started_by_device === device || s.started_by_device === UNRECORDED_STARTER
+  );
+}
+
+/**
+ * Holds a task already running here for the device that started it, and the
+ * orchestrator there. False when there's no such running task; a task this
+ * device didn't start, one an orchestrator here owns, or one another device
+ * holds is refused. Holding the same task again is a no-op.
+ */
+export function holdExisting(
+  id: string,
+  device: string,
+  held: Parameters<typeof holdFor>[2]
+): boolean {
+  const s = db
+    .prepare(
+      `SELECT held_by_device, started_by, started_by_device, task_status, host_id, task_prompt
+       FROM sessions WHERE id = ?`
+    )
+    .get(id) as Holdable | undefined;
+  if (!s?.task_prompt || s.task_status !== "running") return false;
+  if (s.held_by_device === device) return true;
+  if (!mayHold(s, device))
+    throw new Error("Only the machine that started this task can hold it");
+  holdFor(id, device, held);
+  return true;
+}

package/lib/tasks/import.ts

@@ -28,6 +28,7 @@ import { expandHome } from "./session";
 import { ensureProject } from "./project-ref";
 import { checkoutBranchWorktree } from "./branch-worktree";
 import { rewritePaths, writeTranscript } from "./transcript";
+import { holdFor } from "./held";
 import { stepProgress } from "./move-progress";
 import { dropChat, unpackChat } from "./move-chat";
 import { sendChat, stopChat } from "../chat/runner";
@@ -171,20 +172,12 @@ async function arrive(
       // Held for the orchestrator's device. The orchestrator's own state
       // (started_by, its gates) never comes from the bundle: it stays on its
       // machine, and a task coming back takes it from the mirror's record.
-      if (holder)
+      if (holder) {
+        holdFor(id, holder, orch);
         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
-        );
+          `UPDATE sessions SET model_provider = ?, model_overrides = ? WHERE id = ?`
+        ).run(orch.modelProvider, orch.modelOverrides, id);
+      }
     }
     carryTaskState(bundle.moveId, id);
   })();

package/lib/tasks/index.ts

@@ -47,7 +47,8 @@ import {
   type TaskState,
 } from "./state";
 import { expandHome, prFor, storedPR, taskSessions } from "./session";
-import { InProgressError } from "./move-bundle";
+import { InProgressError, type OrchestratedBundle } from "./move-bundle";
+import { holdFor, mayHold, recordStarter } from "./held";
 import { nameFor } from "../session-titles";
 import { taskSetupOf, type TaskSetup } from "./setup";
 import { taskPlan } from "./plan-view";
@@ -160,10 +161,24 @@ export async function createTask(opts: {
   // How its agent runs: as a chat (the default, DEFAULT_START_VIEW) or in
   // a terminal.
   view?: StartView;
+  // Started by another machine's orchestrator, which this one holds it for
+  // (held.ts): that machine's paired device and its description of the task.
+  held?: { device: string; orchestrated: OrchestratedBundle };
+  // The paired device that sent this keyed start: the only one that may hold it later.
+  startedByDevice?: string;
 }): Promise<Session> {
   if (opts.id) {
     const existing = queries.getSession(db).get(opts.id) as Session | undefined;
-    if (existing?.task_status) return existing;
+    if (existing?.task_status) {
+      // A retry of a start that wasn't held holds it now, for the device
+      // that started it and no other.
+      if (opts.held && existing.held_by_device !== opts.held.device) {
+        if (!mayHold(existing, opts.held.device))
+          throw new Error("That id is taken");
+        holdFor(existing.id, opts.held.device, opts.held.orchestrated);
+      }
+      return existing;
+    }
     if (existing) throw new Error("That id is taken");
     if (starting.has(opts.id))
       throw new InProgressError("That task is starting already");
@@ -234,6 +249,7 @@ async function startTask(
       model: typeof opts.model === "string" ? opts.model : undefined,
       baseBranch: opts.baseBranch,
       view,
+      startedBy: opts.startedBy,
     });
     opts.onCreated?.(session.id);
     return session;
@@ -321,6 +337,9 @@ async function startTask(
     opts.startedBy ?? null,
     id
   );
+  const starter = opts.held?.device ?? opts.startedByDevice;
+  if (starter) recordStarter(id, starter);
+  if (opts.held) holdFor(id, opts.held.device, opts.held.orchestrated);
   opts.onCreated?.(id);
   void naming.refine?.(id);
 

package/lib/tasks/move-bundle.ts

@@ -127,7 +127,9 @@ function validateChat(c: ChatBundle): ChatBundle {
 
 const PHASES = ["planning", "implementing"];
 
-function validateOrchestrated(o: OrchestratedBundle): OrchestratedBundle {
+export function validateOrchestrated(
+  o: OrchestratedBundle
+): OrchestratedBundle {
   if (!o || typeof o !== "object") throw new Error("Bad orchestrated task");
   if (
     !isStrOrNull(o.since) ||

package/lib/tasks/move-flow.ts

@@ -18,7 +18,7 @@ import { sessionWorkspace } from "../models/resolve";
 import { arrived as arrivedHere, importTask } from "./import";
 import {
   forgetHostTasks,
-  hostTasks,
+  requireCapability,
   postIdempotent,
   unknownOutcome,
 } from "./remote";
@@ -88,25 +88,6 @@ export async function moveTask(id: string, toHostId: string): Promise<Session> {
   }
 }
 
-// A machine on an older AgentOS would take a chat task as a terminal one,
-// or an orchestrator's task as a plain one that anyone there could merge, or
-// refuse to hand one over.
-async function requireCapability(
-  link: HostLink,
-  capability: string,
-  what: string
-): Promise<void> {
-  const { capabilities = [] } = await hostTasks(link, true).catch((err) => {
-    throw new Error(
-      `Can't ask ${link.hostName} whether it takes ${what}: ${(err as Error).message}`
-    );
-  });
-  if (!capabilities.includes(capability))
-    throw new Error(
-      `${link.hostName}'s AgentOS can't move ${what} yet; update it first`
-    );
-}
-
 const requireChatMoves = (link: HostLink) =>
   requireCapability(link, "chat-move", "chat tasks");
 

package/lib/tasks/placement.ts

@@ -151,6 +151,8 @@ export interface PeerOption {
   name: string;
   view: MachineView;
   capabilities: string[];
+  // It can hold an orchestrator's task (false: an older AgentOS). Unset: yes.
+  holds?: boolean;
   // The project exists there (projectMachines said null).
   hasProject: boolean;
   loadPerCore: number;

package/lib/tasks/queue.ts

@@ -74,7 +74,8 @@ import {
   viewOf,
 } from "../load/machines";
 import { peerReading, peerSource, refreshPeers } from "../hosts/peer-load";
-import { linkedHostIds } from "../hosts/remote-api";
+import { hostLink, linkedHostIds } from "../hosts/remote-api";
+import { hostTasks } from "./remote";
 import { projectMachines } from "../hosts/project-machines";
 import { claimResume, dueResumes } from "./pause";
 
@@ -829,6 +830,20 @@ async function peerOptions(
   const hostIds = [...linkedHostIds()];
   if (!hostIds.length || !rows.length) return out;
   await refreshPeers(hostIds, now);
+  // Whether each machine can hold an orchestrator's task (an older AgentOS
+  // can't, and would fail its start); unreadable counts as no.
+  const holds = new Map<string, boolean>();
+  await Promise.all(
+    hostIds.map(async (hostId) => {
+      const link = hostLink(hostId);
+      const caps = link
+        ? await hostTasks(link)
+            .then((t) => t.capabilities ?? [])
+            .catch(() => [])
+        : [];
+      holds.set(hostId, caps.includes("held-start"));
+    })
+  );
   const perProject = new Map<string, Record<string, string | null>>();
   for (const r of rows) {
     if (out.has(r.project_id)) continue;
@@ -850,6 +865,7 @@ async function peerOptions(
           name: src.label,
           view: viewOf(src, now),
           capabilities: src.capabilities,
+          holds: holds.get(hostId) ?? false,
           hasProject: can[hostId] === null,
           loadPerCore: reading ? reading.load1 / reading.cores : 99,
         };
@@ -925,7 +941,7 @@ export async function tickOnce(now = Date.now()): Promise<"stale" | void> {
     )) {
       const r = rows.find((x) => x.id === c.id)!;
       const options = (peers.get(r.project_id) ?? []).filter(
-        (p) => !taken.has(p.hostId)
+        (p) => !taken.has(p.hostId) && (!r.started_by || p.holds !== false)
       );
       const spot = place(c, home, options, built.get(c.id)!.needs, now);
       if (!spot) continue;

package/lib/tasks/remote.ts

@@ -15,6 +15,7 @@ import {
 } from "../hosts/remote-api";
 import { isRemoteHost } from "../hosts";
 import { projectRef } from "./project-ref";
+import { orchestratedStart } from "./held";
 import type { TaskStatus } from "./state";
 import type { TaskView } from "./index";
 
@@ -33,6 +34,9 @@ export const TASK_CAPABILITIES = [
   // A held task's chat facts and its messages for its orchestrator.
   "held-chat-facts",
   "held-replies",
+  // A keyed start that carries an orchestrator's description holds the task
+  // for the device that sent it, as a move does (lib/tasks/held.ts).
+  "held-start",
 ] as const;
 
 export interface HostTasks {
@@ -48,7 +52,8 @@ export function isMirror(session: Session): boolean {
 export function mirrorTask(
   hostId: string,
   projectId: string | null,
-  remote: Session
+  remote: Session,
+  startedBy?: string | null
 ): void {
   db.prepare(
     `INSERT INTO sessions (id, name, tmux_name, working_directory, model, group_path,
@@ -71,6 +76,35 @@ export function mirrorTask(
     // As that machine runs it: one that predates chat tasks says terminal.
     remote.view === "chat" ? "chat" : "terminal"
   );
+  // What carryTaskState gives a moved task's mirror: the orchestrator that
+  // holds it, and when it began (so its PR is judged from then).
+  if (startedBy)
+    db.prepare(
+      `UPDATE sessions SET started_by = COALESCE(started_by, ?),
+         task_since = COALESCE(task_since, created_at) WHERE id = ?`
+    ).run(startedBy, remote.id);
+}
+
+/**
+ * A machine on an older AgentOS would take a chat task as a terminal one,
+ * or an orchestrator's task as a plain one that anyone there could merge, or
+ * refuse to hand one over.
+ */
+export async function requireCapability(
+  link: HostLink,
+  capability: string,
+  what: string,
+  verb = "move"
+): Promise<void> {
+  const { capabilities = [] } = await hostTasks(link, true).catch((err) => {
+    throw new Error(
+      `Can't ask ${link.hostName} whether it takes ${what}: ${(err as Error).message}`
+    );
+  });
+  if (!capabilities.includes(capability))
+    throw new Error(
+      `${link.hostName}'s AgentOS can't ${verb} ${what} yet; update it first`
+    );
 }
 
 export const unknownOutcome = (err: unknown) =>
@@ -101,16 +135,30 @@ export async function startRemoteTask(
     model?: string;
     baseBranch?: string;
     view?: "chat" | "terminal";
+    // The orchestrator that started it: that machine holds the task for it.
+    startedBy?: string | null;
   }
 ): Promise<Session> {
   const link = requireHostLink(hostId);
+  const { startedBy, ...rest } = opts;
+  if (startedBy)
+    await requireCapability(
+      link,
+      "held-start",
+      "an orchestrator's task",
+      "hold"
+    );
   const { session } = await postIdempotent<{ session: Session }>(
     link,
     "/api/tasks",
-    { project: await projectRef(project), ...opts },
+    {
+      project: await projectRef(project),
+      ...rest,
+      orchestrated: startedBy ? orchestratedStart(startedBy) : undefined,
+    },
     180000
   );
-  mirrorTask(hostId, project.id, session);
+  mirrorTask(hostId, project.id, session, startedBy);
   forgetHostTasks(hostId);
   return db
     .prepare(`SELECT * FROM sessions WHERE id = ?`)

package/package.json

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