@saadnvd1/agent-os 0.3.518 → 0.3.520

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/index.ts

@@ -100,6 +100,8 @@ export interface TaskView {
   // plan step (lib/models).
   model?: string;
   planning?: boolean;
+  // A plan-only task's plan is written and waits for approval.
+  planReady?: boolean;
   // What its starter decided about a plan step, and why; null if unstated.
   // Its plan: ready to read or approve, with a title and capped text.
   plan?: TaskPlan | null;
@@ -128,6 +130,8 @@ export async function createTask(opts: {
   plan?: boolean;
   // Why the starter chose to plan or not: shown on the task's card.
   planReason?: string | null;
+  // Stop after the plan and wait for approval (implies plan).
+  planOnly?: boolean;
   // The orchestrator session that started it (null: a person).
   startedBy?: string | null;
   // Started from this LumifyHub card, which the task then moves.
@@ -198,6 +202,8 @@ async function startTask(
   const hostId = opts.hostId ?? project.host_id;
   const view = opts.view ?? DEFAULT_START_VIEW;
   if (isRemoteHost(hostId)) {
+    if (opts.planOnly)
+      throw new Error("A plan-only task runs on this machine for now");
     if (opts.base || opts.cardId)
       throw new Error(
         "Stacked and card tasks run on this machine only for now"
@@ -216,11 +222,18 @@ async function startTask(
 
   if (opts.baseBranch !== undefined && !isBranchName(opts.baseBranch))
     throw new Error(`"${opts.baseBranch}" isn't a branch name`);
+  if (opts.planOnly && opts.plan === false)
+    throw new Error(
+      "planOnly implies plan; it can't be combined with plan false"
+    );
+  if (opts.planOnly && view !== "chat")
+    throw new Error("A plan-only task needs a chat, not a terminal");
   const routing = taskRouting(
     project.workspace_id,
     view,
     opts.model,
-    opts.plan
+    opts.plan,
+    opts.planOnly
   );
   const projectPath = expandHome(project.working_directory);
   const naming = await nameFor(prompt, projectPath, opts.name);
@@ -266,7 +279,7 @@ async function startTask(
   // Everything the launch needs is on the row, so a restart can resume it.
   db.prepare(
     `UPDATE sessions SET task_prompt = ?, task_brief = ?, task_status = 'running', setup_status = 'running', name_source = ?, view = ?,
-       model_provider = ?, model_overrides = ?, plan_phase = ?,
+       model_provider = ?, model_overrides = ?, plan_phase = ?, plan_only = ?,
        plan_decided = ?, plan_reason = ?, started_by = ? WHERE id = ?`
   ).run(
     prompt,
@@ -280,7 +293,8 @@ async function startTask(
     routing.first.provider.id === ANTHROPIC ? null : routing.first.provider.id,
     routing.override ? JSON.stringify(routing.override) : null,
     routing.plan ? "planning" : null,
-    opts.plan === undefined ? null : opts.plan ? 1 : 0,
+    routing.planOnly ? 1 : null,
+    routing.planOnly ? 1 : opts.plan === undefined ? null : opts.plan ? 1 : 0,
     opts.planReason?.trim() || null,
     opts.startedBy ?? null,
     id
@@ -356,8 +370,10 @@ export async function taskView(session: Session): Promise<TaskView> {
     sessionStatus !== undefined
       ? await shellOnly(session.tmux_name)
       : false;
+  const planReady = live && session.plan_phase === "awaiting";
+  // A plan waiting for approval isn't a question the agent asked.
   const blocked =
-    live && sessionStatus === "waiting"
+    live && sessionStatus === "waiting" && !planReady
       ? blockedReason(
           chat
             ? saidSinceLastMessage(session.id)
@@ -373,6 +389,7 @@ export async function taskView(session: Session): Promise<TaskView> {
     sessionStatus: agentGone ? "dead" : sessionStatus,
     pr,
     blocked: blocked !== null,
+    planReady,
     settingUp: setup?.status === "running" || setup?.status === "held",
   });
   syncTaskCardInBackground(session, state, pr);
@@ -399,6 +416,7 @@ export async function taskView(session: Session): Promise<TaskView> {
     armed: !!session.merge_armed_at,
     model: sessionModelRef(session),
     planning: session.plan_phase === "planning",
+    planReady,
     plan: taskPlan(session),
     quickOf: session.quick_of ?? null,
     lastActiveAt: session.held_by_device ? lastActiveOf(session) : undefined,
@@ -443,20 +461,23 @@ export function taskRouting(
   workspaceId: string | null,
   view: StartView,
   model: unknown,
-  plan?: boolean
+  plan?: boolean,
+  planOnly?: boolean
 ) {
   const override = parseOverride(model);
   const models = effectiveModels();
   const opts = { workspaceId, override };
   const implement = resolveRole("implement", opts, models);
   const planning = resolveRole("plan", opts, models);
+  // Plan only plans even on one model: the stop is the point, not a switch.
   const planStep =
     view === "chat" &&
-    (plan ?? models.planStep) &&
-    planning.ref !== implement.ref;
+    (!!planOnly ||
+      ((plan ?? models.planStep) && planning.ref !== implement.ref));
   return {
     override,
     plan: planStep,
+    planOnly: planStep && !!planOnly,
     first: planStep ? planning : implement,
   };
 }

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-guard.ts

@@ -25,6 +25,8 @@ export function moveRefusal(session: Session): string | null {
     return "It's a quick change its orchestrator makes on this machine, so it stays here";
   if (escalations(session.id).length)
     return "It's waiting on you (an escalated gate), so it stays here";
+  if (session.plan_only && session.plan_phase !== "implementing")
+    return "It's a plan-only task that hasn't been approved, so it stays here";
   const ask = db
     .prepare(
       `SELECT 1 FROM orchestrator_asks WHERE subject IN (?, ?) AND status = 'open' LIMIT 1`

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 {
@@ -123,8 +137,13 @@ function orchestratedBundle(session: Session): OrchestratedBundle {
     since: isoUTC(session.task_since ?? session.created_at),
     modelProvider: session.model_provider ?? null,
     modelOverrides: session.model_overrides ?? null,
-    planPhase: session.plan_phase ?? null,
+    // moveRefusal keeps an unapproved plan-only task here.
+    planPhase: (session.plan_phase ?? null) as
+      | "planning"
+      | "implementing"
+      | 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/plan-view.ts

@@ -102,7 +102,12 @@ export function taskPlan(session: Session): TaskPlan | null {
       return {
         ...base,
         planned: true,
-        status: phase === "planning" ? "writing" : "approved",
+        status:
+          phase === "planning"
+            ? "writing"
+            : phase === "awaiting"
+              ? "ready"
+              : "approved",
         source: "step",
         title: planTitle(body),
         path: text !== null ? PLAN_FILE : null,

package/lib/tasks/queue.ts

@@ -48,6 +48,7 @@ export interface QueueRow {
   // orchestrator session that started it.
   plan: number | null;
   plan_reason: string | null;
+  plan_only: number | null;
   started_by: string | null;
   view: "chat" | "terminal" | null;
   base_branch: string | null;
@@ -222,6 +223,7 @@ export interface QueueRequest {
   model?: ModelOverride;
   plan?: boolean;
   planReason?: string | null;
+  planOnly?: boolean;
   startedBy?: string | null;
   view?: "chat" | "terminal";
   baseBranch?: string;
@@ -277,9 +279,9 @@ export function queueIfNeeded(req: QueueRequest): QueuedTaskView | null {
   if (!req.prompt.trim()) throw new Error("Describe the task");
   const id = randomUUID();
   db.prepare(
-    `INSERT INTO task_queue (id, project_id, prompt, name, model, model_overrides, plan, plan_reason, started_by, view, base_branch,
+    `INSERT INTO task_queue (id, project_id, prompt, name, model, model_overrides, plan, plan_reason, plan_only, started_by, view, base_branch,
        host_id, after_task, after_any, origin_workspace_id, position)
-     VALUES (@id, @project_id, @prompt, @name, @model, @model_overrides, @plan, @plan_reason, @started_by, @view, @base_branch,
+     VALUES (@id, @project_id, @prompt, @name, @model, @model_overrides, @plan, @plan_reason, @plan_only, @started_by, @view, @base_branch,
        @host_id, @after_task, @after_any, @origin,
        (SELECT COALESCE(MAX(position), 0) + 1 FROM task_queue))`
   ).run({
@@ -294,6 +296,7 @@ export function queueIfNeeded(req: QueueRequest): QueuedTaskView | null {
         : null,
     plan: req.plan === undefined ? null : req.plan ? 1 : 0,
     plan_reason: req.planReason?.trim() || null,
+    plan_only: req.planOnly ? 1 : null,
     started_by: req.startedBy ?? null,
     view: req.view ?? null,
     base_branch: req.baseBranch || null,
@@ -472,6 +475,7 @@ async function startRow(
       : (r.model ?? undefined),
     plan: r.plan == null ? undefined : !!r.plan,
     planReason: r.plan_reason,
+    planOnly: !!r.plan_only,
     startedBy: r.started_by,
     view: r.view ?? undefined,
     baseBranch: r.base_branch ?? undefined,

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/lib/tasks/start.ts

@@ -141,7 +141,7 @@ export async function finishTaskStart(
   const task = (session.task_prompt ?? "") + setupNote(setup);
   const planning = session.plan_phase === "planning";
   if (planning) preparePlanDir(session.worktree_path);
-  const prompt = planning ? planPrompt(task) : task;
+  const prompt = planning ? planPrompt(task, !!session.plan_only) : task;
   try {
     if (session.view === "chat") await launchChat(sessionId, prompt);
     else {

package/lib/tasks/state.ts

@@ -41,6 +41,8 @@ export type TaskState =
   | "blocked"
   | "review"
   | "checks-failing"
+  // A plan-only task's plan is written; it waits for approval.
+  | "plan-ready"
   | "exited"
   | "merged"
   | "dropped"
@@ -56,11 +58,14 @@ export interface TaskStateInput {
   blocked: boolean;
   // Its worktree is still being set up; the agent hasn't started yet.
   settingUp?: boolean;
+  // plan_phase "awaiting": no agent runs, and none is needed.
+  planReady?: boolean;
 }
 
 // Ordered by what needs the human first.
 export function deriveTaskState(input: TaskStateInput): TaskState {
-  const { taskStatus, sessionStatus, pr, blocked, settingUp } = input;
+  const { taskStatus, sessionStatus, pr, blocked, settingUp, planReady } =
+    input;
   if (taskStatus === "merged" || pr?.state === "MERGED") return "merged";
   if (taskStatus === "dropped") return "dropped";
   if (taskStatus === "done" || taskStatus === "moved") return "done";
@@ -70,6 +75,7 @@ export function deriveTaskState(input: TaskStateInput): TaskState {
   if (pr?.state === "OPEN") {
     return pr.checks === "fail" ? "checks-failing" : "review";
   }
+  if (planReady && sessionStatus !== "running") return "plan-ready";
   if (!sessionStatus || sessionStatus === "dead") return "exited";
   if (sessionStatus === "running") return "working";
   return "needs-input";

package/package.json

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