agy-mcp-bridge 0.1.21 → 0.1.22

package/dist/src/tools/register.js

@@ -3,6 +3,7 @@ import { requestContext } from '../request-context.js';
 import * as z from 'zod/v4';
 import { delegateSchema, taskIdSchema, waitSchema } from '../security/input.js';
 import { redact } from '../security/redact.js';
+import { missionCancelSchema, missionCreateSchema, missionDispatchSchema, missionExtendSchema, missionIdSchema } from '../missions/missions.js';
 import { readPackageInfo } from '../update.js';
 /** Best-effort label for who delegated: the client's declared name/version when the request carries it, else the HTTP User-Agent. */
 function clientLabel(envelope) {
@@ -21,7 +22,27 @@ export const WAITING_NOTE = 'Still running. Do nothing else and write no message
 const withNextStep = (summary, activity = null) => summary.status === 'running' || summary.status === 'queued'
     ? { task_id: summary.task_id, status: summary.status, duration_ms: summary.duration_ms, ...(activity ? { activity } : {}), next_step: WAITING_NOTE }
     : summary;
-export function createServer(manager, environment) {
+/**
+ * A mission step is started by a task like any other delegation, so the same rule applies after dispatch: report the four fields
+ * the client needs to wait, and let the task tools carry the rest. The mission id and step id stay in the reply because the client
+ * has to come back to this plan after the wait.
+ */
+const withStepNote = (value) => value.status === 'running' || value.status === 'queued'
+    ? { mission_id: value.mission_id, step_id: value.step_id, task_id: value.task_id, status: value.status, duration_ms: value.duration_ms, next_step: 'Step started. Do nothing else and write no message; call antigravity_task_wait with this task_id.' }
+    : value;
+/** The one line that says what the orchestrator can actually do next, computed from the plan rather than repeated from a description. */
+function missionNote(view) {
+    if (view.status === 'canceled')
+        return 'Mission is canceled: no step can be dispatched. Create a new mission to continue.';
+    if (view.ready.length)
+        return `Dispatch a ready step with mission_dispatch (${view.ready.join(', ')}), then call antigravity_task_wait on the task_id it returns.`;
+    if (view.progress.active)
+        return 'A step is running: call antigravity_task_wait on its task_id and make no other call until it ends.';
+    if (view.progress.unmet)
+        return 'No step is ready and at least one ended without completing: review that step, then add a correction step with mission_extend or cancel the mission.';
+    return 'Every step reached a terminal state. Review each diff and test before accepting the mission; the bridge never merges a worktree branch.';
+}
+export function createServer(manager, environment, missions) {
     const server = new McpServer({ name: 'antigravity-mcp-bridge', version: readPackageInfo().version });
     const response = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value });
     const guard = async (action) => {
@@ -77,6 +98,53 @@ export function createServer(manager, environment) {
         description: 'Terminate only the managed task process tree. Partial file changes remain; no automatic rollback.',
         inputSchema: taskIdSchema, annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     }, async ({ task_id }) => guard(() => manager.cancel(task_id)));
+    // Missions: the bridge records and gates the plan, the client drives it. Nothing here starts an agent on its own.
+    const receipt = (mission_id) => {
+        const view = missions.view(mission_id);
+        return { mission_id, workspace: view.workspace, status: view.status, progress: view.progress, ready: view.ready, next_step: missionNote(view) };
+    };
+    server.registerTool('mission_create', {
+        description: 'Record a dependency-ordered plan of agent tasks, all in one workspace, and return its mission_id. Steps are started only by mission_dispatch from this client: the bridge never runs a step by itself. The plan is append-only, so a retry is a new step rather than an edit. Validation is strict: unique step ids, existing dependencies, no cycles, one workspace, bridge limits.',
+        inputSchema: missionCreateSchema, annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: false }
+    }, async (input, ctx) => guard(async () => {
+        const mission = await missions.create(input, { client: clientLabel(ctx.mcpReq.envelope) });
+        return receipt(mission.mission_id);
+    }));
+    server.registerTool('mission_extend', {
+        description: 'Append steps to an open mission. Existing steps are never modified: use this for corrections and follow-up work instead of re-dispatching a step that already ran.',
+        inputSchema: missionExtendSchema, annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: false }
+    }, async ({ mission_id, steps }) => guard(async () => {
+        await missions.extend(mission_id, steps);
+        return receipt(mission_id);
+    }));
+    server.registerTool('mission_dispatch', {
+        description: 'Start one ready step with the arguments recorded in its plan entry, as a normal supervised task. Refused while any dependency is not completed, if the step already has a task, or once the mission is canceled. Returns running with task_id: wait with antigravity_task_wait, then read mission_status. Completion still needs Tech Lead diff/test review, and a worktree branch is never merged automatically.',
+        inputSchema: missionDispatchSchema, annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
+    }, async ({ mission_id, step_id }, ctx) => guard(async () => {
+        const { task } = await missions.dispatch(mission_id, step_id, { client: clientLabel(ctx.mcpReq.envelope) });
+        return withStepNote({ mission_id, step_id, task_id: task.task_id, status: task.status, duration_ms: task.duration_ms });
+    }));
+    server.registerTool('mission_status', {
+        description: 'Mission progress: one short entry per step (state, task_id, dependencies and what blocks them, scope counts) with the step ids that are ready now. No task text or logs, so it is cheap to read after a reconnect or a restart. Does not start or cancel anything.',
+        inputSchema: missionIdSchema, annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async ({ mission_id }) => guard(() => {
+        const view = missions.view(mission_id);
+        return { ...view, next_step: missionNote(view) };
+    }));
+    server.registerTool('mission_plan', {
+        description: 'Full recorded plan: mission goal, requesting client and every step with its exact delegate arguments. Use it to recover the plan after losing context, instead of re-reading the repository.',
+        inputSchema: missionIdSchema, annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async ({ mission_id }) => guard(() => {
+        const view = missions.view(mission_id);
+        return { ...missions.planOf(mission_id), next_step: missionNote(view) };
+    }));
+    server.registerTool('mission_cancel', {
+        description: 'Cancel a mission so no further step can start. Tasks already running or queued are untouched unless cancel_running_tasks is true, because stopping an agent mid-edit is a separate decision; those task ids are returned. Partial file changes remain and nothing is rolled back.',
+        inputSchema: missionCancelSchema, annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
+    }, async ({ mission_id, cancel_running_tasks }) => guard(async () => {
+        const { mission, running, canceled } = await missions.cancel(mission_id, { cancelRunningTasks: cancel_running_tasks === true });
+        return { mission_id, status: mission.status, running_tasks: running, canceled_tasks: canceled, progress: missions.view(mission_id).progress };
+    }));
     return server;
 }
 //# sourceMappingURL=register.js.map

package/dist/src/ui/routes.js

@@ -70,6 +70,7 @@ async function overview(ctx, tzOffsetMinutes = 0) {
         progress: readProgress(ctx.manager.stateDirectory),
         wait: { seconds: ctx.manager.maxWaitSeconds, client_tool_timeout_seconds: clientToolTimeoutSeconds(ctx.manager.maxWaitSeconds) },
         queue: ctx.manager.overview().queue,
+        missions: ctx.missions.overview(),
         warnings: [await ctx.manager.lockDiagnostic()].filter(Boolean),
         update: knownUpdate() && { ...knownUpdate(), package: readPackageInfo().name, command: 'agy-mcp-bridge update' },
         tasks: ctx.manager.list()
@@ -176,6 +177,28 @@ export async function handleUi(req, res, ctx) {
             json(res, 200, ctx.manager.detail(cancel[1]));
             return true;
         }
+        if (pathname === '/ui/api/missions' && method === 'GET') {
+            json(res, 200, { missions: ctx.missions.list(), ...ctx.missions.overview() });
+            return true;
+        }
+        const mission = pathname.match(new RegExp(`^/ui/api/missions/(${UUID})$`));
+        if (mission && method === 'GET') {
+            json(res, 200, ctx.missions.planOf(mission[1]));
+            return true;
+        }
+        // Stopping a plan is a decision a person in front of the page may make, but it never touches a running agent:
+        // cancelling one of its tasks stays on that task's own page.
+        const stopMission = pathname.match(new RegExp(`^/ui/api/missions/(${UUID})/cancel$`));
+        if (stopMission && method === 'POST') {
+            const body = await readJson(req);
+            if (body.confirm !== true) {
+                json(res, 400, { error: 'confirm must be true' });
+                return true;
+            }
+            const { mission: stopped, running } = await ctx.missions.cancel(stopMission[1]);
+            json(res, 200, { ...ctx.missions.planOf(stopped.mission_id), running_tasks: running });
+            return true;
+        }
         if (pathname === '/ui/api/delegation' && method === 'POST') {
             const body = await readJson(req);
             if (typeof body.enabled !== 'boolean') {

package/docs/MULTI-AGENT-PLAN.md

@@ -1,7 +1,7 @@
 # Kế hoạch: MCP Bridge đa agent (Orchestrator + Agent Router)
 
-Trạng thái: Phase 1 hoàn tất (2026-10-26); Phase 2 là bước tiếp theo.
-Cập nhật: 2026-10-26.
+Trạng thái: Phase 1 hoàn tất (2026-10-26); Phase 2 hoàn tất (2026-10-27), chờ duyệt PR.
+Cập nhật: 2026-10-27.
 
 ## 1. Mục tiêu
 
@@ -167,12 +167,65 @@ Kết quả: `npm test` xanh (125 pass, 3 skip do thiếu môi trường); test
 đều có test tự động; đã xác minh `resolveCommand` với Codex npm thật
 (`codex-cli 0.163.0`, shim `.cmd`). Chưa chạy lại `test:live` với Codex thật.
 
-### Phase 2 — Mission daemon + Orchestrator skill
-
-- Lưu mission/plan có cấu trúc; trạng thái từng bước; resume sau restart.
-- Skill hướng dẫn orchestrator: chọn role, chọn agent, cắt context, ngân sách token.
-- Tool: `mission_create`, `mission_status`, `mission_plan`, `mission_cancel`.
-- Không cho agent tự sửa plan của agent khác; plan là dữ liệu chỉ đọc với worker.
+### Phase 2 — Mission daemon + Orchestrator skill (hoàn tất 2026-10-27, chờ duyệt PR)
+
+Bốn quyết định đã chốt với chủ dự án trước khi viết code:
+
+- **Bridge ghi nhận, agent ngoài điều khiển.** Bridge lưu plan + trạng thái từng bước, **từ chối**
+  `mission_dispatch` khi một dependency chưa `completed`, coi plan là append-only, và **không bao giờ
+  tự bắt đầu bước nào**. Restart phục hồi plan nhưng không chạy lại gì.
+- Phạm vi: toàn bộ Phase 2 (mission daemon + UI + skill), không cắt bớt.
+- Hai deliverable song song: trang UI **Nhiệm vụ** và skill thứ hai `mission-orchestrator` — tách
+  khỏi `antigravity-bridge` vì hai hợp đồng khác nhau (một bên là giao việc đơn lẻ + đọc kết quả,
+  một bên là viết plan và điều phối cổng phụ thuộc).
+- Phát hành: nhánh mới từ `main` → PR → chủ dự án tự duyệt; không auto-merge, không release npm.
+
+Đã triển khai:
+
+1. `src/missions/missions.ts` — `MissionManager`: `create` / `extend` / `dispatch` / `cancel` /
+   `view` / `planOf` / `list` / `overview` / `restore`. Chỉ cần `TaskRunner`
+   (`delegate`/`summary`/`cancel`/`stateDirectory`) và `Pick<Config, 'allowed_workspaces' |
+   'max_timeout_seconds'>`, nên mọi cổng chặn test được không cần CLI.
+2. Cổng chặn lúc `dispatch`: mission đã dừng → bước đã bind task → dependency chưa `completed` →
+   bước đang được một call khác dispatch. Sau cổng, việc chạy đi qua **`TaskManager.delegate` y như
+   một task thường**, nên toàn bộ bảo vệ Phase 1 (workspace allowlist, `owns`, worktree, timeout,
+   redaction, reaper) vẫn áp dụng.
+3. Trạng thái bước **không lưu trên đĩa**: suy ra từ bản ghi task mỗi lần đọc; bản ghi task bị
+   retention đuổi thì bước là `lost` — `lost` không bao giờ mở khóa bước kế tiếp.
+4. Sáu tool MCP mới: `mission_create`, `mission_extend`, `mission_dispatch`, `mission_status`,
+   `mission_plan`, `mission_cancel` (tổng 13). Trả lời gọn theo hướng tiết kiệm token:
+   `create`/`extend` trả receipt (id, progress, `ready`, `next_step`) chứ không lặp lại plan;
+   `dispatch` chỉ trả `{mission_id, step_id, task_id, status, duration_ms, next_step}`;
+   `mission_status` bỏ hẳn text của task; chỉ `mission_plan` mang `delegate` đầy đủ.
+5. UI: trang **Nhiệm vụ** (`GET /ui/api/missions`, `GET /ui/api/missions/:uuid`,
+   `POST /ui/api/missions/:uuid/cancel` cần `confirm: true`) + bộ đếm mission trong overview.
+   Trang này **chỉ đọc và dừng kế hoạch**; nút dừng không đi kèm lựa chọn giết agent.
+6. Skill `skills/mission-orchestrator/SKILL.md` + installer đa skill: `packagedSkills()` liệt kê mọi
+   `skills/<name>/SKILL.md`, `--skill <name>` chọn từng cái, `known-versions.json` chuyển sang lịch sử
+   hash **riêng từng skill** để hash của skill này không thể authorize việc ghi đè file của skill kia.
+
+Giới hạn: 12 bước/mission, plan ≤100.000 ký tự, giữ 20 mission (nạn nhân là bản ghi cũ nhất **không**
+có task đang chạy), `step_id` là slug `[a-z0-9][a-z0-9._-]{0,63}`, timeout mỗi bước vẫn chịu
+`max_timeout_seconds` của bridge, một mission chỉ chạy trong **một** workspace.
+
+Sai lệch so với kế hoạch gốc (mục từng nêu bốn tool):
+
+- Thêm `mission_dispatch` và `mission_extend`. `mission_create` không thể bắt đầu bước (điều kiện
+  "bridge không tự chạy"), nên cần tool tách để gọi cổng chặn; và vì plan là append-only, bước sửa
+  sai bắt buộc phải là bước mới → cần `mission_extend`.
+- **Không** có `mission_list`: giữ surface ở 13 tool. Client phải lưu `mission_id` trong bối cảnh;
+  người dùng đọc danh sách ở UI.
+- ý "không cho agent tự sửa plan của agent khác" được hiện thực mạnh hơn dự kiến: plan không đổi
+  được bởi bất kỳ ai (`extend` chỉ append, `dispatch` không sửa `delegate`, `cancel` chỉ đóng).
+
+Bằng chứng: `tests/missions.test.ts` 17 test (rules, schema, allowlist, cổng dependency, failed/lost
+dependency, đúng tham số đã ghi, single-flight, dispatch bị từ chối không bind, cancel hai chiều,
+append-only, retention, restart, record lạ, redaction, MCP surface, UI route). Xem `docs/HANDOFF.md`
+mục 5 cho số liệu suite và bảng mutation.
+
+Việc còn mở của Phase 2: chọn bước tự động (router đề xuất bước kế tiếp) vẫn thuộc Phase 4; **chưa có**
+ngân sách token theo mission — usage vẫn chỉ được ghi và tổng hợp theo task/theo ngày, nên một plan
+12 bước không có trần chi phí; mission không có dependency mang điều kiện (chỉ "bước A xong rồi tới B").
 
 ### Phase 3 — Adapter cho OpenCode, Qoder, Zcode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-mcp-bridge",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Local loopback HTTP MCP bridge that delegates bounded coding tasks to multiple agent CLIs (Antigravity, Codex) with optional parallel git worktrees",
   "license": "MIT",
   "keywords": [

package/skills/known-versions.json

@@ -1,69 +1,77 @@
 {
-  "comment": "sha256 of every SKILL.md this project has shipped, line endings normalized to LF. A file matching one of these is an old packaged copy that `skill install --update` may replace; anything else is treated as the owner's edit. Append the hash of the new SKILL.md here whenever you change it (a test enforces this).",
-  "versions": [
-    {
-      "sha256": "d6776cbecbbbd190df6ba83c16b821140aa7bcc855f8768677a00f210bc9de88",
-      "note": "first packaged skill (installer bundled)"
-    },
-    {
-      "sha256": "4fbf0722123c099625fd70986b5fa314c4210c56d8bf27d00eff926023b3a60b",
-      "note": "added task wait / log-free status"
-    },
-    {
-      "sha256": "3f0169d4f33c76e41521ade852d648e370c7333fbaf42a7e1aec6738b64adf6f",
-      "note": "added \"when not to delegate\" and the delegation switch"
-    },
-    {
-      "sha256": "055f773072ea93535ef09d0d2309074a32165a8f96491b2cc35b751176001415",
-      "note": "documented the queue and queued status"
-    },
-    {
-      "sha256": "9a3cfaf9adb21a637084f19c53ebe2e5d5b43fa673f7c58c04e9b0f0ef7b3087",
-      "note": "npm install commands and agy-mcp-bridge CLI"
-    },
-    {
-      "sha256": "afc8d8e76f977e0623b73bbb1e90f3e485cfdaf55036c36db6234328c111660b",
-      "note": "clarified cancel timing, restart of queued tasks, unlock, environment limitations"
-    },
-    {
-      "sha256": "451fe5791b1753f1550275a709c561442e62d1e8b86d3fe8c4525998d8d85659",
-      "note": "model choice is the owner's setting; no step progress in the tools"
-    },
-    {
-      "sha256": "65c0a72bb016ee8d891bfea17ea5d972dc79dc7c12c57edb17c1e6e8bbd37078",
-      "note": "Antigravity permission level is the owner's setting (agy_permissions)"
-    },
-    {
-      "sha256": "066f499ccd7341c7f77c2a409b3632e4cefe16e45ed2c77e75c8154028e951f9",
-      "note": "long waits (limits.max_wait_seconds), fewer polling calls"
-    },
-    {
-      "sha256": "bf96a492847e59fcdbd4eb7685a316a606699af2d217ea35a8e27dad85ccb2aa",
-      "note": "timeout guidance: split tasks, narrower follow-up after a timeout, limits.max_timeout_seconds"
-    },
-    {
-      "sha256": "83a5d812553cc79e8eec690cef825ced49b82b13e0991d4c632de5b6675b19f1",
-      "note": "opt-in auto-split mode (easy parts to Antigravity, hard parts by the Tech Lead)"
-    },
-    {
-      "sha256": "978deb00a9eb68780297eaf538da9272ac11e94c2942141b1d5e999fee218354",
-      "note": "auto-split mode follows the token-saving workflow (delegate whole, check just enough, short reports)"
-    },
-    {
-      "sha256": "117fa45228f421cf266f45c1a112e37ba2c164fb31c8fd64392495efa025828c",
-      "note": "while a task runs only wait: no reads or messages between waits, next_step note, no custom client"
-    },
-    {
-      "sha256": "d4246abf59e2aea3ad08c7b858cd6404ee79f5656e580142d019f6f6c443f8df",
-      "note": "activity line, slow is not stuck, soft deadline extension"
-    },
-    {
-      "sha256": "243a279ff026ed30ad91eaeb7376a4556bc9a1c4a9f4c206f64301c63d8853c4",
-      "note": "steps are for the user's web UI; do not fetch them"
-    },
-    {
-      "sha256": "fbd0fdebe8fcb95416f89dff95f8b4922e86d243d1139e613a88bde8cc54b034",
-      "note": "multi-agent delegation (agents_list, agent/isolation/owns/autonomy) with no bridge authentication"
-    }
-  ]
+  "comment": "sha256 of the SKILL.md versions of each skill this project has shipped, line endings normalized to LF. A file matching one of these is an old packaged copy that `skill install --update` may replace; anything else is treated as the owner's edit. Append the hash of the new SKILL.md here whenever you change it (a test enforces this).",
+  "skills": {
+    "antigravity-bridge": [
+      {
+        "sha256": "d6776cbecbbbd190df6ba83c16b821140aa7bcc855f8768677a00f210bc9de88",
+        "note": "first packaged skill (installer bundled)"
+      },
+      {
+        "sha256": "4fbf0722123c099625fd70986b5fa314c4210c56d8bf27d00eff926023b3a60b",
+        "note": "added task wait / log-free status"
+      },
+      {
+        "sha256": "3f0169d4f33c76e41521ade852d648e370c7333fbaf42a7e1aec6738b64adf6f",
+        "note": "added \"when not to delegate\" and the delegation switch"
+      },
+      {
+        "sha256": "055f773072ea93535ef09d0d2309074a32165a8f96491b2cc35b751176001415",
+        "note": "documented the queue and queued status"
+      },
+      {
+        "sha256": "9a3cfaf9adb21a637084f19c53ebe2e5d5b43fa673f7c58c04e9b0f0ef7b3087",
+        "note": "npm install commands and agy-mcp-bridge CLI"
+      },
+      {
+        "sha256": "afc8d8e76f977e0623b73bbb1e90f3e485cfdaf55036c36db6234328c111660b",
+        "note": "clarified cancel timing, restart of queued tasks, unlock, environment limitations"
+      },
+      {
+        "sha256": "451fe5791b1753f1550275a709c561442e62d1e8b86d3fe8c4525998d8d85659",
+        "note": "model choice is the owner's setting; no step progress in the tools"
+      },
+      {
+        "sha256": "65c0a72bb016ee8d891bfea17ea5d972dc79dc7c12c57edb17c1e6e8bbd37078",
+        "note": "Antigravity permission level is the owner's setting (agy_permissions)"
+      },
+      {
+        "sha256": "066f499ccd7341c7f77c2a409b3632e4cefe16e45ed2c77e75c8154028e951f9",
+        "note": "long waits (limits.max_wait_seconds), fewer polling calls"
+      },
+      {
+        "sha256": "bf96a492847e59fcdbd4eb7685a316a606699af2d217ea35a8e27dad85ccb2aa",
+        "note": "timeout guidance: split tasks, narrower follow-up after a timeout, limits.max_timeout_seconds"
+      },
+      {
+        "sha256": "83a5d812553cc79e8eec690cef825ced49b82b13e0991d4c632de5b6675b19f1",
+        "note": "opt-in auto-split mode (easy parts to Antigravity, hard parts by the Tech Lead)"
+      },
+      {
+        "sha256": "978deb00a9eb68780297eaf538da9272ac11e94c2942141b1d5e999fee218354",
+        "note": "auto-split mode follows the token-saving workflow (delegate whole, check just enough, short reports)"
+      },
+      {
+        "sha256": "117fa45228f421cf266f45c1a112e37ba2c164fb31c8fd64392495efa025828c",
+        "note": "while a task runs only wait: no reads or messages between waits, next_step note, no custom client"
+      },
+      {
+        "sha256": "d4246abf59e2aea3ad08c7b858cd6404ee79f5656e580142d019f6f6c443f8df",
+        "note": "activity line, slow is not stuck, soft deadline extension"
+      },
+      {
+        "sha256": "243a279ff026ed30ad91eaeb7376a4556bc9a1c4a9f4c206f64301c63d8853c4",
+        "note": "steps are for the user's web UI; do not fetch them"
+      },
+      {
+        "sha256": "fbd0fdebe8fcb95416f89dff95f8b4922e86d243d1139e613a88bde8cc54b034",
+        "note": "multi-agent delegation (agents_list, agent/isolation/owns/autonomy) with no bridge authentication"
+      }
+    ],
+    "mission-orchestrator": [
+      {
+        "sha256": "828f9d44c0edf38a0dbbb39c469f47968b4be37512b224eb12b985b8b15e4624",
+        "note": "first packaged mission skill (Phase 2)"
+      }
+    ]
+  }
 }

package/skills/mission-orchestrator/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: mission-orchestrator
+description: Drive a dependency-ordered plan of delegated coding steps through the MCP bridge (mission_create / extend / dispatch / status / plan / cancel) - one step at a time, each step's agent and scope chosen up front, results reviewed before the next step unlocks. Use when work needs several delegated steps in an order, or to recover such a plan after a reconnect or restart.
+---
+
+# Mission Orchestrator
+
+A mission is a plan the bridge **records and gates but never runs**: it stores the steps and refuses to start one whose dependencies have not completed. You decide the order, dispatch one step at a time, and wait. The bridge has no scheduler, no retry and no background thread; if you stop, the plan simply sits there until you or the user resumes it. Read `antigravity-bridge` first: delegation consent, the kill switch, task observation, permissions and review rules all apply unchanged to mission steps.
+
+## When a mission is the right shape
+
+Use one when the work is genuinely a sequence: implement → test what you changed → fix what the tests found, or several independent modules then an integration step. Use plain `antigravity_delegate` for a single bounded task; a plan of one step adds nothing. Never use a mission to make the bridge "run the whole feature by itself" - it will not, and every step still needs your dispatch call and your review.
+
+## Before writing the plan
+
+- Call `antigravity_environment` and `agents_list`. Require `bridge_status=ready`, `supported.missions=true`, `delegation.enabled=true` and `accepting_tasks=true`, and take the workspace from `allowed_workspaces` (an empty allowlist permits nothing). Read `limits`: `max_mission_steps`, `max_retained_missions`, `max_timeout_seconds`, `max_parallel_worktrees`.
+- Every step runs in the mission's single `workspace`; a step that names another one is rejected. Plan one mission per repository.
+- Look at the repository yourself first (status, the files in scope, existing untracked work) and record a baseline. The plan is where you write down what you already learned, so a step does not have to rediscover it.
+- The tools do not list missions, so save the `mission_id` from the receipt the moment it returns. If it is lost, ask the user to read it in the web UI (Nhiệm vụ page) rather than recreating a plan that may already be running.
+
+## Writing the plan
+
+`mission_create` takes `{title, goal, workspace, steps[]}` and returns only a receipt (`mission_id`, `workspace`, `status`, `progress`, `ready`, `next_step`) - the plan is not echoed back. Each step is `{step_id, title, depends_on[], delegate}` where `delegate` is exactly the object you would pass to `antigravity_delegate` (`task`, `workspace`, `acceptance_criteria`, optional `context`, `timeout_seconds`, `agent`, `isolation`, `owns`, `autonomy`). Strict schema: unknown fields, a duplicate or self-referencing `step_id`, an unknown dependency, a cycle, a foreign workspace, a step timeout above the bridge ceiling, more than `limits.max_mission_steps` steps or a plan over the size limit are all refused at creation.
+
+Write steps that can be checked without the next one:
+
+```json
+{
+  "title": "Range validation for the parser",
+  "goal": "Reject negative counts at the boundary and prove it with tests.",
+  "workspace": "C:/absolute/path/to/approved-project",
+  "steps": [
+    {"step_id": "impl", "title": "Guard the parser", "depends_on": [],
+     "delegate": {"task": "Reject negative values in parseCount (src/count.ts) and update its tests. Preserve the public API. Do not run commands; the Tech Lead runs tests.", "workspace": "C:/absolute/path/to/approved-project", "acceptance_criteria": ["Negative values return the existing validation error"], "context": "parseCount is called from 3 sites; all pass non-negative today.", "agent": "codex", "timeout_seconds": 300}},
+    {"step_id": "verify", "title": "Run the checks", "depends_on": ["impl"],
+     "delegate": {"task": "Add a regression test for the boundary found in step impl.", "workspace": "C:/absolute/path/to/approved-project", "acceptance_criteria": ["The new test fails before the fix and passes after"], "isolation": "worktree", "owns": ["test/count.test.ts"]}}
+  ]
+}
+```
+
+- `step_id` is a lowercase slug (`a-z0-9`, dot, dash, underscore, at most 64 characters). It is the only handle you get back, so name steps for what they prove (`impl`, `api-tests`, `fix-timeout-1`), not for their order.
+- Give the dependent step the criteria you will need to check the step before it. `depends_on` should be the shortest honest chain: two ready steps can run in parallel when worktree-isolated, while a long chain serializes everything behind the first slow step.
+- Put facts the agent cannot see into `context` (contracts, your findings, what is already done). Do not paste the repository, and do not write "as before" - a step is a fresh CLI conversation, and each one reads the files itself.
+- Secrets do not belong in a plan: the bridge redacts secret-shaped text in titles, goals and step instructions before writing to disk, so a `[REDACTED]` in a recovered plan means the value is gone, not hidden.
+- Size each step like a single delegation: one goal, a few files, measurable criteria, a `timeout_seconds` that fits. A mission of 12 small steps beats 2 giant ones - the gate gives you a review point between them.
+
+## Driving it
+
+The loop is always: dispatch one ready step → `antigravity_task_wait` on the `task_id` → read `mission_status` → review the diff → decide the next dispatch.
+
+- Take the step id from `ready` in the receipt or in `mission_status`. A step outside `ready` is refused, and the error says which dependency is in what state; do not retry it hoping for a different answer.
+- `mission_dispatch` starts the task with the arguments **recorded in the plan**, not with arguments you supply now. If the recorded instruction is wrong, append a corrected step with `mission_extend` - a step that already ran keeps its task and is never re-dispatched or edited.
+- The dispatch reply for a `running` or `queued` step carries only `{mission_id, step_id, task_id, status, duration_ms, next_step}`. Save `mission_id`, `step_id` and `task_id` immediately, then wait. While a step runs, waiting is your whole job: no file reads, git, tests or messages between waits (see `antigravity-bridge`).
+- Review the completed step **before** dispatching the one that depends on it. That is the point of the gate: the dependent step is built on top of what the previous step actually did, not on what it claimed.
+- One dispatch per step at a time. A second concurrent call for the same step is refused ("already being dispatched"); two ready steps may both be started, but ordinary tasks run one at a time across the bridge, so the second waits in the queue (`status=queued`, no process, no file changes).
+- `next_step` on every reply states what is actually possible now. Trust it over your memory of the plan.
+
+## Reading state cheaply
+
+`mission_status` is the call to make after a wait, a reconnect or a restart: one short entry per step (`state`, `task_id`, `blocked_by`, agent, `isolation`, `scope`) plus `progress` (`total`, `completed`, `active`, `ready`, `pending`, `unmet`), with no task text at all. `mission_plan` is the same view **with** the recorded delegate arguments - call it only when you have lost the plan (a new session, a compaction, a different client) rather than re-reading the repository to guess what you asked for.
+
+States come from the task records, live: `ready` (dispatchable now), `pending` (a dependency is not `completed`), then the task's own status. `lost` means the bridge dropped that task record under retention - it is not a failure the agent reported, and it never unlocks the step waiting for it. If you need to know what that step changed, inspect the workspace and then append a new step; do not assume it completed.
+
+## Corrections, failure and closing
+
+| Situation | What to do |
+|---|---|
+| Dependency `failed`, `timeout`, `canceled` or `lost` | Nothing unlocks automatically. Read the step's task output, then `mission_extend` a new step (a new `step_id`) that carries the fix, with the failure output and what is already done in its `context`. |
+| A step needs a second attempt | Append a step; the plan is append-only, so an old `step_id` is permanently used. The same `task_id` is never started twice. |
+| Work discovered while the plan runs | `mission_extend` while the mission is `open`. Keep the goal of the mission the same; add steps, do not rewrite history. |
+| The plan no longer matches reality | `mission_cancel`. No further step can be dispatched and no further step can be appended. Start a new mission instead of forcing an old plan. |
+| The user stops the work | `mission_cancel`. Running steps are **not** killed by it: the reply lists them in `running_tasks`, so tell the user they are still running and that stopping one is `antigravity_cancel_task` on that task - or your own decision, with `cancel_running_tasks=true`, which is a separate destructive choice, not a cleanup step. |
+
+Partial file edits from a canceled or failed step stay on disk; nothing is rolled back, and a worktree branch is never merged by the bridge. `unmet` in `progress` counts exactly the steps that can no longer become ready on their own - when it is the only thing left, the plan needs a correction step or a cancel, not more waiting.
+
+## Cost discipline
+
+A mission multiplies delegations, so budget it like a project, not like a task. Choose the agent per step: a mechanical step (add tests, rename, format) goes to the cheap/fast default; a step whose cause is unknown or whose contract is delicate goes to a stronger agent, or you do it yourself. The bridge owner picks the model, not you. Estimate the mission's cost before the first dispatch from the number of steps and their `timeout_seconds`, tell the user what you expect, and stop to report when the real cost crosses that estimate rather than finishing the plan silently. Do not add "verify" steps that re-do work the previous step already proved; do not re-dispatch a step because a wait timed out client-side (the task is still running).
+
+## Hard rules
+
+`isError=true` is an error even when the client renders text. Never invent a mission tool, a field, or an HTTP payload; use the advertised names. Do not edit `.bridge-state` or the mission records on disk to change a plan, unlock a step, or forget a cancellation. Never plan or delegate deployment, a push to a protected branch, data deletion, credential access, dependency or CI changes, or system changes outside the workspace. Never merge a worktree branch yourself without the user's review of the diff. A mission is a plan of code edits under the same consent rules as one delegation: the user's approval to delegate is not approval to run the whole plan unattended.

package/ui/app.css

@@ -160,6 +160,17 @@ details.more .body { padding: 10px 12px 12px; }
 .tabs button[aria-pressed="true"] { background: var(--surface); color: var(--text); box-shadow: 0 1px 2px rgba(0,0,0,.12); }
 pre.log { margin: 0; padding: 12px; border-radius: 10px; background: #0b0e14; color: #d6dbe8; font: 12.5px/1.55 var(--mono); max-height: 320px; overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; }
 
+/* Missions */
+.mission-page { display: grid; gap: 16px; }
+.mission { overflow-x: auto; }
+.mission-head { display: flex; justify-content: space-between; align-items: flex-start; gap: 12px; flex-wrap: wrap; }
+.mission-head h2 { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+.mission-head .meta-line { margin-top: 4px; }
+.pill.ready { background: var(--accent-soft); color: var(--accent); }
+.pill.lost { background: var(--warn-soft); color: var(--warn); }
+.link-btn { margin-left: 8px; border: 0; background: none; padding: 0; color: var(--accent); font: 600 12.5px var(--sans); text-decoration: underline; }
+.step-args { display: grid; gap: 8px; padding: 12px 14px; border: 1px solid var(--border); border-radius: 12px; background: var(--surface-2); min-width: 0; }
+
 /* Settings */
 .settings { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px; align-items: start; }
 .panel { padding: 18px 20px; display: grid; gap: 12px; min-width: 0; }