# ARCHITECTURE.md — tianshu-mcp Architecture

> Applies to version `0.9.4` (2026-10-09).
> This document describes the **system structure and module boundaries** for developers who will modify this repository; the version marker is only bumped on release commits, and the latest release notes live in `docs/release-v<latest>.md`.
> This document describes the **system structure and module boundaries** for developers who will modify this repository.
> For installation, usage, and host integration see [README.en.md](README.en.md); for handover status, troubleshooting, and lessons learned see [HANDOFF.md](HANDOFF.md).
> Chinese version: [ARCHITECTURE.md](ARCHITECTURE.md).

---

## 1. Positioning and system context

`tianshu-mcp` is an **orchestration layer that Tianshu consumes as a standard MCP server**. Tianshu is the commander and the user-facing surface; this server owns three things:

1. **Scheduling** — task queue, concurrency gate, state machine, timeouts, cancellation.
2. **Execution surface** — delivering the task brief to an external AI agent (Codex desktop, TraeWork, ZCode, or any CLI).
3. **Objective acceptance** — verifying against a git baseline with command checks, code analysis, and optional visual pixel comparison, then producing a report.

```text
┌─────────────────────────────────────────────────────────────┐
│ Tianshu (TUI × GUI)                                          │
│   · Calls tools/call synchronously, one call at a time,      │
│     consuming only content[].text and isError                │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP over stdio (stdout carries JSON-RPC only)
┌───────────────────────────▼─────────────────────────────────┐
│ tianshu-mcp (this repository)                                │
│   scheduling ── execution surface ── acceptance instrument   │
└──────────┬──────────────────────────────┬───────────────────┘
           │                              │
   ┌───────▼────────┐            ┌────────▼─────────┐
   │ External agent  │            │ Target workspace │
   │ GUI: drive UI   │            │ git repo + tests │
   │      over CDP   │            │ .tianshu-mcp/    │
   │ CLI: subprocess │            └──────────────────┘
   └────────────────┘
```

### 1.1 Four hard constraints and the architecture they forced

This project's shape is not a free design choice — it was forced by four **measured constraints**. Read this table before changing the architecture:

| # | Measured constraint | Architectural consequence |
|---|---|---|
| C1 | Tianshu's MCP tool call **returns text only**: `content[]` `text` items are concatenated and `isError` passes through | Every result is "human-readable text + a `---tianshu-mcp-meta---` JSON block"; no resources or prompts (`src/mcp/formatter.ts`) |
| C2 | Tianshu calls `tools/call` **synchronously, per call** | Long tasks must be async: `run_task` returns a `taskId` immediately and `query_task` polls. There is no server push |
| C3 | TraeWork agent requests are TDE-encrypted at the TTNet layer and cannot be constructed outside the client | The only viable path is **driving the desktop UI over CDP** and extracting results from the DOM (`src/agents/traework/`) |
| C4 | The Codex desktop app is an **MSIX store package**; a GUI host cannot `CreateProcess` it directly | It must be activated through `IApplicationActivationManager` COM with an injected dedicated `--user-data-dir` before a CDP port opens (`src/agents/codex/launcher.ts`) |

ZCode falls into the same class: it ships no headless CLI, so it is also CDP-driven (settled by measurement in M2).

---

## 2. Layered architecture

```text
┌──────────────────────────────────────────────────────────────────┐
│ L1 Protocol edge   src/index.ts · src/server.ts · src/mcp/        │
│   entry & CLI dispatch · assembly · 8 tool registrations           │
│   parameter validation · text+meta formatting                      │
├──────────────────────────────────────────────────────────────────┤
│ L2 Task domain     src/tasks/                                      │
│   state machine · per-project serial queue · global concurrency    │
│   gate · event-stream persistence · cancellation semantics         │
├──────────────────────────────────────────────────────────────────┤
│ L3 Orchestration   src/loop/                                       │
│   TaskOrchestrator: dispatch → verify → rework → re-verify;        │
│   round accounting and termination decisions                       │
├───────────────────────────────┬──────────────────────────────────┤
│ L4a Execution   src/agents/   │ L4b Acceptance  src/verify/      │
│   AgentAdapter contract       │                 src/visual/      │
│   CLI spawn / GUI CDP         │   git baseline · command checks  │
│                               │   code analysis · visual diff    │
│                               │   report artifacts               │
├───────────────────────────────┴──────────────────────────────────┤
│ L5 Foundation   src/config/ · src/util/                            │
│   zod schema · data home · hot reload · atomic writes · path       │
│   normalization · logging · skill self-install                     │
└──────────────────────────────────────────────────────────────────┘
```

Dependencies point **strictly downward**: L1 → L2 → L3 → {L4a, L4b} → L5. L4a and L4b do not depend on each other and meet only at L3. That is the most important decoupling boundary in the project: **"who does the work" and "how we judge the work" are two independently replaceable concerns**.

---

## 3. Startup assembly and lifecycle

### 3.1 Entry dispatch (`src/index.ts`)

```text
node dist/index.js                → stdio MCP server
node dist/index.js visual <cmd>   → visual acceptance CLI subcommands
                                    (dispatched before any stdio connection,
                                     so it never occupies the protocol stream)
```

- The data home is resolved by `resolveDataHome()`: env `TIANSHU_MCP_HOME` wins, otherwise `~/.tianshu-mcp`.
- The logger initializes to `<data home>/logs/`.
- Skill self-install can be disabled with `--no-skill-install` or `TIANSHU_MCP_NO_SKILL_INSTALL=1`; a "needs change but not auto-overwritable" directory (`autoInstall:"prompt"` or unknown source) can be approved with `--approve-skill-update` or `TIANSHU_MCP_APPROVE_SKILL_UPDATE=1` (see §3.4).
- Shutdown path: `SIGINT` / `SIGTERM` / stdin EOF / stdin close → archive active tasks and terminate child processes → `exit(0)`.

### 3.2 Assembly order (`src/server.ts`)

`buildServer()` is the single assembly point, and its order carries meaning:

```text
resolveDataHome → Logger → DataHome(BUILTIN_PROFILES) → init()
  → loadConfig() → maxRunning
  → TaskStore → AgentAdapterRegistry(loadProfiles) → AcceptanceEngine
  → TaskManager(+makeBuildCtx) → manager.initialize({maxRunning, guiStopWaitMs})   # archive leftover active tasks
  → skill self-install (background, does not block the handshake)
  → register 8 tools → return ServerAssembly{server, manager, dataHome, store, logger, close}
```

`close()` = `manager.shutdownInterrupt()` (archive active tasks, terminate child processes) → `engine.close()` → `server.close()`.

Tool registration is **data-driven**: it walks `TOOL_DEFS`, looks up each name in `handlers`, logs an error and skips if missing, and passes along `_meta.requireApproval`, `_meta.capability`, and the MCP `annotations` (readOnly / destructive / openWorld / idempotent — `idempotentHint` is true only for `run_task` / `verify_task`, and only means anything when the caller supplies `idempotencyKey`; see §5.6) for the host's policy layer.

### 3.3 Data home layout

```text
<data home>/                      default ~/.tianshu-mcp
├── config.json                   server config (concurrency, timeouts, skills)
├── agent-profiles.json           user-defined / overriding agent profiles
├── projects.json                 project registry (incl. per-project verify config)
├── idempotency.json              idempotency mapping (key→taskId/digest, TTL + capacity pruning; issue #15)
├── logs/server.log               all-level diagnostic log (same source as stderr)
├── browsers/                     managed Chrome for the visual module
├── visual-candidates/<uuid>/     pending baseline candidates (candidate.json + PNGs + preview.html)
├── visual-locks/<sha256>.lock    mutual exclusion for visual operations
└── tasks/<taskId>/               per-task isolated directory (below)
```

Per-task directory (`src/tasks/task-store.ts`):

| File | Contents |
|---|---|
| `task.jsonl` | Append-only event stream (the authoritative timeline) |
| `task.json` | Latest `TaskMeta` snapshot (atomic write) |
| `baseline.json` | Git baseline captured before work started |
| `agent-<round>.log` | Agent output (round is 0-based) |
| `verify-<round>.log` | Verification command output |
| `report-<round>.md` / `.json` | Acceptance report (`.md` for humans, `.json` for machines) |
| `report-<round>.html` | Offline visual report, **only when the report contains visual results** |
| `rework-<taskId>-r<round>.md` | Repair plan (non-Codex path) |
| `qoder-session.json` | Qoder CN send checkpoint (**Qoder only**, see §8.2) |
| `visual/<round>/<pageId>/<viewportId>/` | Visual quadruple: `actual/baseline/diff/regions.png` + `metrics.json` |
| `visual-snapshot.json` | Visual rules snapshot frozen for the task's duration |

Project-side artifacts: `<project>/.tianshu-mcp/acceptance.json` (project-level acceptance config), `<project>/tests/visual/baselines/...` (visual baselines), and for the Codex path `<project>/.zcode/plans/codex-fix-r<N>.md` (repair plan).

### 3.4 Trust and decision model of skill self-install (issue #16)

Module `src/util/skill-install.ts`, run **in the background** inside `buildServer()` (`void`, never blocking the handshake); failures only warn and never block the server.

**Source location**: resolved relative to the package via `import.meta.url` only (`<module>/../../skills/tianshu-mcp`) — a source run and a dist run have the same relative depth, so one candidate suffices. It **deliberately does not fall back to `process.cwd()`**: any cwd-based content discovery turns "debugging the server inside some third-party repository" into a poisoning surface. When no source is found, install is skipped with a warning.

**Install manifest**: kept inside the target at `<dest>/.tianshu-mcp-install.json` (`schema`/`name`/`packageVersion`/`contentHash`/`installedAt`/`sourceDir`, plus `pendingUpdate` when a `"prompt"` hold is recorded). `contentHash` comes from `hashSkillTree()`, which **excludes the manifest itself** (otherwise writing the manifest would prove the target changed) and platform noise (`.DS_Store`/`Thumbs.db`/`desktop.ini`/`._*`/`.git*`). Copying uses the same exclusion predicate, so "hash right after install" equals the source hash exactly (the root of idempotency).

**Decision matrix** (`decideInstall()`, a pure function separating decision from IO):

| Target state | Criterion | `auto` (default) | `"prompt"` | plus `--approve-skill-update` |
|---|---|---|---|---|
| Absent | — | install | install | install |
| Present, content == package | — | skip (repair/calibrate manifest if needed) | skip | skip |
| Manifest ok, content == manifest record ≠ package | untouched stale package copy (trusted) | **backup + overwrite** (warn) | keep + warn + `pendingUpdate` in manifest | **backup + overwrite** (warn) |
| Manifest ok, content ≠ manifest record | local edits (confirmed) | **keep + loud warn** | same | **same (approval has no effect)** |
| No valid manifest (missing/corrupt/not a dir) and content ≠ package | unknown source | **keep + warn** | same | **backup + overwrite** (warn) |

- With `skills.autoInstall: false`, `server.ts` short-circuits and never calls this module; `--no-skill-install` and `false` outrank the approval flag.
- An overwrite happens **only** in the "trusted stale copy" and "explicitly approved" cells; `--approve-skill-update` has **no effect** on confirmed local edits (your skill-document tuning is never silently clobbered).

**Atomic install**: `installFromSource()` follows "copy into `<dest>.incoming-<ts>-<hex>` (manifest included) → rename the old directory to `<dest>.bak-<ts>` → rename into place"; on failure it removes the tmp tree and rolls the backup back (a failed rollback only warns and the backup remains). Stale `.incoming-*` directories older than one hour are cleaned on startup.

**Log levels**: skip / manifest repair = `INFO`; stale-copy upgrade, local edits kept, unknown source, install failure = `WARN`. Searchable stable markers: `含本地修改`, `来源不明`, `未自动覆盖`.

**Backup governance**: after a successful overwrite, `skills.backupKeep` (default 3, `0` = never prune) prunes — matching only directories named exactly `<SKILL_NAME>.bak-<digits>`, keeping the newest N by timestamp and logging deletions at `INFO`; a failed delete only warns. The first-install and skip/keep paths never prune.

---

## 4. MCP tool surface and return contract

Thirteen tools (`src/mcp/tools.ts`), split into three families: `read` (queries, no side effects), `write` (side effects, all require approval), and `execute` (runs project-side commands without modifying sources; currently only `verify_task`, still approval-free per R11):

| Tool | Capability | Approval | Purpose |
|---|---|---|---|
| `run_task` | write | yes | Dispatch work; returns a `taskId` asynchronously |
| `manage_task` | write | yes | Task lifecycle management (merges the former `cancel_task` / `continue_task` / `rework_task`): `action=cancel` cancels (CLI kills the process tree; GUI best-effort stop click + bounded wait); `action=continue` resumes a `needs_user` task in its original session; `action=rework` manual rework feeding the failure summary back to the same agent. **Annotation `destructiveHint=true`** (tool-level; cannot vary per action) |
| `query_task` | read | no | Poll status / progress / log tail |
| `query_info` | read | no | Unified info lookup (merges the former `list_tasks` / `get_task_report` / `get_profiles`): `type=tasks` historical task list; `type=report` full text of a given round's `report.md`; `type=profiles` agent support status and executable discovery results |
| `cancel_task` | write | yes | Cancel (CLI: kill the process tree; GUI: best-effort stop click + bounded wait) |
| `verify_task` | **execute** | no | Run one verification over a task or project path: it runs project commands and may produce build artifacts, but **does not modify sources**, hence approval-free |
| `wait_task` | read | no | Block until a single task reaches a stop point (terminal status or `needs_user`) or the timeout elapses; read-only, harmless |

| `rework_task` | write | yes | Manual rework; feeds the failure summary back to the same agent |
| `prepare_visual_baseline` | write | yes | Produce a baseline candidate and digest (does not adopt a baseline) |
| `approve_visual_baseline` | write | yes | After user review, check the digest and write the baseline |

> **`readOnlyHint` derivation**: `server.ts` emits MCP `readOnlyHint` from `capability === "read"`, so `verify_task` reports **false** for it (as of v0.6.1; it was wrongly `true` before). **`readOnlyHint` is not an approval signal** — approval is carried separately by `_meta.requireApproval`, which stays `false` for `verify_task`.

**Return contract** (`src/mcp/formatter.ts`): human-readable body plus a trailing meta block the host can extract with a regex.

```text
<human-readable text>
---tianshu-mcp-meta---
{ ...MetaBlockFields: taskId, status, ok, round, changedFiles, diffstat, ... }
---tianshu-mcp-meta---
```

**Validation happens in two stages**: `server.ts` first runs `inputSchema.safeParse()` for protocol-level validation (failures return `Error: 参数不合法 — <path>: <message>`); handlers then apply semantic gates, such as the `projectPath` safety check (absolute, exists, realpath-normalized, rejecting the home directory and root-level/system directories), rejecting `mode` for anything but TraeWork, and allowing `allowCreateProject` only for ZCode.

Progress is **persisted, never pushed**: GUI adapters report on the `gui.progressIntervalMs` cadence (default 30 s), `TaskOrchestrator` writes a `note` event into `task.jsonl` and refreshes the snapshot's `progressSummary` / `lastRunSignal`, and `query_task` reads the latest snapshot plus event stream on each call. A poller therefore sees the *last persisted* progress. Besides that free-text progress there is a **semantic** fine-grained event stream (`onEvent`, issue #18), see §5.8 — both are written into the same `task.jsonl`: `note` carries free text, fine-grained events carry node semantics.

---

## 5. Task domain: state machine, queue, persistence

### 5.1 State machine (`src/tasks/task.ts`)

```text
                        ┌──────────────────────────────┐
   run_task ──► queued ─┤──► running ──► verify_start ──┤──► succeeded
                 │      │      ▲            │          │──► failed
                 │      │      │            ▼          │──► needs_attention
                 │      │      └──── fixing ◄──────────┘
                 │      │
                 │      ├──► needs_user  ──► queued   (resumed by manage_task(action='continue'))
                 │      ├──► cancelled
                 │      └──► interrupted
                 └──► cancelled | interrupted
```

- **Statuses**: `queued, running, verify_start, fixing, succeeded, failed, needs_attention, needs_user, cancelled, interrupted`.
- **Terminal**: `succeeded, failed, needs_attention, cancelled, interrupted`.
- **Active**: `queued, running, verify_start, fixing`.
- **`needs_user` is neither active nor terminal** — it can be resumed to `queued` by `manage_task(action="continue")`, or cancelled. This is the host-visible form of a GUI agent waiting for a human.
- `TRANSITIONS` enumerates legal moves explicitly; `TaskStore.updateStatus` additionally guards that "a terminal state can only be re-entered by an explicit continue/rework".
- `errorType`: `timeout | spawn | setup_failed | agent_failed | verify_failed | cancelled | interrupted | agent_unresolved | internal`.
  (`setup_failed` = **logical** failure during setup (mode not ready / project unbound / model unavailable) —
  retrying or changing environments will not help; `spawn` = infrastructure failure (process/install/CDP).
  Declared by the adapter via `AgentRunResult.errorType`; the orchestrator defaults to `spawn`.)

### 5.2 Persistence and crash recovery

Two writes with different jobs:

- **`task.jsonl` (authoritative event stream)**: append-only, with events such as `created / queued / started / verify_start / verify_round / fix_start / succeeded / failed / needs_attention / needs_user / continued / cancel_requested / cancelled / interrupted / timeout_killed / note`. Corrupt lines are skipped on read.
- **`task.json` (query snapshot)**: atomic write (temp file + rename) for fast reads and reconstruction after a crash.

Concurrent-write protection: `TaskStore` chains writes for the same task through `statusWriteTails` to prevent reordering, and `waitForStatusWrite()` is a **read barrier** ensuring a query or cancel never observes an in-memory terminal state before the JSONL event is flushed.

**Crash recovery archives rather than resumes.** `TaskManager.initialize()` scans leftover active tasks and marks them all `interrupted` with `abortSource="shutdown"`. Rationale: GUI sessions and child processes are gone once the server exits, so silently resuming would produce un-attributable half-finished work. Recovery must be an explicit human `rework_task`.

### 5.3 Queue and concurrency

| Mechanism | Rule |
|---|---|
| Global concurrency gate | `concurrency.maxRunning` (default 2, overridable by `maxRunningOverride`) |
| Per-project serialization | Queues are bucketed by `queueKeyOf()`: the normalized `projectPath` in project mode, and the constant key `__zcode_default_workspace__` in no-project mode (never `undefined` / `""`) |
| Scheduling | `pump()`: while `runningCount < maxRunning`, start one task for each project whose queue head is eligible; `projectBusy()` blocks a second concurrent task for the same project |
| Task timeout guard | Beyond the orchestrator's own deadline, `startTask` arms an extra `taskTimeoutMs + 15s` timer in case the orchestrator itself hangs |

### 5.4 Cancellation semantics (by state)

| State at cancel time | Behavior |
|---|---|
| `queued` | Removed from the queue → `cancelled` |
| `needs_user` | Directly → `cancelled`; the terminal message states plainly that the GUI-side waiting session was not stopped (the MCP side holds no CDP connection) |
| Active | `markCancelRequested` → abort → bounded poll for a terminal state (`CANCEL_SETTLE_TIMEOUT_MS = 30s`); returns `settled:false` when the stop is unconfirmed |
| Terminal | No cancellation action; if the task carries the GUI pending marker (`guiResidualUnconfirmed`) this call performs the **manual acknowledgement** instead (terminal status unchanged, see §5.5) |

Cancellation of a GUI agent is **best-effort and honestly reported**, but the adapters differ in what they can do:

| Adapter | Clicks the in-UI stop button on cancel? | Reports `guiStop`? |
|---|---|---|
| Codex / Kimi Code / Qoder CN | Yes — clicks stop over CDP and bounded-waits (`cancelWaitMs`) for the GUI to go idle | Yes (when `idle=false` the terminal message must admit the stop is unconfirmed) |
| ZCode / TraeWork | **No** — only stops MCP-side observation and keeps the instance | No (the terminal message states "no stop result to confirm") |

Shutdown (`shutdownInterrupt()`, issue #14): abort every controller → **spawn tasks keep their bounded 2 s wait per task, while GUI tasks wait until the shared `shutdown.guiStopWaitMs` (15 s by default) global deadline** → mark both `running` and `queued` as `interrupted`. A GUI task's terminal message branches honestly on `guiStop` (confirmed / unconfirmed / no stop result) and **never** claims "the process has been terminated", which only holds for spawn children.

### 5.5 GUI terminal-state facts and manual acknowledgement (issue #14)

| Field | Meaning | Written by |
|---|---|---|
| `TaskMeta.guiStop` | the GUI-side stop result `{clicked, idle}` of the most recent abort (persisted for **every** GUI agent) | `abortTerminal()` / run-result capture |
| `TaskMeta.interruptedCleanStop` | whether this interruption is **confirmed** stopped (true only when `guiStop.idle === true`) | `abortTerminal()` / `persistInterrupted()` |
| `TaskMeta.guiResidualUnconfirmed` | a GUI leftover archived on restart awaits manual confirmation (no connection exists at restart, so it is always set) | `initialize()`; cleared by `cancel_task` |
| meta block `guiStopUnconfirmed` | the single read-side predicate: `guiResidualUnconfirmed===true \|\| interruptedCleanStop===false` | `metaFromTask()` |

Decision matrix (the single implementation of red line 8, `guiStopDisclosure()`): `idle===true` → confirmed stopped; `idle===false` → a stop was attempted but is unconfirmed; **field absent → no stop result, and a stop must not be claimed either**.

The window name is derived from `profile.displayName` (`guiAppNameOf()`, stripping descriptive parentheticals and generic suffixes, falling back to the original string when stripping would empty it) instead of hard-coding `agentId`. **Explicitly not done**: `initialize()` never reconnects over CDP to click stop — there is no session anchor after a restart and the adapters are fail-closed for instances without proof of ownership, so unattended clicking carries more risk than value.

### 5.6 Idempotency keys: retry-safe dispatch and verification (issue #15)

`run_task` (both the project and project-less dispatch paths) and `verify_task` accept an optional `idempotencyKey`. The implementation lives in `src/tasks/idempotency.ts` (`IdempotencyIndex`) and is held by a closure inside `makeHandlers()` — it is **not** added to `AppContext`, so no construction site (including test fakes) has to change.

| Decision | Implementation |
|---|---|
| Namespaces | `run_task` / `verify_task` are independent (map key is `scope\u0000key`) |
| Argument digest | `canonicalDigest()`: stable serialisation (sorted object keys, `undefined` dropped) → same key with different arguments fails closed; the digest covers only the parsed arguments plus the normalised path, never runtime defaults or profile-derived values |
| Hit decision | `lookup()` returns `hit` / `conflict` / `miss`; an entry past its TTL is a miss and is pruned lazily |
| `run_task` hit | Always returns the original `taskId` and its current meta (terminal tasks included — read-only, never re-dispatched); a record whose task snapshot is unreadable counts as not-yet-effective and is re-dispatched |
| `verify_task` hit | Finished → returns the recorded `reportRound` / verdict / report paths (nothing re-runs); running → a success result with `idempotencyReplay: "in_progress"` (never `isError`) |
| Concurrency | `runExclusive()` serialises "re-check → write mapping → create task" per `(scope,key)`, so concurrent same-key calls never each create a task |
| Crash window | The mapping is written **before** the task is created inside the same critical section, which is why `TaskManager.submit()` accepts an optional `taskId` |
| Persistence | `<data home>/idempotency.json` (atomic writes, TTL and `maxEntries` pruning); a corrupt file is logged and rebuilt once from task snapshots via `TaskMeta.idempotencyKey/Scope/Digest` |
| Write failure | Fail-open: the dispatched task is still returned, and the response and meta state that it cannot be replayed by key |
| Key privacy | The raw key lives only in local snapshots and the mapping file; logs and event streams use `keyDigest()` (first 8 hex chars of sha256) |

**The "in progress" marker is process-local** (`reserveInFlight` / `releaseInFlight`): an unfinished verification is not cached across a restart (there is no report to return, so a retry honestly re-runs), which also prevents a mapping stuck at `in_progress` while the engine is long dead.

**Boundaries**: a `verify_task(taskId=…)` key is **not** written into the task snapshot (that field carries the task's dispatch key, so it is never overwritten), and rebuild coverage for that one combination relies on `idempotency.json`; no keys for `manage_task` / the visual baseline tools; no cross-process distributed idempotency (the same assumption the visual lock makes).

### 5.7 Terminal-state notifications: webhook hook (issue #22)

For long tasks the caller previously had to babysit the UI. This capability asynchronously POSTs a JSON
body to a configured URL on state transitions.

| Decision | Implementation and rationale |
|---|---|
| The hook point is `TaskStore.updateStatus()` | It is the **single choke point** for state transitions. `TaskOrchestrator.finish()` only covers orchestrator-driven ends — `cancel()`'s queued branch, `initialize()`'s restart archiving, and `shutdownInterrupt()` / `persistInterrupted()` all bypass it |
| Config lives in the global `config.json` (`notifications.webhook`) | Notification routing is a host/transport concern, not project acceptance policy; and `updateStatus` only has the data home, taskId and logger, so it cannot cheaply read project config on every transition |
| "Exactly once" dedupes on `taskId + status + finishedAt` | `prev !== status` **cannot** be the gate: several paths (cancel's queued branch, `shutdownInterrupt`) **write `meta.status` directly first** and only then call `updateStatus`, at which point `prev` already equals the target state. `finishedAt` is refreshed by `updateStatus` on a terminal write and cleared by `rework`/`continueTask`, so repeated writes for one episode are suppressed while a **new episode after rework notifies again for the same status** |
| Sending happens **after** `appendEvent` + `writeSnapshot` | Persist the local fact first, then notify outward |
| `notify()` returns void (fire-and-forget) | Sending and retries run entirely in the background; a slow or dead endpoint **does not block the status-write chain**, and any exception only logs a `warn` |
| Only **true terminal states** are subscribed by default | `needs_attention` (terminal) → `needs_human`; `needs_user` (**non-terminal**, restorable via continue, possibly re-entered later) is a separate class that is off by default — merging them would defeat "only push true terminal states by default" |
| Global `fetch` + `AbortSignal.timeout` + `redirect:"manual"` | The same convention as `src/visual/services.ts`, built into Node ≥ 20, no new dependency |
| Optional HMAC-SHA256 signature | Signs the **raw request body string** (`X-Tianshu-Signature: sha256=<hex>`); a receiver can recompute it with the same secret |
| The notifier is an **optional** third constructor argument of `TaskStore` | Many tests construct `new TaskStore(home, logger)` directly, so backward compatibility is required |

**Disclosed honestly**: best-effort delivery, **not guaranteed** — failures only log; delivery can still
repeat across a server restart or a receiver retry (receivers should be idempotent); the body contains
`projectPath` and local absolute paths to report files, so confirm the receiver is trusted before
forwarding to a public service. See [task notifications](docs/notifications.en.md).

### 5.8 Fine-grained event stream: long-task observability (issue #18)

`query_task` used to return only coarse status: for long tasks — especially GUI agents stuck on confirmation dialogs, file pickers or authorization prompts — callers could not tell "the agent is working normally" apart from "it is stuck waiting for a human". This capability lets adapters report semantic events at key nodes.

The vocabulary lives in `src/agents/agent-events.ts` (**zero dependencies**, to avoid a cycle between `adapter.ts` / `tasks/task.ts` / `tasks/task-store.ts`):

| Event | Meaning |
|---|---|
| `task_dispatched` | Instruction confirmed delivered to the agent |
| `confirmation_dialog_detected` | A confirmation dialog was detected (including stale-dialog cleanup and the native "select folder" dialog) |
| `awaiting_user_authorization` | Waiting for the user to authorize / log in / confirm |
| `file_modification_started` | The agent started executing (**heuristic**: the first UI running signal; does not claim files were changed) |
| `rework_triggered` | Entering rework after acceptance failed (emitted engine-side; `mode` distinguishes auto/manual) |

| Decision | Implementation and rationale |
|---|---|
| Hook location | `AgentRunOptions.onEvent` (`src/agents/adapter.ts`), **not** the agent profile — `agent-profiles.json` is plain JSON and cannot hold a function; forcing one in would break `AgentProfilesFileSchema` parsing and hot reload. "Optional" is expressed by `opts.onEvent?.()` + `makeEmitter` |
| Storage | Written into the **existing** `task.jsonl` (reusing `TaskStore.appendEvent`), **not** an in-memory ring buffer: during long GUI tasks the host may restart and a purely in-memory queue would lose exactly the scene you most need; a parallel stream would create a second source of truth with no shared ordering |
| Bounded memory | Handled on the **read** side: new `readTextTail(p, maxBytes)` (`src/util/fs.ts`) + `TaskStore.readRecentAgentEvents(taskId, limit, maxBytes=64KiB)` read only a tail window, so memory use is decoupled from total file size. `readTextTail` guarantees the result starts at a whole line (it does not drop a whole line when the cut lands on a newline) |
| Reporting robustness | Adapters always report through `makeEmitter`: a no-op when no hook is provided, and it **swallows reporting exceptions** — event reporting is an observability concern and must never affect the task itself |
| Exposure | `query_task`'s `eventLimit` (1..50, default 10); `MetaBlockFields.recentEvents` (passed through `metaFromTask(meta, extra)`'s `...extra`) plus a "recent events" section in the text area. Non-reporting adapters return an empty array and every other field matches v0.6.2 |
| Scope in this version | Only **codex** and **traework** actually report (four emission points each); zcode / kimicode / qoder and all CLI adapters keep the interface but do not report yet |
| Relationship to `note` | `note` is unchanged and remains the progress / audit channel (carrying `progressSummary` / `lastRunSignal`); `recentEvents` filters only the five vocabulary kinds and never mixes `note` in |

**Disclosed honestly**: events are an observability capability, not a delivery guarantee — delivery is not guaranteed, and `query_task` reflects only the last persisted event; `file_modification_started` is a heuristic, so read `changedFiles` / `diffstat` from the acceptance report for hard evidence of changes. See [event stream](docs/event-stream.en.md).

### 5.9 Blocking wait primitive (`wait_task`, issue #28; merges `wait_any` as of v0.9.0)

Turn-driven callers (a Tianshu agent session) only run within the turn that received a user message and cannot poll on their own — once `run_task` returns a `taskId` immediately, "who wakes the session when the task finishes" is a real gap in the tool surface. This capability carries the wait with **one blocking, read-only call**.

| Decision | Implementation and rationale |
|---|---|
| Stop-point definition | `isWaitSettled(status) = isTerminal(status) \|\| status === "needs_user"` (`src/tasks/task.ts`, single decision point). The moment a task **stops making progress** is the moment to wake the caller: `needs_user` is not terminal but has stopped awaiting a human (it can be resumed by `manage_task(action="continue")` and may re-enter) — without waiting for it, `wait_task` blocks until the timeout and the caller knows nothing about "the task is waiting for a person" |
| Wait core | `waitForStops(taskIds, getMeta, {timeoutMs, pollIntervalMs=500, signal})` in `src/tasks/wait.ts`: **pure logic with dependency-injected `getMeta`**, touching neither the filesystem nor TaskManager construction, so it is independently unit-testable; `TaskManager.waitForStops` only wires it (injects `(id) => this.getMeta(id)`, reusing the `waitForStatusWrite` barrier + memory-first + snapshot fallback) |
| Read-only, lossless | During the wait it **writes no task state and touches no task body**; a client truncation / connection drop / timeout never affects the task's continued execution — worst case the caller calls again, and `query_task` yields the latest fact after reconnect |
| Timeout policy | `timeoutMs` defaults to `WAIT_TASK_TIMEOUT_DEFAULT_MS` (50 s, below the common 60 s client tool timeout to leave serialization/round-trip headroom); explicit cap `WAIT_TASK_TIMEOUT_MAX_MS` (600 s), and values above it are **clamped and disclosed honestly** (never silently rewritten, `clampWaitTimeout`). A timed-out response steers the caller into a call loop (≈50 s per round; long tasks need several calls) |
| Interruption awareness | The SDK's `RequestHandlerExtra.signal` (`server.ts` forwards `extra` to the handler) fires on connection close / request cancellation and the wait loop exits immediately without leaking background waits (the SDK's `_onclose` aborts every in-flight handler) |
| `wait_task` batch-mode return semantics | Returns the **first task in `taskIds` array order** that has reached a stop point (determinism first; no `finishedAt` sorting); the entry point validates that all ids exist, failing closed with the missing ids listed if any is absent |

**Known limits**: the wait is **in-process** — after a server restart the original wait call ends with the connection (the caller re-checks via `query_task` after reconnecting); a single call waits at most 600 s, and longer scenarios rely on repeated calls (lossless). See [wait primitives](docs/wait-task.en.md).

---

## 6. Orchestration: the automatic verify-and-rework loop

`TaskOrchestrator` (`src/loop/fix-loop.ts`) is the per-task execution body.

```text
Start
 ├─ Capture the git baseline + freeze/check the visual snapshot
 │    └─ visual error → needs_attention(verify_failed) + pendingVisualVerification
 ├─ If resuming a blocked task: re-verify first (pass ends it, no rework, no wasted round)
 └─ Rework loop (round = meta.roundsUsed, maxRounds = meta.autoFixRounds)
      ├─ status=running → buildCtx(meta, round, feedback) → hold project lock → runAgentOnce
      │     runAgentOnce: adapter.run exists → call it; otherwise runChild + parseExit
      ├─ Branch on the agent result
      │     needs_user            → needs_user (awaits manage_task(action='continue'))
      │     idle/timeout/cdp loss → needs_attention
      │     hardFailure           → failed(spawn)      # infra/auth error, skips verify and rework
      │     timeout / killed      → corresponding terminal state
      ├─ Verify (runVerifyOnce): roundsUsed = round + 1, record report and change set
      └─ Termination decision
            blockingIssues        → needs_attention + pendingVisualVerification
            verdict.passed        → succeeded
            maxRounds > round     → fixing, round += 1, write repair plan, continue
            maxRounds == 0        → failed(verify_failed) + rework hint
            rounds exhausted      → needs_attention
```

**How failure information returns to the agent** — two paths, chosen by agent:

| Path | Artifact | Feedback content |
|---|---|---|
| Codex | `<project>/.zcode/plans/codex-fix-r<N>.md` | Failure evidence extracted from the report, embedded in the fix prompt |
| Others (incl. CLI) | `<task dir>/rework-<taskId>-r<round>.md` | Heading + plan path + `verifySummary` + report path |

**Key design point**: `hardFailure` and "verification failure" are strictly distinguished. The former means environment, auth, or startup problems, for which verification and rework are pointless — the task goes straight to a failed terminal state. Only a genuinely finished agent run enters verification and round accounting.

**Why `pendingVisualVerification` exists**: a task blocked by a missing approved baseline or a mutated baseline must **re-verify first** when resumed by `rework_task`; passing ends it. This avoids burning an agent round on what is actually a rules problem, not a code problem.

---

## 7. The acceptance engine

`AcceptanceEngine.runVerify()` (`src/verify/acceptance.ts`) runs the following stages in order, failing closed on any fatal error:

```text
0. Mutex       withVisualLock(task:<taskId>) then withVisualLock(realpath(projectPath));
               a concurrent verification of the same task is rejected outright
1. Baseline    capture or reuse a git baseline (verify_task reuses the task's stored baseline)
2. Resolve checks  priority: extraChecks > project .tianshu-mcp/acceptance.json
                            > projects.json verify > derived defaults by project type
3. Snapshot freeze #1  freeze the visual rule/baseline digests (**unconditional — independent of visual.enabled**)
4. Git check   built-in git-diff-check runs FIRST (git diff --check, over baseline..HEAD and the worktree)
5. Command checks  serial or bounded-parallel (verifyConcurrency, default 2, clamped 1..4);
                   in parallel mode each writes verify-<round>.parts/NNN-<name>.log,
                   merged back into the main log in declaration order afterwards
6. Visual checks   only when acceptance.json enables visual.enabled, and AFTER the command checks
                   (pages often need the build output first)
7. Code analysis   attribute the change set against the baseline → file list / diffstat / signals
8. Change gate   a git project with zero net change fails → an extra failing `no-changes` check item
9. Snapshot checks #2/#3  once after the commands and once after the visual stage; drift → VISUAL_INTEGRITY
```

> **Order matters**: the built-in `git-diff-check` runs **before** the configured checks, and the visual stage runs **after** the command checks.
> The snapshot freeze and integrity checks are **not** gated by `visual.enabled` — `enabled` only decides whether screenshots/specs/content
> judgement actually run. So "visual disabled" does not mean "nothing visual happens": digests are still frozen and compared, which is what
> detects edits to the acceptance config or the baselines themselves (`VISUAL_INTEGRITY`).

**Derived default checks** (`deriveDefaultChecks`): read `package.json` scripts `typecheck / lint / test / build` and map them to `npm run <script>`; `tsconfig.json` with no scripts → `npx tsc --noEmit` (optional); `pytest.ini` → `pytest -q`; `go.mod` → `go test ./...`; `Cargo.toml` → `cargo test` (the last three are optional).

**Command execution**: `cross-spawn` with structured argv and `shell:false` (**commands are never shell-interpolated**, see §12), `windowsHide:true`, with a `verifyCommandTimeoutMs` deadline (default 5 minutes).

Three fail-closed protections:

1. **Zero-test protection** — a test command that exits 0 while collecting no test cases is flipped to a failure, preventing "the tests ran nothing" from going green. Detection combines output shapes (`# tests 0`, `no tests found`, `no tests ran`, `0 tests (ran|executed|found)`) with name/command recognition of test checks.
2. **Zero-change protection** — a git project with no net change fails through an appended `no-changes` check item; `requireChanges: false` downgrades it to a note. Pure analysis/Q&A tasks must disable it explicitly.
3. **Cancellation fails the round** — any abort during the round sets `passed=false`; checks that never started are recorded as `skipped` ("任务取消，未执行").

### 7.1 Git baseline attribution (`src/verify/git-baseline.ts`)

**Never stash, commit, or roll back.** The flow:

1. Record `HEAD` and the tracked changes and untracked files from `git status --porcelain -uall`.
2. Hash the contents of every file that was **already dirty before work started** (files over 4 MiB are skipped; untracked files are capped at 5000, recording `untrackedHashTruncated` when exceeded).
3. At verification time, diff against `baseline.head`: `git diff --numstat <baseRef> HEAD` (in case the agent moved HEAD) merged with `git diff --numstat HEAD` (the worktree).
4. **Attribution**: files that were dirty before work started and whose current hash still matches the baseline are excluded from "this round's changes"; hash-truncated files are marked `unattributable` and excluded with an aggregate note. So `changedFiles` in the report reflects **what this round's agent actually changed**, not pre-existing dirt in the repository.

### 7.2 Report artifacts (`src/verify/report.ts`)

`report-<round>.md` structure: title and header metadata → `## Automatic command checks` (each `[PASS]/[FAIL]/[SKIP]` with exit code and output tail) → `## Code analysis` (change list / diffstat / suspicious signals and warnings) → `## Structured repair directives` → visual evidence → human-readable conclusion. `report-<round>.json` is the machine-readable counterpart (including the `repairDirectives` field).

The suspicious-signal scan (`src/verify/signals.ts`) is **deterministic regexes** and is advisory only, never a standalone failure cause: `TODO/FIXME/HACK/XXX`, `console.*` / `debugger`, three or more consecutive full-line comments, and secret-like literals.

### 7.3 Structured repair directives (`src/verify/directives.ts`, issue #19)

A repair report is a full narrative, so the agent has to locate by itself "which line has the type mismatch, which file has a TODO" — high reasoning cost and easy to misread. This module parses failure reasons into **directly executable actions** `{file?, line?, issue, action, source}`.

| Decision | Implementation and rationale |
|---|---|
| Matching | The repo has **no** per-verifier modules (typecheck/test/build are all generic argv command checks), so sources match on "check name / argv heuristics" plus structured data inside the report |
| Built-in sources | `typecheck` (parses pretty / plain TS errors out of failed typecheck checks' `outputTail`; absolute paths normalized to project-relative POSIX; duplicates collapsed) and `diffstat` (oversized single-file changes, modified lockfiles, and line-level counts for TODO / debug output / secret-like patterns) |
| **No** test-class extraction | Test-framework output has no stable file/line; parsing it anyway would produce **wrong** locations, which is worse than producing none — those always take the fallback path |
| Never throws | A single source's exception is swallowed and recorded in `fallbackReason` while the other sources keep working |
| Explicit fallback | A non-empty `fallbackReason` means renderers (both repair-plan variants and the rework message) must state "unavailable" and tell the agent to return to the full failure output — a **silent gap is not allowed** |
| Failed rounds only | A passing round has nothing to fix; extracting there would only bloat the report |
| Persistence | Written into `report-<round>.json`: the manual-rework path re-reads this file, and it must survive a server restart |
| Line-level signals never fake a file | `signals.ts` only counts and has no stable file or line, so those directives **omit** `file` |

**Known limitation**: `CheckResult.outputTail` is truncated to the last 4000 characters (`runner.ts`), and a large project's total error count can far exceed that, so **only tail errors are extractable** — the rest is covered by the fallback. This trade-off is accepted deliberately (report size is not inflated for extraction). See [structured repair directives](docs/repair-directives.en.md).

### 7.4 Three-level acceptance config inheritance (`src/config/acceptance-merge.ts`, issue #20)

With several similar projects mounted under one Tianshu host, creating a `.tianshu-mcp/acceptance.json` per project is costly and easy to forget. Hence an inheritance chain (low → high priority): `<data home>/acceptance.default.json` → `<project>/.tianshu-mcp/acceptance.json` → the `acceptanceOverride` argument of `run_task`/`verify_task`. The resolution point remains `resolveChecks()`.

| Decision | Implementation and rationale |
|---|---|
| **Layer schemas carry no defaults** | New `PartialAcceptanceConfigSchema` (every field optional, **no `.default()`**). This is the hazard fixed in this version: parsing a project file that only sets `verifyConcurrency` with the `.default(true)`-bearing `AcceptanceConfigSchema` materializes `requireChanges: true`, which would **in turn override the global layer's `false`**. Defaults are applied by consumers only when the final effective value is absent |
| Merge granularity = field | A field a higher layer **explicitly writes** wins outright; `undefined` means "not written by this layer" and does not participate |
| Arrays replace wholesale | If `checks` is written it replaces the whole array. Concatenating would turn "the project adds one check" into "the project can never remove a global check" |
| **`visual` replaces wholesale, never deep-merged** | Nearly every `VisualConfigSchema` field carries a default, so with deep merging a lower layer's **explicit** value would be silently clobbered by a higher layer's "not written, present only as a default" field (the same `.default()` pollution class as `requireChanges`). Doing it correctly requires merging raw JSON and validating only the result — a larger change for limited benefit, so wholesale replacement is the deliberate choice |
| Broken layer fails closed | A layer that exists but is unreadable / invalid JSON / fails validation is not skipped as empty; it pushes the round to `needs_attention` naming the layer and file (`readAcceptanceLayer`, matching existing project-level semantics). Only `ENOENT` counts as "layer absent" |
| visual comes from the merged result | `executeVerify` no longer re-reads the project file (otherwise the visual from override/global layers would change meaning based on whether a project file happens to exist) |
| Task override stored on `TaskMeta` | It is **task snapshot data**, not configuration: it writes no `acceptance*.json` and affects no other task or project; rework/continue reuse the same snapshot, so it keeps applying |
| Included in idempotency digests | Both `runTaskKeyedFields()` and `verifyIdempotencyDigest()` include `acceptanceOverride` — otherwise a same-key replay would return an old task built on a **different** policy |
| One summary line per round | `resolveChecks()` emits `生效层=… checks=… requireChanges=… verifyConcurrency=…`, sharing its source with the `config acceptance` command so troubleshooting needs no extra tooling |

**Debug command**: `tianshu-mcp config acceptance [projectPath] [--task <taskId>]` (`src/config/cli.ts`, dispatched by `src/index.ts` before the server is created). It is not nested under the `visual` namespace — `acceptance.json` is the acceptance engine's config and merely shares a file with visual acceptance. See the [acceptance config spec](docs/acceptance-config.en.md).

### 7.5 dryRun mode (`src/verify/dry-run.ts`, issue #21)

`run_task` normally drives the agent straight into editing source, and a misunderstanding can produce a
large diff needing rollback. `dryRun` provides the intermediate "see the plan, then decide" state.

| Decision | Implementation and rationale |
|---|---|
| Where the read-only constraint is injected | `makeBuildCtx()` (`src/mcp/context.ts`) merges `DRY_RUN_CONSTRAINT` into `ctx.context`. **One change covers all seven adapters** (they all append `ctx.context`), and since dryRun is a round-0 first dispatch, the zcode/kimicode guard that only appends context on `initialDispatch` does not swallow it |
| A dedicated engine method rather than a branch in `executeVerify` | `AcceptanceEngine.runDryRun()` returns a `DryRunReport` (different meaning from `VerifyReport`). Folding it into the same return value would require a union type or a fake `VerifyReport`, polluting the types and complicating round accounting |
| Consumes no acceptance round | Its report is `dry-run-report-<round>.*`, which does not match `^report-(\d+)\.(md\|json)$`, so `nextReportRound()`'s scan ignores it naturally |
| **The zero-change gate is the core evidence** | `analyzeChanges()` diffs against the pre-work baseline; if changes remain after excluding MCP-owned artifacts (the plan file and any `planDoc` named in the task book) → `dry_run_violation` (error). It **does not depend on the plan being correct**: it still works when the agent produces no plan at all |
| Missing plan degrades but stays visible | `planExtracted: false` plus a `fallbackReason` stating why, with checks degrading to the zero-change gate only; both the report and the message state "plan extraction: failed" honestly |
| Verdict is `needs_attention`, not `failed` | A bad plan needs a **human decision**; it is not a code defect that can be auto-reworked |
| Never enters the rework loop | Same reason: there is no "broken code" to fix in a dry run |
| Ignores `autoVerify` | dryRun's semantics are "review first", not "verify" |
| Requires `projectPath` | Project-less mode has no file tree or baseline to analyse statically; `runTaskWithoutProject` rejects it explicitly rather than degrading into an ordinary task |
| The plan document lives **inside the project** | `.tianshu-mcp/dry-run-plan-<taskId>.md`: `planDoc` can only read project files, so putting it in the task data dir would make it unreachable for the agent. `meta.dryRunPlanDoc` reports the **project-relative** path |

**Disclosed honestly**: a rehearsal is still a real agent invocation (consuming quota and time); the
read-only constraint relies on task-book instructions plus the post-hoc gate, so **violations are caught
and reported honestly but changes that already happened are not rolled back** (the MCP never auto-commits,
auto-stashes or auto-checks-out); the static checks can only verify "the file exists, the location matches,
no obvious contradiction" and **cannot judge whether the plan itself is sensible** — which is exactly what
the human review step is for. Also note `planDoc` is currently consumed only by **Codex and Qoder CN**;
CLI agents and ZCode/Kimi Code/TraeWork do not read it, so for those the plan path must go into the `task`
text. See [dryRun mode](docs/dry-run.en.md).

---

## 8. The agent driver layer

### 8.1 The contract (`src/agents/adapter.ts`)

```ts
interface AgentAdapter {
  id: string;
  buildInvocation(ctx, resolved): SpawnInvocation;    // required: command/args/cwd/env/prompt
  parseExit(res): AgentRunResult;                     // required: child exit → semantic result
  run?(ctx, resolved, opts): Promise<AgentRunResult>; // optional: custom execution surface
}
```

**The one two-path seam**: when `run()` exists, `TaskOrchestrator` does not spawn a child process but calls it (GUI adapters); otherwise it goes through `runChild()` (CLI adapters).

- **CLI path** (`src/agents/cli.ts` + `src/agents/spawn.ts`): `cross-spawn` launches a child process, stdout/stderr go to the log, and the exit code decides the outcome. `promptMode` supports `arg` / `stdin` / `file` for brief delivery.
- **GUI path**: all seven adapters' `buildInvocation()` throws outright and `run()` carries the entire CDP orchestration. **Six of them (Codex / ZCode / Kimi Code / Qoder CN / Open Design / MiniMax Code) add a module-level serial gate** where tasks of the same adapter queue up and a cancelled waiter returns `aborted` without overtaking the current holder; TraeWork has no serial gate and relies on the per-project serial queue plus the global concurrency gate instead.

`AgentRunResult` is the cross-layer information carrier; the key fields:

| Field | Meaning |
|---|---|
| `ok / exitCode / timeout / killed` | Basic outcome |
| `hardFailure` | Infra/auth error that **skips verification and rework** |
| `endReason` | Structured end cause (values per driver below) |
| `needsUserKind` | The specific kind of human intervention needed |
| `guiStop:{clicked,idle}` | Whether the GUI side actually stopped on cancel |
| `session / keptInstance` | Session anchor and whether the instance was kept, for `manage_task(action="continue")` |
| `progressSummary` | Progress persisted for `query_task` to observe |

### 8.2 Execution order for the seven GUI drivers (measured; do not reorder casually)

**TraeWork** (CDP-driven TRAE SOLO CN):

```text
Ensure instance → wait for UI ready → new conversation → switch to target mode
  → bind the project within that mode → switch model → send → poll to completion
```

> Work / Code / Design **each keep their own project binding**, and switching modes swaps the composer's project back to whatever that mode last used. So you must **switch mode first, then bind within the target mode**, and afterwards re-check that both mode and project landed — fail loudly if either is wrong.

**ZCode** (CDP-driven; no-project dispatch since v0.5.2):

```text
Discover install → launch/reuse CDP instance (shared deadline budget) → bind project
  (staged trigger location + layered binding criterion) → pick model (direct selection first,
  provider/family grouping as fallback, decode stable attributes on read-back)
  → full-access permission → send (button readiness check → marker/session diff location)
  → run detection / question detection → poll to completion
```

> **The binding criterion is layered (v0.7.4, issue #24)**: ZCode 3.14.x removed
> `data-project-path` and `data-testid^="workspace-item-"`, so the project path is **no longer
> available** in the DOM and only the display name remains. `boundProjectVerdict()`
> (`src/agents/zcode/project.ts`) therefore layers by evidence strength: **strict equality whenever a
> path is available** (3.11.x semantics unchanged), and **the display name when there is no path
> channel** — requiring the project list to be free of same-name entries (more than one yields
> `project_ambiguous`; it never guesses). That list comes from `projects()`, which only falls back to
> harvesting the expanded `[role="menuitemcheckbox"]` menu when the legacy contracts yield nothing
> (including `aria-checked`, excluding "work outside a project"). The display name is **never written
> into `projectPath`**: with no path channel that field stays an empty string, which is exactly why
> `workspaceIsDefault` still holds in project-less mode. On-device evidence entry point:
> `npm run probe:zcode -- dom-contracts`.

**Codex** (MSIX COM activation):

```text
MSIX discovery (Appx query first + disk scan fallback) → COM activation with a dedicated
  user-data-dir and CDP port → project registration/binding → pick model and reasoning level
  → send (planDoc/designSystem folded into the initial instruction)
  → run detection (stop button + conversation-hash stall) → poll to completion
```

**Kimi Code** (CDP-driven, **two renderer processes**):

```text
Discover install → launch/reuse CDP instance (an existing non-CDP instance → needs_user(close_existing_instance))
  → connect the main window and bring it to front (bringToFront, wait for visibilityState to settle)
  → new draft (bounded retry keyed on ws-chip mounting)
  → bind workspace (full-path match + read-back; unregistered goes through the native "add workspace" dialog)
  → pick model (pill read-back → overlay shortcut menu → "more models…" dialog)
  → thinking tier (validated against the tier set the UI actually renders) → execution mode "fully automatic"
  → send (marker + bounded 60s confirmation) → run detection (stop button / send.is-starting) → poll to completion
```

> **The model menu, thinking tiers and execution-mode menu are not in the main window** — the app's
> `browserOverlayOpenMenu()` renders them into a separate `Kimi Browser Overlay` renderer process, while the
> workspace menu and the "switch model" dialog stay in the main window.
> `src/agents/kimicode/cdp.ts` is therefore a **two-page client** (main + overlay) and excludes the `Screenshot` target.
> "Is the menu open?" must be judged from the overlay's `visibilityState` — content may linger briefly after closing.
> Kimi Code **does not support project-less dispatch**: the task must bind a workspace folder, and `workspaceMode=default`
> or a missing `projectPath` is rejected with `setup_failed`.

**Qoder CN** (CDP-driven, ships its own send checkpoint):

```text
discover installation (explicit gui.exePath → D-drive-first candidates → relative-path templates → standard dirs;
                       non-win32 fails immediately with hardFailure(unsupported_platform))
  → launch/reuse the CDP instance (a live instance without usable CDP → needs_user(close_existing_instance); never restarted)
  → new session (or restore the original by resumeId) → bind workspace (full-path criterion; unregistered goes through "new workspace" + native picker)
  → pick model (exact match inside the default/custom group, disambiguated by modelSource) → thinking tier (saved in Model Management, re-read by reopening)
  → write checkpoint qoder-session.json BEFORE sending → marker + bounded acknowledgement → run detection (data-send-button=generating)
  → this turn's user id paired with assistant:<user id> plus data-assistant-actions → poll to completion
```

> **Completion must belong to this turn's user message**: a "done" in an older reply, a static screen, or a dropped connection never qualifies.
> Pending interactions (question/approval) outrank the stop button — judge `needs_user` first, or the task deadlocks as `running`.
> A checkpoint is written before sending or submitting answers, and **an unconfirmed acknowledgement means observe-only, never an automatic resend**;
> `manage_task(action="continue")` merely re-observes for approval/login waits, and only `agent_question` submits answers back to the original session
> (multi-question answers use a JSON object keyed by the UI's exact question text).
> A static screen with no this-turn completion evidence pauses as `setup_recovery` and **never enters acceptance** — Qoder emits no `idle_timeout`.
> Cancellation stops **only the bound original session** (`stopQoder` requires two consecutive non-running polls before it reports `idle`);
> when unconfirmed, the instance is kept and re-dispatch is blocked. macOS is `research` and dispatch is disabled.

**Open Design** (CDP-driven, **artifact signal**; UI driver wired up; Windows machine-verified, macOS `research` and fail-closed):

```text
launch/reuse the CDP instance after environment sanitisation (drop ELECTRON_RUN_AS_NODE etc.;
  a live instance without CDP → needs_user(close_existing_instance))
  → close this instance's stray #32770 windows (a modal swallows the main window's synthetic clicks)
  → version gate (install config appVersion)
  → bind the working directory (skip when already bound; expand → Select directory → native "Select Folder" via two routes → **read-back verification**)
  → pick model (exact match + echo candidates) → pick design system (search filter + read-back) → pick design direction (Prototype/Document/Website clone only)
  → type the task → send → three-signal run detection (stop button + conversation-text hash + **artifact mtime/size fingerprint**) → poll to completion
  → visual acceptance (the page source is **derived as a suggestion** by visual.ts; acceptance.json is never modified automatically)
  → on failure write .opendesign/plans/opendesign-fix-r<N>.md at the project root → send the plan name in the same session → re-accept
```

> **Two real-machine traps (both fixed; do not regress)**:
> 1. `Open Design.exe` is an Electron launcher with embedded Node. If the caller carries `ELECTRON_RUN_AS_NODE=1`,
>    the launcher is put into Node mode and **rejects `--remote-debugging-port`** (`bad option:`), showing
>    "no window, no log lines, no crash dump". Managed launches always sanitise the environment
>    (`OPEN_DESIGN_ENV_DENYLIST`) while leaving the command line unchanged.
> 2. The launcher uses a "**detached child**" shape: after accepting the port it prints `DevTools listening on …`
>    and **exits 0 by itself**; the real Electron main process is the detached child it spawned.
>    **Exit code 0 never means failure** — the announced port must be parsed from stderr and polling must continue.
>
> **The CDP transport has two paths** (`transport.ts`): `/json/version` is fine, but `/json` (Target enumeration)
> runs on the UI thread and **hangs** during startup because the product's main thread is busy with its own
> billing/telemetry requests. So the layer first tries HTTP `/json`, and on timeout/failure falls back to the
> browser-level WebSocket `Target.getTargets` + `Target.attachToTarget(flatten)` to obtain a `sessionId` and continue.
>
> **It is the only driver with an "artifact signal"**: Open Design writes files continuously while not refreshing the
> conversation for long stretches, so text-only judging would call that normal work "idle and finished". The quiet
> criterion therefore requires **both text and artifacts to be stable**.
> **The UI driver is now fully wired**: every `primary` in `selectors.ts` has landed (evidence comes from the product's
> own web-frontend artifacts' `data-testid` hooks, **not from eyeballing screenshots**), and the 12-step execution chain
> plus the acceptance/rework loop are connected; the shared building blocks are `menu.ts` (trigger → exact match →
> read-back menu selection), `send.ts` (input and send confirmation — click once, never resend) and `recovery.ts`
> (per-step budgets), with failure plans written at the project root by `src/loop/fix-loop.ts`.
> **Binding success means a matching read-back** (not "the native dialog closed"); on selector drift it still
> **hard-fails with `selector_drift`** listing the missing keys and never clicks blindly.
> The version gate compares `appVersion` from `<install dir>/resources/open-design-config.json` (the **Electron**
> version reported by CDP is not a product version). See [opendesign-cdp.en.md](docs/opendesign-cdp.en.md).

**MiniMax Code** (CDP-driven, **two renderer processes**, the seventh GUI agent to be added):

```text
discover install (explicit gui.exePath → fixed-drive relative-path templates with preferredDrives first
                  → uninstall-registry InstallLocation → standard dirs → PATH;
                  non-win32 returns ok:false, macOS is research and dispatch is disabled)
  → launch/reuse the CDP instance (port base 9999, range 9999–10008; a live non-CDP instance → needs_user(close_existing_instance))
  → connect the main window (targetRank convergence; a login/onboarding page → needs_user(login_required))
  → close this instance's stray #32770 windows (a modal swallows the main window's synthetic clicks)
  → re-dispatch guard (a running signal still present on the managed instance → try to stop; if not idle, instance_busy)
  → new task and bind project (`data-workspace-dir` full-path normalised criterion; unregistered goes through "new project"
    → in-app modal → native Select Directory → modal submit)
  → pick model / reasoning level / context window (**a second-level submenu revealed by hovering the model item**,
    with the candidate set varying per model)
  → confirm permission mode (read-back comparison only; candidates are not verified so it never auto-switches)
  → send the task (tiptap input + marker read-back + bounded 60 s send confirmation)
  → three-signal run detection (stop button / failure-text regex / text-hash stability) → poll to completion
  → on failure write .minimax/plans/minimax-fix-r<N>.md at the project root → send the plan name in the same session → re-accept
```

> **It is a "two renderer processes" driver isomorphic to Kimi Code**: the main window (`app://./archon`) carries the
> sidebar / project / conversation / composer, while the model menu is rendered by a separate `Model menu` window
> (`.../dist/model-menu/index.html`); an unrelated `Rsbuild App` helper page shares the same port and must be filtered out.
> `src/agents/minimax/cdp.ts` therefore holds **two CDP clients** (main window + lazily connected overlay).
> **"Is the overlay open?" cannot be judged from `visibilityState`**: MiniMax's `Model menu` window stays resident and only
> clears its content when closed — the **opposite** of Kimi Code's overlay semantics (that conclusion comes from an independent probe).
>
> **The reasoning level / context window live in a second-level submenu** (a real-machine correction): the product's own
> frontend artifact constants show them flat as `role="group"`, but **the real DOM only renders them after hovering the model item**.
> So the driver must "move the mouse away before hovering" (the submenu container is reused, so entering it directly does not
> fire `mouseenter` and the DOM keeps the previous hovered model's tier set) and "constrain candidate reads by ownership"
> (the submenu root's `aria-label` is exactly the target model name). The candidate set **varies per model**: e.g.
> `M3.1-Flash-Preview` has a full tier + window set, `M3` has no tier group, `deepseek-v4.1-flash` has no window group, and the
> `M2.7` family **has no submenu** — requesting those two settings for a model without a submenu **fails closed before sending**,
> never silently reusing the UI's current value.
>
> **It does not support project-less dispatch** (isomorphic to Kimi Code): the task must bind a project folder, and
> `workspaceMode=default` or a missing `projectPath` is rejected with `setup_failed`.
> Run detection **deliberately does not treat the send button's two states as a run signal** — MiniMax's send button only has an
> `aria-disabled` two-state, and both "empty input" and "sent, awaiting reply" disable it, so the button itself cannot tell them apart;
> counting it as a run signal would make a task "running forever once sent". When every stop-button selector fails, the stable window
> still converges the turn (**slow but correct, by design**). Deadlock breaking: a stop button permanently visible plus text stalled
> beyond `stallTimeoutMs` → `needs_user`. **It emits all six `needsUserKind` values** (`continue` dispatches by kind; environment
> kinds always "re-dispatch fresh and resend the full task", and the user's confirmation text is never sent to the model).
> Conversation entries **have no explicit id attribute**, so the anchor is recorded as "project path + conversation title"
> (`minimaxSessionId` / `minimaxSessionTitle` in separate slots); failing to locate the original session always hard-fails as
> `session_lost` and never degrades to opening the "most recent session".
> **No version gate** (there is no `resources/*-config.json` version file, and the version is only readable from the CDP UA — which is
> exactly what is unreadable when driving fails), so `selector_drift` is the fallback. See [MiniMax Code CDP adapter](docs/minimax-cdp.en.md).

### 8.3 Completion detection: run signal first, completion marker second

All seven drivers share one judgment principle (implemented in each `liveness.ts`):

```text
A run signal exists (stop button / loading indicator / active tool call) → still running, never end
  ↓ run signal gone
A DOM completion marker appears ("由AI生成" and friends)               → completed
  ↓ no completion marker
Text hash unchanged for N consecutive rounds + composer re-enabled     → completed (stableRounds)
  ↓ never observed a run signal
Idle for idleTimeoutMs (default 10 min)                               → idle_timeout
                                                                        (abnormal end, instance kept)
```

**This was learned the hard way.** An earlier version treated "static for about 36 seconds" as completion, which prematurely completed long thinking phases. The rule now is that **the run signal absolutely outranks the completion marker**. ZCode additionally treats "the composer input is enabled again" as the authoritative completion criterion (`inputEnabled`).

> **"A run signal was observed" is a precondition of completion (issue #31)**: the third tier above
> (`stableRounds`) only holds **after a run signal was observed in this run**. In practice each driver's
> `PollState` carries `sawRunning` and the `finished` criterion reads
> `sawRunning && stable >= stableRounds && …`. Without it, when the stop-button / loading selectors drift
> the UI *looks* static, so a running task is misjudged as successful after
> `stableRounds × pollInterval` (≈12s by default) and enters the acceptance / rework chain — exactly the
> case the fourth tier (`idle_timeout`) is meant to absorb.
> Run-signal sets per driver: Codex `stopVisible`; ZCode `stopVisible/loading/activeTool`; Kimi Code
> `stopVisible/sendStarting`; MiniMax Code `stopVisible`; Open Design `stopVisible/sendStarting`.
> **Open Design's artifact fingerprint (`artifactSignature`) is not a run signal**: it is the substrate of
> the stillness verdict, and `fetchArtifactForSummary` keeps writing files after the `finished` terminal
> state. Also, `reobserve` rounds (`user_confirmation` recovery) **seed** `sawRunning`, because the
> observed turn was already confirmed running before the recovery — without the seed, "the turn finished
> right before recovery → `finished` unreachable → a bogus `idle_timeout`" would follow.
>
> Correspondingly, `idle_timeout` (along with `task_timeout` / `cdp_disconnected`) is always parked as
> `needs_attention` in `fix-loop` (a non-terminal status recoverable via `manage_task(action="continue")`) and **must not
> enter the project acceptance chain** — the predicate is `shouldParkAsNeedsAttention()`. Adding the gate
> alone would only turn the misjudgement from `reply_stable` (acceptance) into `idle_timeout` (still
> acceptance, since `autoVerify` defaults to `true`).

### 8.4 `endReason` and `needsUserKind` value tables

`endReason`:

| Codex | TraeWork | ZCode | Kimi Code | Qoder CN |
|---|---|---|---|---|
| `reply_stable` (success) | `completion_mark` (success) | `reply_stable` (success) | `reply_stable` (success) | `completion_mark` (success) |
| `aborted` | `ask_user` (success, but blocked) | `aborted` | `aborted` | `aborted` |
| `task_timeout` | `timeout` | `task_timeout` | `task_timeout` | `task_timeout` |
| `idle_timeout` | `idle_no_completion` | `idle_timeout` | `idle_timeout` | **never emitted** (static screen without this-turn evidence → `setup_recovery`) |
| `needs_user` | `setup_failed` | `needs_user` | `needs_user` | `needs_user` (`pause()` reuses the kind as the endReason) |
| `setup_failed` | `cdp_lost` | `setup_failed` | `setup_failed` | `unsupported_platform` (non-Windows) |
| `instance_busy` | — | `cdp_disconnected` | `instance_busy` | `qoder_error` (runtime error; the text carries the specific cause) |
| `project_ambiguous` | — | `project_ambiguous` | — | — |
| `project_create_failed` | — | `project_mismatch` | — | — |
| `project_mismatch` | — | `project_not_registered` | — | — |
| `model_unavailable` | — | `model_unavailable` | `model_unavailable` | — |
| `model_mismatch` | — | `model_mismatch` | `model_mismatch` | — |
| `permission_unknown` | — | `permission_unknown` | `permission_unknown` | — |
| `input_mismatch` | — | `input_mismatch` | `input_mismatch` | — |
| `send_unknown` | — | `send_unknown` | `send_unknown` | — |
| `cdp_disconnected` | — | `session_lost` | `cdp_disconnected` | — |
| `internal` | — | `internal` | `internal` | — |
| — | — | — | `agent_error` (the UI shows a "continue" button or a failure message) | — |

> Kimi Code organises tasks by **workspace** rather than project, so it never produces the `project_*` family;
> binding failures surface as `setup_failed` or `needs_user(setup_recovery / system_permission)`.
> Qoder CN puts the concrete cause in the `error` text (`qoder_model_ambiguous` / `qoder_workspace_mismatch` /
> `qoder_question_*` / `qoder_session_lost` and friends) while `endReason` stays `qoder_error`.

**Open Design** (UI driver wired up, values actually produced):

| `endReason` | Trigger |
|---|---|
| `reply_stable` | Conversation text and artifact fingerprint both stable (successful completion) |
| `version_mismatch` | The install config's `appVersion` is not in `opendesign.supportedVersions` |
| `selector_drift` | Required selectors miss or page anchors drift — hard failure **before any coordinate click**, listing the missing keys |
| `model_unavailable` | The target model does not appear in the panel (the error text echoes the visible candidates) |
| `model_mismatch` | The model read-back does not match the expectation |
| `design_system_mismatch` | The design system read-back does not match after search/click |
| `input_mismatch` | The task text read-back lacks the marker (input unconfirmed) |
| `send_unknown` | The send result cannot be confirmed (**never an automatic resend**) |
| `session_lost` | The bound main window/session is lost |
| `idle_timeout` | Long stretch with no run signal and no completion evidence (abnormal end, instance kept) |
| `task_timeout` | Task-level timeout |
| `aborted` | Cancelled (`cancel_task` / server exit) |
| `setup_failed` | Entry validation failed (invalid design direction / empty task text / executable not found / launch failure) |
| `needs_user` | Human intervention needed (e.g. a live instance without a debug port, `close_existing_instance`) |

**MiniMax Code** (two-renderer driver; values actually produced):

| `endReason` | Trigger |
|---|---|
| `reply_stable` | The text hash stays stable for `stableRounds` consecutive rounds (success) |
| `aborted` | Cancellation (`manage_task(action="cancel")` / server exit) |
| `task_timeout` | Task-level timeout |
| `idle_timeout` | No run signal and no completion evidence for a long time (abnormal end; instance kept) |
| `needs_user` | Human intervention needed (login / binding permission / close an existing instance / question and confirmation / recovery budget exhausted) |
| `setup_failed` | Entry validation failed (illegal tier value / project-less mode / executable not found / instance not ready / project binding failed / insufficient system permission) |
| `session_lost` | The original session cannot be located (**never degrades to opening the "most recent session"**) |
| `instance_busy` | The managed instance still has an unstoppable run (a stop was attempted without success) |
| `model_unavailable` | The target model is absent from the submenu candidates (the error text echoes the visible candidates) |
| `model_mismatch` | The model read-back differs from the expectation |
| `input_mismatch` | The task input read-back lacks the marker (input unconfirmed) |
| `send_unknown` | The send result cannot be confirmed (**never an automatic resend**) |
| `cdp_disconnected` | CDP connection lost (hardFailure) |
| `agent_error` | This turn's conversation judged failed (a failure message / network error in the UI) |
| `internal` | Internal error |

> MiniMax Code organises tasks by **project** (not workspace) but **does not support project-less dispatch**, so it never
> produces the `project_*` family; binding failures surface as `setup_failed` or `needs_user(system_permission / setup_recovery)`.

`needsUserKind` (six values in the union; each driver produces a different subset):

| Value | Meaning | Producer |
|---|---|---|
| `agent_question` | The agent is asking the user something in the UI | ZCode, Kimi Code (heuristic question detection only when `gui.selectors.userGate` is configured), Qoder CN (dedicated answer controls), **MiniMax Code** |
| `user_confirmation` | Parked on a confirmation screen | Codex, Kimi Code, Qoder CN, **Open Design**, **MiniMax Code** |
| `login_required` | Login needed | Codex, ZCode, Kimi Code, Qoder CN, **Open Design**, **MiniMax Code** |
| `close_existing_instance` | An existing instance holds no CDP port; the user must close it | ZCode, Kimi Code, Qoder CN, **Open Design**, **MiniMax Code** (**not Codex**: its `ensureInstance` declares `needsClose` but never returns true) |
| `system_permission` | Missing system permission (e.g. macOS Accessibility) | ZCode, Kimi Code, **Open Design**, **MiniMax Code** |
| `setup_recovery` | Automatic recovery budget exhausted / send result unknown; a human must step in | ZCode, Kimi Code, Qoder CN, **Open Design**, **MiniMax Code** |

> **Qoder CN and MiniMax Code are the only two adapters that can emit all six kinds** (Qoder CN's `pause(kind, …)` uses the
> kind as the endReason too; MiniMax Code's `continue` dispatches by kind).
> **Open Design emits five kinds** (`login_required` / `user_confirmation` / `system_permission` / `setup_recovery` / `close_existing_instance`),
> and notably not `agent_question` (its "asking the user" case is not an answerable form control).
> TraeWork produces no `needsUserKind` at all: its "asking the user" case ends the turn normally (`ask_user`) and releases the instance,
> and it **never reads `ctx.resume`** — so `manage_task(action="continue")` is meaningless for it.

### 8.5 Registry and executable discovery (`src/agents/registry.ts`)

- The constructor pre-registers eight `CliAdapter` bases (codex / zcode / traework / kimicode / qoder / opendesign / minimax / stub), then swaps in the GUI implementation based on `profile.adapter` (`codex-gui` / `zcode-gui` / `traework-gui` / `kimicode-gui` / `qoder-gui` / `opendesign-gui` / `minimax-gui`); it only rebuilds when the implementation class changes.
- `resolve(agentId)` branches on the profile's `status`:
  - `unsupported` → immediate failure;
  - `research` → ZCode goes through the dedicated `discoverZcode`, others through generic probing;
  - `ready` → in order: explicit absolute path → discovery-directory scan → PATH (`where` / `which`). Placeholder commands (`<...>`) are rejected.
- `codex-gui`, `kimicode-gui`, `qoder-gui`, `traework-gui`, `opendesign-gui` and `minimax-gui` skip generic probing: they resolve their executable through `discoverCodex` (Appx query + disk scan), `discoverKimicode` (drive-root relative paths + standard directories + macOS bundle), `discoverQoder`, `discoverTraework`, `discoverOpenDesign` and `discoverMinimax` respectively. **`traework-gui`, `qoder-gui`, `opendesign-gui` and `minimax-gui` additionally require `process.platform === "win32"`** — on any other platform `resolve` returns `ok:false` even when an installation was found, so they can never be dispatched on macOS. All seven `discovery.ts` modules share one order skeleton: explicit path → fixed-drive relative paths (`preferredDrives` first) → registry `InstallLocation` → shortcut (qoder/traework) → standard dirs (incl. macOS bundle) → PATH.
- `profile.adapter` explicitly outranks `driver`: `driver:"spawn"` + `adapter:"codex-gui"` still installs the GUI implementation. `ensureAdapterFor` rebuilds only when the implementation class changes, so an ad-hoc swap does not disturb a running task.
- Selector overrides: TraeWork / ZCode / Codex / Kimi Code / Qoder CN / **Open Design** / **MiniMax Code** all use **override → primary → fallback chain** (Kimi Code namespaces overlay keys as `overlay.<key>`). As of v0.6.2 Qoder CN was upgraded from a single-value override to a layered structure matching Codex (`QoderSelectorSpec`: `primary/fallbacks/texts/ariaLabels/ariaPatterns/verifiedVersion`); `QoderCdpClient.selector()` still returns the string primary to keep existing semantics, and adds `candidates()/existsKey()/clickKey()` that probe candidates in order before clicking.
- Selector-drift diagnostics (v0.6.2, issue #23): `src/agents/gui-diagnostics.ts` provides `visibleLabelsExpr()` (a page expression that collects visible candidate aria-labels / short texts) and `withDiagnostics()` (idempotently appends "页面可见候选=[…]"). codex / qoder / traework all attach this on selector-resolution failure so drift can be located in one step; each agent's `selectors.ts` records the tested version via `verifiedVersion`.
- Directory scans look up to depth 6, skipping `node_modules` and dot-directories, and **pick the newest by mtime**.
- Profile hot reload keys off a sha256 content stamp (not mtime), so edits within the same timestamp tick are still detected.
- `query_info(type=profiles)` lists the union of registered adapter keys and profile keys (custom profiles that failed to resolve still appear) and reports `[PASS]/[FAIL]` with the discovery source for each.

### 8.6 GUI instance lifecycle

| Stage | Mechanism |
|---|---|
| Launch | Six go through `guiInstanceSpawnOptions()`: **unconditional** `detached: true` + `unref()` (`stdio:"ignore"`); Open Design additionally uses the `guiInstanceDiagSpawnOptions()` variant (stderr captured into a bounded pipe for launch-failure diagnosis) |
| Reuse | Prefer a managed instance (Codex matches the dedicated `--user-data-dir`; ZCode / Kimi Code / Qoder CN / Open Design / MiniMax Code scan a port range; TraeWork probes the port directly). **Qoder CN spawns only when no root process exists, and reuses the existing CDP port when the launcher forwards an exit** (Open Design / MiniMax Code share that forward-and-reuse semantics) |
| Attach | A CDP connection is only accepted after one real DOM round trip (`exists("chatInput")`) |
| Liveness | One DOM evaluation per tick, handed to the respective `judge*Poll` |
| Keeping | Codex / ZCode / Kimi Code / Qoder CN / Open Design / MiniMax Code set `keptInstance: true` on nearly every return path and never kill the process; TraeWork releases its own instance only on a clean completion (`completion_mark` / `ask_user`), and only then reports `keptInstance:false` |
| Ownership checks | TraeWork **re-reads the live command line** before releasing and requires both the recorded `--remote-debugging-port=<port>` and the exe basename; if it cannot read or match them it gives up (avoiding a wrong kill), and its `taskkill` **omits `/T`**. Codex stops only managed instances |
| Orphans | ZCode / Kimi Code / Qoder CN / Open Design / MiniMax Code meeting a live instance *without* a CDP port yield `needs_user(close_existing_instance)` for the user to handle; they never kill blindly. (Codex declares `needsClose` in its instance contract but never returns true, so it has no such path) |

> **`detached: true` is an invariant, not a platform preference**: the desktop instance must outlive the MCP server to honor the `keptInstance` contract. Before v0.5.3 the spawn was platform-branched (not detached on Windows), so the GUI was killed along with the server on exit; that is fixed.
>
> Note the opposite semantics for **execution child processes** (`agents/spawn`, `verify/runner`, `visual/services`, `visual/content-command`): these stay platform-branched (`detached: process.platform !== "win32"`), because they must be reaped together with the server. That family has **no shared helper** — the same spawn-option literal is written out at four call sites; unifying it is known debt (see §15).

---

## 9. The visual acceptance path (optional module, since v0.5.0)

When disabled it has zero effect on existing behavior; when enabled it is an acceptance path **independent of command checks**.

```text
Project .tianshu-mcp/acceptance.json sets visual.enabled=true
  → run_task / verify_task append visual checks after command checks (no new tool needed)
  → before work starts, freeze "visual config digest + baseline digest" and re-check each round
    (any change raises VISUAL_INTEGRITY, a blocker)
  → Pages: three source kinds (existing / command / static) + declarative steps + stabilization
        sampling + explicit masking → pixel comparison against the approved baseline (pixelmatch)
        → if pages[].content is declared, reuse the same screenshot for a content judgement
          (pixel:false does content judgement only)
  → Images: explicit file list + encoding/size/DPI/transparency spec validation
  → Content (v0.5.4, optional): judgement of "does the image/screenshot content match the declared
        expectation" delegated to a user-supplied command
        → majority sampling + task-level input-hash cache (key includes the command binary identity)
        → warning-only by default (optional); a per-rule blocking:true joins failure and rework
  → Defects rework per autoFixRounds; blockers → needs_attention
  → rework_task re-verifies a blocked task first instead of starting the agent
```

**Credential boundary of AI content validation (v0.5.4, red line §12)**: the MCP reads, stores, and forwards no
keys and ships no model/vendor HTTP client; judgement is fully delegated to a command the user declares. The MCP
only expands placeholders (`<image:path>` / `<expect:file>` / `<image:base64:file>`), spawns the child with
`shell:false` and structured argv, and strictly validates the JSON on the last stdout line. The egress gate is
**contract-level**: `allowRemote` defaults to `false`, and a rule without the opt-in using `<image:base64:file>`
is rejected by the schema outright; whether a command actually sends the image out **cannot be blocked at the
system level** and the user must confirm it (see `SECURITY.en.md`).

**Status semantics of content judgement (v0.5.4)**: `VisualResult.status` gains `uncertain` (split votes or
confidence below `minConfidence`), which matches neither `visualFailed` (only `failed`) nor `visualBlocked` (only
`blocked`) and therefore **never affects the verdict**. Whole-round failures (`CONTENT_COMMAND_MISSING` /
`CONTENT_ENV_MISSING`) are raised during the pre-check (`assertContentReady`, which enumerates each rule's
**effective** command and env) and escalate through the `acceptance.ts` try/catch into a `configurationError`,
producing **no result rows at all**.

**Baselines are strictly two-phase**:

1. `prepare_visual_baseline` — produces only a candidate (`visual-candidates/<uuid>/` with `candidate.json`, PNGs, `preview.html`) plus a digest; it **does not adopt a baseline**.
2. `approve_visual_baseline` — called only after explicit user review and authorization. Before writing it checks a **three-way digest** (candidate + previous baseline + config) plus that the target path is not gitignored and that the associated task really is `needs_attention` in the same project, then atomically writes the baseline and a `manifest.json` approval record.

**A missing baseline must never pass, and automatic rework is forbidden from calling the approval entry point.**

Engineering constraints (`src/visual/`):

| Concern | Implementation |
|---|---|
| Browser | `puppeteer-core` headless Chrome/Edge; in `managed` mode `@puppeteer/browsers` installs a pinned revision under `<data home>/browsers` |
| Resource limits | Only local origins plus `allowedOrigins` are allowed; everything else is intercepted (`RESOURCE_BLOCKED`) |
| Stability | Requires `stabilitySamples` (default 3) byte-identical screenshots in a row; otherwise `SCREENSHOT_UNSTABLE` |
| Budget | `VisualBudget`: per-round deadline plus an artifact byte ceiling (default 500 MiB) |
| Mutual exclusion | `withVisualLock()`: `<data home>/visual-locks/<sha256(key)>.lock`, returning `VISUAL_BUSY` when held |
| Missing dependencies | `sharp` / `pixelmatch` / `puppeteer-core` missing **blocks explicitly** rather than degrading silently |
| Rule freezing | Config or baseline changed during a task → `VISUAL_INTEGRITY`, so an agent cannot weaken the acceptance rules |
| Content judgement (v0.5.4) | `src/visual/content*.ts`: command resolution (`where`/`which`), placeholder expansion, `runChild`-semantics subprocess execution, strict JSON on the last stdout line; the pure `tallyContentVotes` handles the majority vote and confidence gate; the task-level cache carries `commandPath`/`commandDigest` so upgrading your CLI invalidates it |
| Semantic-only pages (v0.5.4) | `pages[].pixel:false` skips the baseline requirement and pixel comparison (requires `content`); `prepareBaseline` skips them explicitly and never offers them as candidates; `captureVisualSnapshot` **records null** for their baselines (reading no stray files, so the frozen digest cannot drift) |
| Warning isolation (v0.5.4) | `blocking:false` → `optional:true`, staying out of `visualBlocked`/`visualFailed` and never triggering rework; the repair plan lists "warning-only items (no fix required)" and the pre-existing defect of listing `optional` failures as "must fix" is fixed |

CLI subcommands (`node dist/index.js visual ...`): `init` (writes a disabled template config), `doctor` (now with content-command resolution and budget-comparison findings), `browser install`, `baseline prepare|approve`, `rules review|approve`, `artifacts clean`, `content probe <project> [ruleId]` (runs a real judgement without writing evidence or cache), `content cache clear <taskId>`.

---

## 10. Configuration system and hot reload

### 10.1 Sources and precedence

| Config | Location | Notes |
|---|---|---|
| Server config | `<data home>/config.json` | `concurrency.maxRunning` (2), `defaultTaskTimeoutMs` (30 min), `verifyCommandTimeoutMs` (5 min), `verifyConcurrency` (2, 1..4), `shutdown.guiStopWaitMs` (15 s, global upper bound for the GUI stop wait on shutdown), `idempotency.ttlMs` (24 h), `idempotency.maxEntries` (2000), `skills.autoInstall` (true \| "prompt" \| false), `skills.backupKeep` (3, 0..50, 0 = never prune) |
| Idempotency mapping | `<data home>/idempotency.json` | key→taskId/digest mapping (not a hand-written config file; atomic writes, lazy loading, TTL and capacity pruning — see §5.6) |
| Agent profiles | `<data home>/agent-profiles.json` | **Whole-key override** of built-in profiles |
| Project registry | `<data home>/projects.json` | Includes each project's `verify[]` records |
| Project acceptance | `<project>/.tianshu-mcp/acceptance.json` | `checks[]`, `visual`, `requireChanges` (true), `verifyConcurrency` |

Task timeout resolution: call argument `taskTimeoutMs` > profile `timeoutMs` > `defaultTaskTimeoutMs` > 30 minutes, frozen at submit time.

### 10.2 Hot reload and last-known-good

- Every `loadConfig()` / `loadProfiles()` / `loadProjects()` compares a **sha256 content stamp** and re-reads only on change, so it does not depend on mtime and catches same-second edits.
- **Last-known-good policy**: when JSON parsing or zod validation fails, the server **keeps the previous valid config** rather than clearing it; only a first-ever load failure falls back to schema defaults. A corrupted config file therefore cannot strip configuration from a running service.
- Write paths (`saveConfig` / `registerProject` / `updateProjectVerify`) always write atomically and refresh the stamp.

### 10.3 Agent profile field groups (`src/config/schema.ts`)

| Group | Fields |
|---|---|
| Identity and shape | `id`, `displayName`, `type`, `driver` (spawn\|gui), `adapter` (traework-gui\|zcode-gui\|codex-gui\|kimicode-gui\|qoder-gui\|opendesign-gui\|minimax-gui), `status` (ready\|research\|unsupported) |
| CLI execution | `command`, `argsTemplate`, `promptMode` (arg\|stdin\|file), `cwd` (task\|home), `env`, `timeoutMs`, `killTree` |
| Executable discovery | `executableDiscovery`: `dirs`, `fileNames`, `fallbackCommand`, `preferredDrives`, `appxPackageName`, `scanRoots`, and more |
| GUI orchestration | `gui`: `cdpPort` (9222), `cdpPortRange`, `exePath`, `windowMode`, `launchTimeoutMs` (60 s), `pollIntervalMs` (3 s), `stableRounds` (12), `idleTimeoutMs` (10 min), `stallTimeoutMs` (300 s), `cancelWaitMs` (15 s), `cdpSendTimeoutMs` (15 s), `progressIntervalMs` (30 s), `projectTriggerTimeoutMs` (15 s), `workspaceTriggerTimeoutMs` (15 s, Kimi Code draft-page criterion), `selectors`, `defaultPermissionMode`, `defaultAutoFixRounds`, `activation` (spawn\|msix-com), `userDataDir`, `fixPlanDir`, and more |

`gui.selectors` is the primary way to **adapt to client UI upgrades without touching code**: when a client release breaks selectors, diagnose with `scripts/probe-*.mjs` first, then override through the profile.

> **Declared but currently unused fields** (check before assuming a setting does something): `gui.windowMode` (schema default plus comments only),
> `gui.modelRequired` (whether a model is mandatory is decided unconditionally by each `parse*Model`), and ZCode's `gui.stallTimeoutMs` /
> `gui.cancelWaitMs` (copied into locals and never read — ZCode has no stall path and never clicks stop). `gui.activation` is consumed by Codex only.

---

## 11. Cross-platform strategy

Goal: **Windows and macOS both work, with no hard-coded machine paths.**

| Concern | Approach |
|---|---|
| Path placeholders | `{LOCALAPPDATA}`, `{APPDATA}`, `{PROGRAMFILES}`, `{PROGRAMFILES(X86)}`, `{SYSTEMDRIVE}`, `{HOME}`, `{USERPROFILE}`, `{XDG_DATA_HOME}` expand via `expandEnvPath()` (case-insensitive); unset directories fall back to platform default discovery dirs |
| Path normalization | `normPath()`: absolutize + POSIX separators + lowercase drive letter + strip trailing slashes; project directories additionally go through `realpath` (eliminating `/tmp → /private/tmp`-class traps) |
| Process-tree termination (execution) | Windows: `taskkill /pid <pid> /T /F`; POSIX: process-group SIGTERM, then SIGKILL after 800 ms |
| Process enumeration | Windows: PowerShell `Get-CimInstance Win32_Process`; POSIX: `ps -axo pid=,command=` |
| Executable lookup | Windows: `where`; POSIX: `which` |
| Native dialog automation | Windows: PowerShell + UIA; macOS: `osascript` / System Events (ZCode has both branches; Codex and TraeWork native dialogs are **Windows-only and fail closed on macOS**) |
| Drive enumeration | No hard-coded drive letters; fixed drives come from a WMI query |
| Versions / AUMID | Always discovered dynamically, never hard-coded |

Platform differences are concentrated in profiles and a handful of `platform` decision points rather than scattered through business logic.

---

## 12. Security boundary and hard red lines

Violating any of these causes runtime corruption or an incident:

1. **Never blind-kill TraeWork's process tree**: only terminate PIDs this module created and whose command line it verified, and never with `/T`. (Past incident: a verification-time `taskkill /PID <pid> /T /F` killed an instance the user was actively using.)
2. **Reuse the user's instance by default**: `gui.windowMode = "reuse"`, never start a second one; managed instances (Codex / ZCode launched with a dedicated `user-data-dir`) likewise never touch an instance the user opened manually.
3. **computer-use allowlist**: only the TraeWork folder-selection dialog (window title and host process both verified); anything else is `COMPUTER_USE_DENIED`.
4. **Zero credential handling**: never read, decrypt, or forward any agent credential; GUI adapters only drive the UI. **AI content validation (v0.5.4) is bound by the same rule**: no model/vendor HTTP client and no key reads — judgement is delegated to a user-supplied command, and the egress gate is contract-level only (the schema rejects `<image:base64:file>` without an `allowRemote` opt-in). The MCP **cannot block a user command from sending images out at the system level**, and that boundary must be stated plainly (see `SECURITY.en.md`).
5. **Never build commands through a shell**: verification commands are structured argv with `shell:false`.
6. **Never auto commit / stash / roll back**: capture a git baseline before work and compute reports relative to it.
7. **No hard-coded paths**: machine paths, user names, and ports come from profiles or placeholders.
8. **stdout carries JSON-RPC only**: all diagnostic logs go to stderr (and append to the same `logs/server.log`). Any noise on stdout breaks the MCP stream and fails the handshake with strict clients.
9. **Skill content comes from the package only**: the skill to be installed is located relative to the package via `import.meta.url`; **there is no cwd-based content discovery**, and a target whose content cannot be proven untouched is never overwritten silently (see §3.4).

**Path safety gate**: `projectPath` is validated at submit time — it must be absolute, the directory must exist, symlinks are realpath-normalized (the receipt states the resolved source), and **the home directory itself and system/root-level directories are rejected outright**, preventing a worker's write permissions from covering an entire system subtree.

---

## 13. Extension points

### 13.1 Adding a CLI agent (the common case)

Usually this **only needs a profile**, no code change: write a `driver: "spawn"` profile in `<data home>/agent-profiles.json` (`command`, `argsTemplate`, `promptMode`, `timeoutMs`, `executableDiscovery`) and it becomes usable via `run_task(agentId=...)` and visible in `query_info(type=profiles)`. See [docs/agent-profiles.md](docs/agent-profiles.md) and the `codex-cli` example in the README.

### 13.2 Adding a GUI agent

This requires a new adapter directory implementing `AgentAdapter` with `run()` as the execution surface, typically containing:

| Responsibility | Suggested module |
|---|---|
| Adapter and serial gate | `adapter.ts` |
| Executable discovery | `discovery.ts` |
| Instance start/stop and reuse | `instance.ts` / `launcher.ts` |
| CDP client and selectors | `cdp.ts` / `selectors.ts` |
| Project and model selection | `project.ts` / `model.ts` |
| Completion detection | `liveness.ts` |
| Orchestration | `run.ts` |
| Registration | add a `profile.adapter` branch in `agents/registry.ts` and a default profile in `agents/builtin.ts` |

### 13.3 Other extension surfaces

| To extend | Landing spot |
|---|---|
| Add an MCP tool | Add metadata in `src/mcp/tools.ts` + implementation in `src/mcp/handlers.ts` + an input schema in `src/config/schema.ts` |
| Add an acceptance check source | The `resolveChecks()` precedence chain in `src/verify/acceptance.ts` |
| Project-level acceptance rules | The project's `.tianshu-mcp/acceptance.json` (no code change) |
| A selector drifting with a client upgrade | Profile `gui.selectors` override (no code change) |
| A new visual case type | `src/visual/schema.ts` + job construction in `engine.ts` |

---

## 14. Testing and delivery pipeline

### 14.1 Test layers

| Layer | Location | Coverage |
|---|---|---|
| Unit | `test/unit/` | Pure functions and component logic: reply / selectors / launcher / liveness / recovery for all seven drivers, the acceptance engine (including parallelism), baseline attribution, atomic writes, hot reload, the path gate, the visual module |
| Integration | `test/integration/` | The three stub-agent scripts, cancel / timeout / baseline, fake-CDP TraeWork / Codex / ZCode / Kimi Code / Qoder CN / Open Design end-to-end and rework loops, race regressions, visual services / capture / flow |
| Protocol | `test/protocol/` | An official SDK client asserting the 8-tool surface and return format |
| Real-hardware (manual) | `scripts/probe-*.mjs`, `scripts/smoke-zcode.mjs`, `scripts/evidence-visual-windows.mjs` | Require a real client or an installed browser |
| Consumer | `scripts/check-visual-consumer.mjs` | Installs the production tarball into a directory with no dev dependencies and runs real-browser visual acceptance plus the offline report |

### 14.2 Gate discipline (all learned from CI failures)

1. Assistant replies in `test/fake-cdp.ts` must be **appended synchronously**; do not revert to a timer — with a short poll interval and a low `stableRounds`, a timer races the stability fallback.
2. Integration tests must **isolate native dialog enumeration**: the default `listDialogs` stub in `depsFor` is not optional, or tests reach the real `listOwnedDialogs`, whose darwin branch fails closed and throws on runners without the required authorization.
3. Real-browser cases default to `skipIf(TIANSHU_VISUAL_BROWSER_TEST !== "1")`; CI's `visual-browser` job opts in explicitly.

### 14.3 CI and release

| Workflow | Trigger | Contents |
|---|---|---|
| `ci.yml` | Push / PR to master and main | `build-test` (ubuntu / windows / macos × Node 20/22/24), `pack-check`, `visual-browser` (ubuntu / windows / macos-15-intel / macos-15 × Node 20/22/24, real browser) |
| `release.yml` | Push of a `v*` tag | Full gate → verify tag version === `package.json` version → require a successful CI run for the same SHA → bilingual body (`docs/release-v<ver>.md` + `.en.md`; **a missing document fails the run**) → publish the GitHub Release with the tgz attached → idempotently create the Gitee release via `scripts/gitee-release.mjs` |

Three places must agree on the version: `package.json`, `package-lock.json`, and `src/version.generated.ts` (the last is generated from `package.json` by `scripts/sync-version.mjs` before every build — **do not edit it by hand**).

---

## 15. Known gaps and technical debt

Ordered by impact on a successor:

1. **UI signals are the only reliable completion criterion** — all seven GUI drivers depend on DOM structure and visible signals. Client upgrades can drift selectors; fix in `selectors.ts` or via a profile override, and real-hardware re-verification is not optional.
2. **A session waiting in the GUI cannot be stopped while the task is `needs_user`** — the MCP side holds no CDP connection. Terminal messages state this honestly. Stopping via a temporary CDP connection is listed under "planned" in `CHANGELOG.md`.
3. **Single-session serialization** — a GUI is a single-session resource, same-project tasks serialize behind `projectBusy()`, and global concurrency is capped by `maxRunning`. This is a design constraint, not a defect.
4. **macOS verification matrix is incomplete** — Codex and ZCode have real-hardware macOS happy paths, but cancel / rework / `manage_task(action="continue")` / new-project matrices are uncovered, so both stay `research` on darwin; TraeWork, Kimi Code, Qoder CN, Open Design and MiniMax Code fail closed on macOS (Kimi Code / Qoder CN / Open Design / MiniMax Code stay `research` on darwin, while TraeWork returns `ok:false` outright on non-Windows).
5. **No-project dispatch is ZCode-only and Windows-verified only**; ZCode's auto-import of unregistered projects is unavailable on Windows (register the directory manually first, or pass `allowCreateProject=false` to fail explicitly). **Kimi Code does not support project-less dispatch at all** (it must bind a workspace).
6. **Kimi Code cancellation / question answering / same-name workspace ambiguity are covered by hermetic integration tests only** (no hardware stop click, no real question card triggered).
7. **Visual module platform-evidence boundary** — macOS evidence comes from CI-hosted runners and has not been re-confirmed on the maintainer's own macOS device.
8. **Acceptance fail-closed affects pure analysis tasks** — a git project requires changes by default, so pure Q&A/analysis tasks must explicitly set `requireChanges: false`.
9. **Execution children have no shared spawn-option helper** — `agents/spawn`, `verify/runner`, `visual/services` and `visual/content-command` each inline the same platform branch (`detached: process.platform !== "win32"`). Same semantics, four copies; an edit can easily miss one.
10. **Some profile fields are declared but unused** — `gui.windowMode`, `gui.modelRequired`, and ZCode's `gui.stallTimeoutMs` / `gui.cancelWaitMs` (see the note in §10.3).
11. **No automatic GUI stop on restart** — `initialize()` only labels GUI leftovers honestly and sets `guiResidualUnconfirmed`; it never reconnects over CDP to click stop, because there is no session anchor after a restart and the adapters are fail-closed for instances without proof of ownership. Confirmation is manual, through `cancel_task` (§5.5).
12. **Subtree denial for dangerous directories has residual edges** — `/etc` `/usr` `/bin` `/sbin` `/private/etc` plus `c:/windows` and `c:/program files*` are denied as subtrees (v0.6.1), but `/var`, `/tmp`, `/opt`, `/library`, `/system`, `/root` and `c:/users` still only block the **exact root**; their subdirectories remain usable as workspaces. That is a deliberate trade-off: on macOS `os.tmpdir()` *is* `/var/folders/...`, so a blanket subtree rule would sever the test base and many legitimate workspaces (see the `DANGEROUS_SUBTREES` comment in `src/util/path.ts`). UNC-shaped gaps were reported through the security channel and are out of scope for this repository's public fixes.
13. **`capability` is consumed on the Tianshu host side** — this repository only guarantees that the emitted `_meta.capability` and MCP `annotations` are self-consistent (the truth table is pinned by `test/protocol/protocol.test.ts`). Since v0.6.1 `verify_task` is `execute` with `readOnlyHint: false`; host policies that hard-code that annotation need to relax accordingly (`requireApproval` is unchanged, so the approval experience does not regress).

---

## 16. The second delivery surface: log viewer GUI (`mcp-gui/`)

`mcp-gui/` is the repository's **second delivery surface** (issue #25): a **read-only local** desktop app built with
Tauri 2.x (Rust backend) + Vue 3 that unifies the four log types and task artifacts written by the MCP server.
Its only relationship with the server is: **they share the same on-disk facts, and no second source of truth exists**.

```text
┌──────────────────────────────┐        ┌──────────────────────────────┐
│ Tianshu                      │        │ Tianshu-mcp Logs (mcp-gui)   │
│ · tools/call: machine-facing │        │ · reads the FS only           │
└──────────────┬───────────────┘        └──────────────┬───────────────┘
               │ MCP over stdio                        │ read-only
┌──────────────▼───────────────┐        ┌──────────────▼───────────────┐
│ tianshu-mcp server           │◀──────▶│ <data home>/logs · /tasks    │
│ · the only writer            │ facts  │ · read-only consumer          │
└──────────────────────────────┘        └──────────────────────────────┘
```

### 16.1 Decoupling boundaries (read before changing anything here)

| Boundary | Rule |
|---|---|
| Data | The GUI is **read-only** for business data; the only writes are its own preferences (system config dir) and user-chosen export/update files |
| Code | `mcp-gui/` has its own `package.json` / `tsconfig` / eslint / vitest and **does not take part in root gates** (root `eslint.config.js` ignores `mcp-gui/**`) |
| Packaging | The root `package.json` `files` allowlist never includes `mcp-gui`; `.gitignore` isolates `node_modules` / `dist` / `target` / `icons` / `Cargo.lock` |
| Releases | The GUI has its own version (`0.1.0-beta.N`) and tag (`gui-v*`) and is **never released with the MCP package** (`release.yml` only matches `v*`) |

The same read-only contract holds for the **insights aggregation command** `get_insights` added in 0.1.1: it scans
only `tasks/tsk_*` and `tasks/vfy_*`, reading each task's `task.json` and its **latest** `report-*.json`, and does
**counting and summing only** (rates / TopN / trend gap-filling / week bucketing happen in the frontend pure
functions in `mcp-gui/src/core/insights.ts`) — it **writes no business data and offers no delete / cleanup entry**.

### 16.2 Anti-drift mechanism for the duplicated schema (the most important rule here)

The Rust side needs its own copy of the state/event vocabulary for classification, and the frontend mirror needs one
for rendering and mock data. The **truth is always** `src/tasks/task.ts` and `src/agents/agent-events.ts`.

`mcp-gui/scripts/check-schema-parity.mjs` parses all three and compares the sets in CI — **any mismatch fails the
build**. The `GUI` workflow also triggers on the two truth files, so TS-side drift is caught too.

| Location | Role |
|---|---|
| `src/tasks/task.ts`, `src/agents/agent-events.ts` | **truth** (sole authority) |
| `mcp-gui/src/core/events.ts` | frontend mirror (rendering / mock decisions) |
| `mcp-gui/src-tauri/src/schema.rs` | Rust mirror (event classification) |

### 16.3 Layering of the read-only backend

| Module | Responsibility |
|---|---|
| `data_home.rs` | data-home resolution (`TIANSHU_MCP_HOME` → `~/.tianshu-mcp`), validation, **relative-path escape guards** (`resolve_rel`), **task-id character allowlist and safe directory joining** (`validate_task_id` / `task_dir`, issue #32) |
| `scanner.rs` | `tasks/` scan + tolerant `task.json` parsing + artifact round aggregation + filtering/sorting |
| `event_stream.rs` | `task.jsonl` parsing (bad lines skipped but counted) and event classification |
| `tail.rs` | byte-window reads (tail window / arbitrary ranges), same semantics as `core/bytes.ts` |
| `watcher.rs` | `notify` watching → `gui/log-changed` events (only the currently open log) |
| `search.rs` | on-demand cross-task scanning + progress events + cancellation (**no full-text index**) |
| `export.rs` | single-file export + whole-task zip (optionally excluding heavy raw logs) |
| `updater.rs` | dual-source probing and selection + three-state switch + `tauri-plugin-updater` (signature gate); **the fallback download page follows the source actually used** (`manual_download_url_for`) |
| `tray.rs` | tray icon creation + menu building / hot-update **per UI language** + window reveal (**touches no business data**; only window visibility and process exit) |

### 16.4 Dual-source auto-update

- **Probe, don't guess**: both manifest endpoints are probed concurrently and ranked by reachability + latency;
  the system region is never trusted (it is unreliable behind a VPN);
- **Same version, same signature on both sides**: the minisign signature covers the **artifact file**, not the source,
  so the Gitee manifest reuses the GitHub `signature` and only changes `url`;
- **Signature verification is a hard gate**: `tauri-plugin-updater` with the embedded public key;
  **a failed verification is always rejected**;
- **Windows payload must be NSIS** (the Tauri updater does not support MSI); macOS uses `.app.tar.gz`;
- **`bundle.productName` is an immutable contract on the upgrade path**: the NSIS uninstall registry key is
  `…\CurrentVersion\Uninstall\<productName>`, so renaming it effectively means "a different app" (the previous
  installation is neither overwritten nor uninstalled and lingers in Apps & features). productName has therefore been
  frozen since `0.1.0-beta.2`; the one-off cleanup of the historical name is handled by
  `mcp-gui/src-tauri/windows/installer-hooks.nsh` (`bundle.windows.nsis.installerHooks` → `NSIS_HOOK_PREINSTALL`),
  which silently runs the legacy uninstaller when it detects a legacy-named uninstall entry and then removes any
  leftover registry keys / shortcuts (it never deletes user data and never recursively deletes the old `$INSTDIR`);
- **Failures never block**: any failure only affects updating; log viewing keeps working, with a "Manual download" entry.
- **The fallback entry must follow the source actually used**: both the manifest endpoint and the fallback download page
  are driven by `resolve_source()`'s result (the `UPDATE_ENDPOINT_*` and `MANUAL_DOWNLOAD_URL_*` constant pairs match up
  one-to-one), and **unknown sources always fall back to GitHub**. Using "the source actually used" rather than the
  literal preference value keeps the entry consistent with the "Source: {s}" already shown in the UI. "Manual download"
  opens via the **system default browser** (see §16.8), **not** an in-webview navigation.

### 16.5 Build boundary (a hard constraint from issue #25)

Rust-side builds and checks (`cargo fmt` / `clippy` / `tauri build`) run **only in CI**; locally only frontend
preview (`npm run dev`) and frontend gates are run. Icons are generated in CI by `tauri icon` from
`assets/tianshu-mcp-icon.svg`; only the SVG source lives in the repository (per the "icons must derive from SVG" rule).

**Triggering and change-detection semantics**: the `GUI` workflow filters pushes by `paths`
(`mcp-gui/**`, the two vocabulary truth sources, and `gui.yml` itself) and then re-checks with a `changed` step so a
docs-only commit does not spin up the whole three-platform matrix. The three events are **deliberately different**:

| Event | Decision | Rationale |
|---|---|---|
| push of tag `gui-v*` | always build | a release must build regardless of changed paths |
| `workflow_dispatch` (manual) | **always build** | manually triggering means "build now"; an earlier revision degraded to diffing the last two commits, so if they happened not to touch `mcp-gui/` the whole matrix was **silently skipped** (the manual run did nothing) |
| push / PR | diff against the previous commit (or the PR base); build only when `mcp-gui/` or `gui.yml` matches | saves runners, while `gui.yml` changes still get re-verified |

**The only difference between a stable release and a preview is the tag shape**: the `publish` job first decides
`prerelease` from whether the tag contains `-beta.` / `-rc.`, then uses it to decide whether the GitHub / Gitee
release page carries the Pre-release flag (`gui-v0.1.0` does not, `gui-v0.1.1-beta.1` does). Both lines **share one
update manifest** (`update/gui/latest.json` and `latest-gitee.json`) and auto-update compares semantic versions
(`0.1.1-beta.1 > 0.1.0`), so the upgrade path **never forks** — that is how "beta and stable interoperate" works.

**The release body comes from a document, not from the workflow**: the `publish` job runs
`scripts/gui-release-body.mjs` to compose a bilingual body from `docs/release-gui-v<version>.md` + `.en.md`
(relative links absolutized to that tag; the GUI is not published to npm, hence **no npm line**), and a **missing
doc exits non-zero** — so a release page can never end up as a bare Full Changelog line. GitHub uses it via
`--notes-file` and Gitee via `--body-file`, so both sides carry the **same body, word for word**; that body is also
the updater manifest's `notes`, which is why the desktop update window shows exactly this release note.

**That path into the manifest is fail-closed**: `build-updater-manifest.mjs merge` must receive the body via
`--notes-file`, and a **read failure exits non-zero** (only "file exists but is empty" falls back to the `--notes`
placeholder title, with a warning). Rationale: the update window's body comes solely from the manifest's `notes`
(`update.body` in `updater.rs`), so silently degrading to a title leaves the window with a single line and the
release chain **reports no error at all** — which is exactly what happened when `0.1.1-beta.1` shipped (its
manifest `notes` was a 28-character title). Both manifests for that version were backfilled under this rule
(version and `platforms` untouched). **Read `test/unit/gui-updater-manifest.test.ts` before changing this
resolution logic** (5 cases: body wins / fallback / empty string / missing file fail-closed / empty file fallback).

### 16.6 Frontend design system and theme contract

The GUI frontend's **presentation layer has its own design system** (**Obsidian Terminal**), decoupled from the MCP package and from the
website directory. Read this section before changing any UI styling.

| Contract | Rule |
|---|---|
| **Layout paradigm** | **A permanent left sidebar plus a two-state content area**: the sidebar (brand · global search · main nav (tasks / server log / **settings**) · **data home (with "Refresh" on the same row)** · task section nav) is always present, while the content area switches between state 1 "task overview" (metrics strip + status chips + filter popover + task card grid + search mode) and state 2 "full-page workspace" (breadcrumb + task summary bar + content, with `server.log` as the second form). **The task section nav shares that one sidebar — there is no second left column; no permanent task rail, no permanent detail column, no horizontal tab row**; the two states and search mode live in local `ref`s in `App.vue` and **add no store fields**; the `server.log` form is derived from `app.tab` (no separate state flag). **The settings entry and the data home both belong to the main nav area** (the data home sits directly below "Settings", grouped by a `border-top` on `.rail-nav > .rail-block`); **"Refresh" is the third icon button on the data-home row, alongside "Add directory / Remove"** (a global action, available in both states); **nothing permanent lives at the bottom of the sidebar** (`.rail-foot` renders the "local preview" notice only under the mock runtime); the brand area **has no decorative colour square** |
| **Overview metrics strip** | Evenly divided reading cells, currently **5**: total / active / finished / **succeeded** / failed (the column count comes from `.metrics`'s `grid-template-columns` — changing the cell count requires changing the column count too). Readings use `.metric-value` with a semantic `tone-*` (active `tone-active`, succeeded `tone-ok`, failed `tone-fail`), and labels always reuse existing i18n keys |
| **Settings panel form** | A **centred modal** (not a right-hand drawer): `.poverlay` is a centred `inset: 0` flex overlay and `.panel` is a rounded card of fixed width `460px` / `max-width: 92vw` / `max-height: 86vh` (`var(--r-2)`, bordered on all sides, `overflow: hidden`); `.panel-body` carries `min-height: 0` so it scrolls internally under the height cap. The entrance animation reuses `@keyframes rise`. Clicking the overlay still closes it |
| Single source of truth | `mcp-gui/src/styles.css`: colors / fonts / spacing / radii / elevation / motion / layout constants are defined **here only** (`:root` holds theme-agnostic tokens; `:root[data-theme="light\|dark"]` holds one color set each; **dark is the default**) |
| Theme mechanism | only `<html data-theme="light\|dark">` is written (`src/theme/index.ts`); components and stylesheets **must not contain hard-coded colors** — variable aliases only (`--bg-*` / `--line-*` / `--fg-*` / `--tone-*`) |
| Accent vs. semantic tones | `--accent` (fluorescent green: `#3DFFA0` dark / `#0E9F6E` light) is used **only** for selection, primary actions, focus rings, the breadcrumb back affordance, and status rails; status labels and chips use **only** `--tone-*` (`active/ok/fail/warn/info/muted`). The two are told apart by **position and shape**, not hue. Tone classification stays in `src/core/status.ts` (mapping only, no copy) |
| Typography | **system fonts only**, monospace-led: mono (`Cascadia Mono` / `SF Mono` / `JetBrains Mono`) / body (`Segoe UI Variable Text` / `SF Pro Text`) / display (`Segoe UI Variable Display` / `SF Pro Display`), with `PingFang SC` / `Microsoft YaHei UI` for CJK. **No font files, no external links** |
| Visual signature | a **1px fluorescent rule** along the left edge of the sidebar and along the top of the breadcrumb bar (the metrics strip on the overview page); a **3px accent rail** marking the current sidebar item; a **3px status rail** plus a `›` prefix on each task card; **bracketed status labels** (`[OK] 已成功`, codes are language-neutral); panel radius 4px / tag and input radius 3px; a very faint dot grid on the dark canvas and a faint 1px grid on the light one (**no purple gradients**) |
| Icons | always the inline SVG path table in `mcp-gui/src/components/AppIcon.vue` (repo rule: **no emoji**); unknown names render empty instead of throwing |
| Numeric alignment | every number that changes with data (times / line numbers / bytes / rounds / counters / exit codes) must use `font-variant-numeric: tabular-nums`; section titles use an eyebrow style (11px / uppercase / `letter-spacing`) |
| Accessibility | a shared `:focus-visible` ring; task cards and nav items are native `<button>` elements (keyboard operable); icon buttons must carry `aria-label` (reusing existing i18n keys); motion collapses under `@media (prefers-reduced-motion: reduce)` |
| Native controls | `color-scheme: light / dark` keeps native `select` and scrollbars in step with the theme; window chrome stays native — **no custom title bar** |

**Change boundary**: a restyle may touch only `App.vue`, `src/components/**`, `src/styles.css`, and `index.html`.
`src/core/**`, `src/api/**`, `src/stores/**`, `src/i18n/**`, `src/theme/index.ts`, and `src-tauri/**` (Rust) belong to the
functional and data layers and **must not be modified** as part of styling work (i18n copy keys may be added only when **both**
language bundles are updated together).

### 16.7 Tray and close-behaviour contract

| Contract | Rule |
|---|---|
| Ownership | The tray is created on the **Rust side** (`src-tauri/src/tray.rs`) and **consumes no frontend permission** (`capabilities/default.json` needs no new entry) |
| Icon source | Reuses the built-in runtime icon (`AppHandle::default_window_icon()`) — **no new icon asset** (icons are always derived by CI from `assets/*.svg`; the artifacts are not committed) |
| Menu items | Two items: Show Logs / Exit Logs (`tray-icon` feature + `tauri::menu`); **labels follow `Preferences.language`**, with two buckets (Chinese / English) and Chinese as the fallback |
| Language hot-update | A language change always goes through `set_preferences`; that command rebuilds the menu **only when the language changed**, via `run_on_main_thread` (menu creation must happen on the main thread) |
| Close behaviour | Preference `closeAction` (`"tray"` default / `"exit"`); `CloseRequested` is resolved on the Rust side: `tray` → `prevent_close()` + `hide()`, `exit` → `app.exit(0)` |
| Preference compatibility | `Preferences.close_action` **must carry a serde default**: a deserialization failure in `preferences.rs` resets the whole file, so a missing field would also wipe language / theme / data homes |
| Platform differences | Windows notification area / macOS menu bar; left-click reveals the window (the menu opens on right-click only, `show_menu_on_left_click(false)`); macOS additionally handles `RunEvent::Reopen` (clicking the Dock icon reveals the window) |
| Failure isolation | A failed tray creation **does not block startup** (the error is ignored in `setup`); the log-viewing main flow takes priority |

### 16.8 External-open capability and URL allow-list contract

Tauri 2's webview **intercepts new-window requests** (`target="_blank"` / `window.open`); without an external-open
capability wired up, the request is **silently dropped** — which is exactly why "Manual download" used to do nothing when
clicked. Any GUI code that needs to open something externally must follow the table below.

| Contract | Rule |
|---|---|
| Capability source | the official `tauri-plugin-opener` (Rust `tauri-plugin-opener = "2"` + JS `@tauri-apps/plugin-opener`), registered in `lib.rs` alongside dialog / updater |
| Frontend exit point | **only** via `src/api/`: `GuiApi.openExternal(url)` → the Tauri implementation calls `openUrl()`, the mock implementation calls `window.open(..., "noopener,noreferrer")`; components must not import the plugin directly |
| Permission allow-list (security boundary) | `capabilities/default.json` uses `opener:allow-open-url` **with an `allow` list** covering **only `https://github.com/**` and `https://gitee.com/**`**; plugin capabilities beyond `core:default` / `dialog:default` are **not granted wholesale** |
| Scope of use | its only current use is the "Manual download" fallback entry (opening a release page); it **must not** be used to open business data paths (export / reveal has its own commands) |
| Failure isolation | a failed open goes through the existing `setError` and **never blocks the log-viewing main flow** (same rule as the update path) |

### 16.9 Filter semantics and command-palette contract (from 0.1.1-beta.2)

**Filtering is implemented twice and the two must agree** (the same idea as the two-way schema in §16.2):

| Location | Implementation | Notes |
|---|---|---|
| Desktop runtime | `matches_filter` in `src-tauri/src/scanner.rs` | `TaskFilter` arrives via `list_tasks`; the backend filters first |
| Frontend (and local preview) | `filterTasks` in `src/core/filter.ts` | `visibleTasks` filters again; mock's `listTasks` ignores its arguments, so **local preview relies entirely on this copy** |

Adding a filter field therefore means changing **both** copies, with semantics stated word for word: `errorType` is an
exact match (empty string = no restriction), `dryRun` is an exact match, `reworked` = `roundsUsed > 1`
(**one round is not rework**) and `hasVisual` = `artifacts.reportHtml` is non-empty. Every Rust-side field is
`#[serde(default)]`, so older callers that omit it do not fail.

**Where palette actions live**: `src/core/hotkeys.ts` (key → action) and `src/core/palette.ts` (command assembly +
fuzzy matching) are pure and unit-tested; **actions are implemented only in `App.vue`** (the palette component knows
nothing about view state and merely dispatches a command `id`). While the palette is open, `matchHotkey` only
recognises the close keys, so no global action fires behind it; `Ctrl/Cmd + R` is `preventDefault`ed (otherwise the
webview would reload), and combinations with `Alt` / `Shift` are never intercepted.

**Task commands are searched live on every keystroke — nothing is pre-generated and there is no cap**:
`buildStaticCommands` (navigation + data homes, input-independent) is separate from `buildTaskCommands` (walks every
task per keystroke; a blank query returns nothing), and `rankCommands`'s `PALETTE_RESULT_LIMIT = 20` **limits only how
many rows are shown, never the search scope**. Any "pre-generate N rows" design silently makes the N+1-th task
unfindable while only saying "no matching commands" — more misleading than not offering the feature at all.

**Data boundaries of multi-task compare (A4)**: the selection limit is `COMPARE_MAX = 4` and the decision lives in the
pure function `nextCompareSelection` (returning `null` means "not applied this time" — it **never replaces** an existing
pick); reports are read **on demand** (the latest `report-<round>.json`) and cached per `taskId`, and switching the data
home clears both the selection and the cache; missing values stay `null` and render as `—` — **no invented times or verdicts**.

### 16.10 Deep link and single-instance contract (from 0.1.1-beta.3)

From `gui-v0.1.1-beta.3` the app handles `tianshu://task/<taskId>`. Each link in the chain has a fixed responsibility —
**do not swap them** (read this section before changing anything here):

| Link | Location | Contract |
|---|---|---|
| Single instance | `.plugin(tauri_plugin_single_instance::init(..))` in `lib.rs` | **Must be registered first** (plugin order is a hard requirement); its `deep-link` feature forwards the second instance's URL arguments **to the deep-link plugin first**, and the callback only reveals the existing window |
| Platform registration | `deep_link().register("tianshu")` in `lib.rs` setup | A failure **never blocks startup** (macOS returns `UnsupportedPlatform`, which is expected); the scheme is declared in `tauri.conf.json` under `plugins.deep-link.desktop.schemes` |
| Enqueueing | `queue_deeplinks()` | Both cold start (`get_current`) and hot start (`on_open_url`) only **enqueue and emit `gui://deeplink`**; **the queue is the source of truth** — on cold start the event fires before the frontend listens, so emitting alone would lose the link |
| Draining and parsing | the `take_pending_deeplinks` command + `core/deeplink.ts` | On mount and on every signal the frontend runs the same "drain → parse → route"; **parsing lives only in a pure function** (unit-tested) and Rust makes no business decisions |
| Permissions | `capabilities/default.json` | **`deep-link:default` is not added**: the frontend never calls that plugin's JS API, so the webview needs no such capability (the same minimal-permission stance as §16.8) |

**Parsing rules (external input, closed here)**: only `tianshu://task/<id>` is accepted; the host is compared
**case-insensitively** (the URL spec only lowercases the scheme); the id must match `[A-Za-z0-9_-]` (it ends up in a
`tasks/<id>/…` path); anything containing `..` / `%2e` is **rejected outright** (URL normalisation erases `..` and cannot
be reversed, so rather than guessing a different id the link is reported as unrecognised); **malformed percent-encoding is
reported as unrecognised (returns `null`) and a failed decode is never rethrown** (issue #33: `decodeURIComponent` throws
`URIError` on externally controlled malformed escapes such as `%zz` / `%` / `%80`, whereas `parseDeepLink`'s contract is
"everything else returns `null`"; throwing would break the await chain in `App.vue` and kill the deep-link subscription);
**the same allowlist is
enforced down in the Rust command layer** (`data_home.rs::validate_task_id`, issue #32) — `read_events` /
`read_baseline` / `read_report` / `export_task_zip` validate before joining paths and do **not** rely on the frontend
`TASK_ID_RE`; unrecognised links produce an **honest UI notice** and are never dropped silently.

**Fallback**: if cold-start routing turns out not to work on a platform, the hot path stays and the platform difference is
documented honestly in `docs/gui-log-viewer`; the difference is **never hidden** to look uniformly supported.

**Read-only boundaries (the two new A5 / A9 commands)**: `read_baseline` only reads `tasks/<task>/baseline.json`
(missing or broken ⇒ `present = false`); `scan_disk_usage` only `stat`s files — **no contents are read and nothing is ever
deleted** — and it measures **actual directories** (`logs/` plus every subdirectory of `tasks/`, with **no `tsk_`/`vfy_`
prefix filter**, deliberately different from the task-list scan because filtering would under-report real disk usage; the
UI states this).

---

## 17. Further reading

| Topic | Document |
|---|---|
| Install, Tianshu integration, tool usage | [README.md](README.md) / [README.en.md](README.en.md) |
| Handover status, troubleshooting, lessons learned | [HANDOFF.md](HANDOFF.md) |
| TraeWork GUI driver details | [docs/traework-cdp.md](docs/traework-cdp.md) |
| Codex desktop GUI driver details | [docs/codex-gui-cdp.md](docs/codex-gui-cdp.md) |
| ZCode GUI driver details | [docs/zcode-cdp.md](docs/zcode-cdp.md) |
| Kimi Code GUI driver details | [docs/kimi-cdp.md](docs/kimi-cdp.md) |
| Qoder CN GUI driver details | [docs/qoder-cdp.md](docs/qoder-cdp.md) |
| Full agent profile field reference | [docs/agent-profiles.md](docs/agent-profiles.md) |
| Per-agent capability research matrix | [docs/adapter-matrix.md](docs/adapter-matrix.md) |
| Project-level acceptance config spec | [docs/acceptance-config.md](docs/acceptance-config.md) |
| Visual acceptance config and troubleshooting | [docs/visual-acceptance.md](docs/visual-acceptance.md) |
| Development environment and commit conventions | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Security model | [SECURITY.md](SECURITY.md) |