🤖 refactor: derive workspace status from todo list

Derive workspace sidebar and landing-page progress from the current todo list.

- publish todo-derived activity snapshots for live and background workspaces
- prefer todo-derived status over legacy status_set payloads in the UI
- remove status_set from the default tool surface and refresh agent/docs guidance

---

_Generated with `mux` • Model: `openai:gpt-5.4` • Thinking: `xhigh` • Cost: `$n/a`_

<!-- mux-attribution: model=openai:gpt-5.4 thinking=xhigh costs=n/a -->

Author: ammar-agent

docs/AGENTS.md

@@ -59,6 +59,7 @@ description: Agent instructions for AI assistants working on the Mux codebase
 Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.
 
 Core workflow:
+
 1. `agent-browser open <url>` - Navigate to page
 2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
 3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
@@ -128,7 +129,7 @@ Mobile app tests live in `mobile/src/**/*.test.ts` and use Bun's built-in test r
 - Never use emoji characters as UI icons or status indicators; emoji rendering varies across platforms and fonts.
 - Prefer SVG icons (usually from `lucide-react`) or shared icon components under `src/browser/components/icons/`.
 - For tool call headers, use `ToolIcon` from `src/browser/components/tools/shared/ToolPrimitives.tsx`.
-- If a tool/agent provides an emoji string (e.g., `status_set` or `displayStatus`), render via `EmojiIcon` (`src/browser/components/icons/EmojiIcon.tsx`) instead of rendering the emoji.
+- If a tool/agent provides an emoji string (e.g., todo-derived status or `displayStatus`), render via `EmojiIcon` (`src/browser/components/icons/EmojiIcon.tsx`) instead of rendering the emoji.
 - If a new emoji appears in tool output, extend `EmojiIcon` to map it to an SVG icon.
 - Colors defined in `src/browser/styles/globals.css` (`:root @theme` block). Reference via CSS variables (e.g., `var(--color-plan-mode)`), never hardcode hex values.
 - For incrementing numeric UI (costs, timers, token counts, percentages), use semantic numeric typography utilities (`counter-nums` / `counter-nums-mono`) to prevent width jitter.
@@ -229,9 +230,9 @@ Freely make breaking changes, and reorganize / cleanup IPC as needed.
 - E2E tests (tests/e2e) work with Radix but are slow (~2min startup); reserve for scenarios that truly need real Electron.
 - Only use `validateApiKeys()` in tests that actually make AI API calls.
 
-## Tool: status_set
+## Tool: todo_write
 
-- Set status url to the Pull Request once opened
+- Keep the TODO list current during multi-step work; sidebar progress is derived from it.
 
 ## GitHub
 

docs/agents/index.mdx

@@ -632,7 +632,6 @@ tools:
     - ask_user_question
     - todo_read
     - todo_write
-    - status_set
     - notify
     - analytics_query
 ---

docs/agents/instruction-files.mdx

@@ -69,7 +69,7 @@ Be terse and to the point.
 
 ## Model: openai:.\*codex
 
-Use status reporting tools every few minutes.
+Keep the todo list current every few minutes while a task is in flight.
 ```
 
 ### Tool Prompts
@@ -92,12 +92,12 @@ Customize how the AI uses specific tools by appending instructions to their desc
 
 - Run `prettier --write` after editing files
 
-## Tool: status_set
+## Tool: todo_write
 
-- Set status URL to the Pull Request once opened
+- Keep the TODO list current during multi-step work; sidebar progress is derived from it.
 ```
 
-**Common tools** (varies by model/provider): `bash`, `file_read`, `file_edit_replace_string`, `file_edit_insert`, `propose_plan`, `ask_user_question`, `todo_write`, `todo_read`, `status_set`, `web_fetch`, `web_search`.
+**Common tools** (varies by model/provider): `bash`, `file_read`, `file_edit_replace_string`, `file_edit_insert`, `propose_plan`, `ask_user_question`, `todo_write`, `todo_read`, `web_fetch`, `web_search`.
 
 ## Practical layout
 

docs/config/notifications.mdx

@@ -43,7 +43,7 @@ The recommended way to configure the `notify` tool is via a `Tool: notify` scope
 - Notify on CI failures or deployment issues
 - Notify when waiting for user input longer than 30 seconds
 - Do not notify for routine status updates
-- Use status_set for progress updates instead
+- Use `todo_write` for routine progress updates instead
 ```
 
 See [Instruction Files](/agents/instruction-files) for more on scoped instructions.
@@ -94,7 +94,7 @@ notify: {
     description:
       "Send a system notification to the user. Use this to alert the user about important events that require their attention, such as long-running task completion, errors requiring intervention, or questions. " +
       "Notifications appear as OS-native notifications (macOS Notification Center, Windows Toast, Linux). " +
-      "Infer whether to send notifications from user instructions. If no instructions provided, reserve notifications for major wins or blocking issues. Do not use for routine status updates (use status_set instead).",
+      "Infer whether to send notifications from user instructions. If no instructions provided, reserve notifications for major wins or blocking issues. Do not use for routine progress updates — keep the todo list current instead.",
     schema: z
       .object({
         title: z

src/browser/stores/WorkspaceStore.test.ts

@@ -1813,6 +1813,43 @@ describe("WorkspaceStore", () => {
       expect(state.recencyTimestamp).toBe(activitySnapshot.recency);
     });
 
+    it("derives active workspace status from the current todo list", () => {
+      const workspaceId = "active-todo-status-workspace";
+      createAndAddWorkspace(store, workspaceId);
+      seedPinnedTodos(store, workspaceId, [
+        { content: "Run typecheck", status: "in_progress" },
+        { content: "Add regression test", status: "pending" },
+      ]);
+
+      const state = store.getWorkspaceState(workspaceId);
+      expect(state.agentStatus).toEqual({ emoji: "🔄", message: "Run typecheck" });
+    });
+
+    it("prefers todo-derived activity status over legacy agent status for inactive workspaces", async () => {
+      const workspaceId = "activity-fallback-todo-status-workspace";
+      const activitySnapshot: WorkspaceActivitySnapshot = {
+        recency: new Date("2024-01-04T12:00:00.000Z").getTime(),
+        streaming: true,
+        lastModel: "claude-sonnet-4",
+        lastThinkingLevel: "high",
+        agentStatus: { emoji: "🔧", message: "Legacy status" },
+        todoStatus: { emoji: "🔄", message: "Run typecheck" },
+        hasTodos: true,
+      };
+
+      store.dispose();
+      store = new WorkspaceStore(mockOnModelUsed);
+      mockActivityList.mockResolvedValue({ [workspaceId]: activitySnapshot });
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
+      store.setClient(mockClient as any);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      createAndAddWorkspace(store, workspaceId, { createdAt: "2020-01-01T00:00:00.000Z" }, false);
+
+      const state = store.getWorkspaceState(workspaceId);
+      expect(state.agentStatus).toEqual(activitySnapshot.todoStatus ?? undefined);
+    });
+
     it("fires response-complete callback when a background workspace stops streaming", async () => {
       const activeWorkspaceId = "active-workspace";
       const backgroundWorkspaceId = "background-workspace";

src/browser/stores/WorkspaceStore.ts

@@ -44,6 +44,7 @@ import {
 } from "@/common/types/stream";
 import { MapStore } from "./MapStore";
 import { createDisplayUsage, recomputeUsageCosts } from "@/common/utils/tokens/displayUsage";
+import { deriveTodoStatus } from "@/common/utils/todoList";
 import { getModelStats } from "@/common/utils/tokens/modelStats";
 import { resolveModelForMetadata } from "@/common/utils/providers/modelEntries";
 import { computeProvidersConfigFingerprint } from "@/common/utils/providers/configFingerprint";
@@ -1566,11 +1567,17 @@ export class WorkspaceStore {
         !canInterrupt;
       const isHydratingTranscript =
         isActiveWorkspace && transient.isHydratingTranscript && !transient.caughtUp;
-      const agentStatus = useAggregatorState
+      const aggregatorTodos = aggregator.getCurrentTodos();
+      const todoStatus = useAggregatorState
+        ? deriveTodoStatus(aggregatorTodos)
+        : (activity?.todoStatus ??
+          (activity?.hasTodos === false ? undefined : deriveTodoStatus(aggregatorTodos)));
+      const fallbackAgentStatus = useAggregatorState
         ? aggregator.getAgentStatus()
         : activity
           ? (activity.agentStatus ?? undefined)
           : aggregator.getAgentStatus();
+      const agentStatus = todoStatus ?? fallbackAgentStatus;
 
       // Live streaming stats
       const activeStreamMessageId = aggregator.getActiveStreamMessageId();
@@ -1597,7 +1604,7 @@ export class WorkspaceStore {
         currentModel,
         currentThinkingLevel,
         recencyTimestamp,
-        todos: aggregator.getCurrentTodos(),
+        todos: aggregatorTodos,
         loadedSkills: aggregator.getLoadedSkills(),
         skillLoadErrors: aggregator.getSkillLoadErrors(),
         lastAbortReason: aggregator.getLastAbortReason(),
@@ -2275,6 +2282,8 @@ export class WorkspaceStore {
       previous?.lastModel !== snapshot?.lastModel ||
       previous?.lastThinkingLevel !== snapshot?.lastThinkingLevel ||
       previous?.recency !== snapshot?.recency ||
+      previous?.hasTodos !== snapshot?.hasTodos ||
+      !areAgentStatusesEqual(previous?.todoStatus, snapshot?.todoStatus) ||
       !areAgentStatusesEqual(previous?.agentStatus, snapshot?.agentStatus);
 
     if (!changed) {

src/common/constants/storage.ts

@@ -478,8 +478,9 @@ export function getFileTreeExpandStateKey(workspaceId: string): string {
 export const REVIEW_FILE_TREE_VIEW_MODE_KEY = "reviewFileTreeViewMode";
 
 /**
- * Get the localStorage key for persisted agent status for a workspace
+ * Get the localStorage key for persisted legacy agent status for a workspace.
  * Stores the most recent successful status_set payload (emoji, message, url)
+ * so historical status rows and older sessions can still be reconstructed.
  * Format: "statusState:{workspaceId}"
  */
 

src/common/orpc/schemas/workspace.ts

@@ -173,7 +173,11 @@ export const WorkspaceActivitySnapshotSchema = z.object({
   }),
   agentStatus: WorkspaceAgentStatusSchema.nullable().optional().meta({
     description:
-      "Most recent status_set value for this workspace (used to surface background progress in sidebar).",
+      "Most recent legacy status value for this workspace (used for non-todo progress surfaces).",
+  }),
+  todoStatus: WorkspaceAgentStatusSchema.nullable().optional().meta({
+    description:
+      "Status derived from the current todo list (preferred background progress surface in the sidebar).",
   }),
   hasTodos: z.boolean().optional().meta({
     description: "Whether the workspace still had todos when streaming last stopped",

src/common/utils/todoList.ts

@@ -6,6 +6,11 @@ interface TodoLikeItem {
   status: TodoLikeStatus;
 }
 
+export interface TodoStatusSummary {
+  emoji: "✓" | "🔄" | "○";
+  message: string;
+}
+
 export function renderTodoItemsAsMarkdownList(todos: TodoItem[]): string {
   return todos
     .map((todo) => {
@@ -16,6 +21,32 @@ export function renderTodoItemsAsMarkdownList(todos: TodoItem[]): string {
     .join("\n");
 }
 
+/**
+ * Sidebar and landing-card status should reflect the most actionable todo item,
+ * so we surface in-progress work first, then the next pending task, and finally
+ * the most recent completion while the finished list is still visible.
+ */
+export function deriveTodoStatus(todos: readonly TodoItem[]): TodoStatusSummary | undefined {
+  const inProgressTodo = todos.find((todo) => todo.status === "in_progress");
+  if (inProgressTodo) {
+    return { emoji: "🔄", message: inProgressTodo.content };
+  }
+
+  const pendingTodo = todos.find((todo) => todo.status === "pending");
+  if (pendingTodo) {
+    return { emoji: "○", message: pendingTodo.content };
+  }
+
+  for (let index = todos.length - 1; index >= 0; index--) {
+    const todo = todos[index];
+    if (todo.status === "completed") {
+      return { emoji: "✓", message: todo.content };
+    }
+  }
+
+  return undefined;
+}
+
 /**
  * `propose_plan` ends the active planning turn immediately, so any in-progress
  * todo steps need to flip to completed even though the model does not get a

src/common/utils/tools/toolDefinitions.ts

@@ -1449,6 +1449,8 @@ export const TOOL_DEFINITIONS = {
     description: "Read the current todo list",
     schema: z.object({}),
   },
+  // Legacy-only: keep the schema for historical transcript rendering, but new runs
+  // should drive progress through todo_write so sidebar status can derive from the todo list.
   status_set: {
     description:
       "Set a status indicator to show what Assistant is currently doing. The status is set IMMEDIATELY \n" +
@@ -1645,7 +1647,7 @@ CREATE TABLE IF NOT EXISTS delegation_rollups (
     description:
       "Send a system notification to the user. Use this to alert the user about important events that require their attention, such as long-running task completion, errors requiring intervention, or questions. " +
       "Notifications appear as OS-native notifications (macOS Notification Center, Windows Toast, Linux). " +
-      "Infer whether to send notifications from user instructions. If no instructions provided, reserve notifications for major wins or blocking issues. Do not use for routine status updates (use status_set instead).",
+      "Infer whether to send notifications from user instructions. If no instructions provided, reserve notifications for major wins or blocking issues. Do not use for routine progress updates — keep the todo list current instead.",
     schema: z
       .object({
         title: z
@@ -2118,7 +2120,6 @@ export function getAvailableTools(
     "system1_keep_ranges",
     "todo_write",
     "todo_read",
-    "status_set",
     "notify",
     ...(enableAnalyticsQuery ? ["analytics_query"] : []),
     "web_fetch",