@saadnvd1/agent-os 0.3.519 → 0.3.521

package/lib/orchestrator/act.ts

@@ -33,6 +33,8 @@ import { treeOrder } from "../stacks/tree";
 import type { StackItemView } from "../stacks/types";
 import { doneSession } from "../done";
 import { amendBrief, amendmentsOf } from "./amendments";
+import type { Session } from "../db";
+import { approvePlanNow } from "../models/plan-step";
 import { braked } from "./brakes";
 import { getOrchestrator } from "./home";
 import { addNote } from "./notes";
@@ -99,9 +101,12 @@ export async function startTask(
     after?: string;
     model?: ModelOverride;
     plan?: boolean;
+    planOnly?: boolean;
     planReason?: string;
   } = {}
 ): Promise<string> {
+  if (opts.planOnly && opts.plan === false)
+    throw new Error("plan_only implies plan; pass plan true");
   const project = workspaceProject(workspaceId, projectRef);
   const model = parseOverride(opts.model) ?? undefined;
   const startedBy = orchestratorId(workspaceId);
@@ -121,6 +126,7 @@ export async function startTask(
       view,
       model,
       plan: opts.plan,
+      planOnly: opts.planOnly,
       planReason: opts.planReason,
       startedBy,
       baseBranch: opts.base || undefined,
@@ -140,6 +146,7 @@ export async function startTask(
             view,
             model,
             plan: opts.plan,
+            planOnly: opts.planOnly,
             planReason: opts.planReason,
             startedBy,
           }),
@@ -151,11 +158,26 @@ export async function startTask(
     return `Queued (position ${queued.position}) task "${queued.name}" (id ${queued.id.slice(0, 8)}) in ${project.name}${queued.after ? `, after ${queued.after}` : ""}. It starts by itself; you'll get an event when it does.`;
   }
   const task = out.started;
+  const planOnlyNote = opts.planOnly
+    ? " Plan only: it stops after the plan and waits; approve_plan continues it, drop rejects it."
+    : "";
   const skipped =
-    opts.plan && task.plan_phase !== "planning"
+    opts.plan && !opts.planOnly && task.plan_phase !== "planning"
       ? ` Plan step skipped: ${view === "terminal" ? "a terminal task has none" : "planning and implementation use the same model"}.`
       : "";
-  return `Started task "${task.name}" (id ${task.id.slice(0, 8)}, ${view}) in ${project.name} on ${task.branch_name} (from ${task.base_branch}). It ends in a PR; you'll get an event when it opens.${skipped}`;
+  return `Started task "${task.name}" (id ${task.id.slice(0, 8)}, ${view}) in ${project.name} on ${task.branch_name} (from ${task.base_branch}). It ends in a PR; you'll get an event when it opens.${skipped}${planOnlyNote}`;
+}
+
+// The orchestrator approves a plan-only task's plan; a message amends it.
+export async function approveTaskPlan(
+  task: Session,
+  message?: string
+): Promise<string> {
+  const out = await approvePlanNow(task.id, message);
+  const amended = message
+    ? ` Recorded as scope change ${out.amendments} on its brief: its review judges against it.`
+    : "";
+  return `Approved the plan of ${task.name}: implementing on ${out.ref}.${amended}`;
 }
 
 export async function startSession(

package/lib/orchestrator/brief.ts

@@ -41,6 +41,7 @@ You may act without asking on anything inside this workspace that's additive or
 Before you start work, decide what it needs, and hand it to the cheapest model that can do it.
 - Small and clear (a known change, a few files, nothing to discover): start_task with plan false and a plan_reason saying why. Write the steps into the prompt yourself, from what Saad or the card said; do not read code in your own context to do it.
 - Big, unclear or cross-cutting (many files, a design choice, unknown ground): start_task with plan true and a plan_reason. The planning model writes the plan, then the implementation model carries it out; you get one event with the plan file's path and a short summary when it is written.
+- Saad (or the card) says plan only, or you want to see a plan before any code is written: start_task with plan_only true (it implies plan true). It writes the plan and then stops: no implementation model, no implement prompt. You get one event with the plan file's path and a short summary saying it is waiting for approval. While it waits it isn't blocked and isn't idle; read the plan, then \`approve_plan\` (a message amends the plan and is recorded as a scope change, so the review judges against it) or \`drop\` it.
 - Not in a repository (research, a document, a machine task): start_session, which runs on the implementation model, with the steps in the prompt.
 - Implementation on Opus only when the work needs deep reasoning (a subtle concurrency or security change, say). Pass model and say why. Sonnet is the default.
 
@@ -102,7 +103,8 @@ Reading:
 Acting:
 - \`${TOOL_NAMES.send}\` (session, message, scope_change?): message a session; it arrives as its next prompt. scope_change records it on the task's brief for its review.
 - \`${TOOL_NAMES.message_orchestrator}\` (workspace, message): message another workspace's orchestrator, the only thing you reach outside this workspace. Use it to hand over a bug or ask for something in its projects; it decides what to do there.
-- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, model?, plan, plan_reason): a task in its own worktree that ends in a PR. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
+- \`${TOOL_NAMES.start_task}\` (project, prompt, base?, name?, view?, after?, model?, plan, plan_only?, plan_reason): a task in its own worktree that ends in a PR. Write the prompt as a full brief; name it in 2-6 words, or it's named from the prompt. It runs as a chat; pass view terminal only when the job needs a TUI. Pass after (a task's id or name, or "any") to hold it until that task finishes, instead of remembering it in your notes. Over the workspace's running task limit it's queued too: the result says "Queued (position N)", it starts by itself, and you get an event when it does. Its models follow the role settings (it plans on the planning model, then implements on the implementation one); State plan and plan_reason for every task (see "Triage every job"). Pass model ("provider/model", or a map of role to one) only when Saad asks for one, or to put implementation on Opus when the work needs deep reasoning (say why in plan_reason or a note); another provider than anthropic only when Saad asks.
+- \`${TOOL_NAMES.approve_plan}\` (task, message?): continue a plan_only task whose plan is ready; it implements on the implementation model, once. message amends the plan and is recorded on the task's brief as a scope change. Reject a plan with drop.
 - \`${TOOL_NAMES.set_task_model}\` (task, model, message?): move a paused task to another model and carry on in the same conversation and worktree; it keeps that model from then on. Only when Saad asks.
 - \`${TOOL_NAMES.start_session}\` (project, prompt, name?, view?, model?): a session without a worktree or PR, a chat unless view is terminal. It runs on the implementation model (Sonnet) unless you pass model; use it for work outside a repository, with the steps in the prompt.
 - \`${TOOL_NAMES.quick_change}\` (project, name): a worktree and branch cut from the project's default branch for a small, low-risk edit you make yourself: a typo, a config value, a one-file fix. It returns the worktree's path; edit there with Write and Edit, and run git there only as \`git -C <path> <status|diff|log|show|add|rm|mv|restore|reset>\`. Anything that needs real work, tests or a long investigation is a task: start_task. At most a few open at once.

package/lib/orchestrator/conditions.ts

@@ -135,6 +135,7 @@ function sessionConditions(
     shouldPR &&
     !pr &&
     !finished &&
+    !f.plan?.awaiting &&
     f.status !== "running" &&
     idleFor >= IDLE_NO_PR_MS
   )

package/lib/orchestrator/describe.ts

@@ -39,7 +39,7 @@ function sessionLine(f: SessionFacts): string {
   }
   if (f.plan)
     parts.push(
-      `${f.plan.planned ? "planned" : "no plan"}${f.plan.reason ? `: ${untrusted(f.name, f.plan.reason)}` : ""}`
+      `${f.plan.awaiting ? "plan ready, awaiting your approve_plan" : f.plan.planned ? "planned" : "no plan"}${f.plan.reason ? `: ${untrusted(f.name, f.plan.reason)}` : ""}`
     );
   if (f.stack) {
     const card = f.stack.ticket ? ` ${f.stack.ticket}` : "";

package/lib/orchestrator/facts.ts

@@ -50,7 +50,12 @@ export interface SessionFacts {
   // A quick change the orchestrator makes itself (quick.ts): no agent.
   quick?: boolean;
   // The orchestrator's call on a plan step, with its reason, when stated.
-  plan?: { planned: boolean; reason: string | null } | null;
+  plan?: {
+    planned: boolean;
+    reason: string | null;
+    // A plan-only task's plan is written; it waits for approve_plan.
+    awaiting?: boolean;
+  } | null;
   task: {
     state: TaskState;
     pr: TaskPR | null;
@@ -344,7 +349,11 @@ export async function sessionFacts(
         plan:
           s.plan_decided == null
             ? null
-            : { planned: !!s.plan_decided, reason: s.plan_reason ?? null },
+            : {
+                planned: !!s.plan_decided,
+                reason: s.plan_reason ?? null,
+                awaiting: s.plan_phase === "awaiting",
+              },
         task,
         stack: stackOf(s.id),
       };

package/lib/orchestrator/serve.ts

@@ -2,6 +2,7 @@ import { resumeOnModel } from "../models/resume";
 import { workspaceTask } from "./targets";
 import { getWorkspace } from "../workspaces";
 import {
+  approveTaskPlan,
   done,
   drop,
   moveTaskTo,
@@ -48,6 +49,7 @@ const ACTING = new Set<ToolName>([
   "land",
   "drop",
   "move",
+  "approve_plan",
   "stop",
   "done",
   "review",
@@ -114,9 +116,15 @@ export async function runTool(
         after: a.after,
         model: a.model,
         plan: a.plan,
+        planOnly: a.plan_only,
         planReason: a.plan_reason,
       });
     }
+    case "approve_plan": {
+      const a = p(tool, raw);
+      const task = workspaceTask(w, a.task);
+      return approveTaskPlan(task, a.message);
+    }
     case "set_task_model": {
       const a = p(tool, raw);
       const task = workspaceTask(w, a.task);

package/lib/orchestrator/tool-names.ts

@@ -22,6 +22,7 @@ export const TOOL_NAMES = {
   stack: name("stack"),
   stack_status: name("stack_status"),
   land: name("land"),
+  approve_plan: name("approve_plan"),
   drop: name("drop"),
   move: name("move"),
   stop: name("stop"),

package/lib/orchestrator/tool-schemas.ts

@@ -121,6 +121,12 @@ export const TOOL_SHAPES = {
       .describe(
         "Your decision for this job: true to plan first on the planning model, then implement on the implementation model; false to skip the plan and put the steps in the prompt yourself"
       ),
+    plan_only: z
+      .boolean()
+      .optional()
+      .describe(
+        "true: write the plan on the planning model, then stop and wait; implementation starts only when you approve_plan it (drop rejects it). Implies plan true"
+      ),
     plan_reason: z
       .string()
       .trim()
@@ -192,6 +198,18 @@ export const TOOL_SHAPES = {
   },
   stack_status: { id: stackId },
   land: { id: stackId },
+  approve_plan: {
+    task,
+    message: z
+      .string()
+      .trim()
+      .min(1)
+      .max(8000)
+      .optional()
+      .describe(
+        "Amends the plan: recorded on the task's brief as a scope change, so its review judges the PR against it. Only for a change Saad made"
+      ),
+  },
   drop: { task, reason: z.string().trim().min(1).max(2000) },
   move: {
     task,

package/lib/orchestrator/tools.ts

@@ -62,7 +62,7 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   message_orchestrator:
     "Message another workspace's orchestrator, by workspace name; never any other session there. It arrives as its next prompt, marked as from you and fenced as untrusted.",
   start_task:
-    "Start a task: an agent in its own worktree that ends in a PR. It runs as a chat unless view is terminal (only for a job that needs a TUI). With after (a task's id or name, or \"any\"), or over the workspace's running task limit, it's queued and starts by itself; the result says Queued (position N). Its models follow the role settings (planning, implementation, review, scope); give model only when Saad asks for one. Always state plan (true or false) and plan_reason: plan true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. Refused while a brake holds.",
+    "Start a task: an agent in its own worktree that ends in a PR. It runs as a chat unless view is terminal (only for a job that needs a TUI). With after (a task's id or name, or \"any\"), or over the workspace's running task limit, it's queued and starts by itself; the result says Queued (position N). Its models follow the role settings (planning, implementation, review, scope); give model only when Saad asks for one. Always state plan (true or false) and plan_reason (plan_only true plans, then stops and waits for approve_plan instead of implementing): plan true for a big, unclear or cross-cutting job, false for a small, clear one whose steps you write into the prompt. Refused while a brake holds.",
   set_task_model:
     'Resume a paused task on another model ("provider/model", or a map of role to one), keeping its conversation and worktree; it\'s told to carry on (or message). Refused mid-turn.',
   start_session:
@@ -75,6 +75,8 @@ const DESCRIPTIONS: Record<ToolName, string> = {
     "Run a LumifyHub board's open cards as stacked tasks (each start braked), or with plan_only just show the plan.",
   stack_status: "One stack's items, PRs and progress.",
   land: "Merge a whole stack bottom-up, each PR through the sign-off gates at its current head.",
+  approve_plan:
+    'Approve the plan of a plan_only task that is waiting ("plan ready"): it continues on the implementation model, once. An optional message amends the plan and is recorded on the task\'s brief as a scope change. Reject a plan with drop.',
   drop: "Reject a task: close its PR and remove its worktree. A task still waiting in the queue is removed by its id. Logged with the reason.",
   move: 'Carry a running task to a linked machine, or back with "here": for heavy test or build work. It keeps its branch, conversation and plan; the gates, events, read, send, stop, done and drop work the same wherever it runs, and the machine it lands on can\'t merge it. Takes a few minutes and runs in the background; an event says when it lands. Refused while paused, for a task waiting on Saad (an escalation or open ask), and for card and stacked tasks.',
   stop: "Stop a session's agent mid-turn, even while it's thinking, keeping its conversation, worktree and branch; your next message runs as its next turn.",

package/lib/settings-url.ts

@@ -12,6 +12,7 @@ export const SETTINGS_SECTIONS = [
   "notifications",
   "schedules",
   "audits",
+  "setup",
 ] as const;
 
 export type SettingsSection = (typeof SETTINGS_SECTIONS)[number];

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-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

@@ -137,7 +137,11 @@ 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/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/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/lib/welcome-url.ts

@@ -0,0 +1,33 @@
+// The welcome has its own address: `/?welcome=<step>`, beside `?settings=`
+// and `?session=`. `/welcome` redirects here.
+
+export const WELCOME_PARAM = "welcome";
+
+export const WELCOME_STEPS = ["agents", "project", "finish"] as const;
+
+export type WelcomeStep = (typeof WELCOME_STEPS)[number];
+
+export interface WelcomeLocation {
+  open: boolean;
+  step: WelcomeStep;
+}
+
+const BASE = "http://agentos.invalid";
+
+export const isWelcomeStep = (v: unknown): v is WelcomeStep =>
+  (WELCOME_STEPS as readonly unknown[]).includes(v);
+
+/** What the address says; a bare or unknown step starts at the first. */
+export function welcomeFromHref(href: string): WelcomeLocation {
+  const value = new URL(href, BASE).searchParams.get(WELCOME_PARAM);
+  if (value === null) return { open: false, step: WELCOME_STEPS[0] };
+  return { open: true, step: isWelcomeStep(value) ? value : WELCOME_STEPS[0] };
+}
+
+/** The same address with the welcome set (or removed), as path+query+hash. */
+export function hrefWithWelcome(href: string, at: WelcomeLocation): string {
+  const url = new URL(href, BASE);
+  if (at.open) url.searchParams.set(WELCOME_PARAM, at.step);
+  else url.searchParams.delete(WELCOME_PARAM);
+  return url.pathname + url.search + url.hash;
+}

package/lib/welcome.ts

@@ -0,0 +1,88 @@
+/**
+ * First-run welcome: shown once on a fresh install, never on one that
+ * already has work. Completion is the server's (one server, many devices),
+ * kept in `settings` as an ISO time, or "existing-install" when the install
+ * was already in use.
+ */
+
+import type Database from "better-sqlite3";
+import { db } from "./db";
+
+export const WELCOME_KEY = "welcome.completed_at";
+export const EXISTING_INSTALL = "existing-install";
+
+export interface WelcomeGate {
+  // The welcome should open now.
+  show: boolean;
+  // No sessions and no project of the user's own.
+  fresh: boolean;
+  completedAt: string | null;
+}
+
+export interface GateInput {
+  completedAt: string | null;
+  sessionCount: number;
+  // Projects other than the built-in Uncategorized one.
+  projectCount: number;
+  demo: boolean;
+  skip: boolean;
+}
+
+export function welcomeGate(i: GateInput): WelcomeGate {
+  const fresh = i.sessionCount === 0 && i.projectCount === 0;
+  return {
+    show: !i.completedAt && fresh && !i.demo && !i.skip,
+    fresh,
+    completedAt: i.completedAt,
+  };
+}
+
+export function readCompletedAt(d: Database.Database = db): string | null {
+  const row = d
+    .prepare(`SELECT value FROM settings WHERE key = ?`)
+    .get(WELCOME_KEY) as { value: string } | undefined;
+  return row?.value ?? null;
+}
+
+// Keeps the first stamp unless `overwrite`.
+export function completeWelcome(
+  value: string = new Date().toISOString(),
+  d: Database.Database = db,
+  overwrite = false
+): void {
+  d.prepare(
+    overwrite
+      ? `INSERT INTO settings (key, value) VALUES (?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+      : `INSERT OR IGNORE INTO settings (key, value) VALUES (?, ?)`
+  ).run(WELCOME_KEY, value);
+}
+
+export function counts(d: Database.Database = db) {
+  const n = (sql: string) => (d.prepare(sql).get() as { n: number }).n;
+  return {
+    sessionCount: n(`SELECT COUNT(*) AS n FROM sessions`),
+    projectCount: n(
+      `SELECT COUNT(*) AS n FROM projects WHERE is_uncategorized = 0`
+    ),
+  };
+}
+
+/** The gate for this server. An install found in use is stamped as such. */
+export function readWelcomeGate(
+  demo: boolean,
+  d: Database.Database = db
+): WelcomeGate {
+  const c = counts(d);
+  let completedAt = readCompletedAt(d);
+  if (!completedAt && (c.sessionCount > 0 || c.projectCount > 0)) {
+    completeWelcome(EXISTING_INSTALL, d);
+    completedAt = readCompletedAt(d);
+  }
+  return welcomeGate({
+    completedAt,
+    ...c,
+    demo,
+    skip: !!process.env.AGENTOS_SKIP_WELCOME,
+  });
+}

package/package.json

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

package/stores/addProject.ts

@@ -13,14 +13,32 @@ export const addProjectUi = proxy<{
   } | null;
 }>({ open: null });
 
+// Who asked for the dialog and wants the new project instead of the draft
+// that opens in it. A function, so it stays out of the proxy.
+let onProjectAdded: ((projectId: string) => void) | null = null;
+
 export const addProjectActions = {
-  show: (kind: AddProjectKind, hostId: string) => {
+  show: (
+    kind: AddProjectKind,
+    hostId: string,
+    onDone?: (projectId: string) => void
+  ) => {
+    onProjectAdded = onDone ?? null;
     addProjectUi.open = { kind, hostId, workspaceId: sidebarUi.workspaceId };
   },
+  /** Called once a project is made; false if nobody took it over. */
+  finish: (projectId: string): boolean => {
+    const handler = onProjectAdded;
+    addProjectActions.close();
+    if (!handler) return false;
+    handler(projectId);
+    return true;
+  },
   setWorkspace: (workspaceId: string | null) => {
     if (addProjectUi.open) addProjectUi.open.workspaceId = workspaceId;
   },
   close: () => {
+    onProjectAdded = null;
     addProjectUi.open = null;
   },
 };